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

@@ -729,35 +729,6 @@ retrieve $Items from Module.Entity where Active = true;
 
 **Note**: `returns type as $Var` in the microflow signature does NOT create an activity variable — it only names the return value. So `$Var = call java action ...` after `returns as $Var` is fine (one creation).
 
-## 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 form. DESCRIBE prefers Module.Document names when references are resolvable.
-$Root = call web service 'SampleSOAP.OrderService'
-operation 'FetchSampleItems'
-send mapping 'SampleSOAP.OrderRequest'
-receive mapping 'SampleSOAP.OrderResponse'
-timeout 30
-on error rollback;
-
--- Raw IDs are accepted when old project references are dangling or unavailable.
-$Root = call web service 'sample-service-id'
-operation 'FetchSampleItems'
-send mapping 'sample-send-mapping-id'
-receive mapping 'sample-receive-mapping-id';
-
--- Raw escape hatch emitted for unsupported SOAP fields.
-$Root = call web service raw 'AQID';
-```
-
-**Design note:** the raw payload is base64-encoded BSON for the complete action
-and is authoritative on re-exec. Treat this as round-trip support, not a
-recommended authoring format for new integrations.
-
 ## REST Service Calls
 
 MDL supports two patterns for calling REST APIs from microflows:
@@ -854,11 +825,35 @@ 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 the action should open the file inline instead of forcing
-a download.
+`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;
@@ -880,9 +875,9 @@ $Total = call java action SampleModule.Recalculate(
 );
 ```
 
-`...` is a round-trip-only placeholder. New scripts should bind every
-parameter to a real expression; reach for `...` only when regenerating MDL
-from an existing project that already had unbound parameters.
+`...` 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
 

docs/11-proposals/PROPOSAL_microflow_call_web_service_statement.md

@@ -50,6 +50,7 @@ callWebServiceStatement
         (RECEIVE MAPPING STRING_LITERAL)?
         (TIMEOUT expression)?)
       onErrorClause?
+      SEMICOLON
     ;
 ```
 
@@ -71,20 +72,20 @@ syntax covers them.
 
 ## Tests And Examples
 
-- Parser/visitor coverage for structured and raw forms.
-- Builder/writer coverage for real `WebServiceCallAction` construction and raw
-  BSON preservation.
-- Formatter coverage for qualified-name resolution and raw-ID fallback.
+- 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`.
 
-## 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.
-
 ## 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.

docs/11-proposals/PROPOSAL_microflow_download_file_statement.md

@@ -18,8 +18,8 @@ activity without adding new semantics.
 
 Projects that already contain download-file actions should survive
 describe/exec/describe without losing the activity or falling back to an
-unsupported-action comment. The statement also gives users a straightforward way
-to author file downloads when the file document variable already exists.
+unsupported-action comment. The statement also gives users a straightforward
+way to author file downloads when the file document variable already exists.
 
 ## Syntax
 
@@ -44,6 +44,8 @@ download file $GeneratedReport show in browser on error rollback;
 
 ## Tests And Examples
 
-- Parser/visitor coverage for both normal and `show in browser` forms.
-- Builder/writer coverage for `DownloadFileAction`.
+- Parser/visitor coverage: `TestDownloadFileStatement`.
+- Builder/writer coverage: `TestBuildFlowGraph_DownloadFileCreatesRealAction`
+  and MPR parser tests for `DownloadFileAction`.
 - Example script: `mdl-examples/doctype-tests/download_file.test.mdl`.
+

docs/11-proposals/PROPOSAL_microflow_variable_alias_collision.md

@@ -39,8 +39,8 @@ deterministic and reviewable.
 - The first output keeps its original name.
 - Later outputs are renamed to the first available suffix:
   `Foo_2`, `Foo_3`, and so on.
-- Subsequent variable references and attribute paths are rewritten to the active
-  alias.
+- Subsequent references in variables, paths, and preserved source expressions
+  are rewritten to the active alias.
 - Moving to a different position resets the alias for that variable name.
 
 This is primarily a describe/round-trip preservation rule. Authored MDL should

docs/11-proposals/README.md

@@ -43,11 +43,11 @@ BSON schema Registry ◄──── multi-version Support
 |----------|--------|---------|------------|
 | [MDL Syntax Improvements v1](PROPOSAL_mdl_syntax_improvements.md) | Draft | Go-style assignment, C-style braces, fluent list APIs | — |
 | [MDL Syntax Improvements v2](PROPOSAL_mdl_syntax_improvements_v2.md) | Proposed | Consolidated v2: unified variable declaration, C-style braces, fluent list ops | Syntax Improvements v1 |
-| [Microflow Free Annotation](PROPOSAL_microflow_free_annotation.md) | Draft | Order-sensitive `@annotation` handling for free-floating visual notes in microflows | — |
 | [Microflow Download File Statement](PROPOSAL_microflow_download_file_statement.md) | Draft | `download file $FileDocument [show in browser]` for `DownloadFileAction` round-trip and authoring | — |
-| [Microflow Call Web Service Statement](PROPOSAL_microflow_call_web_service_statement.md) | Draft | Structured and raw MDL syntax for legacy SOAP `CallWebServiceAction` round-trip preservation | — |
+| [Microflow Call Web Service Statement](PROPOSAL_microflow_call_web_service_statement.md) | Draft | Legacy SOAP `CallWebServiceAction` preservation, including a raw BSON escape hatch | — |
 | [Ellipsis Placeholder Expression](PROPOSAL_ellipsis_placeholder_expression.md) | Draft | `...` placeholder for unbound code-action parameters; round-trip preservation of empty `BasicCodeActionParameterValue` bindings | — |
 | [Microflow Variable Alias Collision](PROPOSAL_microflow_variable_alias_collision.md) | Draft | Deterministic `Foo_2` aliases for duplicate implicit outputs at the same microflow position | — |
+| [Microflow Free Annotation](PROPOSAL_microflow_free_annotation.md) | Draft | Order-sensitive `@annotation` handling for free-floating visual notes in microflows | — |
 | [Page Syntax V2](PROPOSAL_page_syntax_v2.md) | Superseded | Page/widget syntax with `{}` blocks and `->` binding. Superseded by V3 (archived) | — |
 | [Page Styling Support](page-styling-support.md) | Partial | CSS classes, inline styles, dynamic classes, design properties. Phase 1 (Class/Style) done | — |
 | [Page Composition](proposal_page_composition.md) | Proposed | Fragment definitions and ALTER PAGE for partial page editing | Page Syntax V2, Page Styling |