fix(modelsdk): serialize microflow annotations (@annotation was dropped)

@annotation 'text' on a microflow activity was silently dropped on the modelsdk
(default) engine: the write path had no case for Microflows$Annotation and never
emitted the AnnotationFlow that links a note to its activity. The legacy engine
wrote both; modelsdk produced 0 annotation objects.

Add an Annotation case to microflowObjectToGen and serialize the
ObjectCollection's AnnotationFlows in microflowToGen (version-gated line shape,
mirroring the legacy serializeAnnotationFlow). @annotation now round-trips
through modelsdk (write → read → describe) and mx check reports 0 errors.

Also corrects the doctype example M021_2: Mendix for-loops have no editable
caption (LoopedActivity has no Caption property — confirmed against a
Studio-Pro-saved loop, which stores an Annotation note + AnnotationFlow, not a
loop caption). The example now uses @annotation instead of @caption, matching
what Studio Pro produces.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ako

mdl-examples/bug-tests/microflow-annotation-modelsdk.mdl

@@ -0,0 +1,41 @@
+-- ============================================================================
+-- Microflow @annotation dropped on the modelsdk engine
+-- ============================================================================
+--
+-- Symptom (before fix):
+--   @annotation 'text' on a microflow activity (including a loop) was silently
+--   dropped on the modelsdk (default) engine — no Microflows$Annotation object
+--   and no AnnotationFlow were written. The legacy engine wrote them; modelsdk
+--   had no serialization for either type.
+--
+--   (Related: for-loops have no caption in Mendix — LoopedActivity has no
+--   Caption property — so @caption on a loop is not representable. An
+--   annotation note is the supported way to label a loop, matching what Studio
+--   Pro produces when you attach a note to the loop.)
+--
+-- After fix:
+--   microflowObjectToGen serializes Microflows$Annotation and microflowToGen
+--   emits the AnnotationFlow, so @annotation round-trips through the modelsdk
+--   engine and mx check reports 0 errors.
+--
+-- Usage:
+--   mxcli exec mdl-examples/bug-tests/microflow-annotation-modelsdk.mdl -p app.mpr
+--   mxcli -p app.mpr -c "describe microflow AnnTest.MF_Loop"   # shows @annotation
+-- ============================================================================
+
+create module AnnTest;
+create persistent entity AnnTest.Thing ( Name: string(50) );
+/
+
+create microflow AnnTest.MF_Loop ( $Things: list of AnnTest.Thing )
+returns integer as $count
+begin
+  declare $count integer = 0;
+  @annotation 'Process the things'
+  loop $Thing in $Things
+  begin
+    set $count = $count + 1;
+  end loop;
+  return $count;
+end;
+/

mdl-examples/doctype-tests/02-microflow-examples.mdl

@@ -679,9 +679,13 @@ end;
 /
 
 /**
- * Example 6.1b: LOOP with custom caption
+ * Example 6.1b: LOOP with an annotation note
  *
- * Demonstrates activity metadata on a loop.
+ * Mendix for-loops have no editable caption (LoopedActivity has no Caption
+ * property — Studio Pro auto-labels them from the iterator). To document a
+ * loop, attach an annotation note with @annotation, which creates a
+ * Microflows$Annotation connected by an AnnotationFlow — the same thing you
+ * get by drawing a note onto the loop in Studio Pro.
  */
 create microflow MfTest.M021_2_LoopWithCaption (
   $ProductList: list of MfTest.Product
@@ -690,7 +694,7 @@ returns integer as $count
 begin
   declare $count integer = 0;
 
-  @caption 'Process products'
+  @annotation 'Process products'
   loop $Product in $ProductList
   begin
     set $count = $count + 1;

mdl/backend/modelsdk/microflow_annotation_test.go

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/modelsdk/codec"
+	"github.com/mendixlabs/mxcli/sdk/microflows"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// TestMicroflowObjectToGen_Annotation guards that a microflow annotation note
+// (from @annotation) is serialized. The modelsdk write path previously had no
+// case for it, so @annotation was silently dropped on the default engine.
+func TestMicroflowObjectToGen_Annotation(t *testing.T) {
+	ann := &microflows.Annotation{
+		BaseMicroflowObject: microflows.BaseMicroflowObject{
+			BaseElement: model.BaseElement{ID: model.ID("ann-1")},
+			Position:    model.Point{X: 100, Y: 100},
+			Size:        model.Size{Width: 200, Height: 50},
+		},
+		Caption: "Process products",
+	}
+	g := microflowObjectToGen(ann)
+	if g == nil {
+		t.Fatal("microflowObjectToGen(Annotation) returned nil — annotation dropped")
+	}
+	raw, err := (&codec.Encoder{}).Encode(g)
+	if err != nil {
+		t.Fatalf("encode: %v", err)
+	}
+	r := bson.Raw(raw)
+	if got := r.Lookup("$Type").StringValue(); got != "Microflows$Annotation" {
+		t.Errorf("$Type = %q, want Microflows$Annotation", got)
+	}
+	if got := r.Lookup("Caption").StringValue(); got != "Process products" {
+		t.Errorf("Caption = %q, want Process products", got)
+	}
+}
+
+// TestAnnotationFlowToGen guards the AnnotationFlow that connects a note to its
+// activity, including the version-specific line shape (Line/BezierCurve on 10+).
+func TestAnnotationFlowToGen(t *testing.T) {
+	af := &microflows.AnnotationFlow{
+		BaseElement:   model.BaseElement{ID: model.ID("af-1")},
+		OriginID:      model.ID("ann-1"),
+		DestinationID: model.ID("act-1"),
+	}
+	raw, err := (&codec.Encoder{}).Encode(annotationFlowToGen(af, 11))
+	if err != nil {
+		t.Fatalf("encode: %v", err)
+	}
+	r := bson.Raw(raw)
+	if got := r.Lookup("$Type").StringValue(); got != "Microflows$AnnotationFlow" {
+		t.Errorf("$Type = %q, want Microflows$AnnotationFlow", got)
+	}
+	if _, err := r.LookupErr("OriginPointer"); err != nil {
+		t.Errorf("OriginPointer missing: %v", err)
+	}
+	if _, err := r.LookupErr("DestinationPointer"); err != nil {
+		t.Errorf("DestinationPointer missing: %v", err)
+	}
+	if _, err := r.LookupErr("Line"); err != nil {
+		t.Errorf("Line (BezierCurve) missing on major>=10: %v", err)
+	}
+}

mdl/backend/modelsdk/microflow_write.go

@@ -204,11 +204,15 @@ func microflowToGen(mf *microflows.Microflow, major int) *genMf.Microflow {
 	}
 	out.SetObjectCollection(oc)
 
-	// Flows live on the microflow, not in the object collection.
+	// Flows live on the microflow, not in the object collection. Sequence flows
+	// and annotation flows share the same Flows list.
 	if mf.ObjectCollection != nil {
 		for _, f := range mf.ObjectCollection.Flows {
 			out.AddFlows(sequenceFlowToGen(f, major))
 		}
+		for _, af := range mf.ObjectCollection.AnnotationFlows {
+			out.AddFlows(annotationFlowToGen(af, major))
+		}
 	}
 
 	if major >= 10 {
@@ -314,11 +318,43 @@ func microflowObjectToGen(obj microflows.MicroflowObject) element.Element {
 		g.SetRelativeMiddlePoint(pointStr(o.Position))
 		g.SetSize(sizeStr(o.Size))
 		return g
+	case *microflows.Annotation:
+		// A microflow annotation (yellow note); its caption is the note text.
+		// Connected to an activity by an AnnotationFlow (serialized in
+		// microflowToGen). Without this, `@annotation` was silently dropped.
+		g := genMf.NewAnnotation()
+		g.SetID(element.ID(o.ID))
+		g.SetCaption(o.Caption)
+		g.SetRelativeMiddlePoint(pointStr(o.Position))
+		g.SetSize(sizeStr(o.Size))
+		return g
 	default:
 		return nil // unsupported object type (added in later activity groups)
 	}
 }
 
+// annotationFlowToGen builds a Microflows$AnnotationFlow connecting an Annotation
+// (origin) to the activity it documents (destination). The line shape is
+// version-specific, mirroring the legacy serializeAnnotationFlow.
+func annotationFlowToGen(af *microflows.AnnotationFlow, major int) element.Element {
+	g := genMf.NewAnnotationFlow()
+	g.SetID(element.ID(af.ID))
+	g.SetOriginID(element.ID(af.OriginID))
+	g.SetDestinationID(element.ID(af.DestinationID))
+	g.SetOriginConnectionIndex(0)
+	g.SetDestinationConnectionIndex(0)
+	if major <= 9 {
+		g.SetOriginBezierVector("0;0")
+		g.SetDestinationBezierVector("0;0")
+	} else {
+		line := genMf.NewBezierCurve()
+		line.SetOriginControlVector("0;0")
+		line.SetDestinationControlVector("0;0")
+		g.SetLine(line)
+	}
+	return g
+}
+
 // loopSourceToGen builds a loop's source (iterate-over-list or while-condition).
 func loopSourceToGen(ls microflows.LoopSource) element.Element {
 	switch s := ls.(type) {