fix: preserve rule split describer output and free annotations

The microflow describer round-trip was lossy in three ways after the
rule-split parser landed:

1. `DESCRIBE MICROFLOW` of an IF whose condition was a RuleSplitCondition
   silently emitted `if true then`, because the ExclusiveSplit formatter
   only recognised ExpressionSplitCondition. `describe -> exec` demoted
   every rule-based decision to `if true` — the MPR still loaded but
   Studio Pro showed the wrong condition.

2. `@caption` was only emitted for ActionActivity. Splits store their
   human-readable label (e.g. "Right format?") on the split itself, not
   on the expression, so round-tripping the describer output produced
   an ExclusiveSplit with no caption even when Mendix had one.

3. Free-floating Annotation objects (those without an AnnotationFlow
   pointing to them) were silently dropped by the describer, losing
   author/date comments on flows that contained no activities.

The IF flow builder also emitted a dangling SequenceFlow whenever a
nested IF had `thenReturns` in an outer context with `needMerge=false`,
because the flow-emission check only looked at `!thenReturns`. Studio
Pro rejected the resulting MPR with "Sequence contains no matching
element". Guard the three branch-to-merge flows on `needMerge` so the
parent handles the continuation.

Changes:

- `cmd_microflows_format_action.go`: extract `formatSplitCondition`
  helper that renders ExpressionSplitCondition verbatim and
  RuleSplitCondition as `Module.RuleName(Param = arg, ...)` using the
  already-parsed `RuleQualifiedName` and `ParameterName` fields.
- `cmd_microflows_show_helpers.go`: emit `@caption` for ExclusiveSplit
  and InheritanceSplit when a caption is present.
- `cmd_microflows_show.go`: prepend free-floating annotations as
  `@annotation` entries on the first activity in both `describeMicroflow`
  and `renderMicroflowMDL`.
- `cmd_microflows_builder_control.go`: add `&& needMerge` guards to
  all three branch-to-merge flow emissions so empty mergeID never
  reaches the BSON writer.
- `sdk/mpr/writer_core.go`: document that an empty id in
  `idToBsonBinary` indicates a caller bug rather than a valid input —
  the random-UUID fallback produces references to nothing and shows up
  in Studio Pro as KeyNotFoundException.

Depends on `submit/microflow-split-subtype-preservation` for the
`RuleQualifiedName` / `ParameterName` fields on RuleSplitCondition /
RuleCallParameterMapping and for the RuleCall-aware parser.

Author: hjothamendix

mdl/executor/cmd_microflows_builder_control.go

@@ -127,8 +127,10 @@ func (fb *flowBuilder) addIfStatement(s *ast.IfStmt) model.ID {
 			}
 		}
 
-		// Connect THEN body to merge only if it doesn't end with RETURN
-		if !thenReturns {
+		// Connect THEN body to merge only if it doesn't end with RETURN and a merge exists.
+		// When needMerge=false, the continuing branch is wired up by the parent via
+		// nextConnectionPoint/nextFlowCase, so we must not emit a dangling flow here.
+		if !thenReturns && needMerge {
 			if lastThenID != "" {
 				fb.flows = append(fb.flows, newHorizontalFlow(lastThenID, mergeID))
 			} else {
@@ -163,8 +165,10 @@ func (fb *flowBuilder) addIfStatement(s *ast.IfStmt) model.ID {
 			}
 		}
 
-		// Connect ELSE body to merge only if it doesn't end with RETURN
-		if !elseReturns {
+		// Connect ELSE body to merge only if it doesn't end with RETURN and a merge exists.
+		// When needMerge=false, the continuing branch is handled by the parent; emitting
+		// a flow with an empty mergeID would create an orphan SequenceFlow.
+		if !elseReturns && needMerge {
 			if lastElseID != "" {
 				fb.flows = append(fb.flows, newUpwardFlow(lastElseID, mergeID))
 			}
@@ -206,8 +210,10 @@ func (fb *flowBuilder) addIfStatement(s *ast.IfStmt) model.ID {
 			}
 		}
 
-		// Connect THEN body to merge only if it doesn't end with RETURN
-		if !thenReturns {
+		// Connect THEN body to merge only if it doesn't end with RETURN and a merge exists.
+		// With no ELSE + thenReturns, needMerge=false and the FALSE path is threaded through
+		// the parent — any flow emitted here would dangle with mergeID="".
+		if !thenReturns && needMerge {
 			if lastThenID != "" {
 				fb.flows = append(fb.flows, newUpwardFlow(lastThenID, mergeID))
 			} else {

mdl/executor/cmd_microflows_format_action.go

@@ -39,12 +39,7 @@ func formatActivity(
 		return formatAction(ctx, activity.Action, entityNames, microflowNames)
 
 	case *microflows.ExclusiveSplit:
-		condition := "true"
-		if activity.SplitCondition != nil {
-			if exprCond, ok := activity.SplitCondition.(*microflows.ExpressionSplitCondition); ok {
-				condition = exprCond.Expression
-			}
-		}
+		condition := formatSplitCondition(activity.SplitCondition)
 		return fmt.Sprintf("if %s then", condition)
 
 	case *microflows.ExclusiveMerge:
@@ -1159,3 +1154,42 @@ func (e *Executor) formatListOperation(op microflows.ListOperation, outputVar st
 func (e *Executor) formatRestCallAction(a *microflows.RestCallAction) string {
 	return formatRestCallAction(e.newExecContext(context.Background()), a)
 }
+
+// formatSplitCondition renders an ExclusiveSplit's condition as an MDL expression.
+// ExpressionSplitCondition is emitted verbatim. RuleSplitCondition is rendered as
+// a rule call expression using the rule's qualified name — Mendix expressions
+// allow calling a rule the same way as a microflow, so this is re-parseable.
+// Unknown or nil conditions fall back to "true" so the describer still produces
+// valid MDL; callers should rely on the original Caption (emitted via @caption)
+// to preserve human-readable intent.
+func formatSplitCondition(cond microflows.SplitCondition) string {
+	switch c := cond.(type) {
+	case *microflows.ExpressionSplitCondition:
+		expr := strings.TrimRight(c.Expression, " \t\n\r")
+		if expr == "" {
+			return "true"
+		}
+		return expr
+	case *microflows.RuleSplitCondition:
+		name := c.RuleQualifiedName
+		if name == "" {
+			return "true"
+		}
+		args := make([]string, 0, len(c.ParameterMappings))
+		for _, pm := range c.ParameterMappings {
+			paramName := pm.ParameterName
+			if idx := strings.LastIndex(paramName, "."); idx >= 0 {
+				paramName = paramName[idx+1:]
+			}
+			arg := strings.TrimRight(pm.Argument, " \t\n\r")
+			if paramName != "" {
+				args = append(args, fmt.Sprintf("%s = %s", paramName, arg))
+			} else {
+				args = append(args, arg)
+			}
+		}
+		return fmt.Sprintf("%s(%s)", name, strings.Join(args, ", "))
+	default:
+		return "true"
+	}
+}

mdl/executor/cmd_microflows_show.go

@@ -276,6 +276,15 @@ func describeMicroflow(ctx *ExecContext, name ast.QualifiedName) error {
 	// Generate activities
 	if targetMf.ObjectCollection != nil && len(targetMf.ObjectCollection.Objects) > 0 {
 		activityLines := formatMicroflowActivities(ctx, targetMf, entityNames, microflowNames)
+		freeAnnots := collectFreeAnnotations(targetMf.ObjectCollection)
+		if len(freeAnnots) > 0 && len(activityLines) > 0 {
+			prefix := make([]string, 0, len(freeAnnots))
+			for _, text := range freeAnnots {
+				escaped := strings.ReplaceAll(text, "'", "''")
+				prefix = append(prefix, fmt.Sprintf("@annotation '%s'", escaped))
+			}
+			activityLines = append(prefix, activityLines...)
+		}
 		for _, line := range activityLines {
 			lines = append(lines, "  "+line)
 		}
@@ -533,6 +542,15 @@ func renderMicroflowMDL(
 		} else {
 			activityLines = formatMicroflowActivities(ctx, mf, entityNames, microflowNames)
 		}
+		freeAnnots := collectFreeAnnotations(mf.ObjectCollection)
+		if len(freeAnnots) > 0 && len(activityLines) > 0 {
+			prefix := make([]string, 0, len(freeAnnots))
+			for _, text := range freeAnnots {
+				escaped := strings.ReplaceAll(text, "'", "''")
+				prefix = append(prefix, fmt.Sprintf("@annotation '%s'", escaped))
+			}
+			activityLines = append(prefix, activityLines...)
+		}
 		for _, line := range activityLines {
 			lines = append(lines, "  "+line)
 		}

mdl/executor/cmd_microflows_show_helpers.go

@@ -84,6 +84,15 @@ func emitObjectAnnotations(obj microflows.MicroflowObject, lines *[]string, inde
 		}
 	}
 
+	if split, ok := obj.(*microflows.ExclusiveSplit); ok && split.Caption != "" {
+		escapedCaption := strings.ReplaceAll(split.Caption, "'", "''")
+		*lines = append(*lines, indentStr+fmt.Sprintf("@caption '%s'", escapedCaption))
+	}
+	if split, ok := obj.(*microflows.InheritanceSplit); ok && split.Caption != "" {
+		escapedCaption := strings.ReplaceAll(split.Caption, "'", "''")
+		*lines = append(*lines, indentStr+fmt.Sprintf("@caption '%s'", escapedCaption))
+	}
+
 	// @annotation (attached Annotation objects)
 	if annotationsByTarget != nil {
 		for _, caption := range annotationsByTarget[currentID] {

sdk/mpr/writer_core.go

@@ -15,6 +15,10 @@ import (
 // idToBsonBinary converts a UUID string to BSON Binary format.
 // For invalid or empty UUIDs (e.g. test placeholders), generates a random ID
 // to maintain backward compatibility with existing serialization paths.
+//
+// WARNING: an empty id here is almost always a bug (e.g. an unset pointer on a
+// SequenceFlow) and produces a random UUID that references nothing — which
+// Studio Pro surfaces as "KeyNotFoundException". Fix callers to pass a real ID.
 func idToBsonBinary(id string) primitive.Binary {
 	blob := types.UUIDToBlob(id)
 	if blob == nil || len(blob) != 16 {