draft: stage remaining microflow roundtrip fixes

Symptom: the focused upstream PR set does not yet include every local roundtrip-validity fix found during long-running audits of large legacy Mendix projects.

Root cause: several remaining fixes are intertwined across microflow control-flow reconstruction, handler routing, split/case preservation, validation, and writer/parser compatibility. They need further extraction before they are suitable for review as individual upstream PRs.

Fix: stage the remaining all-fixes tree as one draft branch so the outstanding local work is visible upstream while smaller PRs continue to be split out from it. This draft is not intended to merge as-is.

Tests: make build, make test, and make lint-go pass on the staged tree.

Author: hjothamendix

.claude/commands/mxcli-dev/review.md

@@ -32,6 +32,9 @@ proactively. Add a row after every review that surfaces something new.
 | 7 | Skill/doc table references a function that doesn't exist (e.g. `formatActionStatement()` vs `formatAction()`) | Docs quality | Grep function names before writing: `grep -r "func formatA" mdl/executor/` |
 | 8 | "Always X" rule is too absolute for trivial edge cases (e.g. "always write failing test first" for one-char typos) | Docs quality | Soften to "prefer X" or add an exception clause; include the reasoning so readers can judge edge cases |
 | 9 | Doc comment promises a fallback/feature that doesn't exist in the code (e.g., "raw-map fallback in the client" when no such fallback was implemented) | Docs quality | Grep for function/type names referenced in doc comments to confirm they exist before committing |
+| 10 | New MDL keyword or statement added without a parser example in `mdl-examples/` | Syntax feature | Add a minimal `mdl-examples/doctype-tests/*.mdl` fixture and include the statement in the quick reference before review |
+| 11 | Commit titled `fix:` actually introduces new MDL syntax | Scope & atomicity | Split the syntax addition into a `feat:` or proposal-backed PR; keep bug fixes separate from language design |
+| 12 | Round-trip bug patched on only one half of parse/write | DESCRIBE/EXEC symmetry | Fix both parser/defaulting and writer serialization, then add tests for missing/default fields and explicit fields |
 
 ---
 

.claude/skills/mendix/write-microflows.md

@@ -559,6 +559,7 @@ commit $Product;
 
 **Rules:**
 - `@annotation` before an activity attaches the note to that activity
+- `@annotation` before activity-binding metadata such as `@position`, `@caption`, `@color`, `@excluded`, or `@anchor` stays free-floating when later metadata binds the following activity
 - `@annotation` at the end (no following activity) creates a free-floating note
 - Escape single quotes by doubling: `@annotation 'Don''t forget'`
 - `@position` always appears in DESCRIBE output; `@caption` only when custom; `@color` only when not Default
@@ -824,6 +825,60 @@ rest call delete 'https://api.example.com/items/{1}' with (
 
 **REST CALL supports full error handling** (`on error continue`, `on error rollback`, custom error handlers).
 
+## Legacy SOAP Web Service Calls
+
+`call web service` preserves legacy Mendix SOAP activities. Prefer REST clients
+for new integrations; this syntax exists mainly so existing projects can round-trip
+without dropping SOAP actions.
+
+```mdl
+-- Structured passthrough form using Mendix document IDs.
+$Root = call web service 'sample-service-id'
+operation 'FetchSampleItems'
+send mapping 'sample-send-mapping-id'
+receive mapping 'sample-receive-mapping-id'
+timeout 30
+on error rollback;
+
+-- Raw escape hatch emitted by describe when the SOAP action has fields that
+-- are not expressible yet. The base64 payload is the authoritative BSON action.
+$Root = call web service raw 'AQID';
+```
+
+**Design note:** service and mapping references are currently opaque Mendix IDs,
+not qualified names. Treat this as round-trip support, not a recommended authoring
+syntax for new SOAP actions.
+
+## File Downloads
+
+Use `download file` to stream a `System.FileDocument` from a microflow. Add
+`show in browser` when Studio Pro's action should open the file inline instead
+of forcing a download.
+
+```mdl
+download file $GeneratedReport show in browser;
+download file $GeneratedExport;
+```
+
+## Empty Java-Action Argument (`...`)
+
+When `describe` round-trips a Java-action call that has an unbound parameter
+in Studio Pro, it emits `...` as the argument value. This preserves the
+underlying empty `BasicCodeActionParameterValue.Argument` so that the next
+`describe → exec → describe` cycle stays symmetric.
+
+```mdl
+$Total = call java action SampleModule.Recalculate(
+  CompanyId       = ...,
+  RecalculateAll  = true,
+  ItemList        = ...
+);
+```
+
+`...` is a *round-trip-only* placeholder. New scripts should bind every
+parameter to a real expression; reach for `...` only when you're regenerating
+MDL from an existing project that already had unbound parameters.
+
 ## Error Handling
 
 MDL supports error handling for activities that may fail (microflow calls, commits, external service calls, etc.).

cmd/mxcli/lsp_completions_gen.go

@@ -215,6 +215,7 @@ authentication basic, session
 | List declaration | `declare $list list of Module.Entity = empty;` | |
 | Assignment | `set $Var = expression;` | Variable must be declared first |
 | Create object | `$Var = create Module.Entity (attr = value);` | |
+| Duplicate implicit output | `$Var`, `$Var_2`, `$Var_3` | Describe may alias same-position duplicate outputs for round-trip preservation |
 | Change object | `change $entity (attr = value);` | |
 | Commit | `commit $entity [with events] [refresh];` | |
 | Delete | `delete $entity;` | |
@@ -223,14 +224,18 @@ authentication basic, session
 | Retrieve (Assoc) | `retrieve $list from $Parent/Module.AssocName;` | Retrieve by association |
 | Call microflow | `$Result = call microflow Module.Name (Param = $value);` | |
 | Call nanoflow | `$Result = call nanoflow Module.Name (Param = $value);` | |
+| Call web service | `$Result = call web service 'Module.Service' operation 'OperationName';` | Legacy SOAP; unresolved dangling refs fall back to raw IDs |
+| Call web service raw | `$Result = call web service raw 'base64-bson';` | Escape hatch for byte-for-byte legacy SOAP round-trip |
 | Show page | `show page Module.PageName ($Param = $value);` | Also accepts `(Param: $value)` |
 | Close page | `close page;` | |
+| Download file | `download file $FileDocument [show in browser];` | Streams a `System.FileDocument` |
 | Validation | `validation feedback $entity/attribute message 'message';` | Requires attribute path + MESSAGE |
 | Log | `log info\|warning\|error [node 'name'] 'message';` | |
 | Position | `@position(x, y)` | Canvas position (before activity) |
 | Caption | `@caption 'text'` | Custom caption (before activity) |
 | Color | `@color Green` | Background color (before activity) |
 | Annotation | `@annotation 'text'` | Visual note attached to next activity |
+| Free annotation | `@annotation 'text'` before `@position(...)` | Free-floating visual note preserved by order |
 | IF | `if condition then ... [else ...] end if;` | |
 | LOOP | `loop $item in $list begin ... end loop;` | FOR EACH over list |
 | WHILE | `while condition begin ... end while;` | Condition-based loop |
@@ -775,6 +780,7 @@ Module.OrderResponse_CustomerInfo/Module.CustomerInfo as customer {
 | Create exposed action | `... exposed as 'caption' in 'Category' as $$ ... $$;` | Toolbox-visible in Studio Pro |
 | Drop Java action | `drop java action Module.Name;` | Delete a Java action |
 | Call from microflow | `$Result = call java action Module.Name(Param = value);` | Inside BEGIN...END |
+| Empty argument | `call java action Module.Name(Param = ...);` | `...` placeholder for an unbound code-action parameter (round-trip only) |
 
 **Parameter Types:** `string`, `integer`, `long`, `decimal`, `boolean`, `datetime`, `Module.Entity`, `list of Module.Entity`, `enum Module.EnumName`, `enumeration(Module.EnumName)`, `stringtemplate(sql)`, `stringtemplate(Oql)`, `entity <pEntity>` (type parameter declaration), bare `pEntity` (type parameter reference).
 

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -0,0 +1,111 @@
+# Ellipsis Placeholder Expression
+
+Status: Draft
+
+## Summary
+
+Add a single-token expression `...` that represents an unbound /
+intentionally-empty argument value in microflow call statements.
+
+```mdl
+$Total = call java action SampleModule.Recalculate(
+  CompanyId       = ...,
+  RecalculateAll  = true,
+  ItemList        = ...
+);
+```
+
+`...` produces a parameter binding with an empty `Argument` string in the
+serialized BSON (`Microflows$BasicCodeActionParameterValue.Argument = ""`).
+Re-executing a script that contains `...` reproduces the same empty
+binding byte-for-byte, so describe → exec → describe stays symmetric for
+existing Studio Pro projects that have unbound code-action parameters.
+
+## Motivation
+
+Studio Pro's Java-action call dialog allows a developer to leave individual
+parameters empty — for example, when a Java action declares a parameter that
+the calling microflow does not yet have a meaningful value for, or when an
+external mapping is expected to fill the slot at runtime. The on-disk
+representation is a `Microflows$JavaActionParameterMapping` whose `Value` is a
+`BasicCodeActionParameterValue` with `Argument: ""`.
+
+Before `...` existed, the describer had two options for these empty bindings:
+
+1. Emit `''` (empty string literal). On re-exec, the visitor would round-trip
+   to a non-empty single-quote literal whose `Argument` was `''`, not `""`,
+   and Studio Pro would render the parameter as the literal string `''`.
+2. Drop the parameter entirely. Studio Pro would then add a back a
+   placeholder mapping with a generated value, breaking the round-trip.
+
+Both lose information. `...` lets the describer round-trip the empty binding
+without inventing a fake value.
+
+## Syntax
+
+```antlr
+atomicExpression
+    : literal
+    | ELLIPSIS
+    | ...
+    ;
+```
+
+Where `ELLIPSIS` is the lexer token `'...'`. The token is reserved for this
+single use; it is not valid in arithmetic / boolean / comparison
+expressions.
+
+## Semantics
+
+- `...` is recognised by the builder via `isPlaceholderExpression` in
+  `mdl/executor/cmd_microflows_builder_calls.go`.
+- Inside a Java-action `callArgument`, `...` produces a
+  `BasicCodeActionParameterValue` with `Argument: ""`.
+- Outside of `callArgument` lists, `...` parses but the builder rejects it
+  (it never resolves to a runtime value). Future statements may extend the
+  set of contexts that accept `...` — see Open Questions.
+
+## Examples
+
+```mdl
+-- Java action call with two unbound and one bound argument
+$Total = call java action SampleModule.Recalculate(
+  CompanyId       = ...,
+  RecalculateAll  = true,
+  ItemList        = ...
+);
+```
+
+The Mendix BSON for the unbound arguments is:
+
+```
+JavaActionParameterMapping {
+  Parameter: 'SampleModule.Recalculate.CompanyId',
+  Value: BasicCodeActionParameterValue { Argument: '' }
+}
+```
+
+## Tests And Examples
+
+- Builder coverage: `TestBuildJavaAction_PlaceholderArgumentPreservesEmptyBasicValue`
+  in `mdl/executor/cmd_microflows_builder_java_action_test.go`.
+- Visitor coverage: `atomicExpression`'s `ELLIPSIS` arm produces
+  `ast.SourceExpr{Source: "..."}` (see
+  `mdl/visitor/visitor_microflow_expression.go`).
+- Example script: `mdl-examples/doctype-tests/ellipsis_placeholder.test.mdl`.
+
+## Open Questions
+
+- Should `...` be allowed as an argument to `call microflow` and
+  `call nanoflow` calls as well? Today only Java actions consume the
+  `BasicCodeActionParameterValue` form, so there is no symmetric BSON
+  representation, but a future proposal could extend this.
+- Should we explicitly document `...` as round-trip-only and warn the linter
+  when an authored microflow uses `...` outside of a known describe-emitted
+  context? This would prevent users from authoring scripts that produce
+  Studio Pro warnings ("unbound parameter") on import.
+- Should the surface syntax be `...` or a clearer keyword like
+  `unspecified` / `default` / `unbound`? `...` was chosen because it is
+  visually distinct, short, and matches existing "this is intentionally
+  blank" conventions in other tools (Python's `Ellipsis`, TypeScript's
+  `never` placeholder, etc.).

docs/11-proposals/PROPOSAL_ellipsis_placeholder_expression.md

@@ -0,0 +1,91 @@
+# Microflow Call Web Service Statement
+
+Status: Draft
+
+## Summary
+
+Add MDL support for legacy Mendix SOAP `Microflows$CallWebServiceAction`.
+
+```mdl
+$Root = call web service 'SampleSOAP.OrderService'
+operation 'FetchSampleItems'
+send mapping 'SampleSOAP.OrderRequest'
+receive mapping 'SampleSOAP.OrderResponse'
+timeout 30;
+
+$Root = call web service 'dangling-service-id'
+operation 'FetchSampleItems'
+send mapping 'dangling-send-mapping-id'
+receive mapping 'dangling-receive-mapping-id';
+
+$Root = call web service raw 'AQID';
+```
+
+This proposal is primarily about safe round-trip preservation of existing SOAP
+actions. New integrations should prefer consumed REST services or inline REST
+calls.
+
+## Motivation
+
+Legacy projects can contain SOAP web service calls. Without an MDL
+representation, describe output either drops the activity or emits an
+unsupported-action comment that cannot be re-executed into the same model.
+
+The immediate goal is therefore fidelity:
+
+- Parse existing `CallWebServiceAction` BSON.
+- Emit an MDL statement that can be executed back into the MPR.
+- Preserve unsupported or version-specific BSON fields when the structured
+  fields are incomplete.
+
+## Syntax
+
+```antlr
+callWebServiceStatement
+    : (VARIABLE EQUALS)? CALL WEB SERVICE
+      (RAW STRING_LITERAL
+      | STRING_LITERAL
+        (OPERATION STRING_LITERAL)?
+        (SEND MAPPING STRING_LITERAL)?
+        (RECEIVE MAPPING STRING_LITERAL)?
+        (TIMEOUT expression)?)
+      onErrorClause?
+      SEMICOLON
+    ;
+```
+
+## Design Notes
+
+The structured form prefers stable qualified names for the imported web service
+and mapping references. During `describe`, mxcli resolves known
+`WebServices$ImportedWebService`, `ExportMappings$ExportMapping`, and
+`ImportMappings$ImportMapping` IDs through the backend and emits
+`Module.DocumentName`.
+
+If a reference is dangling or the backend cannot resolve it, mxcli deliberately
+falls back to the raw ID string so unsupported legacy projects still round-trip.
+
+The `raw` form is an explicit escape hatch. Its string is base64-encoded BSON
+for the complete action payload and is authoritative when re-executed. It exists
+so unsupported SOAP fields can be preserved byte-for-byte until the structured
+syntax covers them.
+
+## Tests And Examples
+
+- Parser/visitor coverage: `TestCallWebServiceStatement` and
+  `TestCallWebServiceRawStatement`.
+- Builder/writer coverage: `TestBuildFlowGraph_WebServiceCallCreatesRealAction`,
+  `TestBuildFlowGraph_WebServiceCallPreservesRawBSON`, and MPR RawBSON tests.
+- Example script: `mdl-examples/doctype-tests/call_web_service.test.mdl`.
+
+## Open Questions
+
+- Should the raw payload eventually move to a generic
+  `raw microflow action '...'` escape hatch instead of remaining under
+  `call web service raw`?
+
+## Resolved Questions
+
+- Service and mapping references are emitted as `Module.Document` names when
+  the backend can resolve them. Raw IDs remain the fallback for dangling
+  references and incomplete project metadata.