From 13accfcae5ebaf36082dc61a32e8b4cb57ab11ee Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 14 Sep 2026 11:34:50 +0000
Subject: [PATCH 01/24] docs(wiki): re-sync describe-round-trip-gaps after #923
 closed out
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Triggered by the irreducible-graph work landing (named join points, then Mode 2
and Mode 3 describe). Sources gained the two new describe-side files, the graph
classifier and the proposal; the existing three kept.

Three changes, grounded in the 13 mdl/executor findings since the last sync.

A FIFTH SHAPE at the end of the survival ordering: "means something else". The
other four all leave evidence — output that will not parse, a missing property, an
invented clause, vanished structure. This one parses, executes, yields a valid
model, drops nothing and invents nothing, and denotes a different program. No
automated signal can see it; only comparing behaviour finds it.

SOME DOCUMENTS CANNOT BE DESCRIBED FAITHFULLY AT ALL, which is a vocabulary limit
rather than a careless describer: MDL's `if` is single-entry/single-exit against
an arbitrary digraph, so the remedy is to extend the language, and per
Boehm-Jacopini one sub-class has no faithful rendering at any effort. The beat
earns its place by telling a reader whether to reach for a fix or a proposal.

VERIFICATION rewritten around the trap that let shape five survive: a round trip
that is a fixed point on the corpus you have is not evidence it is faithful,
because the describer's inference rule was reverse-engineered from that corpus and
agrees with it by construction — the disagreeing case has to be constructed. Plus
three measurement rules that each hid a defect until applied: compare identities
rather than counts; diff the whole corpus against a baseline binary (a refactor
must be byte-identical, a feature must move only its targets); algebra is not
behaviour.

Also removes the quoted "83 of 248" count — the area has since more than doubled
to 615, so the figure was simply wrong. The Do-not-duplicate line now says counts
are computed, per CLAUDE.md's "coverage is computed, never quoted".

Separately, three findings written 2026-09-13/14 used the shard filename
(mdl-executor) as their `area` where the other 613 use the path (mdl/executor),
so digest-status bucketed them into "(32 areas < 5)". Corrected in place before
using those counts to choose this run's scope. This is the THIRD occurrence —
the same correction was made on 2026-09-12 — and the repetition is the tell that
correcting is not fixing: check-findings validates that the field exists, not
that its value is in the vocabulary.

Two SYNC_LOG rows appended, one for the correction and one for the page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hifgRSawfaRWXS44YKtSJ
---
 .../fix-issue/findings/mdl-executor.jsonl     |  6 +-
 docs-wiki/SYNC_LOG.md                         |  2 +
 .../bug-patterns/describe-round-trip-gaps.md  | 81 +++++++++++++++----
 3 files changed, 69 insertions(+), 20 deletions(-)

diff --git a/.claude/skills/fix-issue/findings/mdl-executor.jsonl b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
index d490dadc9b..13ad0d576c 100644
--- a/.claude/skills/fix-issue/findings/mdl-executor.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
@@ -607,9 +607,9 @@
 {"area": "mdl/executor", "date": "2026-09-13", "symptom": "A workflow with `boundary event timer '\u2026'` (no interrupting / non interrupting) passes check and builds at 0 errors; the runtime then fails to start: `Class 'Workflows$TimerBoundaryEvent' could not be found`", "cause": "The bare form maps to `Workflows$TimerBoundaryEvent`, which exists in no cached 11.x runtime (only Interrupting/NonInterruptingTimerBoundaryEvent). mxbuild tolerates the unknown type. It was the documented syntax example", "file": "`mdl/executor/validate_workflow_refs.go` (`bareTimerBoundaryEventErrors`, MDL-WF07), `cmd/mxcli/syntax/features_workflow.go`", "insight": "**A type mxbuild accepts is not a type the runtime has.** Found only because a verification boot of an unrelated fix loaded it. When a grammar has a default branch that maps to a storage type, check that type against the runtime's class list, not against `mx check`", "fix": "Refuse the bare form on 11+ at check and exec, CREATE and every ALTER op that can carry a boundary event; update syntax help, skill table and the ako/mxcli#415 bug-test script to name the kind"}
 {"area": "mdl/executor", "date": "2026-09-13", "symptom": "A view entity whose association column is also declared as an attribute (`MeterRef: Trends.Meter` or `MeterRef: Trends.Meter.ID` beside `select m.ID as MeterRef`) passes `mxcli check`; `check -p` says 'OQL select has 1 columns but 2 attributes declared'; exec writes `Enumeration(Trends.Meter)` and mx check reports CE1613, or throws 'An error occurred when trying to set the Enumeration property' for the three-part form", "cause": "A bare qualified name parses as TypeEnumeration (the entity/enum ambiguity), and execCreateViewEntity converted it with convertDataType without asking what it names. The alias-to-attribute alignment skips association columns, so the declared attribute had no column and was compared against the next one", "file": "`mdl/executor/oql_view_associations.go` (`ValidateViewAttributeDeclarations` MDL080, `viewAttributeEntityTypeErrors`), `mdl/executor/cmd_entities.go` (`execCreateViewEntity`), `mdl/executor/validate.go`, `mdl/executor/validate_program.go`, `cmd/mxcli/lsp_diagnostics.go`", "insight": "**The TypeEnumeration/TypeEntity ambiguity has a consumer wherever a data type becomes a stored type, and view entity attributes were one nobody had listed.** Split the refusal by what it needs: an association column's alias and a three-part name are decidable from the script, so they belong in the no-project phase that exec's pre-check also runs; entity-vs-enum needs the project, so it goes in check -p AND the handler, because exec --no-check skips both phases. Verify the handler refusal by counting changed files, not by the error text", "fix": "Refuse in ValidateProgram/LSP (MDL080) and at the top of execCreateViewEntity before any backend call; report an attribute once"}
 {"area": "mdl/executor", "date": "2026-09-13", "symptom": "Three new MDL-WIDGET27 tests passed locally and failed in CI on the same commit: two reported the fallback remedy (\"move the entries into the widget body as container blocks\") instead of naming the container keyword, and the third found 0 violations where it wanted 1", "cause": "The tests resolved the widget through `LoadWidgetRegistry(fixtureProject(t))`, which reads `.def.json` files from `testdata/expr-checker/.mxcli/widgets/`. That directory is GITIGNORED — the definitions are derived, not tracked — so they exist for any developer who has ever run `mxcli widget docs` against the fixture (I generated them earlier in the same session, while investigating) and never exist on the runner. With no definition, `containerKeyword` returns \"\" and the two definition-dependent branches degrade exactly as designed: fallback wording, and silence for the scalar case", "file": "`mdl/executor/validate_widget_object_property_test.go` (`fixtureProjectWithDefs`)", "insight": "**A gitignored fixture makes a test environment-dependent in the one direction nobody checks** — the developer's tree is a superset of the runner's, so the test is green exactly where it is not being tested. The fix is to DERIVE the artifact from tracked inputs inside the test (`RefreshWidgetDefinitions` over the fixture's tracked `.mpk` files, into a temp copy, after removing any `.mxcli` the developer's tree carries), so local and CI see identical inputs. Reproduce by moving the gitignored directory aside before believing any diagnosis. **The sibling lesson is why this was not caught by the existing suite**: #999's test asserted `strings.Contains(msg, \"attribute\")` on a widget whose property is named `attributes`, so the property name alone satisfied it and the assertion passed with NO definition loaded — a substring assertion whose needle is a substring of the data it is meant to distinguish from proves nothing. Tightened to the remedy shape (`` `attribute <name> (…)` blocks ``) and verified with the derivation stubbed: all four then fail, where before only the three new ones did", "refs": []}
-{"area": "mdl-executor", "date": "2026-09-13", "symptom": "DESCRIBE silently deletes an ExclusiveMerge: describe -> exec leaves the microflow with fewer merge nodes than the stored graph, with no warning, no MDL-FLOW01 and mx check clean", "cause": "The nested describer walks straight through a merge with a single incoming path without emitting anything for it, so the rebuild has no reason to create it. Only two merge shapes were represented: a split's join point (rendered by `end if`) and a labelled error rejoin (`merge <label>`).", "file": "mdl/executor/cmd_microflows_show_merge.go", "fix": "droppedMergeWarnings() emits a describe-time warning for any ExclusiveMerge that is neither a split join point, nor a labelled error rejoin, nor has in-degree >= 2. Wired into both describe paths beside irreducibleGraphWarnings.", "insight": "The obvious rule (represented == the join point findSplitMergePoints pairs with a split) is WRONG on real code and produces a false positive on ordinary Marketplace microflows. findMergeForSplit needs a join common to ALL branches, so a split where one branch returns pairs with nothing -- yet its merge is still emitted as the continuation after `end split` and survives with its $ID intact (Administration.ManageMyAccount). The in-degree clause is what separates the two. Establish the rule by CORRELATING survival with structure over a corpus rather than reasoning from the describer's code: measuring merge $IDs before and after a round trip over 21 microflows gave in-degree=1 deleted 7 of 7, in-degree>=2 survived 6 of 7. The one exception is a merge lost to flattening in an irreducible graph, which MDL-FLOW01 already owns with a stronger message. Also: count-based comparison cannot tell 'preserved' from 'deleted and recreated' -- compare $IDs. And when scanning describe output for your own warning, grep a string unique to it: MDL-FLOW01's text also contains 'is not represented', which faked a false positive for one round of measurement."}
-{"area":"mdl-executor","date":"2026-09-13","symptom":"DESCRIBE renders a microflow whose branches cross as `c1 and c2` when the activity actually runs on `not(c1) or c2` — a program that always logs described as one that never does, with mx check clean","cause":"Nested if/then/else is single-entry/single-exit; a Mendix microflow is an arbitrary digraph. When an inner split's branch lands where an outer split's branch lands, the describer walks the graph as a tree and emits the conjunction of the guards along one path.","file":"mdl/executor/cmd_microflows_normalize.go","fix":"DESCRIBE MICROFLOW ... NORMALIZED (Mode 3): fold the branch guards into one condition via mdl/microflownorm and rewrite a COPY of the graph into the equivalent nested one, then let the existing describer render it. Refuses per-decision when the region holds an activity, a rule-based split, or genuinely interleaved branches.","insight":"Do not write a second describer for a second rendering mode — rewrite the GRAPH and reuse the one describer, or the two drift and every activity renderer is implemented twice. Two verification lessons. (1) A boolean simplifier needs a truth-table equivalence test over generated formulas, not per-rule unit tests: an unsound rewrite produces a pretty WRONG guard, which is the original bug from the other direction. Run it with a rule deliberately broken as the control — mine caught it at the first assignment. (2) Algebra is not behaviour: build the original and the microflow rebuilt from its normalized description side by side and compare return values over the whole input truth table on a real runtime. The rows that matter are the ones the OLD rendering got wrong, so make the fixture's return value distinguish them (a `log` activity is invisible to a test; a `$Result` string is not). Also: the fold leaves the entry merge with in-degree 1, which describe->exec would then silently delete, so splice it out in the transform — otherwise Mode 3's output does not describe the graph its own re-execution builds."}
+{"area": "mdl/executor", "date": "2026-09-13", "symptom": "DESCRIBE silently deletes an ExclusiveMerge: describe -> exec leaves the microflow with fewer merge nodes than the stored graph, with no warning, no MDL-FLOW01 and mx check clean", "cause": "The nested describer walks straight through a merge with a single incoming path without emitting anything for it, so the rebuild has no reason to create it. Only two merge shapes were represented: a split's join point (rendered by `end if`) and a labelled error rejoin (`merge <label>`).", "file": "mdl/executor/cmd_microflows_show_merge.go", "fix": "droppedMergeWarnings() emits a describe-time warning for any ExclusiveMerge that is neither a split join point, nor a labelled error rejoin, nor has in-degree >= 2. Wired into both describe paths beside irreducibleGraphWarnings.", "insight": "The obvious rule (represented == the join point findSplitMergePoints pairs with a split) is WRONG on real code and produces a false positive on ordinary Marketplace microflows. findMergeForSplit needs a join common to ALL branches, so a split where one branch returns pairs with nothing -- yet its merge is still emitted as the continuation after `end split` and survives with its $ID intact (Administration.ManageMyAccount). The in-degree clause is what separates the two. Establish the rule by CORRELATING survival with structure over a corpus rather than reasoning from the describer's code: measuring merge $IDs before and after a round trip over 21 microflows gave in-degree=1 deleted 7 of 7, in-degree>=2 survived 6 of 7. The one exception is a merge lost to flattening in an irreducible graph, which MDL-FLOW01 already owns with a stronger message. Also: count-based comparison cannot tell 'preserved' from 'deleted and recreated' -- compare $IDs. And when scanning describe output for your own warning, grep a string unique to it: MDL-FLOW01's text also contains 'is not represented', which faked a false positive for one round of measurement."}
+{"area": "mdl/executor", "date": "2026-09-13", "symptom": "DESCRIBE renders a microflow whose branches cross as `c1 and c2` when the activity actually runs on `not(c1) or c2` \u2014 a program that always logs described as one that never does, with mx check clean", "cause": "Nested if/then/else is single-entry/single-exit; a Mendix microflow is an arbitrary digraph. When an inner split's branch lands where an outer split's branch lands, the describer walks the graph as a tree and emits the conjunction of the guards along one path.", "file": "mdl/executor/cmd_microflows_normalize.go", "fix": "DESCRIBE MICROFLOW ... NORMALIZED (Mode 3): fold the branch guards into one condition via mdl/microflownorm and rewrite a COPY of the graph into the equivalent nested one, then let the existing describer render it. Refuses per-decision when the region holds an activity, a rule-based split, or genuinely interleaved branches.", "insight": "Do not write a second describer for a second rendering mode \u2014 rewrite the GRAPH and reuse the one describer, or the two drift and every activity renderer is implemented twice. Two verification lessons. (1) A boolean simplifier needs a truth-table equivalence test over generated formulas, not per-rule unit tests: an unsound rewrite produces a pretty WRONG guard, which is the original bug from the other direction. Run it with a rule deliberately broken as the control \u2014 mine caught it at the first assignment. (2) Algebra is not behaviour: build the original and the microflow rebuilt from its normalized description side by side and compare return values over the whole input truth table on a real runtime. The rows that matter are the ones the OLD rendering got wrong, so make the fixture's return value distinguish them (a `log` activity is invisible to a test; a `$Result` string is not). Also: the fold leaves the entry merge with in-degree 1, which describe->exec would then silently delete, so splice it out in the transform \u2014 otherwise Mode 3's output does not describe the graph its own re-execution builds."}
 {"area":"mdl/executor","date":"2026-09-13","symptom":"CATALOG.GRAPH_CYCLES returns 0 rows on a project whose CATALOG.GRAPH_MODULE_COUPLING lists mutual Source/Target module pairs, so a user reads 'no circular dependencies' from a table that was never computed (mendixlabs/mxcli#1060)","cause":"graph_cycles_data is written only by the graph-analysis pass (REFRESH CATALOG COMMUNITIES), while graph_module_coupling is a plain SQL view over refs that any full-mode catalog answers. GRAPH_CYCLES and its four siblings appeared in neither fullOnlyTables nor sourceOnlyTables, so no warning fired; and the recorded build mode is only fast/full/source, so a communities-augmented cache is indistinguishable from a plain full one — which also let a later `refresh catalog full` drop the graph tables silently","file":"`mdl/executor/cmd_catalog.go` (`communitiesOnlyTables`, `warnIfCatalogModeInsufficient`, `tableRequiredMode`, `carryGraphAnalysis`, `cachedCatalogInfo`), `mdl/catalog/catalog.go` (`MetaGraphAnalysis`), `mdl/catalog/builder_graph.go`, `mdl/catalog/builder.go`","insight":"**An empty analytic table is only an answer once something distinguishes 'computed and empty' from 'never computed'.** The mode ladder could not carry that bit: fast/full/source is a LEVEL, and the graph pass is orthogonal to it (it augments any level), so folding it in makes 'source' and 'full+graph' incomparable — it has to be a flag, not a rank. Guard it by MEASUREMENT, not a second hand-written list: run the pass on a synthetic refs graph and diff which tables went from empty to non-empty, then compare that set to the classification map. Shape the fixture so every table fills — two clusters for the community split and the integration surface, one MUTUAL pair for cycles — or the guard silently skips the very table the bug was about","fix":"Record MetaGraphAnalysis/MetaGraphResolution when the pass runs; classify the six tables in communitiesOnlyTables and warn 'requires refresh catalog communities (not run for this catalog)'; report it in SHOW CATALOG STATUS; re-run the pass when a full rebuild replaces a cache that had it"}
-{"area":"mdl-executor","date":"2026-09-14","symptom":"DESCRIBE flattens a microflow whose branches cross into nested ifs that mean something else, and warns MDL-FLOW01 'must not be re-executed' instead of describing it","cause":"Nested if/then/else is single-entry/single-exit. A merge reached by branches of two different splits has no place in a tree, so the describer walked past it and emitted the conjunction along one path.","file":"mdl/executor/cmd_microflows_show_crossed.go","fix":"Mode 2: label the shared-suffix entry AND the split's post-dominator, emit `join <label>` at every branch end, then declare each merge as a top-level section after the traversal. MDL-FLOW01 is retired per decision when the description actually declared the merge.","insight":"Three traps, each of which produced plausible-looking output. (1) A crossed merge must be emitted the OPPOSITE way from an error-rejoin merge -- rejoin is DECLARED where the traversal meets it, crossed is JOINED by each branch and declared once afterwards -- so the label alone cannot drive emission; carry a crossed set beside the names. (2) Emit the join BEFORE the visited guard: arriving twice is what 'crossed' MEANS, and the guard silently swallows the second branch's join, leaving that path falling off the end. (3) Retire a warning on what was EMITTED, not on what was labelled. An inheritance split has its own traversal that walks through a labelled merge without emitting a join, so the label goes unused and the reader still gets the nested rendering -- suppressing on the label alone silenced MDL-FLOW01 on Administration.ManageMyAccount, whose description is byte-identical with and without the feature. That forced warnings to be computed AFTER the body instead of before it. Method: keep a baseline binary (git stash -u; build) and diff `describe` over every microflow in a corpus -- the refactor step should be byte-identical (it was, 18 of 18) and the feature step should change only the microflows it targets (2 of 18). Anything else changing is the bug."}
+{"area": "mdl/executor", "date": "2026-09-14", "symptom": "DESCRIBE flattens a microflow whose branches cross into nested ifs that mean something else, and warns MDL-FLOW01 'must not be re-executed' instead of describing it", "cause": "Nested if/then/else is single-entry/single-exit. A merge reached by branches of two different splits has no place in a tree, so the describer walked past it and emitted the conjunction along one path.", "file": "mdl/executor/cmd_microflows_show_crossed.go", "fix": "Mode 2: label the shared-suffix entry AND the split's post-dominator, emit `join <label>` at every branch end, then declare each merge as a top-level section after the traversal. MDL-FLOW01 is retired per decision when the description actually declared the merge.", "insight": "Three traps, each of which produced plausible-looking output. (1) A crossed merge must be emitted the OPPOSITE way from an error-rejoin merge -- rejoin is DECLARED where the traversal meets it, crossed is JOINED by each branch and declared once afterwards -- so the label alone cannot drive emission; carry a crossed set beside the names. (2) Emit the join BEFORE the visited guard: arriving twice is what 'crossed' MEANS, and the guard silently swallows the second branch's join, leaving that path falling off the end. (3) Retire a warning on what was EMITTED, not on what was labelled. An inheritance split has its own traversal that walks through a labelled merge without emitting a join, so the label goes unused and the reader still gets the nested rendering -- suppressing on the label alone silenced MDL-FLOW01 on Administration.ManageMyAccount, whose description is byte-identical with and without the feature. That forced warnings to be computed AFTER the body instead of before it. Method: keep a baseline binary (git stash -u; build) and diff `describe` over every microflow in a corpus -- the refactor step should be byte-identical (it was, 18 of 18) and the feature step should change only the microflows it targets (2 of 18). Anything else changing is the bug."}
 {"area": "mdl/executor", "date": "2026-09-13", "symptom": "describe page -> create or replace page broke a button's icon. An icon into an IMAGE collection came back as `Icon: 'DesignSystem.Icons_SVG.edit'` and the build failed [CE1613] \"The selected custom icon 'DesignSystem.Icons_SVG.edit' no longer exists.\" A GLYPH icon produced no describe output at all -- no clause, no comment -- and replay DELETED it at exit 0.", "cause": "Mendix stores three icon elements and two put a qualified name under the same BSON key: Forms$IconCollectionIcon{Image}->CustomIcons$CustomIcon, Forms$ImageIcon{Image}->Images$Image, Forms$GlyphIcon{Code}. extractIconRef read `Image` off whichever element was there and threw the $Type away, and the page builder writes Forms$IconCollectionIcon unconditionally -- so the two named variants were spelled identically on the way out and collapsed into one on the way back in.", "file": "mdl/executor/cmd_pages_describe_output.go (extractButtonIcon, widgetIconMDL, widgetIconNote), mdl/executor/cmd_pages_describe.go (rawWidget.IconType/IconCode), mdl/executor/cmd_pages_describe_parse.go; tests mdl/executor/cmd_pages_describe_icon_test.go", "insight": "The identical three-variant defect was fixed in NAVIGATION eight days earlier (2026-09-05, same area file) and the page path never received it -- so the cheapest possible diagnosis was `grep MenuIconKindOf`, and the fix reuses that resolver rather than adding a second one. **Generalisable: when a fix teaches a layer to distinguish polymorphic variants, grep for every OTHER reader of the same element.** The find was one `git grep Forms\\$ImageIcon` away all along. Two things the report got understandably wrong and that the fix depends on getting right: it is not about third-party vs native collections (a third-party ICON collection round-trips fine -- and CE1613 naming the reference is itself proof the name was never a custom icon, since mxbuild would otherwise have resolved it), and the reported image-icon case is the CHEAPER half -- the glyph case is silent on both sides, so nothing in the output even hints at the loss. **Measure the silence, not the wrong answer**: `grep -c icon` over describe output of a stock marketplace project's FeedbackModule pages returned 0 before and 3 after, which is the only form the glyph bug has. The note has to fire on an UNRECOGNISED $Type too, not a known-bad list, or the next variant Mendix adds is dropped the same way. Controls that matter: an icon-collection icon must still emit a bare `Icon:` and NO note (else the fix passes by flagging everything), and an iconless button must emit neither. No .mdl repro is possible -- mxcli cannot author an image or glyph icon on a button, so the input to the round trip cannot be constructed in MDL; the reproduction is a stored-widget map in the unit test. Also observed in passing and NOT fixed: a nameless `statictext` makes describe output unparseable (pre-existing, confirmed against the base binary), and NavigationList item / DropDownButton icons are never read at all, so they are dropped as silently as the glyph was.", "refs": ["#1059", "#1008", "#602"], "ce": ["CE1613"]}
 {"area": "mdl/executor", "date": "2026-09-13", "symptom": "Follow-on to #1059: a widget's image and glyph icons were readable but unwritable, so describe -> exec could only be made honest (a `-- NOT re-executable` note), not lossless. Authoring them needed the kind to reach the element $Type through grammar, AST, visitor, builder and BOTH engines.", "cause": "Three separate vocabularies for the same three Mendix icon elements: types.MenuIconKind (navigation), pages.IconType (the page model's own three-value enum), and a bare string in the widget property map. The page path had no kind at all, so it could not express one.", "file": "mdl/grammar/domains/MDLPage.g4 (widgetIconV3), mdl/ast/ast_page_v3.go (WidgetIcon), mdl/visitor/visitor_page_v3.go (buildWidgetIconV3), mdl/executor/cmd_pages_builder_v3_widgets.go (buildWidgetIcon), mdl/backend/modelsdk/widget_write.go (iconToGen), sdk/mpr/writer_widgets_display.go (buildWidgetIconBson), mdl/executor/validate_icon_refs.go, mdl/executor/validate_glyph_codes.go", "insight": "**Delete the second vocabulary as part of the fix, not after it.** pages.IconType existed for exactly the same three kinds as types.MenuIconKind and had drifted to a different value set; replacing it (2 call sites) is what made the writers a dispatch rather than an inference. A feature that adds a third copy would have re-created the bug in a new place. **The pre-existing tests of the OLD feature are the safety net for the new one**: MDL078's menu tests caught a python replace of mine that silently no-opped (anchor did not match, no assert), which nothing else would have. Always assert on the replacement count when editing by script. **Measure the premise, don't reason by analogy** — extending MDL078 to widget glyphs assumed mxbuild resolves a widget glyph the same way it resolves a menu one. It does, measured: `Icon: glyph 57562` fails `mxbuild --target=deploy` with `System.InvalidOperationException: Sequence contains no matching element` — but it names the **page**, not a layout, so the rule's own message was wrong and had to be corrected from the measurement. **The reference check had the mirror-image bug waiting**: resolving an image reference against the ICON collections reports a correct name as a typo, which is the same conflation pointed the other way — per-kind resolution plus an `otherKindHint` naming the remedy. **An empty listing is 'could not establish', not 'none'** — each half of the index is independent, so a project that yields icon collections but no image collections still resolves what it can. Verified on 11.13.0: all three authored, mx check 0 errors, deploy BUILD SUCCEEDED, right $Type on disk; controls reproduce CE1613 (image written without `image`) and the glyph build failure. Corpus sweep 531 clean.", "refs": ["#1059", "#1008", "#602"], "ce": ["CE1613"]}
diff --git a/docs-wiki/SYNC_LOG.md b/docs-wiki/SYNC_LOG.md
index 57a645d1dc..cb88aa8d4a 100644
--- a/docs-wiki/SYNC_LOG.md
+++ b/docs-wiki/SYNC_LOG.md
@@ -58,3 +58,5 @@ not capture, because sources are upstream of the commit.
 | 2026-09-12 | bug-patterns/check-mxbuild-drift.md | .claude/skills/fix-issue/findings/mdl-executor.jsonl + mdl-backend.jsonl + mdl-grammar.jsonl (55 records dated after the last sync), mdl/executor/validate_program.go, docs/11-proposals/PROPOSAL_check_mxbuild_gap_heuristics.md | **Re-sync.** 90 mdl/executor findings had landed since 2026-08-31 and this was the dominant class. Three new sections. (1) *Three answers, not two*: a check needs resolved / not-resolved / **could not establish**, where exec needs two — turning "I could not look" into "your attribute is missing" is a false error that blocks a script which builds cleanly, and the guards are non-obvious (a module the script creates; an EMPTY listing meaning the backend could not answer). Includes that `check` normally runs with **no project**, which is also the CI default, and the allow-list/deny-list choice for type-keyed rules. (2) *Don't model what you can run*: the mutator-probe technique — run the real setter against a throwaway deep copy whose Save is refused — as the strongest form of the existing "both passes or neither". (3) *The instruments lie in specific ways*: one error per microflow hides the one being measured; a load failure suppresses the error-count line while still exiting non-zero (third occurrence); the corpus sweep has a noise floor (11 of 515 scripts nondeterministic) and is blind to a misparse, since it diffs diagnostics. Also added a remedy beat — two rules shipped whose `Fix:` line broke a working project |
 | 2026-09-12 | bug-patterns/widget-type-object-drift.md | .claude/skills/fix-issue/findings/ mdl-executor.jsonl + cmd-mxcli.jsonl + sdk.jsonl + mdl-backend.jsonl (49 CE0463/CE3637 records across the corpus), .claude/skills/diagnose-ce0463.md, .claude/skills/debug-bson.md, sdk/widgets/templates/README.md, sdk/mpr/writer_widgets.go | **Re-sync**, first since 4e185f73 and the oldest page in the category. `sources:` **added** diagnose-ce0463.md (written after the last sync; debug-bson.md's own header defers to it) and replaced the bare findings *directory* with the four shards that actually carry the records. The page had none of the framing that makes the class tractable: that **two unrelated bugs wear this error** (package upgraded after authoring — not an mxcli defect — versus authored-fresh-and-wrong) and that the two controls separating them are not optional; that `mxcli docker check` runs `mx update-widgets` first and so reports 0 errors on a project that has a CE0463; that a difference from the reference is not a cause (25 differences, 3 patched in isolation, none moved the count). Added the two new findings' contribution: evaluate a visibility rule against the configuration that will be WRITTEN rather than the one the package declares, and compare enum values against the .mpk's `enumerationValue` keys, not captions |
 | 2026-09-12 | (no page) findings `area` normalisation | .claude/skills/fix-issue/findings/mdl-executor.jsonl, mdl-backend.jsonl | Not a sync. Two records written 2026-09-10 used the SHARD FILENAME (`mdl-executor`, `mdl-backend`) as their `area` where all 677 others use the path (`mdl/executor`, `mdl/backend`). `make check-findings` passes either way — it requires the field, not a vocabulary — so `make digest-status` had silently bucketed both into its "(32 areas < 5)" row. Corrected in place before using those counts to choose this run's scope |
+| 2026-09-14 | (no page) findings `area` normalisation | .claude/skills/fix-issue/findings/mdl-executor.jsonl | Not a sync. **Third occurrence** of the slip recorded on 2026-09-12: three records written 2026-09-13/14 used the SHARD FILENAME (`mdl-executor`) as their `area` where the other 613 use the path (`mdl/executor`), so `make digest-status` bucketed them into "(32 areas < 5)" and showed mdl/executor as having moved 10 findings rather than 13. Corrected in place before using those counts to choose this run's scope — same remedy as last time, which is the tell that the correction is not the fix: `make check-findings` validates that the field EXISTS, not that its value is in the vocabulary, so nothing stops occurrence four |
+| 2026-09-14 | bug-patterns/describe-round-trip-gaps.md | .claude/skills/fix-issue/findings/mdl-executor.jsonl (the 13 records dated after the last sync, of which 11 touch a describe path), mdl/executor/cmd_workflows.go, mdl/executor/cmd_pages_describe_pluggable.go, mdl/executor/cmd_microflows_show_crossed.go, mdl/executor/cmd_microflows_normalize.go, mdl/microflowgraph/structure.go, docs/11-proposals/PROPOSAL_structured_microflow_description.md | **Re-sync**, triggered by mendixlabs/mxcli#923 closing out (named join points, then Mode 2 and Mode 3 describe). `sources:` **added** the two new describe-side files, the graph classifier, and the proposal; the existing three kept. Three changes. (1) A **fifth shape** at the end of the survival ordering — *means something else*: parses, executes, valid model, drops nothing, invents nothing, and denotes a different program, so no automated signal can see it and only a behaviour comparison finds it. (2) A new framing beat: **some documents cannot be described faithfully at all**, which is a vocabulary limit rather than a careless describer — MDL's `if` is single-entry/single-exit against an arbitrary digraph, so the remedy is to extend the language, and per Böhm–Jacopini one sub-class has no faithful rendering at any effort. Tells a reader whether to reach for a fix or a proposal. (3) The verification section rewritten around the trap that let shape five survive: **a fixed point on the corpus you have is not evidence of fidelity**, because a describer's inference rule was reverse-engineered from that corpus and agrees with it by construction — the disagreeing case must be CONSTRUCTED. Plus three measurement rules that each hid a defect until applied (compare identities not counts; diff the whole corpus against a baseline binary, where a refactor must be byte-identical and a feature must move only its targets; algebra is not behaviour). Also **removed the quoted "83 of 248" count** — the area has since more than doubled, and the Do-not-duplicate line now says counts are computed, per CLAUDE.md's "coverage is computed, never quoted". Added [[flow-graph-geometry]] and [[silent-property-drop]] cross-refs |
diff --git a/docs-wiki/bug-patterns/describe-round-trip-gaps.md b/docs-wiki/bug-patterns/describe-round-trip-gaps.md
index 3cf4ff73ab..f834559e52 100644
--- a/docs-wiki/bug-patterns/describe-round-trip-gaps.md
+++ b/docs-wiki/bug-patterns/describe-round-trip-gaps.md
@@ -1,25 +1,32 @@
 ---
 title: DESCRIBE Round-Trip Gaps
 category: bug-pattern
-last-synced: ced830e0
+last-synced: 888e78cf
 sources:
   - .claude/skills/fix-issue/findings/mdl-executor.jsonl
   - mdl/executor/cmd_workflows.go
   - mdl/executor/cmd_pages_describe_pluggable.go
+  - mdl/executor/cmd_microflows_show_crossed.go
+  - mdl/executor/cmd_microflows_normalize.go
+  - mdl/microflowgraph/structure.go
+  - docs/11-proposals/PROPOSAL_structured_microflow_description.md
 ---
 
 > **Do not duplicate**: the per-construct fix recipes live in the findings
 > (`grep -l describe .claude/skills/fix-issue/findings/*.jsonl`), the MDL syntax
-> in `docs/01-project/MDL_QUICK_REFERENCE.md`, and the round-trip requirement in
-> CLAUDE.md's PR checklist. This page describes the failure class only.
+> in `docs/01-project/MDL_QUICK_REFERENCE.md`, the round-trip requirement in
+> CLAUDE.md's PR checklist, and the irreducible-graph design in
+> [its proposal](../../docs/11-proposals/PROPOSAL_structured_microflow_description.md).
+> This page describes the failure class only. Counts are computed
+> (`make digest-status`, or grep the findings), never quoted here.
 
 ## What this is
 
 `DESCRIBE` is a **second implementation of MDL**, written in the opposite
 direction and validated by nothing. Every construct has a writer (MDL → BSON)
 and a describer (BSON → MDL) built separately, and no mechanism forces them to
-agree. This is the single largest class of defect in the executor: **83 of the
-248 findings** for `mdl/executor` involve a describe path.
+agree. It is the single largest class of defect in the executor — roughly two
+findings in five for `mdl/executor` touch a describe path.
 
 The reason it accumulates is that the write path has an oracle and the read path
 does not. `mxbuild` validates the *model*, and it never sees DESCRIBE output at
@@ -34,7 +41,7 @@ exactly when someone is trying to reuse work.
 
 ## How it fits
 
-**Four shapes, in increasing order of how long they survive.**
+**Five shapes, in increasing order of how long they survive.**
 
 *Won't parse.* The emitter produces text MDL's own grammar rejects — a
 reserved-word name emitted bare, an internal spelling (`call_microflow X`,
@@ -60,10 +67,30 @@ formatter renders an enum whose fallback value is also a legal authored value,
 read-back cannot invert the write; render only the values that are never
 defaults.
 
-*Destroys.* Rarest and worst — the round trip removes structure rather than
-losing a field. A list view's specialization templates went 4 → 0; an accordion
-group's contents vanished; a loop body was emitted empty because an annotation
-sat to its left. `mx check` reported 0 errors on both sides of each.
+*Destroys.* The round trip removes structure rather than losing a field. A list
+view's specialization templates went 4 → 0; an accordion group's contents
+vanished; a loop body was emitted empty because an annotation sat to its left.
+`mx check` reported 0 errors on both sides of each.
+
+*Means something else.* The worst, and the one that hides longest, because every
+other shape leaves evidence. Here the description parses, executes, yields a
+valid model, drops nothing and invents nothing — and **denotes a different
+program**. A microflow whose activity ran on `¬c1 ∨ c2` described as `c1 ∧ c2`;
+with the reporter's actual expressions, one that always logged described as one
+that never did. Nothing in the toolchain can see it: there is no missing field to
+notice and no error to raise, so the only detector is someone comparing
+behaviour.
+
+**Some documents cannot be described faithfully at all**, and that is a different
+diagnosis from a careless describer. MDL's `if` is a single-entry/single-exit
+block; a Mendix microflow is an arbitrary directed graph. When branches cross, no
+amount of care in the describer helps, because the target language cannot spell
+the graph — the remedy is to **extend the language** (named join points) rather
+than to fix a bug. One sub-class provably has no faithful rendering at any
+effort: per Böhm–Jacopini, nesting genuinely interleaved branches requires either
+duplicating an activity the user drew once or inventing a boolean they never
+wrote, and both are model rewrites rather than descriptions. Recognising that a
+gap is a *vocabulary* limit tells you whether to reach for a fix or a proposal.
 
 **The defect is usually the copy, not the case.** Describers get written
 per-widget and per-container, so one lookup exists four or five times and some of
@@ -71,19 +98,36 @@ the copies are wrong. Patching the switch named in the report leaves the others
 drift again. A datasource means the same thing wherever it sits; so does an
 action slot, and so does a text template. The fix that holds is one reader and one
 renderer, with the type set taken from `generated/metamodel` rather than from the
-copies.
+copies. The same logic applies to a second *rendering mode*: build it by rewriting
+the graph into one the existing describer already handles, never by writing a
+second describer, or every activity renderer exists twice and drifts.
 
 **Fixing one half is worse than the bug.** Where a describer has two defects at
 once — say, quoting *and* a missing property — shipping the quoting fix alone
 turns unparseable output into output that parses cleanly while silently dropping
 something. That is strictly worse: a wrong page that validates.
 
-**The round trip is the only sound test**, and it has to be measured against the
-model rather than the text. A describe-to-describe text diff matched exactly on a
-page that had lost its datasource. `mx check` on the source proves nothing,
-because the lossy model is valid. Counting failures before and after hid an
-equal-sized swap of which pages failed. What works: describe → exec → describe
-byte-identical, plus `mx check` on the *rebuilt* model.
+**A round trip that is a fixed point on the corpus you have is not evidence that
+it is faithful.** This is the trap that makes the *means something else* shape
+survive. Where a describer rests on an inference rule — "an empty error handler
+means the path falls through to here" — the rule was reverse-engineered from the
+corpus, so the corpus agrees with it by construction. The test that matters is one
+where the stored document means something *other* than the rule assumes, and you
+have to **construct** it: repoint one pointer in a copy and re-describe. The real
+microflow that motivated all of this round-tripped correctly by luck.
+
+Three further measurement rules, each of which hid a defect until it was applied:
+
+- **Compare identities, not counts.** A count cannot tell "preserved" from
+  "deleted and recreated", and it hid an equal-sized swap of which pages failed.
+- **Diff the whole corpus against a baseline binary.** Keep a pre-change build,
+  describe every document with both, and diff. A pure refactor must come out
+  byte-identical; a feature must change only the documents it targets. Anything
+  else moving is the bug — this is what caught a warning being retired on the
+  strength of a label nothing ever emitted.
+- **Algebra is not behaviour.** When a change reasons about equivalence, the
+  proof is two documents side by side on a real runtime over the whole input
+  space, not a convincing derivation. See `.claude/skills/verify-in-runtime.md`.
 
 One consequence worth knowing: other code re-parses DESCRIBE output.
 `use building block … (datasource: …)` matches against the rendered form, so
@@ -94,7 +138,10 @@ callers of the emitter before changing what it emits.
 
 - [fix-issue findings](../../.claude/skills/fix-issue/findings/) — the per-construct
   recipes; `grep -l describe *.jsonl` reaches this class
+- [[flow-graph-geometry]] — the sibling class where the generated graph's
+  coordinates and wiring are wrong, rather than its rendering
 - [[widget-type-object-drift]] — the neighbouring class where the *written* widget
   is wrong rather than the described one
+- [[silent-property-drop]] — the write-side twin of *silently drops*
 - `.claude/skills/verify-in-runtime.md` — for the cases where neither the model
   nor its description is the thing that is wrong

From 60ff7f7c224c66d018c4ec51569b9f78c8ac5156 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 14 Sep 2026 11:58:49 +0000
Subject: [PATCH 02/24] docs(plans): removal plan for the legacy engine
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 2026-06-05 adoption plan stops at the cutover and still reads as though
legacy were the default. This covers what it deferred to "Phase 5 — Cleanup"
and never specified.

The plan's whole job is refusing to treat one name as one job. Retiring the
legacy ENGINE (mdl/backend/mpr, 2,808 lines, five production importers) is
small, unblocked and reversible. Retiring the legacy SERIALIZER underneath it
(sdk/mpr, 41,243 lines) is fifteen times larger and gated on consumers that
never touched the engine seam — the public api/ package, the MCP backend, eight
cmd/mxcli commands.

One measurement reorders the sequence. The earlier plan deferred the
mongo-driver v1->v2 migration "to the cutover", reasoning the engines could
coexist on different module paths. They can, but the split does not fall on the
engine flag: modelsdk/ is 117 files v2 and 0 v1; sdk/mpr is 113 v1 and 0 v2; the
adapter between them straddles both. So deleting the legacy backend moves the
driver migration NOT AT ALL — what unblocks v2 is deleting sdk/mpr, which is
behind a product decision about the public API. Sequenced the other way, phase
one looks like it owes a 41k-line migration and never starts.

Everything in the "already true" section was verified rather than inherited: no
"not supported by the modelsdk engine" message remains; errUnimplemented cannot
fire on a default run (17 of 19 methods measured dead, the 2 live ones
implemented, the set pinned by a passing test); the dependency runs one way
(modelsdk does not import the legacy backend — a grep says it does and is
matching a comment); legacy is strictly weaker.

Also records what goes stale on removal, including that the modelsdk package doc
still describes the engine as a read slice whose write methods are unimplemented
and whose CLI prints a read-only warning — three false clauses, the warning
having been gone for some time.

Phases 3 and 4 are deliberately NOT scheduled: they need an answer about whether
anything outside this repository depends on api/, which is a maintainer question
rather than a measurement.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hifgRSawfaRWXS44YKtSJ
---
 docs/plans/2026-09-14-retire-legacy-engine.md | 172 ++++++++++++++++++
 1 file changed, 172 insertions(+)
 create mode 100644 docs/plans/2026-09-14-retire-legacy-engine.md

diff --git a/docs/plans/2026-09-14-retire-legacy-engine.md b/docs/plans/2026-09-14-retire-legacy-engine.md
new file mode 100644
index 0000000000..8ee1c58088
--- /dev/null
+++ b/docs/plans/2026-09-14-retire-legacy-engine.md
@@ -0,0 +1,172 @@
+# Implementation Plan — Retire the legacy engine
+
+**Date:** 2026-09-14
+**Status:** Draft plan
+**Continues:** [`2026-06-05-adopt-modelsdk-engine.md`](2026-06-05-adopt-modelsdk-engine.md), which
+stops at the cutover. That plan still reads as though `legacy` were the default; it is not, and has
+not been since the codec engine took over. This plan covers what the earlier one deferred to
+"Phase 5 — Cleanup" and never specified.
+**Related:** [ADR-0004](../13-decisions/0004-full-codec-engine.md) (route all document types through
+the codec), [ADR-0002](../13-decisions/0002-backend-abstraction.md) (the seam this all hangs off).
+
+---
+
+## 1. The plan in one paragraph
+
+Retiring the legacy engine is **three independent removals wearing one name**, and the whole value
+of writing this down is refusing to treat them as one job. Deleting the legacy *backend*
+(`mdl/backend/mpr`, 2,808 lines) is small, unblocked, and reversible. Deleting the legacy
+*serializer* underneath it (`sdk/mpr`, 41,243 lines) is fifteen times larger and is gated on
+migrating consumers that never touched the engine seam at all — the public `api/` package, the MCP
+backend, eight `cmd/mxcli` commands. The mongo-driver v1→v2 migration the earlier plan promised at
+cutover is **gated on the second, not the first**, which is the opposite of what that plan assumed.
+Phase 1 can start today; Phases 2 and 3 need decisions that are not this plan's to make.
+
+## 2. Why this is not one job (the measurement that reorders everything)
+
+The 2026-06-05 plan deferred the tree-wide driver migration "to the cutover", on the reasoning that
+the two engines could coexist because "v1 and v2 are different module paths". They can, and they
+still do. But the split does not fall where that plan implies:
+
+| Package | mongo-driver v1 | v2 | What it is |
+|---|---|---|---|
+| `modelsdk/` | **0** | **117** | the codec engine |
+| `sdk/mpr` | **113** | **0** | the legacy serializer |
+| `mdl/backend/modelsdk` | 44 | 45 | the adapter where the two meet |
+| `mdl/executor` | 17 | 5 | |
+
+The driver split maps almost exactly onto the **serializer** split, not onto the engine flag. The
+codec is already wholly on v2; `sdk/mpr` is wholly on v1; the adapter straddles both because it
+converts between semantic types and gen documents. So **deleting the legacy backend does not move
+the driver migration at all** — what unblocks v2 is deleting `sdk/mpr`, and that is Phase 3, behind
+a decision about the public API.
+
+Stating this is the point of the plan. Sequenced the other way round, Phase 1 looks like it owes a
+41k-line migration and never gets started.
+
+## 3. What is already true (verified 2026-09-14, not assumed)
+
+Every one of these was checked rather than inherited from the earlier plan:
+
+- **No feature falls back to legacy.** No "not supported by the modelsdk engine" message exists
+  anywhere in the tree. The last five widget gaps are closed
+  (`mdl/backend/modelsdk/widget_write_legacy_gaps.go` records which were real: the name-based scan
+  said twenty-three, the reachable set was five, and one of those five turned out to be a Mendix
+  type that does not exist).
+- **`errUnimplemented` cannot fire on a default run.** Of 19 unported `FullBackend` methods, a
+  per-method build probe found 17 dead and 2 live; the live pair is implemented and the dead set is
+  pinned by `mdl/backend/modelsdk/unimplemented_reachability_test.go`, which passes.
+- **The dependency runs one way.** `mdl/backend/modelsdk` does not import `mdl/backend/mpr`; its
+  reader is `modelsdk/mpr`. (A grep says otherwise — it matches a comment. Check the import block.)
+- **Legacy is strictly weaker.** Rules, menus, layouts, message definitions and regular expressions
+  all refuse on it.
+- **The legacy backend has five production importers**: `cmd/mxcli/engine.go` (the factory seam),
+  `mdl/repl/repl.go`, `mdl/enginecompare/compare.go`, and two `examples/`. Plus six test files.
+
+## 4. Phases
+
+### Phase 1 — Delete the legacy backend and its flag *(Effort: S, Risk: Low)*
+
+Everything in §3 says this is unblocked. It is the phase that delivers the stated goal.
+
+1. Remove `engineLegacy` and `engineCompare` from `cmd/mxcli/engine.go`; the flag and
+   `MXCLI_ENGINE` become either absent or a one-value no-op (see §5, decision A).
+2. Delete `mdl/backend/mpr/` and its tests.
+3. Delete `mdl/enginecompare/` and the `engine-diff` make target. The package compares two engines
+   and has no meaning with one; its own header still describes write comparison as "Phase 2", which
+   never landed.
+4. Drop the `engines` matrix leg from `.github/workflows/nightly.yml`. Its comment already says
+   *"drop this line only together with the engine itself"* — this is that moment. Per-push CI
+   already runs modelsdk alone.
+5. Repoint the two `examples/` and the six test files at the codec backend.
+6. **`mdl/repl.New()` hardcodes `mprbackend.New()` as its factory default.** Not a live bug —
+   `cmd/mxcli/main.go:171` overrides it immediately — but it must go with the package, and a
+   caller that forgets to override should not silently get a deleted engine.
+
+**Done when**: `grep -r "MXCLI_ENGINE=legacy"` returns nothing outside history, the full gate passes,
+and the doctype corpus runs green on the one remaining engine.
+
+**Reversibility**: total, until Phase 3. `sdk/mpr` is untouched and every deleted file is one
+`git revert` away.
+
+### Phase 2 — Fix what goes stale the moment legacy leaves *(Effort: S, Risk: Low)*
+
+These currently misdescribe the engine and would become actively false, so they belong with Phase 1
+rather than after it:
+
+- `mdl/backend/modelsdk`'s **package doc still says the engine is a read slice**: *"Phase 1 … is a
+  READ slice … Write methods are NOT implemented yet — callers must not rely on them persisting;
+  the CLI prints a read-only warning when this engine is selected."* All three clauses are false,
+  and the read-only warning no longer exists in the code.
+- The 2026-06-05 plan needs a status line pointing here; it reads as current and is not.
+- `PROPOSAL_backend_strategy.md` is still `status: draft` from 2026-05-31 and describes a
+  multi-backend future in which legacy is one of the backends.
+- CLAUDE.md's `--engine` line, and the flag's help text.
+
+### Phase 3 — Decide the fate of `sdk/mpr` *(Effort: L, Risk: Med — NOT scheduled here)*
+
+This is where the size is, and this plan deliberately does not schedule it: **it is a product
+decision about the public API, not a cleanup.**
+
+`sdk/mpr` is 41,243 lines and has consumers that never routed through the engine seam:
+
+| Consumer | Why it matters |
+|---|---|
+| `api/` (9 files, 3,287 lines) | the public fluent API — `modelsdk.Open` / `OpenForWriting` |
+| `mdl/backend/mcp` | a **shipped, live backend**; breaking it breaks Studio Pro integration |
+| 8 `cmd/mxcli` commands | `bson dump`/`compare`/`discover`, `extract-templates`, `new`, … — these hold a concrete reader on purpose |
+| `examples/`, `scripts/mprsnapshot` | |
+
+Three options, and the answer is not obvious:
+
+- **(a) Keep `sdk/mpr` as a reader-only SDK.** Cheapest. Leaves the tree on two drivers
+  indefinitely, which means v2's improvements stay out of reach and every new file has to pick a
+  driver.
+- **(b) Port the consumers to `modelsdk/mpr` and delete `sdk/mpr`.** Unblocks the driver migration.
+  Costs an `api/` rewrite and therefore a breaking change to the one thing mxcli publishes as a
+  library.
+- **(c) Reimplement `api/` on the codec** and keep its signatures, absorbing the cost inside the
+  package. Most work, least disruption to users.
+
+**The prerequisite either way** is knowing whether anything outside this repository depends on
+`api/`. That is a question for the maintainer, not a measurement.
+
+### Phase 4 — mongo-driver v1 → v2 *(Effort: L, Risk: Med — gated on Phase 3)*
+
+Only reachable via 3(b) or 3(c). With `sdk/mpr` gone the remaining v1 files are the
+`mdl/backend/modelsdk` adapter's 44 and `mdl/executor`'s 17, both of which exist to bridge the two
+worlds and shrink as the semantic types move to v2. Not worth sequencing until Phase 3 resolves.
+
+## 5. Decisions to confirm before Phase 1 starts
+
+- **A. Does `--engine` survive as a no-op?** Keeping it as an accepted-and-ignored value is kinder
+  to scripts in the wild; removing it is honest. The current code makes an unrecognised value
+  **fatal** so typos are loud, which argues for an explicit, friendly error naming the removal
+  rather than silence.
+- **B. One release of deprecation, or delete now?** The earlier plan promised legacy would stay
+  "reachable for one release as an escape hatch" after cutover. Whether that release has passed is
+  a release-history question, not a code one.
+- **C. Does `mxcli bson compare` still make sense?** It is a user-facing command whose purpose was
+  comparing engine output. It may have a second life as a Studio-Pro-vs-mxcli diff, which is a
+  different feature wearing the same name.
+
+## 6. What could go wrong
+
+- **The nightly is the only thing exercising legacy.** It is also the only thing that would notice
+  if some path still reaches it. Delete the matrix leg and the backend in the **same** change, so
+  there is no window where an untested engine is still shippable — the `#808` failure mode (an
+  integration test that had only ever skipped) is exactly this shape.
+- **A concrete-reader caller is not an engine caller.** Several `cmd/mxcli` commands hold a
+  `*mpr.Reader` directly. They survive Phase 1 untouched and must not be swept into it; conflating
+  them is what makes Phase 1 look big.
+- **Deleting `mdl/enginecompare` deletes a measurement capability**, not just a test. If a future
+  change needs "does the codec still agree with a known-good serializer", that ability leaves with
+  Phase 1 — which is an argument for doing it *after* any outstanding codec parity work, not
+  before.
+
+## 7. First concrete steps
+
+1. Answer decisions A and B (§5). They are one-line answers and they gate the diff's shape.
+2. Phase 1 as a single PR, with the CI matrix change in it.
+3. Phase 2 in the same PR — the stale docs are wrong the moment Phase 1 lands.
+4. Open Phase 3 as a **proposal**, not a plan: it needs the `api/` decision before a sequence exists.

From 9ee0bccb17e0d65603d35818f36f4b78a585035d Mon Sep 17 00:00:00 2001
From: Ako <andrej@koelewijn.net>
Date: Mon, 14 Sep 2026 22:34:44 +0000
Subject: [PATCH 03/24] feat(workflow): author event handlers and on-created
 microflows
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two of the workflow constructs only Studio Pro could set, which #466 made
rewrites refuse rather than reset (phase 1 of
PROPOSAL_workflow_studio_pro_constructs.md):

  user task … on created microflow Mod.MF
  create workflow … on workflow events (UserTaskStarted, …) microflow Mod.MF as '…'
  create workflow … on any workflow event microflow Mod.MF as '…'

Both engines write and read them in the shape ako/TestApp (11.14.0) stores,
describe emits them, and a rewrite that restates them proceeds; one that
declares fewer than are stored is refused.

Measured on mxbuild 11.13.0 first: on-created takes exactly
(WorkflowUserTask, context) in either order (CE6683) and returns nothing
(CE5012); a handler takes exactly (WorkflowEvent, WorkflowRecord,
WorkflowActivityRecord) in any order (CE6691); and the build does NOT check
event type names — an invented one builds at 0 errors — so mxcli refuses an
unknown name (MDL-WF12) and one measured absent from the project version.
Studio Pro stores the full list for "every event", so `any` expands per
version from a table measured off the 11.6/11.10/11.13/11.14 mxbuilds
(32/36/42/42), and is refused below 11.6.

Fixes found on the way:
- legacy parser read OnCreatedEvent as a string, so every on-created
  microflow read back as none;
- none of the workflow rewrite guards worked on the legacy engine: its raw
  units carry arrays as primitive.A, which the guards' []any switches never
  matched, so a rewrite the modelsdk engine refused deleted stored state.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../fix-issue/findings/mdl-executor.jsonl     |   1 +
 .claude/skills/fix-issue/findings/sdk.jsonl   |   1 +
 .../skills/mendix/write-workflows/SKILL.md    |  30 ++-
 CHANGELOG.md                                  |   8 +
 cmd/mxcli/syntax/features_workflow.go         |  59 ++++-
 docs-site/src/language/workflow-activities.md |   5 +-
 docs-site/src/language/workflow-structure.md  |  41 +++-
 docs/01-project/MDL_QUICK_REFERENCE.md        |  16 +-
 ...PROPOSAL_workflow_studio_pro_constructs.md | 206 ++++++++++++++++++
 .../doctype-tests/24-workflow-examples.mdl    |  47 ++++
 mdl/ast/ast_workflow.go                       |  13 ++
 .../modelsdk/workflow_handlers_test.go        | 133 +++++++++++
 mdl/backend/modelsdk/workflow_read.go         |  23 ++
 mdl/backend/modelsdk/workflow_write.go        |  37 +++-
 mdl/executor/cmd_workflows.go                 |  65 ++++++
 mdl/executor/cmd_workflows_write.go           |  68 ++++++
 mdl/executor/validate_workflow.go             |   1 +
 mdl/executor/validate_workflow_handlers.go    | 200 +++++++++++++++++
 .../validate_workflow_handlers_test.go        | 192 ++++++++++++++++
 mdl/executor/validate_workflow_refs.go        |   4 +
 mdl/executor/validate_workflow_rewrite.go     | 171 +++++++++++++--
 .../validate_workflow_rewrite_legacy_test.go  |  84 +++++++
 .../validate_workflow_rewrite_test.go         |  56 ++++-
 .../validate_workflow_task_signature.go       |  18 +-
 mdl/executor/workflow_event_types.go          | 182 ++++++++++++++++
 mdl/executor/workflow_event_types_test.go     |  97 +++++++++
 .../workflow_handlers_describe_test.go        | 140 ++++++++++++
 mdl/grammar/domains/MDLWorkflow.g4            |  15 ++
 mdl/visitor/visitor_workflow.go               |  34 ++-
 mdl/visitor/visitor_workflow_handlers_test.go | 100 +++++++++
 sdk/mpr/parser_workflow.go                    |  36 ++-
 sdk/mpr/workflow_handlers_test.go             | 103 +++++++++
 sdk/mpr/writer_workflow.go                    |  54 ++++-
 sdk/versions/mendix-10.yaml                   |   4 +
 sdk/versions/mendix-11.yaml                   |   4 +
 sdk/workflows/workflow.go                     |  13 ++
 36 files changed, 2199 insertions(+), 62 deletions(-)
 create mode 100644 docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
 create mode 100644 mdl/backend/modelsdk/workflow_handlers_test.go
 create mode 100644 mdl/executor/validate_workflow_handlers.go
 create mode 100644 mdl/executor/validate_workflow_handlers_test.go
 create mode 100644 mdl/executor/validate_workflow_rewrite_legacy_test.go
 create mode 100644 mdl/executor/workflow_event_types.go
 create mode 100644 mdl/executor/workflow_event_types_test.go
 create mode 100644 mdl/executor/workflow_handlers_describe_test.go
 create mode 100644 mdl/visitor/visitor_workflow_handlers_test.go
 create mode 100644 sdk/mpr/workflow_handlers_test.go

diff --git a/.claude/skills/fix-issue/findings/mdl-executor.jsonl b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
index d4d727be65..aa9de8b26f 100644
--- a/.claude/skills/fix-issue/findings/mdl-executor.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
@@ -617,3 +617,4 @@
 {"area": "mdl/executor", "date": "2026-09-15", "symptom": "`describe workflow` of a workflow whose branch ends the workflow (Studio Pro: an End at the end of a user-task outcome) printed `'Reject' { }`. Re-executed, the branch fell through into the main flow — every later task was created for a request already rejected — with check, exec and mx check all clean. MDL also had no statement to write such an End, so authored workflows had the same fallthrough.", "cause": "formatWorkflowActivities skipped every EndWorkflowActivity as 'implicit', but only the main flow's End is implicit; the function is shared by the top level and every nested flow. On the write side, the first workflow grammar dropped `workflowEndStmt` for colliding with the closing END WORKFLOW, leaving ast.WorkflowEndNode and buildEndWorkflow unwired.", "fix": "Top-level body split into workflowMainBody (no End statement) and workflowBody for brace blocks (accepts `end workflow [comment '...']`, walked in child order); describer skips only the main flow's End; builder reserves the implicit Start/End names; MDL-WF08..11 (validate_workflow_end.go) predict CE1844/CE6671/CE6689/`return`; checkNoDroppedWorkflowConstructs refuses a rewrite that deletes stored nested Ends. An End's Name is a fixed base 'End' (de-duplicated), never its caption.", "file": "mdl/executor/cmd_workflows.go", "insight": "A shared formatter with a skip meant for one call site is a silent data-loss bug on every other call site — and the output still parsed, so round-trip tests that only re-parse cannot see it; the defect is semantic (fallthrough), visible only in the rebuilt graph or at runtime. Three measurement lessons: (1) a spike that swaps a placeholder `call microflow END_<caption>` for an AST node measured every placement before any grammar existed, with the caption doubling as attribution in mxbuild's messages; (2) the reachability rule needed rows a reading of CE6689 would not suggest — jumps terminate a path as surely as an End, termination reaches through a nested decision, and a main flow ending in a direct jump is CE6679 as well; (3) a test fixture called 'a valid workflow' (a main flow ending in `jump to`) was the second time a new rule proved that fixture invalid — measure the fixture, not the rule, before weakening either. (4) Deriving an activity Name from its caption, the pattern every other builder uses, was wrong for an End: `end workflow comment 'Rejected by manager'` built CE7247 'The name ... is not valid'. The end-to-end fixture passed because every caption in it was one word; the doctype script's spaced caption is what caught it. An End is never referenced by name, so a fixed base name removes the whole class instead of sanitising it — and a fixture's captions should include a space whenever a name may be derived from one."}
 {"area": "mdl/executor", "date": "2026-09-14", "symptom": "A workflow user task whose task page takes the context entity instead of System.WorkflowUserTask (CE7412), takes no parameters (CE7410), or whose targeting microflow does not take exactly System.Workflow plus the context entity (CE6677) passed `mxcli check` AND `check --references`, was written by exec, and failed only under the native mx check. Reported in a team briefing on building workflows from MDL as two of the reasons 'a green CLI check is not evidence for workflows'.", "cause": "validateWorkflowReferences resolved the user task's page and targeting microflow by NAME only — it reported a document that does not exist, never one that exists with the wrong signature. Neither signature was in `mxcli syntax workflow` either, so authors had nothing to copy.", "fix": "validate_workflow_task_signature.go checks both signatures from the script's own definitions first (scriptContext now records page parameter entities and entity generalizations, beside flowParams) and then the project, for CREATE WORKFLOW (incl. nested and multi-user tasks) and ALTER WORKFLOW (inserted tasks, SET ACTIVITY PAGE / TARGETING MICROFLOW, context entity read off the stored workflow). Wired into validateWorkflowStatementRefs / validateAlterWorkflowRefs. check --references reports before anything is written; exec calls the same function at the workflow statement, so the workflow is never written but earlier statements in the script already are. Gated on Mendix 11, where it is measured.", "file": "mdl/executor/validate_workflow_task_signature.go", "insight": "Measure the CLEAN edges before writing a refusal — three of the nine rows would have been false refusals from a plausible reading of the error text: a task page MAY take extra parameters besides WorkflowUserTask, a targeting microflow MAY take its two parameters in either order, and its context parameter MAY be a generalization of the context entity (but not a specialization). Since exec refuses on a check error, a false refusal is a blocker. Where the inheritance chain leaves what can be resolved (a script entity extending something unknown), return 'not proven' rather than a mismatch. Also a harness caveat worth keeping: the control run that stubbed the version gate first reported 0 failures because the harness only counted `--- FAIL` lines containing '/', i.e. subtests; the gate test is top-level. A silent control is a claim about the harness before it is a claim about the test. And run `make test-integration` before pushing a reference-path rule: the unit suite gates the rule on a mock project with no version, so it never fired there, while the integration round-trip tests exec against a real 11.x project — and their shared helper created task pages with no parameters and targeting microflows with none, which CI refused. Those fixtures had never been built; the rule was right, they were repaired."}
 {"area": "mdl/executor", "date": "2026-09-14", "symptom": "An `exec` / `check --references` error on a CREATE WORKFLOW statement ends with 'hint: M.W is defined later in this script — move its create statement before this one', naming the failing workflow itself (or a workflow already created earlier in the script).", "cause": "annotateForwardRef draws candidate names from scriptContext.allNames (which includes workflows) and excludes the statement's own name and already-created names via scriptContext.has — which checked modules, entities, enumerations, microflows, nanoflows, pages, snippets and code actions but NOT workflows. A parallel list that drifted from the one it filters.", "fix": "scriptContext.has also answers for sc.workflows.", "file": "mdl/executor/validate.go", "insight": "Two lists over the same kinds (allNames and has) with nothing tying them together — the same drift shape as collectDefinitions/collectSingle. The misfire only became visible once an error routinely named its own workflow, i.e. a new rule surfaced a latent bug in how every rule's message is decorated. When adding a document kind to scriptContext, check every method that enumerates kinds, not just the collector."}
+{"area": "mdl/executor", "date": "2026-09-14", "symptom": "On the **legacy** engine (MXCLI_ENGINE=legacy), `create or modify workflow` that does not restate stored event handlers / boundary events / nested Ends / AI agent tasks / completion rules is written (\"Created workflow\") and deletes them, while the default modelsdk engine refuses the same statement with the guard-don't-drop list", "cause": "The workflow rewrite guards walk `ctx.Backend.GetRawUnit` with type switches on `map[string]any` / `[]any`. The legacy backend decodes with mongo-driver v1 `bson.Unmarshal` into map[string]any, which yields nested documents as map[string]any but ARRAYS AS `primitive.A` — a named type a `case []any` does not match. So every guard saw no list at all (measured with a probe: `OnWorkflowEvent primitive.A`, `Flow map[string]interface {}`). The modelsdk reader normalizes to plain slices (`modelsdk/mpr/reader_raw.go normalizeBSONValue`), which is why only legacy was blind", "file": "`mdl/executor/validate_workflow_rewrite.go` (`plainRawUnit`, applied in `checkNoDroppedWorkflowConstructs` and `validateAlterReplaceKeepsStudioProState`)", "insight": "A guard tested only with hand-built `[]any` fixtures proves nothing about the legacy engine: build the fixture, then `bson.Marshal` + `bson.Unmarshal` into map[string]any to get the shape legacy's GetRawUnit really returns (`legacyShaped` in validate_workflow_rewrite_legacy_test.go). Normalized in the guard, not in MprBackend.GetRawUnit, because catalog (`builder_regularexpressions.go`) asserts `bson.A` on raw units. Found only by running the e2e rewrite on BOTH engines — the modelsdk run was green. Other `[]any`-only raw walkers (REST body guard, queued-call guard) are suspects of the same class. Control: normalizer returning its input fails the legacy-shape tests"}
diff --git a/.claude/skills/fix-issue/findings/sdk.jsonl b/.claude/skills/fix-issue/findings/sdk.jsonl
index 8a98c1a2d9..8fd781469a 100644
--- a/.claude/skills/fix-issue/findings/sdk.jsonl
+++ b/.claude/skills/fix-issue/findings/sdk.jsonl
@@ -41,3 +41,4 @@
 {"area": "sdk", "date": "2026-09-04", "symptom": "REPORTED AS A BUG, MEASURED AS A NON-BUG. `create association \u2026 type ReferenceSet owner Both` without `STORAGE TABLE` writes `StorageFormat: \"Column\"`, which was reported as \"not a legal many-to-many\" and worked around by respelling every such association.", "cause": "Nothing is broken. Measured on Mendix 11.13 against a live PostgreSQL, with the two spellings side by side in one app: `App.PA_PB` (ReferenceSet, StorageFormat Column) and `App.PC_PD` (ReferenceSet, StorageFormat Table) produce IDENTICAL DDL \u2014 `app$pa_pb(app$paid, app$pbid)` and `app$pc_pd(app$pcid, app$pdid)`, two FK constraints each. The app boots and serves HTTP 200, and `mx check` reports 0 errors. Mendix ignores StorageFormat for a reference set and always uses a junction table.", "file": "no code change \u2014 `mdl/executor/cmd_associations.go` defaults storageFormat to Column for every association type, and that is harmless", "insight": "A reported bug is a symptom plus an EXPLANATION, and the explanation is the part to re-measure. \"mxcli writes Column\" was true; \"which is not a legal many-to-many\" was the inference, and it cost the reporter a rewrite of ten associations. The cheap discriminator was to author BOTH spellings in one app and compare the DDL the runtime actually creates \u2014 a side-by-side control in the same boot, rather than reasoning about what a column could hold. Note the pkill trap from the same FINDINGS (\u00a711) applies when tidying up afterwards: `pkill -f \"mxcli run\"` matches the calling shell and kills it (exit 144)."}
 {"area": "sdk/mpr", "date": "2026-09-06", "symptom": "`mx check` reported CE0066 \"Entity access is out of date\" at \"Domain model of module 'BusinessEvents'\" after `create or modify persistent entity BusinessEvents.PublishedBusinessEvent ( EventId: long )` over the real BusinessEvents 3.12.0 marketplace module. LEGACY ENGINE ONLY — the codec engine produced 0 errors from the same script. Caught by the integration gate (TestMxCheck_DoctypeScripts/13-business-events-examples.mdl/legacy), not by any unit test.", "cause": "ReconcileMemberAccesses in sdk/mpr/writer_security.go skipped any rule whose MemberAccesses list held only the storage marker (`if len(maArr) <= 1 { break }`), so it never topped one up. A rule with zero member entries on an entity that HAS members is precisely the out-of-date state CE0066 names, so the skip left behind the one thing the function exists to prevent. Nothing reached that state until `create or modify entity` started PRESERVING access rules instead of deleting them: the rewrite dropped all five attributes the Administrator rule covered, the prune emptied the list, and the new EventId then never got an entry. Fixed by narrowing the guard to `len(maArr) == 0` (no storage marker at all).", "file": "`sdk/mpr/writer_security.go` (ReconcileMemberAccesses, the MemberAccesses loop); tests `sdk/mpr/writer_security_reconcile_test.go`", "insight": "A fix that starts PRESERVING something reaches states no prior code could produce, so its blast radius is every consumer of that thing — here a reconcile function untouched for months. The engine split is the tell worth acting on: identical script, 0 errors on modelsdk and CE0066 on legacy, which localises the defect to the legacy path in one measurement and makes the codec engine the reference for what the document should contain (dumped both: 1 member entry vs 0). Also note where this was caught — only the integration gate exercises a real marketplace module, and only that module had a rule whose entire member set the script drops. The unit tests written for the entity fix were green throughout, and were right to be: the entity layer did exactly what it should. Keep the empty-list case as a named test on both sides, with a member-less entity as the control, since the old guard covered that case by accident and removing it must not turn every member-less entity into a write."}
 {"area": "sdk/mpr", "date": "2026-09-12", "symptom": "The legacy writer's image widgets disagree with Studio Pro. `serializeStaticImage` omits AlternativeText entirely; `serializeDynamicImage` writes one containing a `FallbackValue` string; both write BSON null for the unset Image / DefaultImage. mxbuild accepts all of it at 0 errors", "cause": "`Forms$ClientTemplate` has exactly three properties — Fallback (Texts$Text), Parameters, Template (generated/metamodel, and all three Studio Pro references). The dynamic image hand-rolled its own holder instead of calling `serializeClientTemplate`, and invented FallbackValue. AlternativeText is declared without omitempty on both image types and appears in 3/3 references, so omitting it is a drop, not an optional key", "file": "`sdk/mpr/writer_widgets_display.go` (serializeStaticImage, serializeDynamicImage, emptyAlternativeText)", "insight": "**A hand-rolled copy of a shared serializer is where the invented key lives.** The correct helper was four lines away and carried a comment naming this exact mistake; the copy still got it wrong, because nothing compares the two. Grep for a type's $Type string and check whether every construction site goes through one builder. **mxbuild is not a check for this class at all** — it tolerates unknown properties, while Studio Pro resolves every stored property against the type's property list and throws \"Sequence contains no matching element\" at MprProperty.cs. The available substitutes are generated/metamodel (the arbiter) and a real Studio Pro document from a marketplace module in the fixture", "refs": []}
+{"area": "sdk/mpr", "date": "2026-09-14", "symptom": "Legacy engine: a user task's on-created microflow (set in Studio Pro) reads back as empty — `describe workflow` omits it and the semantic `UserTask.OnCreated` is \"\" — while the modelsdk engine reads it", "cause": "`parseUserTask` did `raw[\"OnCreatedEvent\"].(string)`, but the stored value is a PART document: `{ $Type: Workflows$MicroflowBasedEvent, Microflow: \"Mod.MF\" }` or `{ $Type: Workflows$NoEvent }`. The type assertion never matched, silently", "file": "`sdk/mpr/parser_workflow.go` (`parseUserTask`)", "insight": "A `.(string)` assertion on a key whose metamodel type is a part/by-name-in-a-part fails silently and yields the zero value — indistinguishable from 'not set'. When a field reads empty on one engine only, check the stored shape with a Studio Pro reference document (ako/TestApp) before assuming the model lacks it. The test round-trips the writer's own document through `bson.Marshal`/`Unmarshal` so the parser sees real decoded types; control: restoring the string assertion fails it"}
diff --git a/.claude/skills/mendix/write-workflows/SKILL.md b/.claude/skills/mendix/write-workflows/SKILL.md
index ecca1d8a2a..8148118712 100644
--- a/.claude/skills/mendix/write-workflows/SKILL.md
+++ b/.claude/skills/mendix/write-workflows/SKILL.md
@@ -25,8 +25,8 @@ the `LeaveRequest` being reviewed). User tasks render a page bound to
 ## Syntax — CREATE WORKFLOW
 
 The header options are **order-sensitive** (parameter → display → description →
-export level → overview page → due date), and the body **must** close with
-`END WORKFLOW`.
+export level → overview page → due date → event handlers), and the body **must**
+close with `END WORKFLOW`.
 
 ```sql
 create workflow Module.ApprovalFlow
@@ -35,6 +35,9 @@ create workflow Module.ApprovalFlow
   description 'Approves incoming requests'   -- optional
   export level Hidden                        -- optional: Hidden | API (default Hidden)
   overview page Module.WF_Overview           -- optional admin overview page
+  on workflow events (UserTaskStarted, UserTaskEnded)   -- optional, repeatable
+    microflow Module.ACT_AuditTask as 'Task audit'
+  on any workflow event microflow Module.ACT_LogEvent   -- every type this Mendix version has
 begin
   -- activities here, each terminated with ;
 end workflow;
@@ -71,6 +74,7 @@ begin
   user task Review 'Review the request'
     page Module.ReviewPage
     targeting users microflow Module.ACT_Reviewers   -- or: targeting users xpath '[Active = true()]'
+    on created microflow Module.ACT_AssignReviewer   -- optional: runs when the task is created
     description 'Please review'
     outcomes
       'Approve' { call microflow Module.ACT_Process; }
@@ -258,7 +262,9 @@ mxcli refuses the two cases where that would lose something:
 - a stored **event sub-process** — MDL cannot express one, so the rewrite is
   refused outright;
 - **more stored boundary events than the statement declares** — restate them and
-  the rewrite proceeds, which is what `describe workflow` now emits for you.
+  the rewrite proceeds, which is what `describe workflow` now emits for you;
+- **more stored workflow event handlers, or user tasks with an on-created
+  microflow, than the statement declares** — the same: restate them.
 
 The safe way to change one activity in a workflow carrying hand-placed structure
 is `ALTER WORKFLOW`, which mutates in place and touches nothing else.
@@ -323,8 +329,8 @@ documented in `system-module`.
 ## Platform rules
 
 - **Some workflow state has no MDL spelling, and a rewrite refuses rather than
-  reset it.** An event sub-process, a workflow event handler, an AI agent task, a
-  user task's on-created microflow, and a multi-user task's completion rule other
+  reset it.** An event sub-process, an AI agent task, a workflow event handler
+  subscribed to no event types, and a multi-user task's completion rule other
   than consensus falling back to its first outcome are set in Studio Pro.
   `create or modify` on a workflow that holds any of them is refused with the
   list, and so is `alter workflow … replace activity` on an activity that holds
@@ -350,6 +356,20 @@ documented in `system-module`.
   An outcome left **empty** does not stop anything — it rejoins the main flow.
   `comment '…'` sets the End's caption, as on every workflow activity.
 
+- **Handler microflows have fixed signatures** (measured, mxbuild 11.13):
+  - `on created microflow` takes exactly `System.WorkflowUserTask` and the context
+    entity, in either order — anything else is `CE6683` — and returns nothing
+    (`CE5012`).
+  - A workflow event handler takes exactly `System.WorkflowEvent`,
+    `System.WorkflowRecord` and `System.WorkflowActivityRecord`, in any order
+    (`CE6691`).
+  - **Event type names are not checked by the build** — an invented one builds at
+    0 errors and never fires. mxcli refuses an unknown name (`MDL-WF12`) and a type
+    the project's version does not have. The list is in `mxcli syntax
+    workflow.event-handlers`.
+  - `on any workflow event` stores the full list for the project's version (Studio
+    Pro stores a list, not a flag), so it needs Mendix 11.6+; name the types on
+    older projects.
 - A user task needs a **task page** to be useful; without one Mendix flags the
   task (`CE1834`). Bind the page to `System.WorkflowUserTask`.
 - **The task page takes the TASK, not the workflow's context object.** It must
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0e5a002490..03c5254f55 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- **Workflow event handlers and on-created microflows** (docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md, phase 1) — two of the workflow constructs a team building workflows from MDL still had to add in Studio Pro after every scripted rewrite, and which #466 made rewrites refuse rather than reset. A user task takes `on created microflow Mod.MF`; the workflow header takes `on workflow events (UserTaskStarted, UserTaskEnded) microflow Mod.MF as 'Task audit'` and `on any workflow event microflow Mod.MF`, repeatable. Both engines write and read them in the shape ako/TestApp (Studio Pro 11.14.0) stores, `describe workflow` emits them, and a rewrite that restates them now proceeds — refused only when the statement declares fewer than are stored.
+
+  The rules were measured on mxbuild 11.13.0 before any check was written: an on-created microflow takes exactly `System.WorkflowUserTask` and the context entity in either order (CE6683) and returns nothing (CE5012); a handler takes exactly `System.WorkflowEvent`, `System.WorkflowRecord` and `System.WorkflowActivityRecord` in any order (CE6691). The measurement also showed that **the build does not check event type names** — a handler listing an invented type builds at 0 errors and never fires — so mxcli refuses an unknown name without a project (MDL-WF12) and, with one, a type measured absent from the project's version. Studio Pro stores a handler's types as an explicit list even when every box is ticked, so `on any workflow event` writes the list for the project's version, from a table measured off the 11.6, 11.10, 11.13 and 11.14 mxbuilds (32, 36, 42, 42 types); below 11.6 it is refused rather than guessed.
+
 - **`end workflow` — end a workflow from inside a branch** (docs/11-proposals/PROPOSAL_workflow_end_activity.md) — the one structural gap a team building native workflows from MDL reported after four projects: a user-task outcome, a decision branch or a boundary-event path could continue or jump, but not stop the process, so "Reject ends the workflow" was rebuilt as a backward jump or hand-added in Studio Pro after every scripted rewrite. `end workflow [comment '<caption>'];` is now legal in any `{ }` block and ends the whole workflow — the workflow counterpart of a microflow's `return`, which in a workflow body is refused with a pointer to it (MDL-WF11). The first workflow grammar had dropped the statement for colliding with the closing `END WORKFLOW`; the collision only exists at the top level, which is the one place Mendix refuses an explicit End, so the top-level body is now its own rule.
 
   Where it may go was measured before any syntax was designed, one workflow per placement on mxbuild 11.13.0, both engines: legal as the last statement of an outcome, a decision branch, a call-microflow outcome or an **interrupting** boundary path, at any depth. Refused at check time, because a platform rule reported as a parse error reads as "not implemented": under a parallel split or a **non-interrupting** boundary path, at any depth (CE1844, MDL-WF08); followed by anything in its block (CE6671, MDL-WF09); and when every path of an activity ends — in an End or a jump, also through a nested decision — with anything after it or as the main flow's last activity (CE6689, MDL-WF10), which also covers a main flow ending in a direct `jump to` (CE6679 + CE6689). All four run without a project; ALTER inserts are checked too, including a target that already sits under a split in the stored workflow. The End's name is generated and reserved against the main flow's own End, which the measurement caught as CE0495.
@@ -139,6 +143,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Fixed
 
+- **Workflow rewrite guards did nothing on the legacy engine.** The guards that refuse a `create or modify workflow` which would delete stored boundary events, nested `end workflow`s, AI agent tasks, completion rules — and now event handlers and on-created microflows — walk the stored unit's lists, and the legacy engine returns those lists as `primitive.A`, which the guards' `[]any` type switches never matched. Measured end to end: with `MXCLI_ENGINE=legacy` a rewrite restating none of a workflow's two event handlers was written and deleted them, while the default engine refused it. The guards now normalize the stored unit first; covered by tests that decode their fixtures the way the legacy engine does.
+
+- **Legacy engine read every user task's on-created microflow as none.** `OnCreatedEvent` is a document (`Workflows$MicroflowBasedEvent` carrying `Microflow`), and the parser read it as a string, which never matched. Found while making the property authorable; the modelsdk reader was unaffected.
+
 - **Rewriting a workflow silently reset what Studio Pro configured and MDL cannot express** — measured on a Studio Pro reference workflow (ako/TestApp, Mendix 11.14.0, 0 errors under mxbuild): `ALTER WORKFLOW … REPLACE ACTIVITY` with an identical user task reset its **on-created microflow** to none while exec reported "Altered workflow" (`SET ACTIVITY`, which edits the stored document in place, kept it). A rebuild writes a default for everything MDL has no spelling for — a user task's on-created microflow becomes `NoEvent`, **workflow event handlers** an empty list, a multi-user task's **completion rule** Consensus on its first outcome — and `describe` shows an **AI agent task** only as a comment. `create or modify` now refuses a workflow that holds any of these, listing every reason at once (the rule an event sub-process already had), and `REPLACE ACTIVITY` refuses an activity that holds one. What a rebuild reproduces exactly — no handler, `NoEvent`, Consensus falling back to the first outcome, which is what the reference stores — is not refused.
 
 - **The `describe` output of an activity with two boundary events did not parse** — describe writes `boundary event …` before every event, and `mxcli syntax workflow boundary-event` documents that form, but the grammar took the keyword once followed by all the clauses (`mismatched input 'boundary' expecting ';'`). So describe → exec of any user task, call microflow or wait for notification with more than one boundary event failed, on both engines. The grammar now accepts the keyword before each clause and still accepts the shared form. The workflow round-trip integration tests compare describe output but never re-parse it, which is how this survived.
diff --git a/cmd/mxcli/syntax/features_workflow.go b/cmd/mxcli/syntax/features_workflow.go
index 4f5a9a8f03..db7338d396 100644
--- a/cmd/mxcli/syntax/features_workflow.go
+++ b/cmd/mxcli/syntax/features_workflow.go
@@ -32,9 +32,62 @@ func init() {
 			"create workflow", "new workflow", "define workflow",
 			"parameter", "overview page", "due date",
 		},
-		Syntax:  "CREATE [OR MODIFY] WORKFLOW Module.Name\n  [FOLDER 'path']\n  PARAMETER $Context: Module.Entity\n  [OVERVIEW PAGE Module.OverviewPage]\n  [DUE DATE '<expression>']\nBEGIN\n  <activities>\nEND WORKFLOW;",
+		Syntax:  "CREATE [OR MODIFY] WORKFLOW Module.Name\n  [FOLDER 'path']\n  PARAMETER $Context: Module.Entity\n  [OVERVIEW PAGE Module.OverviewPage]\n  [DUE DATE '<expression>']\n  [ON WORKFLOW EVENTS (<type>, ...) MICROFLOW Module.Handler [AS '<description>']]...\n  [ON ANY WORKFLOW EVENT MICROFLOW Module.Handler [AS '<description>']]...\nBEGIN\n  <activities>\nEND WORKFLOW;",
 		Example: "CREATE WORKFLOW Module.ApprovalFlow\n  PARAMETER $Context: Module.Request\n  OVERVIEW PAGE Module.WF_Overview\nBEGIN\n  USER TASK ReviewTask 'Review the request'\n    PAGE Module.ReviewPage\n    OUTCOMES 'Approve' { } 'Reject' { };\nEND WORKFLOW;",
-		SeeAlso: []string{"workflow.user-task", "workflow.decision", "workflow.drop"},
+		SeeAlso: []string{"workflow.user-task", "workflow.event-handlers", "workflow.decision", "workflow.drop"},
+	})
+
+	Register(SyntaxFeature{
+		Path:    "workflow.event-handlers",
+		Summary: "Run a microflow when workflow events happen (task started, workflow completed, ...)",
+		Keywords: []string{
+			"event handler", "workflow event", "on workflow events", "any workflow event",
+			"audit", "on created", "on-created microflow", "WorkflowEvent", "OnWorkflowEvent",
+		},
+		// Every rule below is an mxbuild 11.13.0 measurement. The invented-type row
+		// is the one worth saying out loud: the build does not check type names.
+		Syntax: "-- Workflow header, before BEGIN; repeat for more handlers:\n" +
+			"ON WORKFLOW EVENTS (<type>, ...) MICROFLOW Module.Handler [AS '<description>']\n" +
+			"ON ANY WORKFLOW EVENT MICROFLOW Module.Handler [AS '<description>']\n\n" +
+			"-- The handler microflow takes exactly these three, in any order (else CE6691):\n" +
+			"--   System.WorkflowEvent, System.WorkflowRecord, System.WorkflowActivityRecord\n\n" +
+			"-- Event types (names are checked by mxcli — mxbuild accepts any name,\n" +
+			"-- and a misspelt type never fires; MDL-WF12):\n" +
+			"--   WorkflowCompleted WorkflowInitiated WorkflowRestarted WorkflowFailed WorkflowAborted\n" +
+			"--   WorkflowPaused WorkflowUnpaused WorkflowRetried WorkflowUpdated WorkflowUpgraded\n" +
+			"--   WorkflowConflicted WorkflowResolved WorkflowJumpToOptionApplied\n" +
+			"--   StartEventExecuted EndEventExecuted DecisionExecuted JumpExecuted\n" +
+			"--   ParallelSplitExecuted ParallelMergeExecuted CallWorkflowStarted CallWorkflowEnded\n" +
+			"--   CallMicroflowStarted CallMicroflowEnded WaitForNotificationStarted WaitForNotificationEnded\n" +
+			"--   WaitForTimerStarted WaitForTimerEnded UserTaskStarted MultiUserTaskOutcomeSelected UserTaskEnded\n" +
+			"--   NonInterruptingTimerEventExecuted InterruptingTimerEventExecuted\n" +
+			"--   11.10+: AIAgentTaskStarted AIAgentTaskEnded\n" +
+			"--           NonInterruptingNotificationEventSubProcessStartExecuted\n" +
+			"--           InterruptingNotificationEventSubProcessStartExecuted\n" +
+			"--   11.13+: NotificationStarted NotificationEnded\n" +
+			"--           NonInterruptingNotificationEventExecuted InterruptingNotificationEventExecuted\n" +
+			"--           NonInterruptingTimerEventSubProcessStartExecuted InterruptingTimerEventSubProcessStartExecuted\n\n" +
+			"-- ANY WORKFLOW EVENT stores every type the project's Mendix version has (Studio Pro\n" +
+			"-- stores the list, not a flag), so it needs Mendix 11.6+; name the types before that.\n\n" +
+			"-- A user task's on-created microflow (see workflow.user-task) takes exactly\n" +
+			"-- System.WorkflowUserTask and the context entity, in either order (else CE6683),\n" +
+			"-- and returns nothing (else CE5012).",
+		Example: "CREATE MICROFLOW HR.ACT_AuditTask (\n" +
+			"  $WorkflowEvent: System.WorkflowEvent,\n" +
+			"  $WorkflowRecord: System.WorkflowRecord,\n" +
+			"  $WorkflowActivityRecord: System.WorkflowActivityRecord\n" +
+			") BEGIN END;\n\n" +
+			"CREATE WORKFLOW HR.LeaveApproval\n" +
+			"  PARAMETER $Request: HR.LeaveRequest\n" +
+			"  ON WORKFLOW EVENTS (UserTaskStarted, UserTaskEnded) MICROFLOW HR.ACT_AuditTask AS 'Task audit'\n" +
+			"  ON ANY WORKFLOW EVENT MICROFLOW HR.ACT_LogEvent AS 'OnAnyEvent'\n" +
+			"BEGIN\n" +
+			"  USER TASK Review 'Review the request'\n" +
+			"    PAGE HR.ReviewPage\n" +
+			"    ON CREATED MICROFLOW HR.ACT_AssignReviewer\n" +
+			"    OUTCOMES 'Approve' { } 'Reject' { };\n" +
+			"END WORKFLOW;",
+		SeeAlso: []string{"workflow.create", "workflow.user-task"},
 	})
 
 	Register(SyntaxFeature{
@@ -52,6 +105,7 @@ func init() {
 		Syntax: "[MULTI] USER TASK <name> '<caption>'\n" +
 			"  PAGE Module.TaskPage\n" +
 			"  [TARGETING [USERS | GROUPS] MICROFLOW Module.MF | TARGETING [USERS | GROUPS] XPATH '<xpath>']\n" +
+			"  [ON CREATED MICROFLOW Module.MF]  -- (System.WorkflowUserTask, <context entity>), returns nothing\n" +
 			"  [ENTITY Module.Entity]\n" +
 			"  [DUE DATE '<expression>']\n" +
 			"  [DESCRIPTION '<text>']\n" +
@@ -112,6 +166,7 @@ func init() {
 		Syntax: "MULTI USER TASK <name> '<caption>'\n" +
 			"  PAGE Module.TaskPage\n" +
 			"  [TARGETING [USERS | GROUPS] MICROFLOW Module.MF | TARGETING [USERS | GROUPS] XPATH '<xpath>']\n" +
+			"  [ON CREATED MICROFLOW Module.MF]  -- (System.WorkflowUserTask, <context entity>), returns nothing\n" +
 			"  [ENTITY Module.Entity]\n" +
 			"  [DUE DATE '<expression>']\n" +
 			"  [DESCRIPTION '<text>']\n" +
diff --git a/docs-site/src/language/workflow-activities.md b/docs-site/src/language/workflow-activities.md
index 4ad42f8390..f05468f3af 100644
--- a/docs-site/src/language/workflow-activities.md
+++ b/docs-site/src/language/workflow-activities.md
@@ -10,6 +10,7 @@ A user task pauses the workflow until a user completes it. Each outcome resumes
 USER TASK <name> '<caption>'
   [PAGE <Module>.<Page>]
   [TARGETING MICROFLOW <Module>.<Microflow>]
+  [ON CREATED MICROFLOW <Module>.<Microflow>]
   OUTCOMES '<outcome>' { <activities> } ['<outcome>' { <activities> }] ...;
 ```
 
@@ -19,6 +20,7 @@ USER TASK <name> '<caption>'
 | `<caption>` | Display label shown to users |
 | `PAGE` | The page opened when the user acts on the task |
 | `TARGETING MICROFLOW` | Microflow that determines which users see the task |
+| `ON CREATED MICROFLOW` | Microflow run when the task is created — for example to assign it. It takes exactly `System.WorkflowUserTask` and the workflow's context entity, in either order (else CE6683), and returns nothing (else CE5012) |
 | `OUTCOMES` | Named outcomes, each with a block of follow-up activities |
 
 Example:
@@ -27,11 +29,12 @@ Example:
 USER TASK ReviewTask 'Review the request'
   PAGE Approval.ReviewPage
   TARGETING MICROFLOW Approval.ACT_GetReviewers
+  ON CREATED MICROFLOW Approval.ACT_AssignReviewer
   OUTCOMES 'Approve' {
     CALL MICROFLOW Approval.ACT_Approve;
   } 'Reject' {
     CALL MICROFLOW Approval.ACT_Reject;
-    END;
+    END WORKFLOW;
   };
 ```
 
diff --git a/docs-site/src/language/workflow-structure.md b/docs-site/src/language/workflow-structure.md
index 50052943bb..0a647bb91e 100644
--- a/docs-site/src/language/workflow-structure.md
+++ b/docs-site/src/language/workflow-structure.md
@@ -8,6 +8,8 @@ A workflow definition consists of a context parameter, an optional overview page
 CREATE [OR MODIFY] WORKFLOW <Module>.<Name>
   PARAMETER $<Name>: <Module>.<Entity>
   [OVERVIEW PAGE <Module>.<Page>]
+  [ON WORKFLOW EVENTS (<type>, ...) MICROFLOW <Module>.<Microflow> [AS '<description>']] ...
+  [ON ANY WORKFLOW EVENT MICROFLOW <Module>.<Microflow> [AS '<description>']] ...
 BEGIN
   <activities>
 END WORKFLOW;
@@ -17,6 +19,7 @@ END WORKFLOW;
 |---------|-------------|
 | `PARAMETER` | The workflow context object, passed when the workflow is started |
 | `OVERVIEW PAGE` | Optional page shown in the workflow admin dashboard |
+| `ON WORKFLOW EVENTS` | A microflow run for each listed workflow event; repeatable. See [Workflow Event Handlers](#workflow-event-handlers) |
 | Activities | A sequence of user tasks, microflow calls, decisions, etc. |
 
 ## Full Example
@@ -46,7 +49,7 @@ BEGIN
         PAGE HR.ManagerReviewPage
         OUTCOMES 'Approve' { } 'Reject' {
           CALL MICROFLOW HR.ACT_RejectOnboarding;
-          END;
+          END WORKFLOW;
         };
     } 'No' { };
 
@@ -54,6 +57,42 @@ BEGIN
 END WORKFLOW;
 ```
 
+## Workflow Event Handlers
+
+A handler runs a microflow whenever one of the listed events happens — a task
+starting or ending, the workflow completing, failing or being aborted. Use one to
+audit a process or react to it without adding activities to the flow.
+
+```sql
+CREATE MICROFLOW HR.ACT_AuditTask (
+  $WorkflowEvent: System.WorkflowEvent,
+  $WorkflowRecord: System.WorkflowRecord,
+  $WorkflowActivityRecord: System.WorkflowActivityRecord
+) BEGIN END;
+
+CREATE WORKFLOW HR.LeaveApproval
+  PARAMETER $Request: HR.LeaveRequest
+  ON WORKFLOW EVENTS (UserTaskStarted, UserTaskEnded) MICROFLOW HR.ACT_AuditTask AS 'Task audit'
+  ON ANY WORKFLOW EVENT MICROFLOW HR.ACT_LogEvent AS 'OnAnyEvent'
+BEGIN
+  USER TASK Review 'Review the request'
+    PAGE HR.ReviewPage
+    OUTCOMES 'Approve' { } 'Reject' { };
+END WORKFLOW;
+```
+
+- The handler microflow takes exactly `System.WorkflowEvent`,
+  `System.WorkflowRecord` and `System.WorkflowActivityRecord`, in any order.
+  Anything else fails the build with CE6691.
+- **The build does not check event type names**: a handler listing a name that is
+  not an event type builds cleanly and never runs for it. `mxcli check` refuses an
+  unknown name (MDL-WF12) and, with a project, a type that project's Mendix
+  version does not have. `mxcli syntax workflow.event-handlers` lists the types.
+- `ON ANY WORKFLOW EVENT` stores every event type the project's Mendix version
+  has — Studio Pro stores the list, not a flag — so it needs Mendix 11.6 or later.
+  On older projects, name the types.
+- `AS '...'` is the handler's description, which is how Studio Pro lists it.
+
 ## DROP WORKFLOW
 
 ```sql
diff --git a/docs/01-project/MDL_QUICK_REFERENCE.md b/docs/01-project/MDL_QUICK_REFERENCE.md
index 8b083837a8..e35ba60dad 100644
--- a/docs/01-project/MDL_QUICK_REFERENCE.md
+++ b/docs/01-project/MDL_QUICK_REFERENCE.md
@@ -659,14 +659,15 @@ Nested folders use `/` separator: `'Parent/Child/Grandchild'`. Missing folders a
 |-----------|--------|-------|
 | Show workflows | `show workflows [in module];` | List all or filter by module |
 | Describe workflow | `describe workflow Module.Name;` | Full MDL output |
-| Create workflow | `create [or modify] workflow Module.Name [folder 'path'] parameter $Ctx: Module.Entity begin ... end workflow;` | See activity types below |
+| Create workflow | `create [or modify] workflow Module.Name [folder 'path'] parameter $Ctx: Module.Entity [on workflow events (<type>, ...) microflow Mod.MF [as '<text>']] [on any workflow event microflow Mod.MF [as '<text>']] begin ... end workflow;` | See activity types and event handlers below |
 | Drop workflow | `drop workflow Module.Name;` | |
 
 **Workflow Activity Types:**
-- `[multi] user task <name> '<caption>' [page Mod.Page] [targeting [users|groups] microflow Mod.MF] [targeting [users|groups] xpath '<expr>'] [outcomes '<out>' { } ...];`
+- `[multi] user task <name> '<caption>' [page Mod.Page] [targeting [users|groups] microflow Mod.MF] [targeting [users|groups] xpath '<expr>'] [on created microflow Mod.MF] [outcomes '<out>' { } ...];`
   - The **task page** must take a `System.WorkflowUserTask` parameter — none at all is CE7410, none of that type is CE7412; extra parameters are allowed.
   - A **targeting microflow** takes exactly `System.Workflow` + the context entity (or a generalization of it), in either order — anything else is CE6677. Users targeting returns a list of `System.User`, groups a list of `System.WorkflowGroup`.
-  - `check --references` reports both before anything is written; `exec` refuses the workflow statement itself (Mendix 11+).
+  - An **on-created microflow** takes exactly `System.WorkflowUserTask` + the context entity, in either order (CE6683), and returns nothing (CE5012).
+  - `check --references` reports these before anything is written; `exec` refuses the workflow statement itself (Mendix 11+).
 - `call microflow Mod.MF [as <name>] [comment '<text>'] [with (<Param> = '<expr>', ...)] [outcomes '<out>' -> { } ...];`
 - `call workflow Mod.WF [as <name>] [comment '<text>'] [with (<Param> = '<expr>', ...)];`
 - `decision [<name>] ['<expression>'] outcomes <true|false|'Module.Enum.Value'> -> { } ...;`
@@ -676,6 +677,15 @@ Nested folders use `/` separator: `'Parent/Child/Grandchild'`. Missing folders a
 - `wait for notification [<name>];`
 - `end workflow [comment '<caption>'];` — only inside a `{ }` block; ends the whole workflow
 
+**Workflow event handlers.** `on workflow events (UserTaskStarted, UserTaskEnded)
+microflow Mod.MF as 'Task audit'` in the header runs the microflow for each listed
+event; the microflow takes exactly `System.WorkflowEvent`, `System.WorkflowRecord`
+and `System.WorkflowActivityRecord` (CE6691). The build does not check event type
+names — an invented one builds and never fires — so mxcli refuses an unknown name
+(MDL-WF12) and one the project's Mendix version lacks. `on any workflow event`
+stores every type the version has (Studio Pro stores the list, not a flag) and
+needs 11.6+. Types: `mxcli syntax workflow.event-handlers`.
+
 **Ending a workflow early.** `end workflow` inside an outcome, a decision branch, a
 call-microflow outcome or an interrupting boundary-event path ends the whole
 workflow — the workflow counterpart of a microflow's `return` (which a workflow
diff --git a/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md b/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
new file mode 100644
index 0000000000..b6b07e166c
--- /dev/null
+++ b/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
@@ -0,0 +1,206 @@
+# Proposal: Workflow constructs only Studio Pro could author
+
+**Status:** Phase 1 implemented; phases 2–4 designed, awaiting reference documents
+**Date:** 2026-09-14
+
+## Problem Statement
+
+A team building Mendix workflows from MDL reported the constructs they still had
+to add in Studio Pro after every scripted rewrite. Since #466 mxcli refuses a
+rewrite that would lose them (guard-don't-drop, ADR-0005), which keeps the model
+safe but leaves the work manual. This proposal makes them authorable, in the order
+the team's workflows reference them:
+
+| Phase | Construct | Stored as | Reference |
+|-------|-----------|-----------|-----------|
+| 1 | on-created microflow of a user task | `OnCreatedEvent` → `Workflows$MicroflowBasedEvent` | ako/TestApp `workflow.Workflow1` |
+| 1 | workflow event handlers | `Workflow.OnWorkflowEvent` → `Workflows$WorkflowEventHandler` | ako/TestApp `workflow.Workflow1` |
+| 2 | AI agent task | `Workflows$AIAgentTaskActivity` | ako/TestApp `workflow.Workflow1` |
+| 3 | multi-user completion rules (majority, threshold, veto, microflow) | `CompletionCriteria` variants | **needed** |
+| 4 | event sub-processes, and `notify workflow` targeting one | `Workflow.EventSubProcesses`, `NotifyWorkflowAction.NotifyTarget` | partial (TestApp has one interrupting notification sub-process) |
+
+## Phase 1 — handlers (implemented)
+
+### BSON structure (ako/TestApp, Studio Pro 11.14.0, 0 errors)
+
+```
+SingleUserTaskActivity / MultiUserTaskActivity
+  OnCreatedEvent: { $Type: "Workflows$MicroflowBasedEvent", Microflow: "workflow.UserTaskEventHandle" }
+               or { $Type: "Workflows$NoEvent" }
+
+Workflow
+  OnWorkflowEvent: [2,
+    { $Type: "Workflows$WorkflowEventHandler",
+      Description: "OnAnyEvent",
+      Documentation: "",
+      EventTypes: [1, "WorkflowCompleted", "WorkflowInitiated", …],   // explicit list, marker 1
+      MicroflowEventHandler: { $Type: "Workflows$MicroflowEventHandler", Microflow: "workflow.WorkflowEventHandle" } } ]
+```
+
+Studio Pro stores a handler's event types as an **explicit list even when every
+box is ticked** — the handler named "OnAnyEvent" stores all 42. There is no "any"
+flag.
+
+Before this change both writers hard-coded `NoEvent` and an empty handler list,
+and the legacy reader parsed `OnCreatedEvent` as a string (it is a document), so an
+on-created microflow read back as none on that engine.
+
+### MDL syntax
+
+```sql
+create workflow HR.LeaveApproval
+  parameter $Request: HR.LeaveRequest
+  on workflow events (UserTaskStarted, UserTaskEnded) microflow HR.ACT_AuditTask as 'Task audit'
+  on any workflow event microflow HR.ACT_LogEvent as 'OnAnyEvent'
+begin
+  user task Review 'Review the request'
+    page HR.ReviewPage
+    targeting microflow HR.GetReviewers
+    on created microflow HR.ACT_AssignReviewer
+    outcomes 'Approve' { } 'Reject' { };
+end workflow;
+```
+
+- Handler clauses follow the other header options, before `begin`, and repeat.
+  `as '…'` is the handler's description — how Studio Pro lists handlers.
+- `on created microflow` sits after the targeting clauses on both `user task`
+  and `multi user task`.
+- A named list is written in Studio Pro's order and de-duplicated; names match
+  case-insensitively. `describe` emits `on any workflow event` exactly when the
+  stored list equals the project version's full set, and otherwise the list (one
+  type per line beyond three), so re-executing stores the same list.
+- A handler's `Documentation` has no MDL spelling; a rewrite carries it from the
+  stored handler with the same microflow and description.
+
+### Measured rules (mxbuild 11.13.0, one task or handler per shape)
+
+| Shape | Verdict |
+|-------|---------|
+| on created `(WorkflowUserTask, Ctx)`, either order | 0 errors |
+| on created `(WorkflowUserTask)`, `(Ctx)`, `()`, `(+ String)`, `(WorkflowUserTask, <specialization>)` | CE6683 |
+| on created returning a value | CE5012 |
+| handler `(WorkflowEvent, WorkflowRecord, WorkflowActivityRecord)`, any order | 0 errors |
+| handler `(WorkflowEvent)`, `()`, `(+ String)`, `(WorkflowEvent, Ctx)` | CE6691 |
+| handler with no microflow | CE0113 |
+| handler listing all 42 types | 0 errors |
+| handler listing an **invented** type | **0 errors** |
+| handler with an empty type list | 0 errors |
+
+The invented-type row decides the design: mxbuild does not check type names, so a
+misspelt type would be written and never fire. mxcli checks them itself —
+**MDL-WF12** without a project, and against the project's version with one.
+
+### Event types per Mendix version
+
+Measured as the type names present in each mxbuild's `Mendix.Modeler.*.dll`:
+
+| Version | Types | Added |
+|---------|-------|-------|
+| 11.6.0 | 32 | workflow, activity, user-task and boundary-timer events |
+| 11.10.0 | 36 | `AIAgentTaskStarted/Ended`, `(Non)InterruptingNotificationEventSubProcessStartExecuted` |
+| 11.13.0, 11.14.0 | 42 | `NotificationStarted/Ended`, `(Non)InterruptingNotificationEventExecuted`, `(Non)InterruptingTimerEventSubProcessStartExecuted` |
+
+- `on any workflow event` writes the set of the newest measured point not above
+  the project version. Below 11.6.0 it is refused with a hint to name the types:
+  no older mxbuild could be measured (Mendix publishes no arm64 10.24 build), and
+  a guess would write types the version may not have.
+- A named type is refused only where it is **measured absent** (at or below the
+  last point before it appeared). Between that point and the one it was seen at,
+  the answer is unknown and the author's choice stands.
+
+### Guard changes
+
+A rewrite now writes handlers and on-created microflows, so they move from
+"cannot express" to "restated?" — the boundary-event rule: refused when the
+statement declares fewer handlers, or fewer on-created microflows, than are
+stored. `replace activity` is refused only when the replacement does not restate
+the stored on-created microflow. Still refused outright: an event sub-process, an
+AI agent task, a non-default completion rule, and a handler with an empty type
+list (no MDL spelling).
+
+Running the end-to-end rewrite on both engines found that **none of the workflow
+rewrite guards worked on the legacy engine**: its `GetRawUnit` returns arrays as
+`primitive.A`, which the guards' `[]any` type switches never matched, so a rewrite
+the modelsdk engine refused was written and deleted the handlers. The guards now
+normalize the stored unit before walking it, and their tests decode fixtures the
+way the legacy engine does.
+
+### Version compatibility
+
+`workflows.event_handlers` min 10.7.0 (`Workflow.onWorkflowEvent` in modelsdk gen)
+gates the handler clauses. `onCreatedEvent` is 9.0.5, older than every supported
+workflow version. The signature checks run on Mendix 11+, where they are measured.
+
+### Files
+
+| File | Change |
+|------|--------|
+| `mdl/grammar/domains/MDLWorkflow.g4` | `workflowEventHandlerClause`; `ON CREATED MICROFLOW` on both user-task alternatives |
+| `mdl/ast/ast_workflow.go`, `mdl/visitor/visitor_workflow.go` | `EventHandlers`, `OnCreated` |
+| `sdk/workflows/workflow.go` | `WorkflowEventHandler`, `Workflow.EventHandlers` |
+| `sdk/mpr/writer_workflow.go`, `sdk/mpr/parser_workflow.go` | legacy write/read; `OnCreatedEvent` parse fix |
+| `mdl/backend/modelsdk/workflow_write.go`, `workflow_read.go` | modelsdk write/read |
+| `mdl/executor/workflow_event_types.go` | measured per-version type table |
+| `mdl/executor/validate_workflow_handlers.go` | MDL-WF12, signatures (CE6683, CE5012, CE6691), version checks |
+| `mdl/executor/cmd_workflows_write.go`, `cmd_workflows.go` | build and describe |
+| `mdl/executor/validate_workflow_rewrite.go` | restated-handler guard |
+
+### Not in phase 1
+
+- `alter workflow` cannot yet add or change a handler or an on-created microflow
+  (`set activity … on created microflow …` and header handler operations). A
+  rewrite restating them is the path today.
+
+## Phase 2 — AI agent task
+
+```sql
+call agent microflow HR.InvokeAgent as aiAgentTask1 comment 'Classify the request'
+  with (Request = '$WorkflowContext');
+```
+
+Stored as `Workflows$AIAgentTaskActivity` with `Caption`, `Name`, `Microflow`,
+`BoundaryEvents` (marker 2), `Outcomes` (marker 3, a `VoidConditionOutcome` with its
+`Flow`) and `ParameterMappings` (marker 2, `MicroflowCallParameterMapping`) — the
+call-microflow shape under a different `$Type`. The TestApp agent microflow takes
+the context entity. Open: the minimum version (agents are 11.9+; the event types
+appear by 11.10), and which signature errors the build reports.
+
+## Phase 3 — completion rules
+
+gen carries `ConsensusCompletionCriteria` (FallbackOutcomePointer),
+`MajorityCompletionCriteria` (CompletionType Absolute|Relative,
+FallbackOutcomePointer), `ThresholdCompletionCriteria` (+ Threshold),
+`VetoCompletionCriteria` (VetoOutcomePointer) and `MicroflowCompletionCriteria`
+(Microflow). **Needed before syntax is designed:** a Studio Pro workflow with one
+multi-user task per rule, including both completion types for majority and
+threshold — pointer semantics and defaults cannot be read off gen.
+
+## Phase 4 — event sub-processes and notify targets
+
+`Workflow.EventSubProcesses` (11.8.0) holds `Workflows$EventSubProcess` with a
+`Caption`, `Name` and `Flow` whose first activity is an
+`(Non)InterruptingNotificationEventSubProcessStartActivity`. Timer starts appear in
+11.13's event types but have no gen type yet. `NotifyWorkflowAction.notifyTarget`
+(11.7.0) is how a microflow notifies a sub-process start; the MDL `notify workflow`
+statement has no target today. **Needed:** a Studio Pro example with a
+non-interrupting and a timer sub-process, and a microflow that notifies one.
+
+## Test plan (phase 1)
+
+- Unit: visitor (clause positions with and without targeting), legacy
+  serialize/parse, modelsdk write→read round trip with the raw unit's markers,
+  the per-version type table, signature rows as mock-backed `check` cases, the
+  version checks, MDL-WF12, describe → re-parse → rebuild, the guard's
+  restated/unrestated cases.
+- Controls: each fix stubbed in turn makes its test fail.
+- Doctype: `24-workflow-examples.mdl` part F builds under `mx check` on both
+  engines.
+- End to end: exec on an 11.13 app, `mx check`, describe → re-exec → identical
+  describe; describe of TestApp's `workflow.Workflow1`.
+
+## Open questions
+
+- Whether a 10.x project knows every type in the 11.6 set. Named types are let
+  through there; `any` is refused.
+- A stored type newer than the table (a future Mendix) is refused by MDL-WF12 on
+  re-execute until the table gains that version's point.
diff --git a/mdl-examples/doctype-tests/24-workflow-examples.mdl b/mdl-examples/doctype-tests/24-workflow-examples.mdl
index 387d76d9c7..4b52f6058e 100644
--- a/mdl-examples/doctype-tests/24-workflow-examples.mdl
+++ b/mdl-examples/doctype-tests/24-workflow-examples.mdl
@@ -572,3 +572,50 @@ alter workflow WFTest.EndInBranches
   insert outcome 'Withdraw' on FinalCheck {
     end workflow comment 'Withdrawn';
   };
+
+-- ############################################################################
+-- PART F: HANDLERS — on-created microflows and workflow event handlers
+-- ############################################################################
+--
+-- `on created microflow` runs when a user task is created; it takes the task
+-- and the context object, in either order, and returns nothing (CE6683,
+-- CE5012). A header `on workflow events (…) microflow …` handler runs for each
+-- listed event and takes System.WorkflowEvent, System.WorkflowRecord and
+-- System.WorkflowActivityRecord, in any order (CE6691). `on any workflow event`
+-- stores every event type the project's Mendix version has, which is what
+-- Studio Pro stores when every box is ticked. Measured on mxbuild 11.13.0;
+-- see docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md.
+
+create microflow WFTest.ACT_TaskCreated (
+  $OrderContext: WFTest.OrderContext,
+  $WorkflowUserTask: System.WorkflowUserTask
+)
+begin
+end;
+/
+
+create microflow WFTest.ACT_AuditWorkflowEvent (
+  $WorkflowEvent: System.WorkflowEvent,
+  $WorkflowRecord: System.WorkflowRecord,
+  $WorkflowActivityRecord: System.WorkflowActivityRecord
+)
+begin
+end;
+/
+
+create workflow WFTest.WithHandlers
+  parameter $OrderContext: WFTest.OrderContext
+  on workflow events (UserTaskStarted, UserTaskEnded) microflow WFTest.ACT_AuditWorkflowEvent as 'Task audit'
+  on any workflow event microflow WFTest.ACT_AuditWorkflowEvent as 'OnAnyEvent'
+begin
+  user task Review 'Review the order'
+    page WFTest.TaskPage
+    on created microflow WFTest.ACT_TaskCreated
+    outcomes 'Approve' { } 'Reject' { };
+
+  multi user task Vote 'Vote on the order'
+    page WFTest.TaskPage
+    on created microflow WFTest.ACT_TaskCreated
+    outcomes 'Yes' { } 'No' { };
+end workflow;
+/
diff --git a/mdl/ast/ast_workflow.go b/mdl/ast/ast_workflow.go
index b0bbb37aa3..44f3dd6a4b 100644
--- a/mdl/ast/ast_workflow.go
+++ b/mdl/ast/ast_workflow.go
@@ -23,10 +23,22 @@ type CreateWorkflowStmt struct {
 	OverviewPage QualifiedName // qualified name of overview page
 	DueDate      string        // due date expression
 
+	// Workflow event handlers, in statement order.
+	EventHandlers []WorkflowEventHandlerNode
+
 	// Activities
 	Activities []WorkflowActivityNode
 }
 
+// WorkflowEventHandlerNode is one `on workflow events (…) microflow M as '…'` or
+// `on any workflow event microflow M as '…'` header clause.
+type WorkflowEventHandlerNode struct {
+	AnyEvent    bool          // `on any workflow event`: every type the project version knows
+	EventTypes  []string      // the named types, as written; empty when AnyEvent
+	Microflow   QualifiedName // the handler microflow
+	Description string        // from AS 'text'
+}
+
 func (s *CreateWorkflowStmt) isStatement() {}
 
 // DropWorkflowStmt represents: DROP WORKFLOW Module.Name
@@ -47,6 +59,7 @@ type WorkflowUserTaskNode struct {
 	Caption         string // display caption
 	Page            QualifiedName
 	Targeting       WorkflowTargetingNode
+	OnCreated       QualifiedName // ON CREATED MICROFLOW: runs when the task is created
 	Entity          QualifiedName // user task entity
 	DueDate         string        // DUE DATE expression
 	Outcomes        []WorkflowUserTaskOutcomeNode
diff --git a/mdl/backend/modelsdk/workflow_handlers_test.go b/mdl/backend/modelsdk/workflow_handlers_test.go
new file mode 100644
index 0000000000..f7e742d80a
--- /dev/null
+++ b/mdl/backend/modelsdk/workflow_handlers_test.go
@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+import (
+	"fmt"
+	"reflect"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// A workflow event handler and an on-created microflow survive a write and a
+// fresh read, in the shape ako/TestApp (Studio Pro 11.14.0) stores: a marker-2
+// OnWorkflowEvent list, marker-1 EventTypes, and a MicroflowBasedEvent on the
+// task. The writer used to hard-code NoEvent and an empty handler list.
+func TestCreateWorkflow_HandlersAndOnCreatedRoundTrip(t *testing.T) {
+	proj := copyFixture(t)
+	b := New()
+	if err := b.Connect(proj); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+	mod, err := b.GetModuleByName("MyFirstModule")
+	if err != nil || mod == nil {
+		t.Fatalf("GetModuleByName: %v", err)
+	}
+
+	task := &workflows.UserTask{
+		BaseWorkflowActivity: workflows.BaseWorkflowActivity{Name: "Review", Caption: "Review"},
+		Page:                 "MyFirstModule.ReviewPage",
+		OnCreated:            "MyFirstModule.ACT_Assign",
+		Outcomes:             []*workflows.UserTaskOutcome{{Value: "Done"}},
+	}
+	plain := &workflows.UserTask{
+		BaseWorkflowActivity: workflows.BaseWorkflowActivity{Name: "Plain", Caption: "Plain"},
+		Outcomes:             []*workflows.UserTaskOutcome{{Value: "Done"}},
+	}
+	wf := &workflows.Workflow{
+		ContainerID: mod.ID,
+		Name:        "ZzHandlers",
+		Parameter:   &workflows.WorkflowParameter{EntityRef: "MyFirstModule.Ctx"},
+		EventHandlers: []*workflows.WorkflowEventHandler{{
+			Description: "Task audit",
+			EventTypes:  []string{"UserTaskStarted", "UserTaskEnded"},
+			Microflow:   "MyFirstModule.ACT_Audit",
+		}},
+		Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+			&workflows.StartWorkflowActivity{BaseWorkflowActivity: workflows.BaseWorkflowActivity{Name: "Start"}},
+			task,
+			plain,
+			&workflows.EndWorkflowActivity{BaseWorkflowActivity: workflows.BaseWorkflowActivity{Name: "End"}},
+		}},
+	}
+	if err := b.CreateWorkflow(wf); err != nil {
+		t.Fatalf("CreateWorkflow: %v", err)
+	}
+
+	b2 := New()
+	if err := b2.Connect(proj); err != nil {
+		t.Fatalf("reconnect: %v", err)
+	}
+	t.Cleanup(func() { _ = b2.Disconnect() })
+	all, err := b2.ListWorkflows()
+	if err != nil {
+		t.Fatalf("ListWorkflows: %v", err)
+	}
+	var got *workflows.Workflow
+	for _, w := range all {
+		if w.Name == "ZzHandlers" {
+			got = w
+		}
+	}
+	if got == nil {
+		t.Fatal("workflow not found after reconnect")
+	}
+
+	if len(got.EventHandlers) != 1 {
+		t.Fatalf("handlers = %d, want 1", len(got.EventHandlers))
+	}
+	h := got.EventHandlers[0]
+	if h.Description != "Task audit" || h.Microflow != "MyFirstModule.ACT_Audit" ||
+		!reflect.DeepEqual(h.EventTypes, []string{"UserTaskStarted", "UserTaskEnded"}) {
+		t.Errorf("handler = %+v", h)
+	}
+	onCreated := map[string]string{}
+	for _, a := range got.Flow.Activities {
+		if ut, ok := a.(*workflows.UserTask); ok {
+			onCreated[ut.Name] = ut.OnCreated
+		}
+	}
+	if onCreated["Review"] != "MyFirstModule.ACT_Assign" || onCreated["Plain"] != "" {
+		t.Errorf("on-created = %v", onCreated)
+	}
+
+	raw, err := b2.GetRawUnit(got.ID)
+	if err != nil {
+		t.Fatalf("GetRawUnit: %v", err)
+	}
+	events, _ := raw["OnWorkflowEvent"].([]any)
+	if len(events) != 2 || fmt.Sprint(events[0]) != "2" {
+		t.Fatalf("OnWorkflowEvent = %v, want marker 2 and one handler", raw["OnWorkflowEvent"])
+	}
+	stored, _ := events[1].(map[string]any)
+	if types, _ := stored["EventTypes"].([]any); len(types) != 3 || fmt.Sprint(types[0]) != "1" {
+		t.Errorf("EventTypes = %v, want marker 1 and two types", stored["EventTypes"])
+	}
+	kinds := map[string]string{}
+	var walk func(v any)
+	walk = func(v any) {
+		switch x := v.(type) {
+		case map[string]any:
+			if ev, ok := x["OnCreatedEvent"].(map[string]any); ok {
+				name, _ := x["Name"].(string)
+				kinds[name] = fmt.Sprint(ev["$Type"], " ", ev["Microflow"])
+			}
+			for _, c := range x {
+				walk(c)
+			}
+		case []any:
+			for _, c := range x {
+				walk(c)
+			}
+		}
+	}
+	walk(raw)
+	if kinds["Review"] != "Workflows$MicroflowBasedEvent MyFirstModule.ACT_Assign" {
+		t.Errorf("Review OnCreatedEvent = %q", kinds["Review"])
+	}
+	if kinds["Plain"] != "Workflows$NoEvent <nil>" {
+		t.Errorf("Plain OnCreatedEvent = %q", kinds["Plain"])
+	}
+}
diff --git a/mdl/backend/modelsdk/workflow_read.go b/mdl/backend/modelsdk/workflow_read.go
index ac5fdc279d..b5dd4fb289 100644
--- a/mdl/backend/modelsdk/workflow_read.go
+++ b/mdl/backend/modelsdk/workflow_read.go
@@ -54,11 +54,34 @@ func (b *Backend) ListWorkflows() ([]*workflows.Workflow, error) {
 		if f, ok := g.Flow().(*genWf.Flow); ok && f != nil {
 			w.Flow = workflowFlowFromGen(f)
 		}
+		w.EventHandlers = workflowEventHandlersFromGen(g.OnWorkflowEventItems())
 		out = append(out, w)
 	}
 	return out, nil
 }
 
+// workflowEventHandlersFromGen converts a workflow's OnWorkflowEvent handlers.
+func workflowEventHandlersFromGen(items []element.Element) []*workflows.WorkflowEventHandler {
+	var out []*workflows.WorkflowEventHandler
+	for _, el := range items {
+		h, ok := el.(*genWf.WorkflowEventHandler)
+		if !ok || h == nil {
+			continue
+		}
+		wh := &workflows.WorkflowEventHandler{
+			Description:   h.Description(),
+			Documentation: h.Documentation(),
+			EventTypes:    append([]string(nil), h.EventTypesItems()...),
+		}
+		wh.ID = model.ID(h.ID())
+		if mh, ok := h.MicroflowEventHandler().(*genWf.MicroflowEventHandler); ok && mh != nil {
+			wh.Microflow = mh.MicroflowQualifiedName()
+		}
+		out = append(out, wh)
+	}
+	return out
+}
+
 // workflowFlowFromGen converts a gen Flow to the semantic Flow.
 func workflowFlowFromGen(g *genWf.Flow) *workflows.Flow {
 	f := &workflows.Flow{}
diff --git a/mdl/backend/modelsdk/workflow_write.go b/mdl/backend/modelsdk/workflow_write.go
index 8c01b05832..6f815239e4 100644
--- a/mdl/backend/modelsdk/workflow_write.go
+++ b/mdl/backend/modelsdk/workflow_write.go
@@ -36,6 +36,7 @@ func init() {
 		"Workflows$TimerBoundaryEvent", "Workflows$InterruptingTimerBoundaryEvent",
 		"Workflows$NonInterruptingTimerBoundaryEvent",
 		"Workflows$MicroflowCallParameterMapping", "Workflows$WorkflowCallParameterMapping",
+		"Workflows$WorkflowEventHandler",
 	} {
 		codec.RegisterListMarker(t, 2)
 	}
@@ -196,7 +197,14 @@ func workflowToGen(wf *workflows.Workflow) element.Element {
 	}
 	addPart(g, "Flow", flowToGen(flow))
 	addStr(g, "Name", wf.Name)
-	// OnWorkflowEvent: empty marker-2 list (via MandatoryListMarkers).
+	// OnWorkflowEvent: a marker-2 list; empty via MandatoryListMarkers.
+	if len(wf.EventHandlers) > 0 {
+		handlers := make([]element.Element, 0, len(wf.EventHandlers))
+		for _, h := range wf.EventHandlers {
+			handlers = append(handlers, workflowEventHandlerToGen(h))
+		}
+		addPartList(g, "OnWorkflowEvent", handlers)
+	}
 	if wf.Parameter != nil {
 		addPart(g, "Parameter", workflowParameterToGen(wf.Parameter))
 	}
@@ -213,6 +221,31 @@ func workflowToGen(wf *workflows.Workflow) element.Element {
 	return g
 }
 
+// workflowEventHandlerToGen builds a Workflows$WorkflowEventHandler in the key
+// order ako/TestApp (11.14.0) stores: Description, Documentation, EventTypes (a
+// marker-1 string list), MicroflowEventHandler.
+func workflowEventHandlerToGen(h *workflows.WorkflowEventHandler) element.Element {
+	g := newElem("Workflows$WorkflowEventHandler", string(h.ID))
+	addStr(g, "Description", h.Description)
+	addStr(g, "Documentation", h.Documentation)
+	addStrList(g, "EventTypes", h.EventTypes)
+	mh := newElem("Workflows$MicroflowEventHandler", "")
+	addStr(mh, "Microflow", h.Microflow)
+	addPart(g, "MicroflowEventHandler", mh)
+	return g
+}
+
+// onCreatedEventToGen builds a user task's OnCreatedEvent: the microflow when one
+// is set, the NoEvent marker otherwise.
+func onCreatedEventToGen(microflow string) element.Element {
+	if microflow == "" {
+		return newElem("Workflows$NoEvent", "")
+	}
+	ev := newElem("Workflows$MicroflowBasedEvent", "")
+	addStr(ev, "Microflow", microflow)
+	return ev
+}
+
 func flowToGen(flow *workflows.Flow) element.Element {
 	g := newElem("Workflows$Flow", string(flow.ID))
 	acts := make([]element.Element, 0, len(flow.Activities))
@@ -296,7 +329,7 @@ func userTaskToGen(a *workflows.UserTask) element.Element {
 	}
 	addStr(g, "DueDate", a.DueDate)
 	addStr(g, "Name", a.Name)
-	addPart(g, "OnCreatedEvent", newElem("Workflows$NoEvent", ""))
+	addPart(g, "OnCreatedEvent", onCreatedEventToGen(a.OnCreated))
 
 	outcomes := make([]element.Element, 0, len(a.Outcomes))
 	for _, o := range a.Outcomes {
diff --git a/mdl/executor/cmd_workflows.go b/mdl/executor/cmd_workflows.go
index 5b470c8069..4aa8714304 100644
--- a/mdl/executor/cmd_workflows.go
+++ b/mdl/executor/cmd_workflows.go
@@ -220,6 +220,8 @@ func describeWorkflowToString(ctx *ExecContext, name ast.QualifiedName) (string,
 		lines = append(lines, fmt.Sprintf("  due date %s", mdlQuoted(targetWf.DueDate)))
 	}
 
+	lines = append(lines, formatWorkflowEventHandlers(ctx, targetWf.EventHandlers)...)
+
 	lines = append(lines, "")
 
 	lines = append(lines, "begin")
@@ -508,6 +510,10 @@ func formatUserTask(a *workflows.UserTask, indent string) []string {
 		}
 	}
 
+	if a.OnCreated != "" {
+		lines = append(lines, fmt.Sprintf("%s  on created microflow %s", indent, a.OnCreated))
+	}
+
 	if a.UserTaskEntity != "" {
 		lines = append(lines, fmt.Sprintf("%s  entity %s", indent, a.UserTaskEntity))
 	}
@@ -550,6 +556,65 @@ func formatUserTask(a *workflows.UserTask, indent string) []string {
 	return lines
 }
 
+// formatWorkflowEventHandlers emits the header's handler clauses. A handler
+// subscribed to exactly the types the project version knows is written as
+// `on any workflow event`, which is what re-executing it would store again; any
+// other list is written out, one type per line when it is long.
+func formatWorkflowEventHandlers(ctx *ExecContext, handlers []*workflows.WorkflowEventHandler) []string {
+	var all []string
+	if pv := ctx.Backend.ProjectVersion(); pv != nil {
+		all, _, _ = allWorkflowEventTypes(pv.MajorVersion, pv.MinorVersion, pv.PatchVersion)
+	}
+	var lines []string
+	for _, h := range handlers {
+		if h == nil {
+			continue
+		}
+		as := ""
+		if h.Description != "" {
+			as = " as " + mdlQuoted(h.Description)
+		}
+		switch {
+		case len(h.EventTypes) == 0:
+			// The grammar has no spelling for an empty list; say so rather than
+			// emit a clause that means something else. Rewrites refuse it.
+			lines = append(lines, fmt.Sprintf("  -- workflow event handler %s (microflow %s) subscribes to no event types, which MDL cannot state",
+				mdlQuoted(h.Description), h.Microflow))
+		case len(all) > 0 && sameStringSet(h.EventTypes, all):
+			lines = append(lines, fmt.Sprintf("  on any workflow event microflow %s%s", h.Microflow, as))
+		case len(h.EventTypes) <= 3:
+			lines = append(lines, fmt.Sprintf("  on workflow events (%s) microflow %s%s", strings.Join(h.EventTypes, ", "), h.Microflow, as))
+		default:
+			lines = append(lines, "  on workflow events (")
+			for i, t := range h.EventTypes {
+				sep := ","
+				if i == len(h.EventTypes)-1 {
+					sep = ""
+				}
+				lines = append(lines, "    "+t+sep)
+			}
+			lines = append(lines, fmt.Sprintf("  ) microflow %s%s", h.Microflow, as))
+		}
+	}
+	return lines
+}
+
+func sameStringSet(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	set := make(map[string]bool, len(a))
+	for _, s := range a {
+		set[s] = true
+	}
+	for _, s := range b {
+		if !set[s] {
+			return false
+		}
+	}
+	return len(set) == len(b)
+}
+
 // formatCallMicroflowTask formats a call microflow task for describe output.
 func formatCallMicroflowTask(a *workflows.CallMicroflowTask, indent string) []string {
 	var lines []string
diff --git a/mdl/executor/cmd_workflows_write.go b/mdl/executor/cmd_workflows_write.go
index 6896034a80..e7fd28eff9 100644
--- a/mdl/executor/cmd_workflows_write.go
+++ b/mdl/executor/cmd_workflows_write.go
@@ -65,6 +65,16 @@ func execCreateWorkflow(ctx *ExecContext, s *ast.CreateWorkflowStmt) error {
 	// Note this runs BEFORE findOrCreateModule, which auto-creates a module on
 	// demand: without it a typo'd module name silently produced a new module
 	// rather than an error.
+	if vs := ValidateWorkflowEventTypes(s); len(vs) > 0 {
+		return mdlerrors.NewValidationf("%s\n  → %s", vs[0].Message, vs[0].Suggestion)
+	}
+	if len(s.EventHandlers) > 0 {
+		if err := checkFeature(ctx, "workflows", "event_handlers", "on workflow events",
+			"remove the `on … workflow event` clauses, or upgrade the project"); err != nil {
+			return err
+		}
+	}
+
 	if refErrors := validateWorkflowStatementRefs(ctx, s, nil); len(refErrors) > 0 {
 		return mdlerrors.NewValidationf("workflow '%s' has reference errors:\n  - %s",
 			s.Name.String(), strings.Join(refErrors, "\n  - "))
@@ -93,6 +103,7 @@ func execCreateWorkflow(ctx *ExecContext, s *ast.CreateWorkflowStmt) error {
 	// exclusion forward (#914).
 	existingExcluded := false
 	var existingDocumentation string
+	var existingHandlers []*workflows.WorkflowEventHandler
 	haveExistingWf := false
 	if existing, ok := pickLive(existingWorkflows,
 		func(w *workflows.Workflow) bool {
@@ -107,6 +118,7 @@ func execCreateWorkflow(ctx *ExecContext, s *ast.CreateWorkflowStmt) error {
 		existingExcluded = existing.Excluded
 		existingContainer = existing.ContainerID
 		existingDocumentation = existing.Documentation
+		existingHandlers = existing.EventHandlers
 		haveExistingWf = true
 
 		// Refuse a rewrite that would delete a stored construct this statement
@@ -154,6 +166,12 @@ func execCreateWorkflow(ctx *ExecContext, s *ast.CreateWorkflowStmt) error {
 	// Due date
 	wf.DueDate = s.DueDate
 
+	handlers, err := buildWorkflowEventHandlers(ctx, s.EventHandlers, existingHandlers)
+	if err != nil {
+		return err
+	}
+	wf.EventHandlers = handlers
+
 	// Build activities with implicit start/end
 	flow := &workflows.Flow{}
 	flow.ID = model.ID(generateWorkflowUUID())
@@ -312,6 +330,52 @@ func buildWorkflowActivity(node ast.WorkflowActivityNode) workflows.WorkflowActi
 	}
 }
 
+// buildWorkflowEventHandlers turns the header's handler clauses into stored
+// handlers. `any workflow event` becomes the list the project version knows,
+// because that is what Studio Pro stores; a named list is written in Studio
+// Pro's order. A handler's documentation cannot be written from MDL, so a
+// rewrite carries it from the stored handler with the same microflow and
+// description.
+func buildWorkflowEventHandlers(ctx *ExecContext, nodes []ast.WorkflowEventHandlerNode, stored []*workflows.WorkflowEventHandler) ([]*workflows.WorkflowEventHandler, error) {
+	var out []*workflows.WorkflowEventHandler
+	for _, n := range nodes {
+		h := &workflows.WorkflowEventHandler{
+			Description: n.Description,
+			Microflow:   n.Microflow.String(),
+		}
+		h.ID = model.ID(generateWorkflowUUID())
+		if n.AnyEvent {
+			pv := ctx.Backend.ProjectVersion()
+			if pv == nil {
+				return nil, mdlerrors.NewUnsupported("`on any workflow event` needs the project's Mendix version, which is not available")
+			}
+			types, _, ok := allWorkflowEventTypes(pv.MajorVersion, pv.MinorVersion, pv.PatchVersion)
+			if !ok {
+				return nil, mdlerrors.NewUnsupported(fmt.Sprintf(
+					"`on any workflow event`: the event types of Mendix %d.%d.%d are not known — name them instead",
+					pv.MajorVersion, pv.MinorVersion, pv.PatchVersion))
+			}
+			h.EventTypes = types
+		} else {
+			var names []string
+			for _, t := range n.EventTypes {
+				if name, ok := canonicalWorkflowEventType(t); ok {
+					names = append(names, name)
+				}
+			}
+			h.EventTypes = sortWorkflowEventTypes(names)
+		}
+		for _, sh := range stored {
+			if sh != nil && strings.EqualFold(sh.Microflow, h.Microflow) && sh.Description == h.Description {
+				h.Documentation = sh.Documentation
+				break
+			}
+		}
+		out = append(out, h)
+	}
+	return out, nil
+}
+
 func buildUserTask(n *ast.WorkflowUserTaskNode) *workflows.UserTask {
 	task := &workflows.UserTask{}
 	task.ID = model.ID(generateWorkflowUUID())
@@ -329,6 +393,10 @@ func buildUserTask(n *ast.WorkflowUserTaskNode) *workflows.UserTask {
 		task.UserTaskEntity = n.Entity.Module + "." + n.Entity.Name
 	}
 
+	if n.OnCreated.Module != "" {
+		task.OnCreated = n.OnCreated.String()
+	}
+
 	// Targeting
 	switch n.Targeting.Kind {
 	case "microflow":
diff --git a/mdl/executor/validate_workflow.go b/mdl/executor/validate_workflow.go
index 1834886e1d..3ac765a5a5 100644
--- a/mdl/executor/validate_workflow.go
+++ b/mdl/executor/validate_workflow.go
@@ -122,6 +122,7 @@ func ValidateWorkflow(stmt *ast.CreateWorkflowStmt) []linter.Violation {
 	})
 	out = append(out, ValidateWorkflowJumpTargets(stmt)...)
 	out = append(out, ValidateWorkflowEnds(stmt)...)
+	out = append(out, ValidateWorkflowEventTypes(stmt)...)
 	return out
 }
 
diff --git a/mdl/executor/validate_workflow_handlers.go b/mdl/executor/validate_workflow_handlers.go
new file mode 100644
index 0000000000..df2bab0e9a
--- /dev/null
+++ b/mdl/executor/validate_workflow_handlers.go
@@ -0,0 +1,200 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// Checks for the two handler hooks a workflow can declare: a user task's
+// on-created microflow and the workflow's event handlers.
+//
+// Signatures, measured on 11.13.0 (one task or handler per shape, verdict = the
+// literal `mx check` line):
+//
+//	on created (WorkflowUserTask, Ctx)                 0 errors
+//	on created (Ctx, WorkflowUserTask)                 0 errors — order is free
+//	on created (WorkflowUserTask) / (Ctx) / ()         CE6683
+//	on created (WorkflowUserTask, Ctx, String)         CE6683 — exactly two
+//	on created (WorkflowUserTask, <specialization>)    CE6683
+//	on created returning Boolean                       CE5012
+//	event handler (WorkflowEvent, WorkflowRecord,
+//	               WorkflowActivityRecord)             0 errors, in any order
+//	event handler (WorkflowEvent) / () / (+ String)
+//	              / (WorkflowEvent, Ctx)               CE6691
+//	event handler listing an invented event type       0 errors (!)
+//	event handler with an empty event type list        0 errors
+//
+// The invented-type row is why event types are checked here at all: mxbuild
+// does not, so a misspelt type would be written and never fire.
+package executor
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/mdl/linter"
+)
+
+const (
+	workflowEventEntity          = "System.WorkflowEvent"
+	workflowRecordEntity         = "System.WorkflowRecord"
+	workflowActivityRecordEntity = "System.WorkflowActivityRecord"
+)
+
+// ValidateWorkflowEventTypes reports an event type name that is not a workflow
+// event type (MDL-WF12). It needs no project, so a typo is caught by a plain
+// `mxcli check`; exec calls it too, because exec is reachable without check.
+func ValidateWorkflowEventTypes(stmt *ast.CreateWorkflowStmt) []linter.Violation {
+	var out []linter.Violation
+	for _, h := range stmt.EventHandlers {
+		for _, t := range h.EventTypes {
+			if _, ok := canonicalWorkflowEventType(t); ok {
+				continue
+			}
+			out = append(out, linter.Violation{
+				RuleID:   "MDL-WF12",
+				Severity: linter.SeverityError,
+				Location: workflowLocation(stmt.Name),
+				Message: fmt.Sprintf("workflow '%s': '%s' is not a workflow event type — mxbuild accepts any name here "+
+					"and the handler would never run for it", stmt.Name.String(), t),
+				Suggestion: "use one of: " + strings.Join(workflowEventTypeOrder, ", ") +
+					" — or `on any workflow event`",
+			})
+		}
+	}
+	return out
+}
+
+// validateWorkflowEventHandlers checks the header's handlers against the
+// project: each microflow resolves and has the handler signature, and each event
+// type exists in the project's Mendix version.
+func validateWorkflowEventHandlers(ctx *ExecContext, s *ast.CreateWorkflowStmt, sc *scriptContext) []string {
+	if ctx == nil || ctx.Backend == nil || !ctx.Connected() || len(s.EventHandlers) == 0 {
+		return nil
+	}
+	var errs []string
+	pv := ctx.Backend.ProjectVersion()
+	var known map[string]bool
+	for _, h := range s.EventHandlers {
+		label := workflowEventHandlerLabel(h)
+		if qn := h.Microflow.String(); qn != "" && qn != "." {
+			if known == nil {
+				known = buildMicroflowQualifiedNames(ctx)
+			}
+			if !known[qn] && (sc == nil || !sc.microflows[qn]) {
+				errs = append(errs, fmt.Sprintf("microflow not found: %s (referenced by %s)", qn, label))
+			}
+		}
+		if pv == nil {
+			continue
+		}
+		if h.AnyEvent {
+			if _, _, ok := allWorkflowEventTypes(pv.MajorVersion, pv.MinorVersion, pv.PatchVersion); !ok {
+				errs = append(errs, fmt.Sprintf(
+					"%s: which event types Mendix %d.%d.%d has is not known to mxcli — Studio Pro stores the list, not "+
+						"\"any\", and the set is measured only from 11.6.0 on; name the types instead: "+
+						"`on workflow events (UserTaskStarted, UserTaskEnded) microflow …`",
+					label, pv.MajorVersion, pv.MinorVersion, pv.PatchVersion))
+			}
+			continue
+		}
+		for _, t := range h.EventTypes {
+			name, ok := canonicalWorkflowEventType(t)
+			if !ok {
+				continue // MDL-WF12
+			}
+			if lastAbsent, missing := workflowEventTypeMissingIn(name, pv.MajorVersion, pv.MinorVersion, pv.PatchVersion); missing {
+				errs = append(errs, fmt.Sprintf(
+					"%s: event type %s does not exist in Mendix %d.%d.%d (it is absent from %s)",
+					label, name, pv.MajorVersion, pv.MinorVersion, pv.PatchVersion, lastAbsent))
+			}
+		}
+	}
+	if c := newWorkflowTaskSignatureChecker(ctx, sc); c != nil {
+		for _, h := range s.EventHandlers {
+			errs = appendIfSet(errs, c.checkEventHandler(workflowEventHandlerLabel(h), h.Microflow.String()))
+		}
+	}
+	return errs
+}
+
+func workflowEventHandlerLabel(h ast.WorkflowEventHandlerNode) string {
+	if h.Description != "" {
+		return fmt.Sprintf("workflow event handler '%s'", h.Description)
+	}
+	return "workflow event handler " + h.Microflow.String()
+}
+
+// checkOnCreated reports an on-created microflow that is not exactly
+// System.WorkflowUserTask plus the context entity (CE6683), or that returns a
+// value (CE5012). A generalization of the context entity is let through: it is
+// accepted for targeting, unmeasured here, and refusing it would be a guess.
+func (c *workflowTaskSignatureChecker) checkOnCreated(label, mfQN, contextEntity string) string {
+	if mfQN == "" || mfQN == "." {
+		return ""
+	}
+	sig, ok := c.flowSignature(mfQN)
+	if !ok || sig == nil {
+		return ""
+	}
+	if contextEntity != "" && contextEntity != "." && c.pairMismatch(sig, workflowUserTaskEntity, contextEntity) {
+		return fmt.Sprintf(
+			"%s: on-created microflow %s takes %s — it must take exactly two parameters, %s and the workflow's "+
+				"context entity %s, in either order; the build fails CE6683",
+			label, mfQN, describeFlowParams(sig), workflowUserTaskEntity, contextEntity)
+	}
+	// Only a return type the script declared is known; a stored flow's is not
+	// read, and unknown is not wrong.
+	if sig.ReturnKind != ast.TypeUnknown && sig.ReturnKind != ast.TypeVoid {
+		return fmt.Sprintf(
+			"%s: on-created microflow %s returns %s — it must return nothing; the build fails CE5012",
+			label, mfQN, sig.ReturnKind.String())
+	}
+	return ""
+}
+
+// pairMismatch reports a signature that is provably not (fixed, context) in
+// either order — the shape targeting and on-created microflows share.
+func (c *workflowTaskSignatureChecker) pairMismatch(sig *flowSignature, fixedEntity, contextEntity string) bool {
+	if len(sig.Params) != 2 {
+		return true
+	}
+	for i, p := range sig.Params {
+		if !strings.EqualFold(p.Entity, fixedEntity) {
+			continue
+		}
+		other := sig.Params[1-i]
+		if other.Entity == "" {
+			continue
+		}
+		if c.contextAssignableTo(contextEntity, other.Entity) != inheritanceNo {
+			return false
+		}
+	}
+	return true
+}
+
+// checkEventHandler reports a handler microflow that does not take exactly the
+// three workflow event records (CE6691).
+func (c *workflowTaskSignatureChecker) checkEventHandler(label, mfQN string) string {
+	if mfQN == "" || mfQN == "." {
+		return ""
+	}
+	sig, ok := c.flowSignature(mfQN)
+	if !ok || sig == nil {
+		return ""
+	}
+	want := []string{workflowEventEntity, workflowRecordEntity, workflowActivityRecordEntity}
+	matches := len(sig.Params) == len(want)
+	if matches {
+		seen := map[string]bool{}
+		for _, p := range sig.Params {
+			seen[strings.ToLower(p.Entity)] = true
+		}
+		for _, w := range want {
+			matches = matches && seen[strings.ToLower(w)]
+		}
+	}
+	if matches {
+		return ""
+	}
+	return fmt.Sprintf(
+		"%s: microflow %s takes %s — a workflow event handler must take exactly %s, in any order; the build fails CE6691",
+		label, mfQN, describeFlowParams(sig), strings.Join(want, ", "))
+}
diff --git a/mdl/executor/validate_workflow_handlers_test.go b/mdl/executor/validate_workflow_handlers_test.go
new file mode 100644
index 0000000000..3405c3689c
--- /dev/null
+++ b/mdl/executor/validate_workflow_handlers_test.go
@@ -0,0 +1,192 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/backend/mock"
+	"github.com/mendixlabs/mxcli/mdl/types"
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/domainmodel"
+	"github.com/mendixlabs/mxcli/sdk/microflows"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// wfHandlerCtx is a project shaped like the handler spike (mxbuild 11.13.0): a
+// context entity Ctx and a Base <- Sub pair, an on-created microflow and an
+// event handler microflow per signature shape, and one stored workflow for ALTER.
+func wfHandlerCtx(t *testing.T, major, minor, patch int) *ExecContext {
+	t.Helper()
+	mod := &model.Module{Name: "M"}
+	mod.ID = "mod1"
+	ctxEnt := &domainmodel.Entity{Name: "Ctx"}
+	base := &domainmodel.Entity{Name: "Base"}
+	sub := &domainmodel.Entity{Name: "Sub", GeneralizationRef: "M.Base"}
+	for _, e := range []*domainmodel.Entity{ctxEnt, base, sub} {
+		e.ContainerID = "dm1"
+	}
+	dm := &domainmodel.DomainModel{Entities: []*domainmodel.Entity{ctxEnt, base, sub}}
+	dm.ID = "dm1"
+	dm.ContainerID = "mod1"
+
+	obj := func(qn string) microflows.DataType { return &microflows.ObjectType{EntityQualifiedName: qn} }
+	mf := func(name string, types ...microflows.DataType) *microflows.Microflow {
+		m := &microflows.Microflow{Name: name}
+		m.ContainerID = "mod1"
+		for i, dt := range types {
+			m.Parameters = append(m.Parameters, &microflows.MicroflowParameter{Name: "p" + string(rune('a'+i)), Type: dt})
+		}
+		return m
+	}
+	stored := &workflows.Workflow{Name: "Stored", Parameter: &workflows.WorkflowParameter{EntityRef: "M.Ctx"}}
+	stored.ContainerID = "mod1"
+
+	mb := &mock.MockBackend{
+		IsConnectedFunc: func() bool { return true },
+		ProjectVersionFunc: func() *types.ProjectVersion {
+			return &types.ProjectVersion{MajorVersion: major, MinorVersion: minor, PatchVersion: patch}
+		},
+		ListModulesFunc: func() ([]*model.Module, error) { return []*model.Module{mod}, nil },
+		GetModuleByNameFunc: func(name string) (*model.Module, error) {
+			if strings.EqualFold(name, "M") {
+				return mod, nil
+			}
+			return nil, nil
+		},
+		ListDomainModelsFunc: func() ([]*domainmodel.DomainModel, error) { return []*domainmodel.DomainModel{dm}, nil },
+		GetDomainModelFunc:   func(model.ID) (*domainmodel.DomainModel, error) { return dm, nil },
+		ListMicroflowsFunc: func() ([]*microflows.Microflow, error) {
+			return []*microflows.Microflow{
+				mf("OC_Good", obj("System.WorkflowUserTask"), obj("M.Ctx")),
+				mf("OC_Reversed", obj("M.Ctx"), obj("System.WorkflowUserTask")),
+				mf("OC_NoCtx", obj("System.WorkflowUserTask")),
+				mf("OC_None"),
+				mf("OC_Extra", obj("System.WorkflowUserTask"), obj("M.Ctx"), &microflows.StringType{}),
+				mf("OC_TakesBase", obj("System.WorkflowUserTask"), obj("M.Base")),
+				mf("OC_TakesSub", obj("System.WorkflowUserTask"), obj("M.Sub")),
+				mf("EH_Good", obj("System.WorkflowEvent"), obj("System.WorkflowRecord"), obj("System.WorkflowActivityRecord")),
+				mf("EH_Reversed", obj("System.WorkflowActivityRecord"), obj("System.WorkflowRecord"), obj("System.WorkflowEvent")),
+				mf("EH_EventOnly", obj("System.WorkflowEvent")),
+				mf("EH_None"),
+				mf("EH_Extra", obj("System.WorkflowEvent"), obj("System.WorkflowRecord"), obj("System.WorkflowActivityRecord"), &microflows.StringType{}),
+				mf("EH_Ctx", obj("System.WorkflowEvent"), obj("M.Ctx")),
+			}, nil
+		},
+		ListWorkflowsFunc: func() ([]*workflows.Workflow, error) { return []*workflows.Workflow{stored}, nil },
+	}
+	ctx, _ := newMockCtx(t, withBackend(mb))
+	return ctx
+}
+
+// Each row is a shape from the mxbuild spike (11.13.0); want is the CE code the
+// build reported, "" where it built at 0 errors.
+func TestWorkflowHandlers_OnCreatedSignature(t *testing.T) {
+	wf := func(ctxEntity, mf string) string {
+		return `create workflow M.W parameter $C: ` + ctxEntity +
+			` begin user task T 'c' on created microflow ` + mf + ` outcomes 'a' { }; end workflow;`
+	}
+	cases := []struct{ name, src, want string }{
+		{"(WorkflowUserTask, Ctx)", wf("M.Ctx", "M.OC_Good"), ""},
+		{"(Ctx, WorkflowUserTask) reversed", wf("M.Ctx", "M.OC_Reversed"), ""},
+		{"(WorkflowUserTask) only", wf("M.Ctx", "M.OC_NoCtx"), "CE6683"},
+		{"no parameters", wf("M.Ctx", "M.OC_None"), "CE6683"},
+		{"extra parameter", wf("M.Ctx", "M.OC_Extra"), "CE6683"},
+		{"specialization of the context", wf("M.Base", "M.OC_TakesSub"), "CE6683"},
+		{"generalization of the context is not refused", wf("M.Sub", "M.OC_TakesBase"), ""},
+		{"multi user task", `create workflow M.W parameter $C: M.Ctx begin multi user task T 'c' on created microflow M.OC_None outcomes 'a' { }; end workflow;`, "CE6683"},
+		{"nested in an outcome", `create workflow M.W parameter $C: M.Ctx begin user task T 'c' outcomes 'a' { user task U 'u' on created microflow M.OC_None outcomes 'x' { }; }; end workflow;`, "CE6683"},
+		{"script microflow returning a value", `create microflow M.ScriptOC ( $t: System.WorkflowUserTask, $c: M.Ctx ) returns boolean as $r begin return true; end;
+` + wf("M.Ctx", "M.ScriptOC"), "CE5012"},
+		{"script microflow returning nothing", `create microflow M.ScriptOC ( $t: System.WorkflowUserTask, $c: M.Ctx ) begin end;
+` + wf("M.Ctx", "M.ScriptOC"), ""},
+		{"unknown microflow", wf("M.Ctx", "M.Nope"), "microflow not found: M.Nope"},
+		{"alter insert", `alter workflow M.Stored insert after T user task U 'u' on created microflow M.OC_NoCtx outcomes 'a' { };`, "CE6683"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			assertHandlerVerdict(t, checkScript(t, wfHandlerCtx(t, 11, 13, 0), c.src), c.want)
+		})
+	}
+}
+
+func TestWorkflowHandlers_EventHandlerSignature(t *testing.T) {
+	wf := func(mf string) string {
+		return `create workflow M.W parameter $C: M.Ctx on workflow events (UserTaskStarted) microflow ` + mf +
+			` as 'h' begin user task T 'c' outcomes 'a' { }; end workflow;`
+	}
+	cases := []struct{ name, src, want string }{
+		{"the three records", wf("M.EH_Good"), ""},
+		{"the three records reversed", wf("M.EH_Reversed"), ""},
+		{"WorkflowEvent only", wf("M.EH_EventOnly"), "CE6691"},
+		{"no parameters", wf("M.EH_None"), "CE6691"},
+		{"extra parameter", wf("M.EH_Extra"), "CE6691"},
+		{"context entity instead", wf("M.EH_Ctx"), "CE6691"},
+		{"unknown microflow", wf("M.Nope"), "microflow not found: M.Nope"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			assertHandlerVerdict(t, checkScript(t, wfHandlerCtx(t, 11, 13, 0), c.src), c.want)
+		})
+	}
+}
+
+// Event types are version-dependent, and mxbuild does not check them.
+func TestWorkflowHandlers_EventTypesPerVersion(t *testing.T) {
+	named := `create workflow M.W parameter $C: M.Ctx on workflow events (NotificationStarted) microflow M.EH_Good begin user task T 'c' outcomes 'a' { }; end workflow;`
+	anyEvent := `create workflow M.W parameter $C: M.Ctx on any workflow event microflow M.EH_Good begin user task T 'c' outcomes 'a' { }; end workflow;`
+	cases := []struct {
+		name                string
+		major, minor, patch int
+		src, want           string
+	}{
+		{"type present", 11, 13, 0, named, ""},
+		{"type measured absent", 11, 10, 0, named, "does not exist in Mendix 11.10.0"},
+		{"type between points is let through", 11, 12, 0, named, ""},
+		{"any, measured version", 11, 13, 0, anyEvent, ""},
+		{"any, below every measured point", 10, 24, 0, anyEvent, "not known to mxcli"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			assertHandlerVerdict(t, checkScript(t, wfHandlerCtx(t, c.major, c.minor, c.patch), c.src), c.want)
+		})
+	}
+}
+
+// The signature rules are measured on 11.13 only — the MDL-WF07 precedent.
+func TestWorkflowHandlers_SignaturesNotAppliedBeforeMendix11(t *testing.T) {
+	src := `create workflow M.W parameter $C: M.Ctx on workflow events (UserTaskStarted) microflow M.EH_None begin user task T 'c' on created microflow M.OC_None outcomes 'a' { }; end workflow;`
+	assertHandlerVerdict(t, checkScript(t, wfHandlerCtx(t, 10, 24, 0), src), "")
+}
+
+// A misspelt type builds at 0 errors and never fires, so it is a syntax-phase
+// error that needs no project.
+func TestWorkflowHandlers_UnknownEventTypeIsMDLWF12(t *testing.T) {
+	stmt := parseWorkflowStmt(t, `create workflow M.W on workflow events (UserTaskStart, usertaskended) microflow M.EH_Good begin end workflow;`)
+	vs := ValidateWorkflow(stmt)
+	var hits []string
+	for _, v := range vs {
+		if v.RuleID == "MDL-WF12" {
+			hits = append(hits, v.Message)
+		}
+	}
+	if len(hits) != 1 || !strings.Contains(hits[0], "UserTaskStart") {
+		t.Errorf("want one MDL-WF12 naming UserTaskStart (the lower-case spelling is valid), got %v", hits)
+	}
+}
+
+func assertHandlerVerdict(t *testing.T, got, want string) {
+	t.Helper()
+	if want != "" {
+		if !strings.Contains(got, want) {
+			t.Errorf("expected %q, got:\n%s", want, got)
+		}
+		return
+	}
+	for _, code := range []string{"CE6683", "CE6691", "CE5012", "not found", "does not exist", "not known"} {
+		if strings.Contains(got, code) {
+			t.Errorf("expected no handler error, got %q:\n%s", code, got)
+		}
+	}
+}
diff --git a/mdl/executor/validate_workflow_refs.go b/mdl/executor/validate_workflow_refs.go
index 20a75e1d48..0ae345c4be 100644
--- a/mdl/executor/validate_workflow_refs.go
+++ b/mdl/executor/validate_workflow_refs.go
@@ -142,6 +142,9 @@ func validateWorkflowReferences(ctx *ExecContext, activities []ast.WorkflowActiv
 			if qn := n.Targeting.Microflow.String(); qn != "." && qn != "" && !knownMicroflow(qn) {
 				report("microflow", qn, "user task targeting")
 			}
+			if qn := n.OnCreated.String(); qn != "." && qn != "" && !knownMicroflow(qn) {
+				report("microflow", qn, "user task on created")
+			}
 		}
 	})
 	return errs
@@ -175,6 +178,7 @@ func validateWorkflowStatementRefs(ctx *ExecContext, s *ast.CreateWorkflowStmt,
 	}
 	errs = append(errs, bareTimerBoundaryEventErrors(ctx, s.Activities, 0)...)
 	errs = append(errs, validateWorkflowReferences(ctx, s.Activities, sc)...)
+	errs = append(errs, validateWorkflowEventHandlers(ctx, s, sc)...)
 	// Then the signatures of the page and targeting microflow each user task
 	// hands work to — names that resolve can still be the wrong shape (CE7410,
 	// CE7412, CE6677). A target that did not resolve is skipped there, so it is
diff --git a/mdl/executor/validate_workflow_rewrite.go b/mdl/executor/validate_workflow_rewrite.go
index 4a80524e4a..eff5ee2e54 100644
--- a/mdl/executor/validate_workflow_rewrite.go
+++ b/mdl/executor/validate_workflow_rewrite.go
@@ -11,6 +11,8 @@ import (
 	"github.com/mendixlabs/mxcli/mdl/ast"
 	mdlerrors "github.com/mendixlabs/mxcli/mdl/errors"
 	"github.com/mendixlabs/mxcli/model"
+
+	"go.mongodb.org/mongo-driver/bson/primitive"
 )
 
 // checkNoDroppedWorkflowConstructs refuses a CREATE OR REPLACE/MODIFY WORKFLOW
@@ -42,10 +44,10 @@ func checkNoDroppedWorkflowConstructs(ctx *ExecContext, workflowID model.ID, qua
 		// path reports its own errors.
 		return nil
 	}
+	raw = plainRawUnit(raw)
 
 	// Constructs MDL cannot express at all. A rebuild writes the default for
-	// each — measured on ako/TestApp (11.14.0): an on-created microflow becomes
-	// NoEvent, workflow event handlers an empty list, a completion rule
+	// each — measured on ako/TestApp (11.14.0): a completion rule becomes
 	// Consensus on the first outcome, and describe shows an AI agent task only as
 	// a comment — so a rewrite loses them without a word. Refused outright, like
 	// an event sub-process, and every reason is listed at once.
@@ -62,6 +64,28 @@ func checkNoDroppedWorkflowConstructs(ctx *ExecContext, workflowID model.ID, qua
 			qualifiedName, strings.Join(cannotExpress, "\n  - ")))
 	}
 
+	// Handlers MDL can now state, but a statement written before it could (or
+	// from an older describe) does not: the rewrite writes what the statement
+	// says, so an unstated handler is deleted and an unstated on-created
+	// microflow reset to none. Counted, like boundary events below, because a
+	// handler has no name to match on and a task may be renamed.
+	if stored := rawEventHandlers(raw); len(stored) > len(stmt.EventHandlers) {
+		return mdlerrors.NewUnsupported(fmt.Sprintf(
+			"workflow %s has %d stored workflow event handler(s) but this statement declares %d — rewriting it would "+
+				"delete the difference:\n  - %s\n"+
+				"  Restate them (`on workflow events (…) microflow … as '…'`), which `describe workflow %s` now emits, "+
+				"or use ALTER WORKFLOW to change one activity at a time.",
+			qualifiedName, len(stored), len(stmt.EventHandlers), strings.Join(stored, "\n  - "), qualifiedName))
+	}
+	if stored, authored := rawOnCreatedMicroflows(raw), countAuthoredOnCreated(stmt.Activities); len(stored) > authored {
+		return mdlerrors.NewUnsupported(fmt.Sprintf(
+			"workflow %s has %d user task(s) with an on-created microflow but this statement declares %d — rewriting "+
+				"it would reset the difference to none:\n  - %s\n"+
+				"  Restate them (`on created microflow …`), which `describe workflow %s` now emits, or use ALTER "+
+				"WORKFLOW to change one activity at a time.",
+			qualifiedName, len(stored), authored, strings.Join(stored, "\n  - "), qualifiedName))
+	}
+
 	// Ends inside branches. MDL could not state one until `end workflow`, and
 	// describe dropped them, so a rewrite from an older describe output would
 	// delete every one — and a branch that ended the workflow would silently
@@ -176,17 +200,24 @@ func countAuthoredBoundaryEvents(activities []ast.WorkflowActivityNode) int {
 }
 
 // studioProOnlyWorkflowState lists what a stored workflow holds that a rebuild
-// from MDL would reset: workflow event handlers, AI agent tasks, and per activity
-// an on-created microflow or a completion rule other than the one mxcli writes.
+// from MDL would reset: AI agent tasks, a workflow event handler subscribed to no
+// event types (the grammar has no empty list), and per activity a completion rule
+// other than the one mxcli writes.
 func studioProOnlyWorkflowState(raw map[string]any) []string {
 	var out []string
 	for _, h := range rawList(raw["OnWorkflowEvent"]) {
-		if hm, ok := h.(map[string]any); ok {
-			microflow := ""
-			if mh, ok := hm["MicroflowEventHandler"].(map[string]any); ok {
-				microflow, _ = mh["Microflow"].(string)
+		hm, ok := h.(map[string]any)
+		if !ok {
+			continue
+		}
+		types := 0
+		for _, t := range rawList(hm["EventTypes"]) {
+			if _, ok := t.(string); ok {
+				types++
 			}
-			out = append(out, fmt.Sprintf("a workflow event handler running %s, which it would delete", orUnnamed(microflow)))
+		}
+		if types == 0 {
+			out = append(out, fmt.Sprintf("workflow event handler %s subscribes to no event types, which MDL cannot state", rawHandlerLabel(hm)))
 		}
 	}
 	walkRawDocs(raw, func(d map[string]any) {
@@ -205,12 +236,6 @@ func studioProOnlyWorkflowState(raw map[string]any) []string {
 func rawActivityState(d map[string]any) []string {
 	var out []string
 	name, _ := d["Name"].(string)
-	if ev, ok := d["OnCreatedEvent"].(map[string]any); ok {
-		if t, _ := ev["$Type"].(string); t == "Workflows$MicroflowBasedEvent" {
-			microflow, _ := ev["Microflow"].(string)
-			out = append(out, fmt.Sprintf("user task '%s' runs on-created microflow %s, which it would reset to none", name, orUnnamed(microflow)))
-		}
-	}
 	cc, ok := d["CompletionCriteria"].(map[string]any)
 	if !ok {
 		return out
@@ -265,6 +290,7 @@ func validateAlterReplaceKeepsStudioProState(ctx *ExecContext, s *ast.AlterWorkf
 	if err != nil || raw == nil {
 		return nil
 	}
+	raw = plainRawUnit(raw)
 	var errs []string
 	for _, o := range replaces {
 		act := resolveStoredActivity(wf.Flow, o.ActivityRef, o.AtPosition)
@@ -275,11 +301,15 @@ func validateAlterReplaceKeepsStudioProState(ctx *ExecContext, s *ast.AlterWorkf
 		walkRawDocs(raw, func(d map[string]any) {
 			if n, _ := d["Name"].(string); n != "" && n == act.GetName() {
 				reasons = append(reasons, rawActivityState(d)...)
+				if mf := rawOnCreatedMicroflow(d); mf != "" && !restatesOnCreated(o.NewActivity) {
+					reasons = append(reasons, fmt.Sprintf(
+						"it runs on-created microflow %s, which the replacement does not restate (add `on created microflow %s`)", mf, mf))
+				}
 			}
 		})
 		if len(reasons) > 0 {
 			errs = append(errs, fmt.Sprintf(
-				"replace activity '%s' is refused: the activity is rebuilt from the statement, and MDL cannot express what it "+
+				"replace activity '%s' is refused: the activity is rebuilt from the statement, and the statement does not carry what it "+
 					"holds — %s. Change it with SET ACTIVITY, which edits it in place, or in Studio Pro.",
 				o.ActivityRef, strings.Join(reasons, "; ")))
 		}
@@ -287,6 +317,115 @@ func validateAlterReplaceKeepsStudioProState(ctx *ExecContext, s *ast.AlterWorkf
 	return errs
 }
 
+// rawEventHandlers labels each stored workflow event handler.
+func rawEventHandlers(raw map[string]any) []string {
+	var out []string
+	for _, h := range rawList(raw["OnWorkflowEvent"]) {
+		if hm, ok := h.(map[string]any); ok {
+			out = append(out, rawHandlerLabel(hm))
+		}
+	}
+	return out
+}
+
+func rawHandlerLabel(h map[string]any) string {
+	microflow := ""
+	if mh, ok := h["MicroflowEventHandler"].(map[string]any); ok {
+		microflow, _ = mh["Microflow"].(string)
+	}
+	if d, _ := h["Description"].(string); d != "" {
+		return fmt.Sprintf("'%s' (microflow %s)", d, orUnnamed(microflow))
+	}
+	return "running microflow " + orUnnamed(microflow)
+}
+
+// rawOnCreatedMicroflows labels each stored user task that runs an on-created
+// microflow.
+func rawOnCreatedMicroflows(raw map[string]any) []string {
+	var out []string
+	walkRawDocs(raw, func(d map[string]any) {
+		if mf := rawOnCreatedMicroflow(d); mf != "" {
+			name, _ := d["Name"].(string)
+			out = append(out, fmt.Sprintf("user task '%s' runs %s", name, mf))
+		}
+	})
+	return out
+}
+
+// rawOnCreatedMicroflow returns the microflow a stored activity's OnCreatedEvent
+// runs, "" for NoEvent or none.
+func rawOnCreatedMicroflow(d map[string]any) string {
+	ev, ok := d["OnCreatedEvent"].(map[string]any)
+	if !ok {
+		return ""
+	}
+	if t, _ := ev["$Type"].(string); t != "Workflows$MicroflowBasedEvent" {
+		return ""
+	}
+	mf, _ := ev["Microflow"].(string)
+	return orUnnamed(mf)
+}
+
+func countAuthoredOnCreated(activities []ast.WorkflowActivityNode) int {
+	n := 0
+	walkWorkflowActivities(activities, func(act ast.WorkflowActivityNode) {
+		if restatesOnCreated(act) {
+			n++
+		}
+	})
+	return n
+}
+
+func restatesOnCreated(act ast.WorkflowActivityNode) bool {
+	t, ok := act.(*ast.WorkflowUserTaskNode)
+	return ok && t.OnCreated.Module != ""
+}
+
+// plainRawUnit returns a copy of a stored unit with every array and document in
+// the plain []any / map[string]any shape the guards in this file walk.
+//
+// The legacy engine decodes a unit's arrays as primitive.A — measured on a
+// workflow it wrote: OnWorkflowEvent and Flow.Activities both — and a type switch
+// on []any does not match that named type. So on the legacy engine every guard
+// here saw no list at all, and allowed each rewrite it exists to refuse (stored
+// handlers, on-created microflows, boundary events, nested Ends, AI agent tasks,
+// completion rules), while the modelsdk engine, which already returns plain
+// slices, refused them. Normalised here rather than in the backend, because
+// other raw consumers (catalog, linter) assert the primitive types.
+func plainRawUnit(raw map[string]any) map[string]any {
+	out, _ := plainRawValue(raw).(map[string]any)
+	return out
+}
+
+func plainRawValue(v any) any {
+	switch t := v.(type) {
+	case map[string]any:
+		m := make(map[string]any, len(t))
+		for k, e := range t {
+			m[k] = plainRawValue(e)
+		}
+		return m
+	case primitive.M:
+		return plainRawValue(map[string]any(t))
+	case primitive.D:
+		m := make(map[string]any, len(t))
+		for _, e := range t {
+			m[e.Key] = plainRawValue(e.Value)
+		}
+		return m
+	case []any:
+		l := make([]any, len(t))
+		for i, e := range t {
+			l[i] = plainRawValue(e)
+		}
+		return l
+	case primitive.A:
+		return plainRawValue([]any(t))
+	default:
+		return v
+	}
+}
+
 // walkRawDocs visits every sub-document of a raw unit, keys in sorted order so
 // the reasons come out the same way every time.
 func walkRawDocs(v any, visit func(map[string]any)) {
diff --git a/mdl/executor/validate_workflow_rewrite_legacy_test.go b/mdl/executor/validate_workflow_rewrite_legacy_test.go
new file mode 100644
index 0000000000..35dcf9e210
--- /dev/null
+++ b/mdl/executor/validate_workflow_rewrite_legacy_test.go
@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/mdl/visitor"
+	"go.mongodb.org/mongo-driver/bson"
+)
+
+// legacyShaped returns raw decoded the way the legacy engine's GetRawUnit
+// decodes a unit — bson.Unmarshal into map[string]any — which yields arrays as
+// primitive.A. Measured end to end: on the legacy engine a `create or modify`
+// that restated none of a workflow's two event handlers was written ("Created
+// workflow") and deleted them, while the modelsdk engine refused it.
+func legacyShaped(t *testing.T, raw map[string]any) map[string]any {
+	t.Helper()
+	data, err := bson.Marshal(raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var out map[string]any
+	if err := bson.Unmarshal(data, &out); err != nil {
+		t.Fatal(err)
+	}
+	return out
+}
+
+func TestWorkflowRewrite_GuardsSeeLegacyShapedUnits(t *testing.T) {
+	boundary := map[string]any{
+		"$Type": "Workflows$Workflow",
+		"Flow": map[string]any{
+			"$Type": "Workflows$Flow",
+			"Activities": []any{3, map[string]any{
+				"$Type":          "Workflows$CallMicroflowTask",
+				"BoundaryEvents": []any{2, map[string]any{"$Type": "Workflows$InterruptingTimerBoundaryEvent"}},
+			}},
+		},
+	}
+	cases := []struct {
+		name string
+		raw  map[string]any
+		src  string
+		want string
+	}{
+		{"event handler", studioProWorkflow(false, true, false, "ConsensusCompletionCriteria", true), wfRewriteTwoTasks, "workflow.WorkflowEventHandle"},
+		{"on-created microflow", studioProWorkflow(true, false, false, "ConsensusCompletionCriteria", true), wfRewriteTwoTasks, "workflow.UserTaskEventHandle"},
+		{"AI agent task", studioProWorkflow(false, false, true, "ConsensusCompletionCriteria", true), wfRewriteTwoTasks, "AI agent task"},
+		{"majority completion", studioProWorkflow(false, false, false, "MajorityCompletionCriteria", true), wfRewriteTwoTasks, "majority"},
+		{"boundary event", boundary, wfNoBoundary, "boundary event"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			stmt := parseWorkflowStmt(t, c.src)
+			err := checkNoDroppedWorkflowConstructs(rawWorkflowCtx(t, legacyShaped(t, c.raw)), "wf1", "M.W", stmt)
+			if err == nil || !strings.Contains(err.Error(), c.want) {
+				t.Errorf("rewrite over a legacy-decoded unit must be refused naming %q, got %v", c.want, err)
+			}
+		})
+	}
+
+	// The control: the same legacy-shaped unit holding only what a rebuild
+	// writes is still allowed, so the conversion does not refuse everything.
+	plain := legacyShaped(t, studioProWorkflow(false, false, false, "ConsensusCompletionCriteria", true))
+	if err := checkNoDroppedWorkflowConstructs(rawWorkflowCtx(t, plain), "wf1", "M.W", parseWorkflowStmt(t, wfRewriteTwoTasks)); err != nil {
+		t.Errorf("a legacy-decoded unit that loses nothing must be allowed, got %v", err)
+	}
+}
+
+func TestAlterWorkflow_ReplaceSeesLegacyShapedUnits(t *testing.T) {
+	prog, errs := visitor.Build(`alter workflow M.W replace activity userTask1 with user task userTask1 'Task' page M.P outcomes 'Fast' { } 'Furious' { };`)
+	if len(errs) > 0 {
+		t.Fatalf("parse errors: %v", errs)
+	}
+	stmt := prog.Statements[0].(*ast.AlterWorkflowStmt)
+	raw := legacyShaped(t, studioProWorkflow(true, false, false, "ConsensusCompletionCriteria", true))
+	got := validateAlterReplaceKeepsStudioProState(storedReplaceCtx(t, raw), stmt)
+	if len(got) != 1 || !strings.Contains(got[0], "workflow.UserTaskEventHandle") {
+		t.Errorf("replace over a legacy-decoded unit must be refused, got %v", got)
+	}
+}
diff --git a/mdl/executor/validate_workflow_rewrite_test.go b/mdl/executor/validate_workflow_rewrite_test.go
index 1ce82711f3..1867f5ca4d 100644
--- a/mdl/executor/validate_workflow_rewrite_test.go
+++ b/mdl/executor/validate_workflow_rewrite_test.go
@@ -220,6 +220,7 @@ func studioProWorkflow(onCreated, handler, agentTask bool, criteria string, fall
 		events = append(events, map[string]any{
 			"$Type":                 "Workflows$WorkflowEventHandler",
 			"Description":           "OnAnyEvent",
+			"EventTypes":            []any{1, "WorkflowCompleted", "UserTaskStarted"},
 			"MicroflowEventHandler": map[string]any{"$Type": "Workflows$MicroflowEventHandler", "Microflow": "workflow.WorkflowEventHandle"},
 		})
 	}
@@ -236,11 +237,12 @@ begin
   multi user task userTask2 'Multi' page M.P outcomes 'Fast' { } 'Furious' { };
 end workflow;`
 
-// Measured on ako/TestApp: every rebuild writes a user task's OnCreatedEvent as
-// NoEvent, a multi-user task's completion criteria as Consensus on its first
-// outcome, OnWorkflowEvent as an empty list, and describe prints an AI agent task
-// only as a comment. MDL can express none of them, so a rewrite that would lose
-// one is refused — the event sub-process rule, applied to the rest.
+// Measured on ako/TestApp: a rebuild writes what the statement says — a user
+// task's OnCreatedEvent as NoEvent unless it states `on created microflow`,
+// OnWorkflowEvent as only the handlers it states, a multi-user task's completion
+// criteria as Consensus on its first outcome — and describe prints an AI agent
+// task only as a comment. A rewrite that would lose one of these is refused. The
+// statement here restates none of them.
 func TestWorkflowRewrite_RefusesDroppingStudioProOnlyState(t *testing.T) {
 	cases := []struct {
 		name string
@@ -276,6 +278,41 @@ func TestWorkflowRewrite_AllowsWhatARebuildReproduces(t *testing.T) {
 	}
 }
 
+// On-created microflows and event handlers are expressible now, so a statement
+// that restates them — the shape `describe workflow` emits — is a rewrite that
+// loses nothing, and the guard must let it through. Without this the guard would
+// block every rewrite of every workflow that uses them.
+func TestWorkflowRewrite_AllowsRestatedHandlers(t *testing.T) {
+	stmt := parseWorkflowStmt(t, `create or modify workflow M.W parameter $C: M.Ctx
+  on workflow events (WorkflowCompleted, UserTaskStarted) microflow workflow.WorkflowEventHandle as 'OnAnyEvent'
+begin
+  user task userTask1 'User Task' page M.P on created microflow workflow.UserTaskEventHandle outcomes 'Good' { } 'Bad' { };
+  multi user task userTask2 'Multi' page M.P outcomes 'Fast' { } 'Furious' { };
+end workflow;`)
+	raw := studioProWorkflow(true, true, false, "ConsensusCompletionCriteria", true)
+	if err := checkNoDroppedWorkflowConstructs(rawWorkflowCtx(t, raw), "wf1", "M.W", stmt); err != nil {
+		t.Fatalf("a rewrite that restates its handlers must be allowed, got %v", err)
+	}
+}
+
+// A handler subscribed to no event types builds (measured, 11.13.0) but has no
+// MDL spelling — the grammar requires at least one type — so restating it is not
+// possible and the rewrite is refused however many handlers the statement has.
+func TestWorkflowRewrite_RefusesHandlerWithNoEventTypes(t *testing.T) {
+	stmt := parseWorkflowStmt(t, `create or modify workflow M.W parameter $C: M.Ctx
+  on workflow events (WorkflowCompleted) microflow workflow.WorkflowEventHandle as 'OnAnyEvent'
+begin
+  user task userTask1 'User Task' page M.P outcomes 'Good' { } 'Bad' { };
+end workflow;`)
+	raw := studioProWorkflow(false, true, false, "ConsensusCompletionCriteria", true)
+	handler := raw["OnWorkflowEvent"].([]any)[1].(map[string]any)
+	handler["EventTypes"] = []any{1}
+	err := checkNoDroppedWorkflowConstructs(rawWorkflowCtx(t, raw), "wf1", "M.W", stmt)
+	if err == nil || !strings.Contains(err.Error(), "no event types") {
+		t.Fatalf("a handler with no event types must be refused, got %v", err)
+	}
+}
+
 // storedReplaceCtx is a project holding M.W: the semantic workflow ALTER resolves
 // its target against, and the raw unit the REPLACE refusal reads.
 func storedReplaceCtx(t *testing.T, raw map[string]any) *ExecContext {
@@ -303,7 +340,12 @@ func storedReplaceCtx(t *testing.T, raw map[string]any) *ExecContext {
 // on-created microflow to NoEvent while exec reported "Altered workflow".
 func TestAlterWorkflow_ReplaceRefusesToResetStudioProState(t *testing.T) {
 	replaceTask := func(name string) *ast.AlterWorkflowStmt {
-		prog, errs := visitor.Build(`alter workflow M.W replace activity ` + name + ` with user task ` + name + ` 'Task' page M.P outcomes 'Fast' { } 'Furious' { };`)
+		clause := ""
+		if strings.HasSuffix(name, "+oncreated") {
+			name = strings.TrimSuffix(name, "+oncreated")
+			clause = ` on created microflow workflow.UserTaskEventHandle`
+		}
+		prog, errs := visitor.Build(`alter workflow M.W replace activity ` + name + ` with user task ` + name + ` 'Task' page M.P` + clause + ` outcomes 'Fast' { } 'Furious' { };`)
 		if len(errs) > 0 {
 			t.Fatalf("parse errors: %v", errs)
 		}
@@ -315,6 +357,8 @@ func TestAlterWorkflow_ReplaceRefusesToResetStudioProState(t *testing.T) {
 		want         string // "" = allowed
 	}{
 		{"on-created microflow", "userTask1", studioProWorkflow(true, false, false, "ConsensusCompletionCriteria", true), "workflow.UserTaskEventHandle"},
+		// The replacement restates it, so nothing is lost.
+		{"on-created microflow, restated", "userTask1+oncreated", studioProWorkflow(true, false, false, "ConsensusCompletionCriteria", true), ""},
 		{"majority rule", "userTask2", studioProWorkflow(false, false, false, "MajorityCompletionCriteria", true), "majority"},
 		// Controls: the same replacements where the stored activity holds only
 		// what a rebuild writes anyway.
diff --git a/mdl/executor/validate_workflow_task_signature.go b/mdl/executor/validate_workflow_task_signature.go
index e0cc187893..7c2c0fd7eb 100644
--- a/mdl/executor/validate_workflow_task_signature.go
+++ b/mdl/executor/validate_workflow_task_signature.go
@@ -121,6 +121,7 @@ func (c *workflowTaskSignatureChecker) checkActivities(activities []ast.Workflow
 		if strings.Contains(n.Targeting.Kind, "microflow") {
 			errs = appendIfSet(errs, c.checkTargeting(label, n.Targeting.Microflow.String(), contextEntity))
 		}
+		errs = appendIfSet(errs, c.checkOnCreated(label, n.OnCreated.String(), contextEntity))
 	})
 	return errs
 }
@@ -172,22 +173,7 @@ func (c *workflowTaskSignatureChecker) checkTargeting(label, mfQN, contextEntity
 // context entity's inheritance chain leaves what can be resolved, the answer is
 // "not proven", which is not a refusal.
 func (c *workflowTaskSignatureChecker) targetingMismatch(sig *flowSignature, contextEntity string) bool {
-	if len(sig.Params) != 2 {
-		return true
-	}
-	for i, p := range sig.Params {
-		if !strings.EqualFold(p.Entity, workflowEntity) {
-			continue
-		}
-		other := sig.Params[1-i]
-		if other.Entity == "" {
-			continue
-		}
-		if c.contextAssignableTo(contextEntity, other.Entity) != inheritanceNo {
-			return false
-		}
-	}
-	return true
+	return c.pairMismatch(sig, workflowEntity, contextEntity)
 }
 
 type inheritance int
diff --git a/mdl/executor/workflow_event_types.go b/mdl/executor/workflow_event_types.go
new file mode 100644
index 0000000000..10e14c5ba4
--- /dev/null
+++ b/mdl/executor/workflow_event_types.go
@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// The workflow event types a handler can subscribe to, per Mendix version.
+//
+// Studio Pro stores a handler's event types as an explicit list, even when every
+// box is ticked (ako/TestApp, 11.14.0: a handler named "OnAnyEvent" stores all 42
+// in the order below). So `on any workflow event` cannot be a flag — it has to be
+// written as the list the project's version knows, and that list grows: Mendix
+// added types for AI agent tasks and event sub-processes.
+//
+// The table is measured, not read off release notes: each point is the set of
+// type names present in that mxbuild's Mendix.Modeler.*.dll. mxbuild is no help
+// at check time — measured on 11.13.0, a handler listing an invented type builds
+// at 0 errors — so a misspelt type would be written silently and dropped or
+// refused later by Studio Pro. That is why names are validated here.
+package executor
+
+import "fmt"
+
+// workflowEventTypeOrder is every known type, in Studio Pro's stored order.
+var workflowEventTypeOrder = []string{
+	"WorkflowCompleted", "WorkflowInitiated", "WorkflowRestarted", "WorkflowFailed", "WorkflowAborted",
+	"WorkflowPaused", "WorkflowUnpaused", "WorkflowRetried", "WorkflowUpdated", "WorkflowUpgraded",
+	"WorkflowConflicted", "WorkflowResolved", "WorkflowJumpToOptionApplied",
+	"StartEventExecuted", "EndEventExecuted", "DecisionExecuted", "JumpExecuted",
+	"ParallelSplitExecuted", "ParallelMergeExecuted",
+	"CallWorkflowStarted", "CallWorkflowEnded", "CallMicroflowStarted", "CallMicroflowEnded",
+	"AIAgentTaskStarted", "AIAgentTaskEnded",
+	"NotificationStarted", "NotificationEnded",
+	"WaitForNotificationStarted", "WaitForNotificationEnded", "WaitForTimerStarted", "WaitForTimerEnded",
+	"UserTaskStarted", "MultiUserTaskOutcomeSelected", "UserTaskEnded",
+	"NonInterruptingTimerEventExecuted", "InterruptingTimerEventExecuted",
+	"NonInterruptingNotificationEventSubProcessStartExecuted", "InterruptingNotificationEventSubProcessStartExecuted",
+	"NonInterruptingNotificationEventExecuted", "InterruptingNotificationEventExecuted",
+	"NonInterruptingTimerEventSubProcessStartExecuted", "InterruptingTimerEventSubProcessStartExecuted",
+}
+
+// workflowEventTypeVersion is a Mendix version at which the type set was measured.
+type workflowEventTypeVersion struct{ major, minor, patch int }
+
+func (v workflowEventTypeVersion) atMost(major, minor, patch int) bool {
+	if v.major != major {
+		return v.major < major
+	}
+	if v.minor != minor {
+		return v.minor < minor
+	}
+	return v.patch <= patch
+}
+
+func (v workflowEventTypeVersion) String() string {
+	return fmt.Sprintf("%d.%d.%d", v.major, v.minor, v.patch)
+}
+
+// workflowEventTypePoints are the measured versions, oldest first, each with the
+// types first seen there. A type is known from its point on.
+var workflowEventTypePoints = []struct {
+	version workflowEventTypeVersion
+	added   []string
+}{
+	{workflowEventTypeVersion{11, 6, 0}, []string{
+		"WorkflowCompleted", "WorkflowInitiated", "WorkflowRestarted", "WorkflowFailed", "WorkflowAborted",
+		"WorkflowPaused", "WorkflowUnpaused", "WorkflowRetried", "WorkflowUpdated", "WorkflowUpgraded",
+		"WorkflowConflicted", "WorkflowResolved", "WorkflowJumpToOptionApplied",
+		"StartEventExecuted", "EndEventExecuted", "DecisionExecuted", "JumpExecuted",
+		"ParallelSplitExecuted", "ParallelMergeExecuted",
+		"CallWorkflowStarted", "CallWorkflowEnded", "CallMicroflowStarted", "CallMicroflowEnded",
+		"WaitForNotificationStarted", "WaitForNotificationEnded", "WaitForTimerStarted", "WaitForTimerEnded",
+		"UserTaskStarted", "MultiUserTaskOutcomeSelected", "UserTaskEnded",
+		"NonInterruptingTimerEventExecuted", "InterruptingTimerEventExecuted",
+	}},
+	{workflowEventTypeVersion{11, 10, 0}, []string{
+		"AIAgentTaskStarted", "AIAgentTaskEnded",
+		"NonInterruptingNotificationEventSubProcessStartExecuted", "InterruptingNotificationEventSubProcessStartExecuted",
+	}},
+	{workflowEventTypeVersion{11, 13, 0}, []string{
+		"NotificationStarted", "NotificationEnded",
+		"NonInterruptingNotificationEventExecuted", "InterruptingNotificationEventExecuted",
+		"NonInterruptingTimerEventSubProcessStartExecuted", "InterruptingTimerEventSubProcessStartExecuted",
+	}},
+}
+
+// workflowEventTypeSince returns the index of the point where name was first
+// measured, or -1 for a name that is not a workflow event type at all.
+func workflowEventTypeSince(name string) int {
+	for i, p := range workflowEventTypePoints {
+		for _, n := range p.added {
+			if n == name {
+				return i
+			}
+		}
+	}
+	return -1
+}
+
+// canonicalWorkflowEventType returns the stored spelling of name, matched
+// case-insensitively (MDL keywords are), and whether it is a known type.
+func canonicalWorkflowEventType(name string) (string, bool) {
+	for _, n := range workflowEventTypeOrder {
+		if equalFoldASCII(n, name) {
+			return n, true
+		}
+	}
+	return "", false
+}
+
+func equalFoldASCII(a, b string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := 0; i < len(a); i++ {
+		x, y := a[i], b[i]
+		if 'A' <= x && x <= 'Z' {
+			x += 'a' - 'A'
+		}
+		if 'A' <= y && y <= 'Z' {
+			y += 'a' - 'A'
+		}
+		if x != y {
+			return false
+		}
+	}
+	return true
+}
+
+// workflowEventTypeMissingIn reports whether a known type is measured ABSENT in
+// the given version: the version is at or below the last point before the type
+// appeared. Between that point and the one where it was seen, the answer is not
+// known, and an explicitly named type is let through rather than refused.
+func workflowEventTypeMissingIn(name string, major, minor, patch int) (lastAbsent string, missing bool) {
+	since := workflowEventTypeSince(name)
+	if since <= 0 {
+		return "", false
+	}
+	prev := workflowEventTypePoints[since-1].version
+	if !prev.atMost(major, minor, patch) {
+		// Older than the last measured absence: absent too, types are not removed.
+		return prev.String(), true
+	}
+	if prev == (workflowEventTypeVersion{major, minor, patch}) {
+		return prev.String(), true
+	}
+	return "", false
+}
+
+// allWorkflowEventTypes returns every type known at the given version, in stored
+// order: the set at the newest measured point not above it. ok is false when the
+// version is older than every measured point — the set there is not known, and
+// guessing would write types the version may not have.
+func allWorkflowEventTypes(major, minor, patch int) (types []string, basis string, ok bool) {
+	last := -1
+	for i, p := range workflowEventTypePoints {
+		if p.version.atMost(major, minor, patch) {
+			last = i
+		}
+	}
+	if last < 0 {
+		return nil, "", false
+	}
+	for _, n := range workflowEventTypeOrder {
+		if since := workflowEventTypeSince(n); since >= 0 && since <= last {
+			types = append(types, n)
+		}
+	}
+	return types, workflowEventTypePoints[last].version.String(), true
+}
+
+// sortWorkflowEventTypes returns the given stored spellings de-duplicated and in
+// Studio Pro's stored order, so an explicit list writes what Studio Pro would.
+func sortWorkflowEventTypes(names []string) []string {
+	seen := map[string]bool{}
+	for _, n := range names {
+		seen[n] = true
+	}
+	out := make([]string, 0, len(seen))
+	for _, n := range workflowEventTypeOrder {
+		if seen[n] {
+			out = append(out, n)
+		}
+	}
+	return out
+}
diff --git a/mdl/executor/workflow_event_types_test.go b/mdl/executor/workflow_event_types_test.go
new file mode 100644
index 0000000000..e1287c47b3
--- /dev/null
+++ b/mdl/executor/workflow_event_types_test.go
@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"reflect"
+	"testing"
+)
+
+// The measured points: 32 types in 11.6.0, 36 in 11.10.0, 42 in 11.13.0 and
+// 11.14.0 (ako/TestApp stores all 42 for a handler named OnAnyEvent).
+func TestWorkflowEventTypes_AnySetPerVersion(t *testing.T) {
+	cases := []struct {
+		major, minor, patch int
+		want                int // -1 = not known
+	}{
+		{10, 24, 0, -1},
+		{11, 5, 9, -1},
+		{11, 6, 0, 32},
+		{11, 9, 3, 32}, // between points: the older point's set, never a guess upward
+		{11, 10, 0, 36},
+		{11, 12, 4, 36},
+		{11, 13, 0, 42},
+		{11, 14, 0, 42},
+		{12, 0, 0, 42},
+	}
+	for _, c := range cases {
+		types, _, ok := allWorkflowEventTypes(c.major, c.minor, c.patch)
+		switch {
+		case c.want < 0 && ok:
+			t.Errorf("%d.%d.%d: got %d types, want not known", c.major, c.minor, c.patch, len(types))
+		case c.want >= 0 && (!ok || len(types) != c.want):
+			t.Errorf("%d.%d.%d: got %d types (ok=%v), want %d", c.major, c.minor, c.patch, len(types), ok, c.want)
+		}
+	}
+	all, _, _ := allWorkflowEventTypes(11, 14, 0)
+	if !reflect.DeepEqual(all, workflowEventTypeOrder) {
+		t.Errorf("11.14 set is not Studio Pro's stored order:\n%v", all)
+	}
+}
+
+// Every ordered type belongs to exactly one measured point, or `any` would skip
+// or double it.
+func TestWorkflowEventTypes_TableIsConsistent(t *testing.T) {
+	seen := map[string]int{}
+	for _, p := range workflowEventTypePoints {
+		for _, n := range p.added {
+			seen[n]++
+		}
+	}
+	for _, n := range workflowEventTypeOrder {
+		if seen[n] != 1 {
+			t.Errorf("%s appears in %d points", n, seen[n])
+		}
+	}
+	if len(seen) != len(workflowEventTypeOrder) {
+		t.Errorf("points name %d types, order lists %d", len(seen), len(workflowEventTypeOrder))
+	}
+}
+
+// A type is refused only where it is measured absent. Between the last absence
+// and the first sighting the answer is not known, and a type the author named is
+// let through.
+func TestWorkflowEventTypes_MissingIn(t *testing.T) {
+	cases := []struct {
+		name                string
+		major, minor, patch int
+		missing             bool
+	}{
+		{"NotificationStarted", 11, 13, 0, false},
+		{"NotificationStarted", 11, 12, 0, false}, // unknown, not refused
+		{"NotificationStarted", 11, 10, 0, true},
+		{"NotificationStarted", 11, 6, 0, true},
+		{"NotificationStarted", 10, 24, 0, true},
+		{"AIAgentTaskStarted", 11, 6, 0, true},
+		{"AIAgentTaskStarted", 11, 7, 0, false},
+		{"UserTaskStarted", 10, 7, 0, false}, // oldest point: never measured absent
+	}
+	for _, c := range cases {
+		if _, got := workflowEventTypeMissingIn(c.name, c.major, c.minor, c.patch); got != c.missing {
+			t.Errorf("%s in %d.%d.%d: missing = %v, want %v", c.name, c.major, c.minor, c.patch, got, c.missing)
+		}
+	}
+}
+
+func TestWorkflowEventTypes_CanonicalAndSorted(t *testing.T) {
+	if got, ok := canonicalWorkflowEventType("usertaskstarted"); !ok || got != "UserTaskStarted" {
+		t.Errorf("canonical(usertaskstarted) = %q, %v", got, ok)
+	}
+	if _, ok := canonicalWorkflowEventType("UserTaskStart"); ok {
+		t.Error("a misspelt type must not be accepted")
+	}
+	got := sortWorkflowEventTypes([]string{"UserTaskEnded", "WorkflowCompleted", "UserTaskEnded"})
+	if want := []string{"WorkflowCompleted", "UserTaskEnded"}; !reflect.DeepEqual(got, want) {
+		t.Errorf("sorted = %v, want %v", got, want)
+	}
+}
diff --git a/mdl/executor/workflow_handlers_describe_test.go b/mdl/executor/workflow_handlers_describe_test.go
new file mode 100644
index 0000000000..d6e80d1e04
--- /dev/null
+++ b/mdl/executor/workflow_handlers_describe_test.go
@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/mdl/backend/mock"
+	"github.com/mendixlabs/mxcli/mdl/types"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+func versionCtx(t *testing.T, major, minor, patch int) *ExecContext {
+	t.Helper()
+	mb := &mock.MockBackend{
+		IsConnectedFunc: func() bool { return true },
+		ProjectVersionFunc: func() *types.ProjectVersion {
+			return &types.ProjectVersion{MajorVersion: major, MinorVersion: minor, PatchVersion: patch}
+		},
+	}
+	ctx, _ := newMockCtx(t, withBackend(mb))
+	return ctx
+}
+
+// Describe output has to parse back into the same handlers — a describe that
+// does not re-execute is how #466's boundary events went unnoticed.
+func TestWorkflowHandlers_DescribeRoundTrips(t *testing.T) {
+	all1113, _, _ := allWorkflowEventTypes(11, 13, 0)
+	all1110, _, _ := allWorkflowEventTypes(11, 10, 0)
+	handlers := []*workflows.WorkflowEventHandler{
+		{Description: "OnAnyEvent", EventTypes: all1113, Microflow: "M.Log"},
+		{Description: "Task audit", EventTypes: []string{"UserTaskStarted", "UserTaskEnded"}, Microflow: "M.Audit"},
+		{EventTypes: all1110, Microflow: "M.Older"}, // a subset at 11.13: written out
+	}
+	ctx := versionCtx(t, 11, 13, 0)
+	lines := formatWorkflowEventHandlers(ctx, handlers)
+	out := strings.Join(lines, "\n")
+
+	for _, want := range []string{
+		"  on any workflow event microflow M.Log as 'OnAnyEvent'",
+		"  on workflow events (UserTaskStarted, UserTaskEnded) microflow M.Audit as 'Task audit'",
+		"  ) microflow M.Older",
+	} {
+		if !strings.Contains(out, want) {
+			t.Errorf("describe lacks %q:\n%s", want, out)
+		}
+	}
+
+	stmt := parseWorkflowStmt(t, "create workflow M.W\n"+out+"\nbegin\nend workflow;")
+	if len(stmt.EventHandlers) != 3 {
+		t.Fatalf("re-parsed %d handlers, want 3:\n%s", len(stmt.EventHandlers), out)
+	}
+	rebuilt, err := buildWorkflowEventHandlers(ctx, stmt.EventHandlers, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for i, h := range handlers {
+		r := rebuilt[i]
+		if r.Description != h.Description || r.Microflow != h.Microflow || !reflect.DeepEqual(r.EventTypes, h.EventTypes) {
+			t.Errorf("handler %d: rebuilt %+v, described %+v", i, r, h)
+		}
+	}
+}
+
+// The same 36-type list is "any" at 11.10 and not at 11.13; describe follows the
+// project version so a re-execute stores the same list.
+func TestWorkflowHandlers_DescribeAnyFollowsProjectVersion(t *testing.T) {
+	all1110, _, _ := allWorkflowEventTypes(11, 10, 0)
+	h := []*workflows.WorkflowEventHandler{{EventTypes: all1110, Microflow: "M.Log"}}
+	if got := strings.Join(formatWorkflowEventHandlers(versionCtx(t, 11, 10, 0), h), "\n"); got != "  on any workflow event microflow M.Log" {
+		t.Errorf("at 11.10: %q", got)
+	}
+	if got := strings.Join(formatWorkflowEventHandlers(versionCtx(t, 11, 13, 0), h), "\n"); strings.Contains(got, "any") {
+		t.Errorf("at 11.13 the 11.10 list is not every type: %q", got)
+	}
+}
+
+// An empty list has no MDL spelling; describe must not emit a clause that parses
+// into something else.
+func TestWorkflowHandlers_DescribeEmptyTypeListIsAComment(t *testing.T) {
+	got := formatWorkflowEventHandlers(versionCtx(t, 11, 13, 0), []*workflows.WorkflowEventHandler{{Description: "Idle", Microflow: "M.Log"}})
+	if len(got) != 1 || !strings.HasPrefix(strings.TrimSpace(got[0]), "--") {
+		t.Errorf("describe = %v, want one comment line", got)
+	}
+}
+
+func TestWorkflowHandlers_DescribeOnCreated(t *testing.T) {
+	task := &workflows.UserTask{
+		Page:       "M.TaskPage",
+		UserSource: &workflows.MicroflowBasedUserSource{Microflow: "M.Targets"},
+		OnCreated:  "M.Assign",
+		Outcomes:   []*workflows.UserTaskOutcome{{Value: "Done"}},
+	}
+	task.Name = "Review"
+	task.Caption = "Review"
+	out := strings.Join(formatUserTask(task, "  "), "\n")
+	targeting := strings.Index(out, "targeting users microflow M.Targets")
+	onCreated := strings.Index(out, "on created microflow M.Assign")
+	outcomes := strings.Index(out, "outcomes")
+	if targeting < 0 || onCreated < targeting || outcomes < onCreated {
+		t.Fatalf("clauses out of grammar order:\n%s", out)
+	}
+	stmt := parseWorkflowStmt(t, "create workflow M.W\nbegin\n"+out+";\nend workflow;")
+	ut, ok := stmt.Activities[0].(*ast.WorkflowUserTaskNode)
+	if !ok || ut.OnCreated.String() != "M.Assign" || ut.Targeting.Microflow.String() != "M.Targets" {
+		t.Errorf("re-parsed task = %+v", stmt.Activities[0])
+	}
+}
+
+// A named list is written in Studio Pro's order whatever order it was typed in,
+// and a handler's documentation — which MDL cannot write — is carried from the
+// stored handler with the same microflow and description.
+func TestWorkflowHandlers_BuildOrdersAndCarriesDocumentation(t *testing.T) {
+	nodes := []ast.WorkflowEventHandlerNode{{
+		EventTypes:  []string{"usertaskended", "WorkflowCompleted", "UserTaskEnded"},
+		Microflow:   ast.QualifiedName{Module: "M", Name: "Audit"},
+		Description: "Task audit",
+	}}
+	stored := []*workflows.WorkflowEventHandler{{Description: "Task audit", Microflow: "M.Audit", Documentation: "Why we audit"}}
+	got, err := buildWorkflowEventHandlers(versionCtx(t, 11, 13, 0), nodes, stored)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := []string{"WorkflowCompleted", "UserTaskEnded"}; !reflect.DeepEqual(got[0].EventTypes, want) {
+		t.Errorf("types = %v, want %v", got[0].EventTypes, want)
+	}
+	if got[0].Documentation != "Why we audit" {
+		t.Errorf("documentation = %q, want it carried", got[0].Documentation)
+	}
+}
+
+func TestWorkflowHandlers_BuildAnyBelowMeasuredVersionIsRefused(t *testing.T) {
+	nodes := []ast.WorkflowEventHandlerNode{{AnyEvent: true, Microflow: ast.QualifiedName{Module: "M", Name: "Log"}}}
+	if _, err := buildWorkflowEventHandlers(versionCtx(t, 10, 24, 0), nodes, nil); err == nil {
+		t.Error("`on any workflow event` below 11.6 must be refused, not guessed")
+	}
+}
diff --git a/mdl/grammar/domains/MDLWorkflow.g4 b/mdl/grammar/domains/MDLWorkflow.g4
index 58016d8035..58f486d202 100644
--- a/mdl/grammar/domains/MDLWorkflow.g4
+++ b/mdl/grammar/domains/MDLWorkflow.g4
@@ -21,9 +21,22 @@ createWorkflowStatement
       (EXPORT LEVEL (IDENTIFIER | API))?
       (OVERVIEW PAGE qualifiedName)?
       (DUE DATE_TYPE dueDate=STRING_LITERAL)?
+      workflowEventHandlerClause*
       BEGIN workflowMainBody END WORKFLOW SEMICOLON? SLASH?
     ;
 
+/**
+ * A workflow event handler: a microflow the runtime calls when one of the named
+ * workflow events happens. Studio Pro stores the event types as an explicit list
+ * even when every one is ticked, so `any workflow event` is written as the list
+ * the project's Mendix version knows. The optional `as` string is the handler's
+ * description, which is how Studio Pro tells handlers apart.
+ */
+workflowEventHandlerClause
+    : ON ANY WORKFLOW EVENT MICROFLOW qualifiedName (AS STRING_LITERAL)?
+    | ON WORKFLOW EVENTS LPAREN IDENTIFIER (COMMA IDENTIFIER)* RPAREN MICROFLOW qualifiedName (AS STRING_LITERAL)?
+    ;
+
 /**
  * The top-level body. It cannot hold `end workflow;` as a statement: there those
  * words close the body, and they ARE the main flow's End — Mendix refuses an End
@@ -88,6 +101,7 @@ workflowUserTaskStmt
       (PAGE qualifiedName)?
       (TARGETING (USERS | GROUPS)? MICROFLOW qualifiedName)?
       (TARGETING (USERS | GROUPS)? XPATH STRING_LITERAL)?
+      (ON CREATED MICROFLOW qualifiedName)?
       (ENTITY qualifiedName)?
       (DUE DATE_TYPE STRING_LITERAL)?
       (DESCRIPTION STRING_LITERAL)?
@@ -97,6 +111,7 @@ workflowUserTaskStmt
       (PAGE qualifiedName)?
       (TARGETING (USERS | GROUPS)? MICROFLOW qualifiedName)?
       (TARGETING (USERS | GROUPS)? XPATH STRING_LITERAL)?
+      (ON CREATED MICROFLOW qualifiedName)?
       (ENTITY qualifiedName)?
       (DUE DATE_TYPE STRING_LITERAL)?
       (DESCRIPTION STRING_LITERAL)?
diff --git a/mdl/visitor/visitor_workflow.go b/mdl/visitor/visitor_workflow.go
index d1614a8f02..642912f5d1 100644
--- a/mdl/visitor/visitor_workflow.go
+++ b/mdl/visitor/visitor_workflow.go
@@ -76,6 +76,23 @@ func (b *Builder) ExitCreateWorkflowStatement(ctx *parser.CreateWorkflowStatemen
 		stmt.DueDate = unquoteString(tok.GetText())
 	}
 
+	// Workflow event handlers: each clause carries its own qualified name, so
+	// they do not shift the header's name indices above.
+	for _, hc := range ctx.AllWorkflowEventHandlerClause() {
+		h := hc.(*parser.WorkflowEventHandlerClauseContext)
+		node := ast.WorkflowEventHandlerNode{AnyEvent: h.ANY() != nil}
+		if qn := h.QualifiedName(); qn != nil {
+			node.Microflow = buildQualifiedName(qn)
+		}
+		for _, id := range h.AllIDENTIFIER() {
+			node.EventTypes = append(node.EventTypes, id.GetText())
+		}
+		if s := h.STRING_LITERAL(); s != nil {
+			node.Description = unquoteString(s.GetText())
+		}
+		stmt.EventHandlers = append(stmt.EventHandlers, node)
+	}
+
 	// Parse CREATE OR MODIFY
 	createStmt := findParentCreateStatement(ctx)
 	if createStmt != nil {
@@ -515,7 +532,17 @@ func buildWorkflowUserTask(ctx parser.IWorkflowUserTaskStmtContext) *ast.Workflo
 	// Determine if group targeting (TARGETING GROUPS vs TARGETING [USERS])
 	isGroupTargeting := len(utCtx.AllGROUPS()) > 0
 
-	if utCtx.MICROFLOW() != nil && nameIdx < len(names) {
+	// MICROFLOW appears in both TARGETING … MICROFLOW and ON CREATED MICROFLOW,
+	// so targeting is present when a MICROFLOW token is left over after the
+	// on-created one. Qualified names come in clause order: page, targeting,
+	// on-created, entity.
+	onCreated := utCtx.CREATED() != nil
+	targetingMicroflows := len(utCtx.AllMICROFLOW())
+	if onCreated {
+		targetingMicroflows--
+	}
+
+	if targetingMicroflows > 0 && nameIdx < len(names) {
 		if isGroupTargeting {
 			node.Targeting.Kind = "group_microflow"
 		} else {
@@ -536,6 +563,11 @@ func buildWorkflowUserTask(ctx parser.IWorkflowUserTaskStmtContext) *ast.Workflo
 		stringIdx++
 	}
 
+	if onCreated && nameIdx < len(names) {
+		node.OnCreated = buildQualifiedName(names[nameIdx])
+		nameIdx++
+	}
+
 	if utCtx.ENTITY() != nil && nameIdx < len(names) {
 		node.Entity = buildQualifiedName(names[nameIdx])
 	}
diff --git a/mdl/visitor/visitor_workflow_handlers_test.go b/mdl/visitor/visitor_workflow_handlers_test.go
new file mode 100644
index 0000000000..6cfc1b20f5
--- /dev/null
+++ b/mdl/visitor/visitor_workflow_handlers_test.go
@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package visitor
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+)
+
+// Header handler clauses sit between the header options and BEGIN. They carry
+// their own qualified names, so the header's positional name reading (parameter
+// entity, overview page) must be unaffected by them.
+func TestWorkflowVisitor_EventHandlers(t *testing.T) {
+	input := `create workflow M.W
+  parameter $C: M.Ctx
+  overview page M.Overview
+  on workflow events (UserTaskStarted, UserTaskEnded) microflow M.ACT_Audit as 'Task audit'
+  on any workflow event microflow M.ACT_Log
+begin
+  user task T 'c' outcomes 'a' { };
+end workflow;`
+	stmt := buildWorkflowStmt(t, input)
+
+	if got := stmt.ParameterEntity.String(); got != "M.Ctx" {
+		t.Errorf("parameter entity = %q", got)
+	}
+	if got := stmt.OverviewPage.String(); got != "M.Overview" {
+		t.Errorf("overview page = %q", got)
+	}
+	if len(stmt.EventHandlers) != 2 {
+		t.Fatalf("handlers = %d, want 2", len(stmt.EventHandlers))
+	}
+	named := stmt.EventHandlers[0]
+	if named.AnyEvent || !reflect.DeepEqual(named.EventTypes, []string{"UserTaskStarted", "UserTaskEnded"}) ||
+		named.Microflow.String() != "M.ACT_Audit" || named.Description != "Task audit" {
+		t.Errorf("named handler = %+v", named)
+	}
+	any := stmt.EventHandlers[1]
+	if !any.AnyEvent || len(any.EventTypes) != 0 || any.Microflow.String() != "M.ACT_Log" || any.Description != "" {
+		t.Errorf("any handler = %+v", any)
+	}
+}
+
+// MICROFLOW occurs in both `targeting … microflow` and `on created microflow`,
+// and qualified names are read by position, so each combination must land its
+// names on the right fields.
+func TestWorkflowVisitor_UserTaskOnCreated(t *testing.T) {
+	input := `create workflow M.W
+begin
+  user task T 'c' page M.P targeting microflow M.Targets on created microflow M.OnCreated entity M.TaskEnt outcomes 'a' { };
+  user task U 'u' on created microflow M.OnlyCreated outcomes 'a' { };
+  multi user task V 'v' page M.P targeting groups microflow M.Groups outcomes 'a' { };
+  multi user task X 'x' page M.P targeting xpath '[true()]' on created microflow M.XCreated outcomes 'a' { };
+end workflow;`
+	stmt := buildWorkflowStmt(t, input)
+	if len(stmt.Activities) != 4 {
+		t.Fatalf("activities = %d, want 4", len(stmt.Activities))
+	}
+	task := func(i int) *ast.WorkflowUserTaskNode {
+		n, ok := stmt.Activities[i].(*ast.WorkflowUserTaskNode)
+		if !ok {
+			t.Fatalf("activity %d is %T", i, stmt.Activities[i])
+		}
+		return n
+	}
+
+	tk := task(0)
+	if tk.Page.String() != "M.P" || tk.Targeting.Kind != "microflow" || tk.Targeting.Microflow.String() != "M.Targets" ||
+		tk.OnCreated.String() != "M.OnCreated" || tk.Entity.String() != "M.TaskEnt" {
+		t.Errorf("T = page %s, targeting %s %s, on created %s, entity %s",
+			tk.Page, tk.Targeting.Kind, tk.Targeting.Microflow, tk.OnCreated, tk.Entity)
+	}
+	u := task(1)
+	if u.Targeting.Kind != "" || u.OnCreated.String() != "M.OnlyCreated" || u.Page.Module != "" {
+		t.Errorf("U = targeting %q, on created %s, page %s", u.Targeting.Kind, u.OnCreated, u.Page)
+	}
+	v := task(2)
+	if v.Targeting.Kind != "group_microflow" || v.Targeting.Microflow.String() != "M.Groups" || v.OnCreated.Module != "" {
+		t.Errorf("V = targeting %q %s, on created %s", v.Targeting.Kind, v.Targeting.Microflow, v.OnCreated)
+	}
+	x := task(3)
+	if !x.IsMultiUser || x.Targeting.Kind != "xpath" || x.OnCreated.String() != "M.XCreated" {
+		t.Errorf("X = multi %v, targeting %q, on created %s", x.IsMultiUser, x.Targeting.Kind, x.OnCreated)
+	}
+}
+
+func buildWorkflowStmt(t *testing.T, input string) *ast.CreateWorkflowStmt {
+	t.Helper()
+	prog, errs := Build(input)
+	if len(errs) > 0 {
+		t.Fatalf("parse errors: %v", errs)
+	}
+	stmt, ok := prog.Statements[0].(*ast.CreateWorkflowStmt)
+	if !ok {
+		t.Fatalf("statement is %T", prog.Statements[0])
+	}
+	return stmt
+}
diff --git a/sdk/mpr/parser_workflow.go b/sdk/mpr/parser_workflow.go
index 285bec3aca..b08498572c 100644
--- a/sdk/mpr/parser_workflow.go
+++ b/sdk/mpr/parser_workflow.go
@@ -82,9 +82,37 @@ func (r *Reader) parseWorkflow(unitID, containerID string, contents []byte) (*wo
 		w.Flow = parseWorkflowFlow(toMap(flowRaw))
 	}
 
+	w.EventHandlers = parseWorkflowEventHandlers(raw["OnWorkflowEvent"])
+
 	return w, nil
 }
 
+// parseWorkflowEventHandlers reads a workflow's OnWorkflowEvent list.
+func parseWorkflowEventHandlers(v any) []*workflows.WorkflowEventHandler {
+	var out []*workflows.WorkflowEventHandler
+	for _, item := range extractBsonArray(v) {
+		m := toMap(item)
+		if m == nil || extractString(m["$Type"]) != "Workflows$WorkflowEventHandler" {
+			continue
+		}
+		h := &workflows.WorkflowEventHandler{
+			Description:   extractString(m["Description"]),
+			Documentation: extractString(m["Documentation"]),
+		}
+		h.ID = model.ID(extractBsonID(m["$ID"]))
+		for _, t := range extractBsonArray(m["EventTypes"]) {
+			if s, ok := t.(string); ok {
+				h.EventTypes = append(h.EventTypes, s)
+			}
+		}
+		if mh := toMap(m["MicroflowEventHandler"]); mh != nil {
+			h.Microflow = extractString(mh["Microflow"])
+		}
+		out = append(out, h)
+	}
+	return out
+}
+
 // extractStringTemplate extracts the text from a Mendix StringTemplate BSON structure.
 // StringTemplates have a "Text" field with the template string.
 func extractStringTemplate(v any) string {
@@ -274,9 +302,11 @@ func parseUserTask(raw map[string]any) *workflows.UserTask {
 		a.UserTaskEntity = ute
 	}
 
-	// OnCreated (BY_NAME reference to microflow)
-	if onCreated, ok := raw["OnCreatedEvent"].(string); ok {
-		a.OnCreated = onCreated
+	// OnCreatedEvent is a part — Workflows$MicroflowBasedEvent carrying the
+	// microflow, or Workflows$NoEvent. Reading it as a string, as this did, never
+	// matched a stored document, so every on-created microflow read as none.
+	if ev := toMap(raw["OnCreatedEvent"]); ev != nil && extractString(ev["$Type"]) == "Workflows$MicroflowBasedEvent" {
+		a.OnCreated = extractString(ev["Microflow"])
 	}
 
 	// UserSource (PART) — legacy field name
diff --git a/sdk/mpr/workflow_handlers_test.go b/sdk/mpr/workflow_handlers_test.go
new file mode 100644
index 0000000000..79b6b72c71
--- /dev/null
+++ b/sdk/mpr/workflow_handlers_test.go
@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package mpr
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+	"go.mongodb.org/mongo-driver/bson"
+)
+
+// The handler shape is ako/TestApp's workflow.Workflow1 (Studio Pro 11.14.0):
+// OnWorkflowEvent is a marker-2 list, each handler's EventTypes a marker-1 list
+// of strings, and the microflow sits in a nested MicroflowEventHandler.
+func TestSerializeWorkflowEventHandlers_Shape(t *testing.T) {
+	arr := serializeWorkflowEventHandlers([]*workflows.WorkflowEventHandler{{
+		Description: "Task audit",
+		EventTypes:  []string{"UserTaskStarted", "UserTaskEnded"},
+		Microflow:   "M.ACT_Audit",
+	}})
+	if len(arr) != 2 || arr[0] != int32(2) {
+		t.Fatalf("OnWorkflowEvent = %v, want marker 2 and one handler", arr)
+	}
+	h, ok := arr[1].(bson.D)
+	if !ok {
+		t.Fatalf("handler is %T", arr[1])
+	}
+	var keys []string
+	for _, e := range h {
+		keys = append(keys, e.Key)
+	}
+	if want := []string{"$ID", "$Type", "Description", "Documentation", "EventTypes", "MicroflowEventHandler"}; !reflect.DeepEqual(keys, want) {
+		t.Errorf("handler keys = %v, want %v", keys, want)
+	}
+	if got := getBSONField(h, "$Type"); got != "Workflows$WorkflowEventHandler" {
+		t.Errorf("$Type = %v", got)
+	}
+	if got := getBSONField(h, "EventTypes"); !reflect.DeepEqual(got, bson.A{int32(1), "UserTaskStarted", "UserTaskEnded"}) {
+		t.Errorf("EventTypes = %v", got)
+	}
+	mh, ok := getBSONField(h, "MicroflowEventHandler").(bson.D)
+	if !ok || getBSONField(mh, "$Type") != "Workflows$MicroflowEventHandler" || getBSONField(mh, "Microflow") != "M.ACT_Audit" {
+		t.Errorf("MicroflowEventHandler = %v", mh)
+	}
+}
+
+func TestSerializeWorkflowEventHandlers_NoneIsTheBareMarker(t *testing.T) {
+	if got := serializeWorkflowEventHandlers(nil); !reflect.DeepEqual(got, bson.A{int32(2)}) {
+		t.Errorf("OnWorkflowEvent = %v, want [2]", got)
+	}
+}
+
+func TestSerializeOnCreatedEvent(t *testing.T) {
+	none := serializeOnCreatedEvent("")
+	if getBSONField(none, "$Type") != "Workflows$NoEvent" || getBSONField(none, "Microflow") != nil {
+		t.Errorf("no microflow = %v, want a bare NoEvent", none)
+	}
+	ev := serializeOnCreatedEvent("M.ACT_Assign")
+	if getBSONField(ev, "$Type") != "Workflows$MicroflowBasedEvent" || getBSONField(ev, "Microflow") != "M.ACT_Assign" {
+		t.Errorf("microflow = %v", ev)
+	}
+}
+
+// The parser read OnCreatedEvent as a string, which a stored document never is,
+// so every on-created microflow read back as none — and a describe of it lost
+// it. Round-tripped through real BSON bytes, as the reader sees them.
+func TestParseWorkflow_OnCreatedAndHandlersRoundTrip(t *testing.T) {
+	doc := bson.D{
+		{Key: "$Type", Value: "Workflows$Workflow"},
+		{Key: "OnWorkflowEvent", Value: serializeWorkflowEventHandlers([]*workflows.WorkflowEventHandler{
+			{Description: "OnAnyEvent", Documentation: "kept", EventTypes: []string{"WorkflowCompleted"}, Microflow: "M.ACT_Log"},
+		})},
+		{Key: "Task", Value: bson.D{
+			{Key: "$Type", Value: "Workflows$SingleUserTaskActivity"},
+			{Key: "Name", Value: "userTask1"},
+			{Key: "OnCreatedEvent", Value: serializeOnCreatedEvent("M.ACT_Assign")},
+		}},
+	}
+	data, err := bson.Marshal(doc)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var raw map[string]any
+	if err := bson.Unmarshal(data, &raw); err != nil {
+		t.Fatal(err)
+	}
+
+	handlers := parseWorkflowEventHandlers(raw["OnWorkflowEvent"])
+	if len(handlers) != 1 {
+		t.Fatalf("handlers = %d, want 1", len(handlers))
+	}
+	h := handlers[0]
+	if h.Description != "OnAnyEvent" || h.Documentation != "kept" || h.Microflow != "M.ACT_Log" ||
+		!reflect.DeepEqual(h.EventTypes, []string{"WorkflowCompleted"}) {
+		t.Errorf("handler = %+v", h)
+	}
+
+	task := parseUserTask(toMap(raw["Task"]))
+	if task.OnCreated != "M.ACT_Assign" {
+		t.Errorf("OnCreated = %q, want M.ACT_Assign", task.OnCreated)
+	}
+}
diff --git a/sdk/mpr/writer_workflow.go b/sdk/mpr/writer_workflow.go
index 56f58c4465..310f8c94a1 100644
--- a/sdk/mpr/writer_workflow.go
+++ b/sdk/mpr/writer_workflow.go
@@ -89,7 +89,7 @@ func (w *Writer) serializeWorkflow(wf *workflows.Workflow) ([]byte, error) {
 		{Key: "ExportLevel", Value: "Hidden"},
 		{Key: "Flow", Value: flowValue},
 		{Key: "Name", Value: wf.Name},
-		{Key: "OnWorkflowEvent", Value: bson.A{int32(2)}},
+		{Key: "OnWorkflowEvent", Value: serializeWorkflowEventHandlers(wf.EventHandlers)},
 	}
 
 	// Parameter
@@ -146,6 +146,52 @@ func renameCallMicroflowWalk(v any) {
 	}
 }
 
+// serializeWorkflowEventHandlers writes OnWorkflowEvent: a marker-2 list of
+// Workflows$WorkflowEventHandler, each with its event types as a marker-1 string
+// list — the shape ako/TestApp (11.14.0) stores.
+func serializeWorkflowEventHandlers(handlers []*workflows.WorkflowEventHandler) bson.A {
+	out := bson.A{int32(2)}
+	for _, h := range handlers {
+		types := bson.A{int32(1)}
+		for _, t := range h.EventTypes {
+			types = append(types, t)
+		}
+		id := string(h.ID)
+		if id == "" {
+			id = generateUUID()
+		}
+		out = append(out, bson.D{
+			{Key: "$ID", Value: idToBsonBinary(id)},
+			{Key: "$Type", Value: "Workflows$WorkflowEventHandler"},
+			{Key: "Description", Value: h.Description},
+			{Key: "Documentation", Value: h.Documentation},
+			{Key: "EventTypes", Value: types},
+			{Key: "MicroflowEventHandler", Value: bson.D{
+				{Key: "$ID", Value: idToBsonBinary(generateUUID())},
+				{Key: "$Type", Value: "Workflows$MicroflowEventHandler"},
+				{Key: "Microflow", Value: h.Microflow},
+			}},
+		})
+	}
+	return out
+}
+
+// serializeOnCreatedEvent writes a user task's OnCreatedEvent part: the microflow
+// when there is one, the NoEvent marker otherwise.
+func serializeOnCreatedEvent(microflow string) bson.D {
+	if microflow == "" {
+		return bson.D{
+			{Key: "$ID", Value: idToBsonBinary(generateUUID())},
+			{Key: "$Type", Value: "Workflows$NoEvent"},
+		}
+	}
+	return bson.D{
+		{Key: "$ID", Value: idToBsonBinary(generateUUID())},
+		{Key: "$Type", Value: "Workflows$MicroflowBasedEvent"},
+		{Key: "Microflow", Value: microflow},
+	}
+}
+
 // serializeWorkflowStringTemplate creates a minimal Mendix StringTemplate BSON structure for workflows.
 func serializeWorkflowStringTemplate(text string) bson.D {
 	return bson.D{
@@ -376,11 +422,7 @@ func serializeUserTask(a *workflows.UserTask) bson.D {
 		bson.E{Key: "Name", Value: a.Name},
 	)
 
-	// OnCreatedEvent (NoEvent)
-	doc = append(doc, bson.E{Key: "OnCreatedEvent", Value: bson.D{
-		{Key: "$ID", Value: idToBsonBinary(generateUUID())},
-		{Key: "$Type", Value: "Workflows$NoEvent"},
-	}})
+	doc = append(doc, bson.E{Key: "OnCreatedEvent", Value: serializeOnCreatedEvent(a.OnCreated)})
 
 	// Outcomes
 	outcomes := bson.A{int32(3)}
diff --git a/sdk/versions/mendix-10.yaml b/sdk/versions/mendix-10.yaml
index 7d70765dba..48e5ed6ee7 100644
--- a/sdk/versions/mendix-10.yaml
+++ b/sdk/versions/mendix-10.yaml
@@ -169,6 +169,10 @@ features:
       min_version: "9.0.0"
     user_task:
       min_version: "9.0.0"
+    event_handlers:
+      min_version: "10.7.0"
+      mdl: "CREATE WORKFLOW … ON WORKFLOW EVENTS (…) MICROFLOW Module.Handler AS '…'"
+      notes: "Workflow.onWorkflowEvent introduced in 10.7.0 (modelsdk gen). `ON ANY WORKFLOW EVENT` expands to the measured per-version type list and needs 11.6.0+."
 
   navigation:
     profiles:
diff --git a/sdk/versions/mendix-11.yaml b/sdk/versions/mendix-11.yaml
index 3a2a56a75f..3c58255858 100644
--- a/sdk/versions/mendix-11.yaml
+++ b/sdk/versions/mendix-11.yaml
@@ -180,6 +180,10 @@ features:
       min_version: "9.0.0"
     user_task:
       min_version: "9.0.0"
+    event_handlers:
+      min_version: "10.7.0"
+      mdl: "CREATE WORKFLOW … ON WORKFLOW EVENTS (…) MICROFLOW Module.Handler AS '…'"
+      notes: "Workflow.onWorkflowEvent introduced in 10.7.0 (modelsdk gen). `ON ANY WORKFLOW EVENT` expands to the measured per-version type list and needs 11.6.0+."
 
   navigation:
     profiles:
diff --git a/sdk/workflows/workflow.go b/sdk/workflows/workflow.go
index 5e4738617d..7f56036c4d 100644
--- a/sdk/workflows/workflow.go
+++ b/sdk/workflows/workflow.go
@@ -29,6 +29,9 @@ type Workflow struct {
 	// Context parameter
 	Parameter *WorkflowParameter `json:"parameter,omitempty"`
 
+	// EventHandlers are the workflow's OnWorkflowEvent handlers, in stored order.
+	EventHandlers []*WorkflowEventHandler `json:"eventHandlers,omitempty"`
+
 	// Flow contains the workflow activities
 	Flow *Flow `json:"flow,omitempty"`
 }
@@ -43,6 +46,16 @@ func (w *Workflow) GetContainerID() model.ID {
 	return w.ContainerID
 }
 
+// WorkflowEventHandler is a Workflows$WorkflowEventHandler: a microflow the
+// runtime calls for each of the listed workflow event types.
+type WorkflowEventHandler struct {
+	model.BaseElement
+	Description   string   `json:"description,omitempty"`   // how Studio Pro names the handler
+	Documentation string   `json:"documentation,omitempty"` // not authorable from MDL; carried
+	EventTypes    []string `json:"eventTypes,omitempty"`    // WorkflowEventType values, stored order
+	Microflow     string   `json:"microflow,omitempty"`     // qualified name of the handler microflow
+}
+
 // WorkflowParameter represents the context parameter of a workflow.
 type WorkflowParameter struct {
 	model.BaseElement

From e0b403689f46352ea0d89b642780f2171f0e4d7b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 15 Sep 2026 05:38:41 +0000
Subject: [PATCH 04/24] =?UTF-8?q?docs(plans):=20measure=20Phase=203=20?=
 =?UTF-8?q?=E2=80=94=20it=20is=20a=20bypass=20problem,=20not=20a=20seriali?=
 =?UTF-8?q?zer=20problem?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two questions from review, both of which the first draft got wrong by reasoning
from line counts instead of measuring callers.

MCP STAYS, and that is compatible. Its entire sdk/mpr dependency is ONE call —
mpr.Open(path) for a deliberately read-only reader, since writes already go over
MCP to Studio Pro. The naive port looks impossible and the reason is worth
recording: MCP calls 37 methods on that reader and modelsdk/mpr.Reader has 7.
But that is the wrong comparison — modelsdk/mpr is a unit/raw reader and the
semantic decoding lives a layer up. Against the modelsdk BACKEND, 33 of 37 are
already implemented. MCP composes the codec backend for reads; its 15,619 lines
are MCP protocol surface and are untouched.

api/ IS NOT DEPENDENT ON THE LEGACY BACKEND. It imports mdl/backend zero times —
it bypasses the abstraction entirely and holds a concrete *mpr.Writer. The
dependency is five symbols and seventeen methods, and FIFTEEN of the seventeen
are already implemented on the modelsdk backend, with all seventeen already
declared on FullBackend. The two missing (AddAttribute, UpdateAttribute) are
missing precisely BECAUSE api/ is their only caller, and ALTER ENTITY's mutator
is the template for both. The builder surface need not change, so the public API
break the first draft treated as a gate is not required.

The unifying finding, and the reason Phase 3 is now sequenced rather than
deferred: unreachableUnimplemented is a CENSUS OF WHO BYPASSES THE ABSTRACTION,
not dead weight. Its reason column names api/, the MCP backend, and the
cmd/mxcli commands that hold a concrete reader on purpose. Those methods are on
the interface because those callers exist and unreachable because those callers
do not use a backend value. Closing the bypasses makes them reachable or
genuinely deletable — and only after that is sdk/mpr's fate a question at all.

Phase 3 accordingly drops from "L, gated on a product decision" to "M", the a/b/c
options are replaced by a four-step sequence, and MCP is recorded as a fixed
constraint rather than a decision.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hifgRSawfaRWXS44YKtSJ
---
 docs/plans/2026-09-14-retire-legacy-engine.md | 127 +++++++++++++-----
 1 file changed, 93 insertions(+), 34 deletions(-)

diff --git a/docs/plans/2026-09-14-retire-legacy-engine.md b/docs/plans/2026-09-14-retire-legacy-engine.md
index 8ee1c58088..5bc07f2f58 100644
--- a/docs/plans/2026-09-14-retire-legacy-engine.md
+++ b/docs/plans/2026-09-14-retire-legacy-engine.md
@@ -13,14 +13,15 @@ the codec), [ADR-0002](../13-decisions/0002-backend-abstraction.md) (the seam th
 
 ## 1. The plan in one paragraph
 
-Retiring the legacy engine is **three independent removals wearing one name**, and the whole value
-of writing this down is refusing to treat them as one job. Deleting the legacy *backend*
-(`mdl/backend/mpr`, 2,808 lines) is small, unblocked, and reversible. Deleting the legacy
-*serializer* underneath it (`sdk/mpr`, 41,243 lines) is fifteen times larger and is gated on
-migrating consumers that never touched the engine seam at all — the public `api/` package, the MCP
-backend, eight `cmd/mxcli` commands. The mongo-driver v1→v2 migration the earlier plan promised at
-cutover is **gated on the second, not the first**, which is the opposite of what that plan assumed.
-Phase 1 can start today; Phases 2 and 3 need decisions that are not this plan's to make.
+Retiring the legacy engine is **three separable removals wearing one name**, and the whole value of
+writing this down is refusing to treat them as one job. Deleting the legacy *backend*
+(`mdl/backend/mpr`, 2,808 lines) is small, unblocked and reversible — that is Phase 1 and it can
+start today. Deleting the legacy *serializer* underneath it (`sdk/mpr`, 41,243 lines) is not a
+serializer problem at all: it is blocked by two callers that **bypass the backend abstraction**
+rather than by the serializer's size, and measuring them (§Phase 3) put that work at a 17-method
+port plus six unimplemented methods, not a rewrite. The mongo-driver v1→v2 migration the earlier
+plan promised at cutover is **gated on the second, not the first** — the opposite of what that plan
+assumed, and the reason it never started.
 
 ## 2. Why this is not one job (the measurement that reorders everything)
 
@@ -38,8 +39,7 @@ still do. But the split does not fall where that plan implies:
 The driver split maps almost exactly onto the **serializer** split, not onto the engine flag. The
 codec is already wholly on v2; `sdk/mpr` is wholly on v1; the adapter straddles both because it
 converts between semantic types and gen documents. So **deleting the legacy backend does not move
-the driver migration at all** — what unblocks v2 is deleting `sdk/mpr`, and that is Phase 3, behind
-a decision about the public API.
+the driver migration at all** — what unblocks v2 is deleting `sdk/mpr`, which is Phase 3.
 
 Stating this is the point of the plan. Sequenced the other way round, Phase 1 looks like it owes a
 41k-line migration and never gets started.
@@ -103,39 +103,88 @@ rather than after it:
   multi-backend future in which legacy is one of the backends.
 - CLAUDE.md's `--engine` line, and the flag's help text.
 
-### Phase 3 — Decide the fate of `sdk/mpr` *(Effort: L, Risk: Med — NOT scheduled here)*
+### Phase 3 — Route the bypass sites through the backend abstraction *(Effort: M, Risk: Low–Med)*
 
-This is where the size is, and this plan deliberately does not schedule it: **it is a product
-decision about the public API, not a cleanup.**
+**Revised 2026-09-15 after measuring it.** The first draft called this "decide the fate of
+`sdk/mpr`", sized it L, and gated it on a product decision about breaking the public API. Measuring
+the two consumers overturned all three.
 
-`sdk/mpr` is 41,243 lines and has consumers that never routed through the engine seam:
+#### The `unreachableUnimplemented` list is a census of who bypasses the abstraction
 
-| Consumer | Why it matters |
+`mdl/backend/modelsdk/unimplemented_reachability_test.go` pins 16 `FullBackend` methods as having no
+caller *through a backend value*. Read its reason column as a map rather than a list and it names
+exactly the sites that hold a concrete `sdk/mpr` reader or writer instead:
+
+| Bypass site | Methods it is the reason for |
 |---|---|
-| `api/` (9 files, 3,287 lines) | the public fluent API — `modelsdk.Open` / `OpenForWriting` |
-| `mdl/backend/mcp` | a **shipped, live backend**; breaking it breaks Studio Pro integration |
-| 8 `cmd/mxcli` commands | `bson dump`/`compare`/`discover`, `extract-templates`, `new`, … — these hold a concrete reader on purpose |
-| `examples/`, `scripts/mprsnapshot` | |
+| `api/` | `AddAttribute`, `UpdateAttribute`, `ExportJSON` |
+| `mdl/backend/mcp` | `GetDomainModelByID`, `GetWorkflow`, `ListNavigationDocuments` |
+| `cmd/mxcli` commands holding a reader | `FindCustomWidgetType`, `ListAllUnitIDs`, `ListRawUnits`, … |
+
+These methods are on the interface *because* those callers exist, and they are unreachable
+*because* those callers do not use a backend value. That circularity is the actual finding: the list
+is not dead weight to delete, it is the work item. Close the bypasses and the methods either become
+reachable and implemented, or become genuinely deletable.
+
+#### `api/` — 3,287 lines, but a 17-method surface
+
+`api/` **does not import `mdl/backend` at all** (measured: zero files). It is not "dependent on the
+legacy backend"; it sidesteps the abstraction entirely, holding a concrete `*mpr.Writer` handed to
+`api.New`. The whole dependency is five symbols — `mpr.NewWriter`, `Writer`, `Reader`, `Open`,
+`GenerateID` — and seventeen methods called through them.
+
+Of those seventeen, **fifteen are already implemented on the modelsdk backend** and all seventeen
+are already declared on `FullBackend`:
+
+    already on modelsdk   GetModuleByName, GetDomainModel, ListModules, UpdateEnumeration,
+                          ListPages, ListMicroflows, DeleteAttribute, ListLayouts,
+                          ListEnumerations, GetModule, CreatePage, CreateMicroflow,
+                          CreateEnumeration, CreateEntity, CreateAssociation
+    missing               AddAttribute, UpdateAttribute
+
+and the two missing ones are missing *because `api/` is their only caller*. The template for
+implementing them already exists: `ALTER ENTITY` does attribute mutation through the mutator.
 
-Three options, and the answer is not obvious:
+So the port is: change `api.New` to take a `backend.FullBackend`, swap seventeen call sites, and
+implement two methods. The public signatures of the builders (`CreateEntity(...).persistent()
+.WithStringAttribute(...)`) need not change at all. **A breaking change to the published library is
+not required**, so "does anything outside this repo depend on `api/`?" stops being a gate and
+becomes a courtesy check on one parameter type (§5, decision D).
 
-- **(a) Keep `sdk/mpr` as a reader-only SDK.** Cheapest. Leaves the tree on two drivers
-  indefinitely, which means v2's improvements stay out of reach and every new file has to pick a
-  driver.
-- **(b) Port the consumers to `modelsdk/mpr` and delete `sdk/mpr`.** Unblocks the driver migration.
-  Costs an `api/` rewrite and therefore a breaking change to the one thing mxcli publishes as a
-  library.
-- **(c) Reimplement `api/` on the codec** and keep its signatures, absorbing the cost inside the
-  package. Most work, least disruption to users.
+#### `mdl/backend/mcp` — stays, and is compatible
 
-**The prerequisite either way** is knowing whether anything outside this repository depends on
-`api/`. That is a question for the maintainer, not a measurement.
+The MCP backend is in active use and its usage is expected to grow, so it is a fixed constraint
+rather than something to migrate away. That constraint is satisfiable: its entire `sdk/mpr`
+dependency is **one call**, `mpr.Open(path)`, for a deliberately read-only reader — writes already
+go over MCP to Studio Pro, which is the whole point of the backend.
+
+The naive port fails and the reason is worth recording: MCP calls **37 methods** on that reader and
+`modelsdk/mpr.Reader` has **7** of them. But that is the wrong comparison — `modelsdk/mpr` is a
+unit/raw reader, and the semantic decoding lives one layer up. Against the modelsdk **backend**,
+**33 of the 37 are already implemented**; the gaps are `GetDomainModelByID`, `GetWorkflow`,
+`ListNavigationDocuments` (the three the census above already attributes to MCP) and `Close`, which
+is lifecycle rather than a read.
+
+So MCP composes the codec backend for its reads instead of opening its own reader. Its 15,619 lines
+are almost entirely the MCP protocol surface and are untouched by this.
+
+#### Sequence
+
+1. Implement the six methods the census attributes to `api/` and MCP.
+2. Point MCP's reads at a composed codec backend; delete its `mpr.Open`.
+3. Change `api.New` to accept `backend.FullBackend`; swap the seventeen call sites.
+4. Re-run the reachability probe. What remains unreachable is the `cmd/mxcli` bson/diag commands,
+   which hold a concrete reader **on purpose** — decide then whether they justify keeping a
+   reader-only `sdk/mpr`, or whether they move too.
+
+**Only after step 4 is `sdk/mpr`'s fate a question at all**, and by then it is a small one.
 
 ### Phase 4 — mongo-driver v1 → v2 *(Effort: L, Risk: Med — gated on Phase 3)*
 
-Only reachable via 3(b) or 3(c). With `sdk/mpr` gone the remaining v1 files are the
-`mdl/backend/modelsdk` adapter's 44 and `mdl/executor`'s 17, both of which exist to bridge the two
-worlds and shrink as the semantic types move to v2. Not worth sequencing until Phase 3 resolves.
+Reachable once Phase 3's step 4 settles whether anything still needs `sdk/mpr`. With it gone the
+remaining v1 files are the `mdl/backend/modelsdk` adapter's 44 and `mdl/executor`'s 17 — both exist
+to bridge the two worlds and shrink as the semantic types move to v2, so the real size of this
+phase is not knowable until Phase 3 lands. Not worth sequencing before then.
 
 ## 5. Decisions to confirm before Phase 1 starts
 
@@ -149,6 +198,14 @@ worlds and shrink as the semantic types move to v2. Not worth sequencing until P
 - **C. Does `mxcli bson compare` still make sense?** It is a user-facing command whose purpose was
   comparing engine output. It may have a second life as a Studio-Pro-vs-mxcli diff, which is a
   different feature wearing the same name.
+- **D. Does `api.New`'s signature change, or does it keep taking a concrete writer?** This is the
+  only user-visible question in Phase 3 and it is much narrower than the first draft implied: the
+  builder surface is unaffected either way (§Phase 3). Taking `backend.FullBackend` is the honest
+  shape; keeping a concrete parameter and adapting inside preserves source compatibility for any
+  out-of-tree caller.
+
+**Fixed constraint, not a decision:** `mdl/backend/mcp` stays. It is in active use and its usage is
+expected to grow. Phase 3 is written to satisfy that rather than to migrate away from it.
 
 ## 6. What could go wrong
 
@@ -169,4 +226,6 @@ worlds and shrink as the semantic types move to v2. Not worth sequencing until P
 1. Answer decisions A and B (§5). They are one-line answers and they gate the diff's shape.
 2. Phase 1 as a single PR, with the CI matrix change in it.
 3. Phase 2 in the same PR — the stale docs are wrong the moment Phase 1 lands.
-4. Open Phase 3 as a **proposal**, not a plan: it needs the `api/` decision before a sequence exists.
+4. Phase 3 is now sequenced in place (it was going to be a proposal until measuring it shrank it).
+   Its first step — implementing the six methods the census attributes to `api/` and MCP — is
+   independent of Phases 1–2 and could be done first or in parallel.

From 9b39ec6726ea61d0340f2d6f943f639ed5209717 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 15 Sep 2026 05:47:11 +0000
Subject: [PATCH 05/24] docs(plans): refresh the plan's measurements against
 current main
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Merging main moved three of the numbers the plan asserts: sdk/mpr 41,243 ->
41,418 lines and 113 -> 114 v1 files, mdl/executor 17 -> 18. The caller
measurements that carry the argument are unchanged — api/ still imports
mdl/backend zero times and needs 17 methods of which 15 are implemented, MCP
still needs 33 of 37, the reachability test still passes, and there are still no
"not supported by the modelsdk engine" messages.

A plan whose figures rot is the specific failure this one was written to correct
in its predecessor, so the verification line is now dated to the merge.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hifgRSawfaRWXS44YKtSJ
---
 docs/plans/2026-09-14-retire-legacy-engine.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/plans/2026-09-14-retire-legacy-engine.md b/docs/plans/2026-09-14-retire-legacy-engine.md
index 5bc07f2f58..555d173c5a 100644
--- a/docs/plans/2026-09-14-retire-legacy-engine.md
+++ b/docs/plans/2026-09-14-retire-legacy-engine.md
@@ -16,7 +16,7 @@ the codec), [ADR-0002](../13-decisions/0002-backend-abstraction.md) (the seam th
 Retiring the legacy engine is **three separable removals wearing one name**, and the whole value of
 writing this down is refusing to treat them as one job. Deleting the legacy *backend*
 (`mdl/backend/mpr`, 2,808 lines) is small, unblocked and reversible — that is Phase 1 and it can
-start today. Deleting the legacy *serializer* underneath it (`sdk/mpr`, 41,243 lines) is not a
+start today. Deleting the legacy *serializer* underneath it (`sdk/mpr`, 41,418 lines) is not a
 serializer problem at all: it is blocked by two callers that **bypass the backend abstraction**
 rather than by the serializer's size, and measuring them (§Phase 3) put that work at a 17-method
 port plus six unimplemented methods, not a rewrite. The mongo-driver v1→v2 migration the earlier
@@ -32,9 +32,9 @@ still do. But the split does not fall where that plan implies:
 | Package | mongo-driver v1 | v2 | What it is |
 |---|---|---|---|
 | `modelsdk/` | **0** | **117** | the codec engine |
-| `sdk/mpr` | **113** | **0** | the legacy serializer |
+| `sdk/mpr` | **114** | **0** | the legacy serializer |
 | `mdl/backend/modelsdk` | 44 | 45 | the adapter where the two meet |
-| `mdl/executor` | 17 | 5 | |
+| `mdl/executor` | 18 | 5 | |
 
 The driver split maps almost exactly onto the **serializer** split, not onto the engine flag. The
 codec is already wholly on v2; `sdk/mpr` is wholly on v1; the adapter straddles both because it
@@ -44,7 +44,7 @@ the driver migration at all** — what unblocks v2 is deleting `sdk/mpr`, which
 Stating this is the point of the plan. Sequenced the other way round, Phase 1 looks like it owes a
 41k-line migration and never gets started.
 
-## 3. What is already true (verified 2026-09-14, not assumed)
+## 3. What is already true (verified 2026-09-15 against main, not assumed)
 
 Every one of these was checked rather than inherited from the earlier plan:
 
@@ -182,7 +182,7 @@ are almost entirely the MCP protocol surface and are untouched by this.
 ### Phase 4 — mongo-driver v1 → v2 *(Effort: L, Risk: Med — gated on Phase 3)*
 
 Reachable once Phase 3's step 4 settles whether anything still needs `sdk/mpr`. With it gone the
-remaining v1 files are the `mdl/backend/modelsdk` adapter's 44 and `mdl/executor`'s 17 — both exist
+remaining v1 files are the `mdl/backend/modelsdk` adapter's 44 and `mdl/executor`'s 18 — both exist
 to bridge the two worlds and shrink as the semantic types move to v2, so the real size of this
 phase is not knowable until Phase 3 lands. Not worth sequencing before then.
 

From 28ae3ea0b6970c00bd9ebc73f13147c81c880de0 Mon Sep 17 00:00:00 2001
From: Ako <andrej@koelewijn.net>
Date: Tue, 15 Sep 2026 06:02:53 +0000
Subject: [PATCH 06/24] feat(workflow): author AI agent tasks with `call agent
 microflow`
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 2 of PROPOSAL_workflow_studio_pro_constructs.md. An AI agent task
(Workflows$AIAgentTaskActivity, Mendix 11.9+) stores exactly the
call-microflow shape under a different $Type (ako/TestApp, 11.14.0), so it is
the call-microflow statement with `agent` added and, in the semantic model, a
CallMicroflowTask with IsAgent — every walker, validator, catalog edge, naming
rule and ALTER path applies unchanged; only $Type, describe and the rewrite
guard branch on it.

  call agent microflow HR.Classify as aiAgentTask1 comment 'Classify'
    with (Request = '$WorkflowContext')
    outcomes true -> { … } false -> { };

Measured on mxbuild 11.13.0 by writing each shape as a call microflow and
switching only the $Type: everything builds the same (context, System.Workflow
or several parameters; Boolean and enumeration outcomes; boundary events)
except an agent microflow with no parameters, which fails CE1590 — the one
new check. Gated on workflows.ai_agent_task (11.9.0) for CREATE and ALTER.

Describe used to print an agent task as a comment, so a rewrite refused the
whole workflow; it now emits `call agent microflow` and the guard counts
restated agent tasks. The modelsdk engine writes and reads it; the retiring
legacy engine carries the $Type through rather than downgrading the task; the
MCP backend sends it as AIAgentTaskActivity — the shape Studio Pro 11.14's
ped_get_schema declares.

Verified in Studio Pro 11.14 over MCP: the agent task, handler and on-created
shapes are accepted and read back as written; the on-created and handler
signature errors match mxbuild's CE6683/CE6691 text; an agent task without
parameter mappings is flagged; an invented event type is refused at create.

Fixed on the way:
- MCP mapper hard-coded onCreatedEvent NoEvent and sent no onWorkflowEvent,
  silently dropping phase 1 over MCP; and Studio Pro 11.14's workflow
  constructor takes `context` and a string workflowName, so every workflow
  create over MCP failed. The shape is now read off the live constructor
  schema.
- describe printed a call microflow's caption only as a `--` comment, so
  describe -> exec replaced it with the microflow's name; an authored caption
  is now `comment '…'`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../fix-issue/findings/mdl-backend.jsonl      |   1 +
 .../fix-issue/findings/mdl-executor.jsonl     |   1 +
 .../skills/mendix/write-workflows/SKILL.md    |  14 +-
 CHANGELOG.md                                  |  11 ++
 cmd/mxcli/syntax/features_workflow.go         |  29 +++-
 docs-site/src/language/workflow-activities.md |  28 ++++
 docs/01-project/MDL_QUICK_REFERENCE.md        |   1 +
 docs/03-development/PED_MCP_CAPABILITIES.md   |  34 ++++
 ...PROPOSAL_workflow_studio_pro_constructs.md |  58 ++++++-
 .../doctype-tests/24-workflow-examples.mdl    |  43 +++++
 mdl/ast/ast_workflow.go                       |   1 +
 mdl/backend/mcp/backend.go                    |   6 +
 mdl/backend/mcp/workflow.go                   | 150 +++++++++++++++++-
 mdl/backend/mcp/workflow_constructor_test.go  |  79 +++++++++
 mdl/backend/mcp/workflow_handlers_test.go     | 101 ++++++++++++
 mdl/backend/mcp/workflow_test.go              |   6 +-
 mdl/backend/modelsdk/workflow_agent_test.go   | 109 +++++++++++++
 mdl/backend/modelsdk/workflow_read.go         |   7 +
 mdl/backend/modelsdk/workflow_write.go        |  15 +-
 mdl/executor/cmd_alter_workflow.go            |   7 +
 mdl/executor/cmd_workflows.go                 |  22 ++-
 mdl/executor/cmd_workflows_write.go           |   8 +-
 mdl/executor/validate_workflow_agent.go       |  63 ++++++++
 mdl/executor/validate_workflow_agent_test.go  | 103 ++++++++++++
 mdl/executor/validate_workflow_rewrite.go     |  32 +++-
 .../validate_workflow_task_signature.go       |   4 +
 .../workflow_callmicroflow_caption_test.go    |  58 +++++++
 mdl/grammar/domains/MDLWorkflow.g4            |   8 +-
 mdl/visitor/visitor_workflow.go               |   1 +
 mdl/visitor/visitor_workflow_agent_test.go    |  35 ++++
 sdk/mpr/parser_workflow.go                    |  17 +-
 sdk/mpr/workflow_agent_test.go                |  32 ++++
 sdk/mpr/writer_workflow.go                    |   6 +-
 sdk/versions/mendix-11.yaml                   |   4 +
 sdk/workflows/workflow.go                     |   5 +
 35 files changed, 1056 insertions(+), 43 deletions(-)
 create mode 100644 mdl/backend/mcp/workflow_constructor_test.go
 create mode 100644 mdl/backend/mcp/workflow_handlers_test.go
 create mode 100644 mdl/backend/modelsdk/workflow_agent_test.go
 create mode 100644 mdl/executor/validate_workflow_agent.go
 create mode 100644 mdl/executor/validate_workflow_agent_test.go
 create mode 100644 mdl/executor/workflow_callmicroflow_caption_test.go
 create mode 100644 mdl/visitor/visitor_workflow_agent_test.go
 create mode 100644 sdk/mpr/workflow_agent_test.go

diff --git a/.claude/skills/fix-issue/findings/mdl-backend.jsonl b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
index 71727447b8..73f8626da3 100644
--- a/.claude/skills/fix-issue/findings/mdl-backend.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
@@ -95,3 +95,4 @@
 {"area": "mdl/backend", "date": "2026-09-12", "symptom": "The modelsdk (default) engine leaves 19 of FullBackend's 276 methods to the errUnimplemented stub, which tells the user to \"rerun with MXCLI_ENGINE=legacy\" — the engine being retired. Nineteen unported methods reads as nineteen reasons legacy has to stay shipped and tested", "cause": "Seventeen of the nineteen cannot be reached at all: they are interface surface that only the MPR backend's own delegation and callers holding a concrete *mpr.Reader / *mpr.Writer (api/, examples/, cmd/mxcli commands that open a reader directly) ever touch, so the stub can never fire. The two that ARE reachable — GetRawUnitByName and ParseMicroflowBSON, four call sites in mdl/executor/cmd_microflows_builder.go — were invisible because each is a fast path with a working slow-path fallback: the stub errored, the code fell through to an O(n) module walk, and the result was identical", "file": "`mdl/backend/modelsdk/raw_lookup.go` (new), `mdl/backend/modelsdk/unimplemented_reachability_test.go` (new), `scripts/backend-reachability.sh` (new)", "insight": "**Grep cannot answer \"is this interface method reachable\" and the compiler can.** `b.reader.GetRawUnitByName(...)` inside the MPR backend and `ctx.Backend.GetRawUnitByName(...)` in the executor are indistinguishable to a regex, and receiver names vary, so a grep-based count said all nineteen had callers. Deleting one method from its interface at a time and rebuilding gives a yes/no per method with no judgement involved: 17 DEAD, 2 LIVE. Slow (one `go build ./...` each, minutes for the set) but decisive — script it, commit it, and pin its OUTPUT in a test rather than re-running it in CI. **A fallback hides an unimplemented method completely.** Nothing was broken and no test failed, because the fast path's failure was indistinguishable from a cache miss; the only symptom was work being done twice. Look for `if x, err := …; err == nil` fast paths when auditing what an engine cannot do. **Measure the speedup before claiming one**: restoring the fast path made no measurable difference (620ms vs 608ms over three runs on a 138-microflow project, within noise), because `mxcli exec` runs `check` first and check's own helpers load ListMicroflows anyway — so the cache the slow path builds is already warm. The value here is the removal of the errUnimplemented cliff, not speed", "refs": []}
 {"area": "mdl/backend", "date": "2026-09-11", "symptom": "`ALTER PAGE REPLACE`/`INSERT` inside a data view bound `datasource: selection <list>` re-scopes the new widget's attribute binding to the OUTER data view's entity (**CE1613** \"The selected attribute 'Mod.Outer.Attr' no longer exists\"), and inside a Gallery/DataGrid 2 sourced by a **microflow/nanoflow** drops it entirely (**CE0402** \"No value specified\", `describe` shows `ContentParams: [{1} = <unbound>]`). `mxcli check --references` and `exec` both report success; `CREATE PAGE` binds the same widget in the same position correctly", "cause": "The mutator resolved a widget's scope in TWO walks that each knew a different subset of the ten Forms$*Source kinds. `Forms$ListenTargetSource` carries no EntityRef at all \u2014 only the listen target's NAME \u2014 so the entity walk saw no source on the selection data view and left the context at the enclosing one. The flow walk (`findNearestDataSourceDoc`) read only a widget's TOP-LEVEL `DataSource` key, so a pluggable list \u2014 whose source sits at `Object.Properties[datasource].Value.DataSource` \u2014 contributed nothing, and its `Objects[].Properties[].Value.Widgets` descent (the one the entity walk gained in #935) was missing too", "file": "`mdl/backend/pagemutator/mutator.go` (`resolveSourceScope`/`resolveSourceScopeVia`, `listenTargetDataSource`, `widgetOwnDataSourceDoc`, `pluggableDataSourceDoc`; `EnclosingEntity`/`EnclosingEntityForChildren`/`EnclosingDataSourceFlow` now share the one walk `findNearestDataSourceDoc`, and `findEnclosingEntityContext` + its two helpers are deleted)", "insight": "**Count the source kinds before fixing one.** `generated/metamodel/types.go`'s `DataSource is implemented by` list closes the set at ten, and they divide exactly three ways \u2014 seven carry an EntityRef, two are flows, one (ListenTarget) borrows the scope of the widget it names \u2014 so one resolver can be complete, where three successive per-kind patches (FINDINGS #55 association+flow, #935 pluggable, this one) each left a hole. **A nearer source that resolves to no entity must SHADOW the outer one**: inheriting is what wrote the wrong entity, and it also mis-scoped a flow-sourced list nested in an entity-bound data view \u2014 a case the report did not name and the old code got wrong. The listen target is found by a shape-independent search for \"a document with this Name that has a data source\", which is what makes it work when the target is a pluggable widget keeping its source three levels inside its Object; a visited-set guards a hand-written listen cycle. **Measurement trap: a CE1613 SUPPRESSES the CE0402s in the same `mx check` run** \u2014 the first reading said mxbuild tolerated the unbound parameter, and the CE0402s only appeared once the re-scoped binding was fixed, so count bindings in `describe`, not errors. The issue's own second repro (a Gallery over a DATABASE source) no longer reproduced \u2014 #935 had fixed it \u2014 and the live defect was its flow-sourced variant, so re-measure a report against main before trusting its class. Tests `mdl/backend/pagemutator/mutator_selection_source_test.go` (7, incl. dangling/cyclic listen targets and the shadowing control); repro `mdl-examples/bug-tests/1076-alter-page-selection-and-flow-scope.mdl` \u2014 2 \u00d7 CE1613 + 3 unbound before, 0 errors after, on mxbuild 11.10.0. Each half proven load-bearing by stubbing it alone and rebuilding the CLI", "refs": ["mendixlabs/mxcli#1076", "#55", "#935"], "ce": ["CE0402", "CE1613"]}
 {"area": "mdl/backend", "date": "2026-09-15", "symptom": "On the default engine, `describe workflow` printed `wait for notification x;` without its boundary events (and their handler flows); the legacy engine described them. A describe -> exec round trip lost them.", "cause": "workflowActivityFromGen's typed switch had no case for *genWf.WaitForNotificationActivity, so it fell to workflowSimpleActivityFromGen, which reads only Name and Caption from raw BSON. That path's comment said the wait activities 'have no genWf struct' — true once, stale by the time gen gained WaitForNotificationActivity with BoundaryEventsItems().", "fix": "Typed case reading boundaryEventsFromGen(a.BoundaryEventsItems()), like the five other activities that carry boundary events.", "file": "mdl/backend/modelsdk/workflow_read.go", "insight": "A fallback path documented as 'for types gen does not model' silently keeps catching a type after gen starts modelling it; the reader then under-reads without any error. When gen is re-vendored, grep the typed switches for types that newly have structs. The bug surfaced only because a probe described what it had just written — reading back your own write, per activity type, is the cheap check."}
+{"area": "mdl/backend/mcp", "date": "2026-09-15", "symptom": "Over MCP (--mcp) against Studio Pro 11.14, `create workflow` fails with `ped_create_document …: Validation errors … {\"/context\":\"Expected reference (string), got undefined\",\"/workflowName\":\"Expected string, got object\"}`; and on any version a workflow's on-created microflows and event handlers were silently absent from the created document", "cause": "(1) Studio Pro 11.14's Workflows$Workflow CONSTRUCTOR takes `context` (entity qualified name) and plain-string `workflowName`/`caption`; the mapper sent the older `parameter` element and a StringTemplate. The element (update) shape is unchanged. (2) mapWorkflowActivity hard-coded `onCreatedEvent: {$Type: Workflows$NoEvent}` and mapWorkflow never sent `onWorkflowEvent`, so constructs added to the semantic model later were dropped", "file": "`mdl/backend/mcp/workflow.go` (`workflowConstructorTakesContext`, `mapWorkflowContent`, `mapOnCreatedEvent`, `mapWorkflowEventHandlers`)", "insight": "`ped_get_schema` is a live oracle — ask it rather than guessing a version: the constructor schema text says `context: Reference<'DomainModels$Entity'` on servers that need the new shape. Any hard-coded default in a PED mapper (NoEvent, empty list) becomes silent data loss the moment the semantic model gains the property — grep the mappers for literals when a construct becomes authorable. ped_check_errors lags: a fresh document reports 'No errors found.' and its real errors only on a later call, so re-check before trusting a clean verdict"}
diff --git a/.claude/skills/fix-issue/findings/mdl-executor.jsonl b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
index aa9de8b26f..cd253f36df 100644
--- a/.claude/skills/fix-issue/findings/mdl-executor.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
@@ -618,3 +618,4 @@
 {"area": "mdl/executor", "date": "2026-09-14", "symptom": "A workflow user task whose task page takes the context entity instead of System.WorkflowUserTask (CE7412), takes no parameters (CE7410), or whose targeting microflow does not take exactly System.Workflow plus the context entity (CE6677) passed `mxcli check` AND `check --references`, was written by exec, and failed only under the native mx check. Reported in a team briefing on building workflows from MDL as two of the reasons 'a green CLI check is not evidence for workflows'.", "cause": "validateWorkflowReferences resolved the user task's page and targeting microflow by NAME only — it reported a document that does not exist, never one that exists with the wrong signature. Neither signature was in `mxcli syntax workflow` either, so authors had nothing to copy.", "fix": "validate_workflow_task_signature.go checks both signatures from the script's own definitions first (scriptContext now records page parameter entities and entity generalizations, beside flowParams) and then the project, for CREATE WORKFLOW (incl. nested and multi-user tasks) and ALTER WORKFLOW (inserted tasks, SET ACTIVITY PAGE / TARGETING MICROFLOW, context entity read off the stored workflow). Wired into validateWorkflowStatementRefs / validateAlterWorkflowRefs. check --references reports before anything is written; exec calls the same function at the workflow statement, so the workflow is never written but earlier statements in the script already are. Gated on Mendix 11, where it is measured.", "file": "mdl/executor/validate_workflow_task_signature.go", "insight": "Measure the CLEAN edges before writing a refusal — three of the nine rows would have been false refusals from a plausible reading of the error text: a task page MAY take extra parameters besides WorkflowUserTask, a targeting microflow MAY take its two parameters in either order, and its context parameter MAY be a generalization of the context entity (but not a specialization). Since exec refuses on a check error, a false refusal is a blocker. Where the inheritance chain leaves what can be resolved (a script entity extending something unknown), return 'not proven' rather than a mismatch. Also a harness caveat worth keeping: the control run that stubbed the version gate first reported 0 failures because the harness only counted `--- FAIL` lines containing '/', i.e. subtests; the gate test is top-level. A silent control is a claim about the harness before it is a claim about the test. And run `make test-integration` before pushing a reference-path rule: the unit suite gates the rule on a mock project with no version, so it never fired there, while the integration round-trip tests exec against a real 11.x project — and their shared helper created task pages with no parameters and targeting microflows with none, which CI refused. Those fixtures had never been built; the rule was right, they were repaired."}
 {"area": "mdl/executor", "date": "2026-09-14", "symptom": "An `exec` / `check --references` error on a CREATE WORKFLOW statement ends with 'hint: M.W is defined later in this script — move its create statement before this one', naming the failing workflow itself (or a workflow already created earlier in the script).", "cause": "annotateForwardRef draws candidate names from scriptContext.allNames (which includes workflows) and excludes the statement's own name and already-created names via scriptContext.has — which checked modules, entities, enumerations, microflows, nanoflows, pages, snippets and code actions but NOT workflows. A parallel list that drifted from the one it filters.", "fix": "scriptContext.has also answers for sc.workflows.", "file": "mdl/executor/validate.go", "insight": "Two lists over the same kinds (allNames and has) with nothing tying them together — the same drift shape as collectDefinitions/collectSingle. The misfire only became visible once an error routinely named its own workflow, i.e. a new rule surfaced a latent bug in how every rule's message is decorated. When adding a document kind to scriptContext, check every method that enumerates kinds, not just the collector."}
 {"area": "mdl/executor", "date": "2026-09-14", "symptom": "On the **legacy** engine (MXCLI_ENGINE=legacy), `create or modify workflow` that does not restate stored event handlers / boundary events / nested Ends / AI agent tasks / completion rules is written (\"Created workflow\") and deletes them, while the default modelsdk engine refuses the same statement with the guard-don't-drop list", "cause": "The workflow rewrite guards walk `ctx.Backend.GetRawUnit` with type switches on `map[string]any` / `[]any`. The legacy backend decodes with mongo-driver v1 `bson.Unmarshal` into map[string]any, which yields nested documents as map[string]any but ARRAYS AS `primitive.A` — a named type a `case []any` does not match. So every guard saw no list at all (measured with a probe: `OnWorkflowEvent primitive.A`, `Flow map[string]interface {}`). The modelsdk reader normalizes to plain slices (`modelsdk/mpr/reader_raw.go normalizeBSONValue`), which is why only legacy was blind", "file": "`mdl/executor/validate_workflow_rewrite.go` (`plainRawUnit`, applied in `checkNoDroppedWorkflowConstructs` and `validateAlterReplaceKeepsStudioProState`)", "insight": "A guard tested only with hand-built `[]any` fixtures proves nothing about the legacy engine: build the fixture, then `bson.Marshal` + `bson.Unmarshal` into map[string]any to get the shape legacy's GetRawUnit really returns (`legacyShaped` in validate_workflow_rewrite_legacy_test.go). Normalized in the guard, not in MprBackend.GetRawUnit, because catalog (`builder_regularexpressions.go`) asserts `bson.A` on raw units. Found only by running the e2e rewrite on BOTH engines — the modelsdk run was green. Other `[]any`-only raw walkers (REST body guard, queued-call guard) are suspects of the same class. Control: normalizer returning its input fails the legacy-shape tests"}
+{"area": "mdl/executor", "date": "2026-09-15", "symptom": "`describe workflow` → `create or modify` → `describe` differs: a call microflow authored with `comment 'Summarise'` comes back captioned with the microflow's name (`-- ACT_Summarise`)", "cause": "`formatCallMicroflowTask` printed the caption only as a trailing `-- caption` MDL comment, which the parser discards; re-execution then fell back to the builder's default caption (the microflow's short name)", "file": "`mdl/executor/cmd_workflows.go` (`formatCallMicroflowTask`)", "insight": "A trailing `--` comment in describe output is documentation, not data — anything round-trippable must be a grammar clause. Emit `comment '…'` only when the caption differs from the derived default, matching jump/wait (issuetracker #16), so an unauthored caption does not start appearing as authored. Only an end-to-end describe → exec → describe with an AUTHORED caption catches it; fixtures without captions pass either way"}
diff --git a/.claude/skills/mendix/write-workflows/SKILL.md b/.claude/skills/mendix/write-workflows/SKILL.md
index 8148118712..36eb23a359 100644
--- a/.claude/skills/mendix/write-workflows/SKILL.md
+++ b/.claude/skills/mendix/write-workflows/SKILL.md
@@ -329,9 +329,9 @@ documented in `system-module`.
 ## Platform rules
 
 - **Some workflow state has no MDL spelling, and a rewrite refuses rather than
-  reset it.** An event sub-process, an AI agent task, a workflow event handler
-  subscribed to no event types, and a multi-user task's completion rule other
-  than consensus falling back to its first outcome are set in Studio Pro.
+  reset it.** An event sub-process, a workflow event handler subscribed to no
+  event types, and a multi-user task's completion rule other than consensus
+  falling back to its first outcome are set in Studio Pro.
   `create or modify` on a workflow that holds any of them is refused with the
   list, and so is `alter workflow … replace activity` on an activity that holds
   one. Change such a workflow with `alter workflow … set activity …` (it edits
@@ -356,6 +356,14 @@ documented in `system-module`.
   An outcome left **empty** does not stop anything — it rejoins the main flow.
   `comment '…'` sets the End's caption, as on every workflow activity.
 
+- **An AI agent task is `call agent microflow`** (Mendix 11.9+) — the call
+  microflow statement stored as `Workflows$AIAgentTaskActivity`, with the same
+  `as`, `comment`, `with (…)`, `outcomes` and boundary events. The microflow is
+  where the agent is invoked. Measured on mxbuild 11.13 against the identical
+  call microflow, one rule differs: **its microflow must take a parameter**
+  (`CE1590 "Missing parameter"`), usually the context object mapped with
+  `with (Param = '$WorkflowContext')`. Return Boolean or an enumeration to
+  branch on the answer.
 - **Handler microflows have fixed signatures** (measured, mxbuild 11.13):
   - `on created microflow` takes exactly `System.WorkflowUserTask` and the context
     entity, in either order — anything else is `CE6683` — and returns nothing
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 417f04afb0..686b5cf215 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+
+- **AI agent tasks in workflows: `call agent microflow`** (docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md, phase 2) — the workflow step that runs an AI agent, which `describe workflow` could only print as a `-- [Workflows$AIAgentTaskActivity]` comment and a rewrite therefore refused. It is the call-microflow statement with `agent` added — same `as`, `comment`, `with (…)`, `outcomes` and boundary events — because Mendix stores exactly the call-microflow shape under a different `$Type` (ako/TestApp, 11.14.0). The rules were measured on mxbuild 11.13.0 by writing each shape as a call microflow and switching only the `$Type`: every shape builds the same except an agent microflow with **no parameters**, which fails **CE1590**, so that is the one new check. Needs Mendix 11.9 (`workflows.ai_agent_task`); describe emits it, and a rewrite that restates it proceeds.
+
+  Verified in Studio Pro 11.14 over MCP as well as mxbuild: the shapes are accepted, and Studio Pro reports the same on-created and handler signature errors, flags an agent task without parameter mappings, and refuses an invented event type at create.
+
+### Fixed
+
+- **Workflows written over MCP lost their on-created microflows and event handlers, and could not be created at all on Studio Pro 11.14.** The MCP mapper hard-coded `onCreatedEvent: NoEvent` and sent no `onWorkflowEvent`, so both constructs from the previous release were dropped without a word; it now sends `MicroflowBasedEvent` and the handlers, and replaces stored handlers on a rewrite. Separately, Studio Pro 11.14's workflow constructor takes the context entity as `context` and `workflowName` as a string and rejects the older payload (`"/context":"Expected reference (string), got undefined"`), so every workflow create over MCP failed; the backend now reads the constructor schema and sends whichever shape the server declares. AI agent tasks are sent as `Workflows$AIAgentTaskActivity`.
+- **`describe workflow` turned a call microflow's caption into the microflow's name on re-execute.** The caption was printed only as a trailing `-- caption` comment, which the parser discards, so describe → exec replaced `comment 'Summarise the order'` with `ACT_Summarise`. An authored caption is now described as `comment '…'`; the derived default is not. Found by the AI agent task's end-to-end round trip.
+
 ## [0.22.0] - 2026-09-14
 
 Headline: **The gap between a model that validates and an app that works.** Almost everything fixed here was invisible to `mxcli check`, to `mx check` and to mxbuild — a workflow that loads, validates and then deadlocks at run time; a `describe` round trip that deletes what it just described; a widget spelling that storage drops — because in each case the model Mendix loaded was perfectly valid, just not the one that was written. Alongside that, offline synchronization, SOAP request bodies and a microflow's join points become authorable, closing three of the places where MDL could describe a model it could not write.
diff --git a/cmd/mxcli/syntax/features_workflow.go b/cmd/mxcli/syntax/features_workflow.go
index db7338d396..7ab63cd036 100644
--- a/cmd/mxcli/syntax/features_workflow.go
+++ b/cmd/mxcli/syntax/features_workflow.go
@@ -229,7 +229,34 @@ func init() {
 		// author ends up writing the unquoted form (ako/mxcli#1023).
 		Syntax:  "CALL MICROFLOW Module.MF [AS <name>] [COMMENT '<text>']\n  [WITH (<Param> = '<expression>', ...)]\n  [OUTCOMES '<outcome>' -> { <activities> } ...];",
 		Example: "CALL MICROFLOW HR.SendNotification\n  COMMENT 'Notify manager';\n\n-- Parameter values are quoted, and named by their BARE parameter name:\nCALL MICROFLOW HR.Escalate AS callMicroflow1\n  WITH (Request = '$WorkflowContext');",
-		SeeAlso: []string{"workflow.create", "workflow.call-workflow"},
+		SeeAlso: []string{"workflow.create", "workflow.call-workflow", "workflow.ai-agent-task"},
+	})
+
+	Register(SyntaxFeature{
+		Path:    "workflow.ai-agent-task",
+		Summary: "AI agent task — a workflow step that runs an agent through a microflow (Mendix 11.9+)",
+		Keywords: []string{
+			"ai agent task", "agent task", "call agent", "call agent microflow",
+			"agent", "llm", "genai", "AIAgentTaskActivity",
+		},
+		// Measured on mxbuild 11.13.0 against the same activity written as a call
+		// microflow: the only difference in what builds is CE1590 for a microflow
+		// with no parameters.
+		Syntax: "CALL AGENT MICROFLOW Module.MF [AS <name>] [COMMENT '<text>']\n" +
+			"  [WITH (<Param> = '<expression>', ...)]\n" +
+			"  [OUTCOMES <true|false|'Module.Enum.Value'|''> -> { <activities> } ...]\n" +
+			"  [BOUNDARY EVENT ...];\n\n" +
+			"-- The same statement as CALL MICROFLOW, stored as an AI agent task. The microflow\n" +
+			"-- is where the agent is invoked; it must take at least one parameter (else CE1590),\n" +
+			"-- usually the workflow's context object. Return Boolean or an enumeration to\n" +
+			"-- branch on the agent's answer with OUTCOMES. Needs Mendix 11.9+.",
+		Example: "CREATE MICROFLOW HR.ACT_ClassifyRequest ($Request: HR.LeaveRequest)\n" +
+			"RETURNS Boolean AS $Urgent\nBEGIN\n  -- call the agent here\n  RETURN false;\nEND;\n\n" +
+			"CALL AGENT MICROFLOW HR.ACT_ClassifyRequest AS aiAgentTask1 COMMENT 'Classify the request'\n" +
+			"  WITH (Request = '$WorkflowContext')\n" +
+			"  OUTCOMES true -> { USER TASK Expedite 'Expedite' PAGE HR.TaskPage OUTCOMES 'Done' { }; }\n" +
+			"           false -> { };",
+		SeeAlso: []string{"workflow.call-microflow", "agents"},
 	})
 
 	Register(SyntaxFeature{
diff --git a/docs-site/src/language/workflow-activities.md b/docs-site/src/language/workflow-activities.md
index f05468f3af..d57006dbf1 100644
--- a/docs-site/src/language/workflow-activities.md
+++ b/docs-site/src/language/workflow-activities.md
@@ -53,6 +53,33 @@ Example:
 CALL MICROFLOW HR.ACT_SendNotification COMMENT 'Notify the applicant';
 ```
 
+## AI Agent Task
+
+A step that runs an AI agent (Mendix 11.9 or later). It is written like `CALL
+MICROFLOW` with `AGENT` added, and takes the same name, comment, parameter
+mappings, outcomes and boundary events. The microflow is where the agent is
+invoked — build agents with the Studio Pro Agent Editor, or `CREATE AGENT`.
+
+```sql
+CALL AGENT MICROFLOW <Module>.<Name> [AS <name>] [COMMENT '<text>']
+  [WITH (<Param> = '<expression>', ...)]
+  [OUTCOMES <true|false|'Module.Enum.Value'|''> -> { <activities> } ...];
+```
+
+Example — branch on the agent's answer:
+
+```sql
+CALL AGENT MICROFLOW HR.ACT_ClassifyRequest AS aiAgentTask1 COMMENT 'Classify the request'
+  WITH (Request = '$WorkflowContext')
+  OUTCOMES true -> {
+    USER TASK Expedite 'Expedite the request' PAGE HR.TaskPage OUTCOMES 'Done' { };
+  } false -> { };
+```
+
+The microflow must take at least one parameter — usually the workflow's context
+object — or the build fails with CE1590. Return Boolean or an enumeration to
+branch with `OUTCOMES`; return nothing for a single path.
+
 ## Call Workflow
 
 Start a sub-workflow:
@@ -166,6 +193,7 @@ Typically used inside an outcome block to stop the workflow after a rejection or
 |----------|---------|-----------------|
 | `USER TASK` | Wait for human action | Yes |
 | `CALL MICROFLOW` | Execute server logic | No |
+| `CALL AGENT MICROFLOW` | Run an AI agent step (11.9+) | No |
 | `CALL WORKFLOW` | Start sub-workflow | Depends on sub-workflow |
 | `DECISION` | Branch on condition | No |
 | `PARALLEL SPLIT` | Concurrent execution | Yes (waits for all paths) |
diff --git a/docs/01-project/MDL_QUICK_REFERENCE.md b/docs/01-project/MDL_QUICK_REFERENCE.md
index e35ba60dad..1cd8fc2b2c 100644
--- a/docs/01-project/MDL_QUICK_REFERENCE.md
+++ b/docs/01-project/MDL_QUICK_REFERENCE.md
@@ -669,6 +669,7 @@ Nested folders use `/` separator: `'Parent/Child/Grandchild'`. Missing folders a
   - An **on-created microflow** takes exactly `System.WorkflowUserTask` + the context entity, in either order (CE6683), and returns nothing (CE5012).
   - `check --references` reports these before anything is written; `exec` refuses the workflow statement itself (Mendix 11+).
 - `call microflow Mod.MF [as <name>] [comment '<text>'] [with (<Param> = '<expr>', ...)] [outcomes '<out>' -> { } ...];`
+- `call agent microflow Mod.MF [as <name>] [comment '<text>'] [with (<Param> = '<expr>', ...)] [outcomes … -> { } ...];` — an **AI agent task** (Mendix 11.9+): the call-microflow statement stored as `Workflows$AIAgentTaskActivity`. Its microflow must take at least one parameter (CE1590).
 - `call workflow Mod.WF [as <name>] [comment '<text>'] [with (<Param> = '<expr>', ...)];`
 - `decision [<name>] ['<expression>'] outcomes <true|false|'Module.Enum.Value'> -> { } ...;`
 - `parallel split [<name>] path 1 { } path 2 { };`
diff --git a/docs/03-development/PED_MCP_CAPABILITIES.md b/docs/03-development/PED_MCP_CAPABILITIES.md
index 3168ea9cdc..7a7a5530ad 100644
--- a/docs/03-development/PED_MCP_CAPABILITIES.md
+++ b/docs/03-development/PED_MCP_CAPABILITIES.md
@@ -468,6 +468,40 @@ rejects `Microflows$Nanoflow` (*"Did you mean: Microflows$Microflow?"*),
 `Projects$Folder` and `JavaActions$JavaAction`. Two gaps moved — see the gaps table
 for both.
 
+### Workflows: constructor shape, AI agent tasks, handlers (measured live 2026-09-15)
+
+Captured against Studio Pro 11.14 with ako/TestApp open, via `cmd/mcpprobe`
+(`ped_get_schema`, `ped_create_document`, `ped_check_errors`, `ped_read_document`).
+
+- **The `Workflows$Workflow` constructor changed shape.** It takes the context
+  entity as `context: Reference<'DomainModels$Entity'>` and `workflowName` /
+  `caption` as plain strings, and rejects the older payload outright:
+  `{"/context":"Expected reference (string), got undefined","/workflowName":"Expected
+  string, got object"}` — so **every workflow create over MCP failed** on 11.14.
+  The *element* shape used by updates (`/parameter/entity`, `/workflowName/text`) is
+  unchanged. Which release made the change is not established (11.13 was not
+  re-probed), so the backend reads the constructor schema instead of gating on a
+  version (`workflowConstructorTakesContext`).
+- **`Workflows$AIAgentTaskActivity`** has the call-microflow fields — `name`,
+  `caption`, `microflow`, `outcomes`, `parameterMappings`, `boundaryEvents` (timer
+  events, `MaxLength<5, 'CE6696'>`). Created and read back clean.
+- **`onWorkflowEvent`** takes `Workflows$WorkflowEventHandler` (`description`,
+  `documentation`, `eventTypes`, `microflowEventHandler{microflow}`); a user task's
+  `onCreatedEvent` takes `Workflows$MicroflowBasedEvent{microflow}`. The MCP mapper
+  used to send `NoEvent` and no handlers, silently dropping both.
+- **`eventTypes` is a schema enum of the same 42 names** mxcli validates, and PED
+  refuses an invented one at create (`Expected one of [WorkflowCompleted, …]`) —
+  where mxbuild accepts it at 0 errors.
+- **Signature rules match mxbuild, message for message:** an on-created microflow
+  with the handler signature and a handler with the on-created signature each
+  report the CE6683 / CE6691 text; an agent task without parameter mappings reports
+  "The parameters of the selected microflow have changed".
+- **`description` is typed `MinLength<1, 'MW0006'>`**, but a handler with an empty
+  one produced no MW0006 in `ped_check_errors` output — inconclusive whether the tool
+  omits warnings.
+- **The error-list lag bites here too:** both probe documents first checked "No
+  errors found." and reported their errors only on a later call.
+
 ## Capability gaps (established 11.11, status re-checked each release)
 
 These are the *absences* that bound what the backend can do. They are as
diff --git a/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md b/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
index b6b07e166c..f1811189d6 100644
--- a/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
+++ b/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
@@ -1,6 +1,6 @@
 # Proposal: Workflow constructs only Studio Pro could author
 
-**Status:** Phase 1 implemented; phases 2–4 designed, awaiting reference documents
+**Status:** Phases 1 and 2 implemented; phases 3–4 designed, awaiting reference documents
 **Date:** 2026-09-14
 
 ## Problem Statement
@@ -114,9 +114,10 @@ A rewrite now writes handlers and on-created microflows, so they move from
 "cannot express" to "restated?" — the boundary-event rule: refused when the
 statement declares fewer handlers, or fewer on-created microflows, than are
 stored. `replace activity` is refused only when the replacement does not restate
-the stored on-created microflow. Still refused outright: an event sub-process, an
-AI agent task, a non-default completion rule, and a handler with an empty type
-list (no MDL spelling).
+the stored on-created microflow. Still refused outright: an event sub-process, a
+non-default completion rule, and a handler with an empty type list (no MDL
+spelling). (AI agent tasks were refused outright too until phase 2 made them
+restatable.)
 
 Running the end-to-end rewrite on both engines found that **none of the workflow
 rewrite guards worked on the legacy engine**: its `GetRawUnit` returns arrays as
@@ -151,7 +152,7 @@ workflow version. The signature checks run on Mendix 11+, where they are measure
   (`set activity … on created microflow …` and header handler operations). A
   rewrite restating them is the path today.
 
-## Phase 2 — AI agent task
+## Phase 2 — AI agent task (implemented)
 
 ```sql
 call agent microflow HR.InvokeAgent as aiAgentTask1 comment 'Classify the request'
@@ -161,9 +162,50 @@ call agent microflow HR.InvokeAgent as aiAgentTask1 comment 'Classify the reques
 Stored as `Workflows$AIAgentTaskActivity` with `Caption`, `Name`, `Microflow`,
 `BoundaryEvents` (marker 2), `Outcomes` (marker 3, a `VoidConditionOutcome` with its
 `Flow`) and `ParameterMappings` (marker 2, `MicroflowCallParameterMapping`) — the
-call-microflow shape under a different `$Type`. The TestApp agent microflow takes
-the context entity. Open: the minimum version (agents are 11.9+; the event types
-appear by 11.10), and which signature errors the build reports.
+call-microflow shape under a different `$Type` (ako/TestApp, 11.14.0).
+
+Because the shape is identical, the semantic model is `CallMicroflowTask` with an
+`IsAgent` flag rather than a new type: every walker, validator, catalog edge,
+activity-name rule and ALTER path that handles a call microflow handles an agent
+task unchanged, and only the `$Type`, describe and the rewrite guard branch on it.
+
+**Measured** (mxbuild 11.13.0) by writing each shape as a call-microflow activity
+and switching only the `$Type`, so the two columns differ in nothing else:
+
+| Agent microflow | call microflow | AI agent task |
+|---|---|---|
+| `(Ctx)`, mapped | 0 errors | 0 errors |
+| `()` — no parameters | 0 errors | **CE1590** "Missing parameter" |
+| `(Ctx, String)`, both mapped | 0 errors | 0 errors |
+| `(System.Workflow)` | 0 errors | 0 errors |
+| returns Boolean, true/false outcomes | 0 errors | 0 errors |
+| returns an enumeration, value outcomes | 0 errors | 0 errors |
+| interrupting timer boundary event | 0 errors | 0 errors |
+
+So `check` refuses an agent microflow with no parameters, and nothing else new.
+
+**Confirmed in Studio Pro 11.14 over MCP** (ped_get_schema, then a created
+document checked with `ped_check_errors` once its error list settled): the agent
+task, event handler and on-created shapes mxcli writes are accepted; an on-created
+microflow with the handler signature and a handler with the on-created signature
+report the CE6683 / CE6691 messages mxbuild reports; an agent task without
+parameter mappings is flagged; and an invented event type is refused at create by
+the schema's enum of the same 42 names. Details in
+`docs/03-development/PED_MCP_CAPABILITIES.md`.
+
+**Version.** `AIAgentTaskActivity` is absent from the 11.6 mxbuild and present
+from 11.10; the writer already records that Mendix 11.9 split
+`MicroflowBasedActivity` into `CallMicroflowActivity` + `AIAgentTaskActivity`.
+`workflows.ai_agent_task` min 11.9.0 gates CREATE and the activities ALTER adds.
+
+**Guard.** A rewrite declaring fewer agent tasks than are stored is refused
+(restate with `call agent microflow`, which describe emits); it was refused
+outright before, since describe printed an agent task only as a comment.
+
+**Engines.** Written and read by the modelsdk engine. The retiring legacy engine
+carries the flag through (same shape, agent `$Type`) rather than silently turning
+an agent task into a call microflow; the MCP backend refuses one, since PED's
+agent element has not been measured.
 
 ## Phase 3 — completion rules
 
diff --git a/mdl-examples/doctype-tests/24-workflow-examples.mdl b/mdl-examples/doctype-tests/24-workflow-examples.mdl
index 4b52f6058e..00ce6ab1b3 100644
--- a/mdl-examples/doctype-tests/24-workflow-examples.mdl
+++ b/mdl-examples/doctype-tests/24-workflow-examples.mdl
@@ -619,3 +619,46 @@ begin
     outcomes 'Yes' { } 'No' { };
 end workflow;
 /
+
+-- @version: 11.9+
+-- ############################################################################
+-- PART G: AI AGENT TASK — call agent microflow (Mendix 11.9+)
+-- ############################################################################
+--
+-- `call agent microflow` is the call-microflow statement stored as an AI agent
+-- task. Its microflow must take at least one parameter (CE1590); return Boolean
+-- or an enumeration to branch on the agent's answer.
+
+create microflow WFTest.ACT_SummariseOrder (
+  $OrderContext: WFTest.OrderContext
+)
+begin
+end;
+/
+
+create microflow WFTest.ACT_ClassifyOrder (
+  $OrderContext: WFTest.OrderContext
+)
+returns boolean as $Urgent
+begin
+  return false;
+end;
+/
+
+create workflow WFTest.WithAgentTasks
+  parameter $OrderContext: WFTest.OrderContext
+begin
+  call agent microflow WFTest.ACT_SummariseOrder as aiAgentTask1 comment 'Summarise the order'
+    with (OrderContext = '$WorkflowContext');
+
+  call agent microflow WFTest.ACT_ClassifyOrder as aiAgentTask2 comment 'Classify the order'
+    with (OrderContext = '$WorkflowContext')
+    outcomes
+      true -> {
+        user task Expedite 'Expedite the order'
+          page WFTest.TaskPage
+          outcomes 'Done' { };
+      }
+      false -> { };
+end workflow;
+/
diff --git a/mdl/ast/ast_workflow.go b/mdl/ast/ast_workflow.go
index 44f3dd6a4b..320d8bfed7 100644
--- a/mdl/ast/ast_workflow.go
+++ b/mdl/ast/ast_workflow.go
@@ -87,6 +87,7 @@ type WorkflowUserTaskOutcomeNode struct {
 // WorkflowCallMicroflowNode represents a CALL MICROFLOW activity.
 type WorkflowCallMicroflowNode struct {
 	Name              string // explicit activity name (`as <name>`); see ako/mxcli#408
+	Agent             bool   // `call agent microflow`: an AI agent task (Workflows$AIAgentTaskActivity)
 	Microflow         QualifiedName
 	Caption           string
 	Outcomes          []WorkflowConditionOutcomeNode
diff --git a/mdl/backend/mcp/backend.go b/mdl/backend/mcp/backend.go
index a7046bd9fb..15c3e86cf6 100644
--- a/mdl/backend/mcp/backend.go
+++ b/mdl/backend/mcp/backend.go
@@ -64,6 +64,12 @@ type Backend struct {
 	// this session (the contract asks for a schema fetch before create/add).
 	schemaFetched map[string]bool
 
+	// workflowCtorContext caches whether the server's Workflows$Workflow
+	// constructor takes the context entity as `context` (Studio Pro 11.14) rather
+	// than a `parameter` element; nil until probed. See
+	// workflowConstructorTakesContext.
+	workflowCtorContext *bool
+
 	// capsCache memoizes the session's resolved capability set. Every authoring
 	// gate consults it and resolution costs a tools/list round-trip, so it is
 	// computed once per connection.
diff --git a/mdl/backend/mcp/workflow.go b/mdl/backend/mcp/workflow.go
index ae48bac650..fdeb2c623c 100644
--- a/mdl/backend/mcp/workflow.go
+++ b/mdl/backend/mcp/workflow.go
@@ -24,7 +24,8 @@ func (b *Backend) CreateWorkflow(wf *workflows.Workflow) error {
 	if err != nil {
 		return fmt.Errorf("resolve container for workflow %q: %w", wf.Name, err)
 	}
-	content, err := b.mapWorkflow(wf)
+	contextShape := b.workflowConstructorTakesContext()
+	content, err := b.mapWorkflowContent(wf, contextShape)
 	if err != nil {
 		return err
 	}
@@ -34,6 +35,22 @@ func (b *Backend) CreateWorkflow(wf *workflows.Workflow) error {
 	if err := b.pedCreateDocument(moduleName, workflowDocType, wf.Name, content, folderPath); err != nil {
 		return err
 	}
+	if contextShape {
+		// The context-shaped constructor has no documentation or description;
+		// both are leaves of the created element.
+		var ops []pedOpEntry
+		if wf.Documentation != "" {
+			ops = append(ops, pedOpEntry{Path: "/documentation", Operation: pedOperation{Type: "set", Value: wf.Documentation}})
+		}
+		if wf.WorkflowDescription != "" {
+			ops = append(ops, pedOpEntry{Path: "/workflowDescription/text", Operation: pedOperation{Type: "set", Value: wf.WorkflowDescription}})
+		}
+		if len(ops) > 0 {
+			if err := b.pedUpdateDoc(workflowDocType, moduleName+"."+wf.Name, ops...); err != nil {
+				return err
+			}
+		}
+	}
 	if wf.ID == "" {
 		wf.ID = model.ID("mcp~workflow~" + moduleName + "~" + wf.Name)
 	}
@@ -70,6 +87,10 @@ func (b *Backend) UpdateWorkflow(wf *workflows.Workflow) error {
 	if err != nil {
 		return err
 	}
+	storedHandlers, err := b.workflowListCount(qn, "/onWorkflowEvent")
+	if err != nil {
+		return err
+	}
 
 	var ops []pedOpEntry
 	// Drop the original middle activities (indices 1..n-2, high→low; index 0 is
@@ -87,6 +108,15 @@ func (b *Backend) UpdateWorkflow(wf *workflows.Workflow) error {
 		ops = append(ops, pedOpEntry{Path: "/flow/activities", Operation: pedOperation{Type: "add", Value: middles[i], Index: &afterStart}})
 	}
 
+	// Event handlers: replace the stored list with the statement's. The executor's
+	// rewrite guard has already refused a statement declaring fewer than are stored.
+	for i := storedHandlers - 1; i >= 0; i-- {
+		ops = append(ops, removeAtOp("/onWorkflowEvent", i))
+	}
+	for _, h := range mapWorkflowEventHandlers(wf.EventHandlers) {
+		ops = append(ops, pedOpEntry{Path: "/onWorkflowEvent", Operation: pedOperation{Type: "add", Value: h}})
+	}
+
 	title := wf.WorkflowName
 	if title == "" {
 		title = wf.Name
@@ -130,10 +160,16 @@ func stripStartEnd(acts []any) []any {
 
 // workflowActivityCount returns the number of top-level activities in a workflow's flow.
 func (b *Backend) workflowActivityCount(qn string) (int, error) {
+	return b.workflowListCount(qn, "/flow/activities")
+}
+
+// workflowListCount returns the number of elements in a list property of a
+// stored workflow, addressed by JSON pointer.
+func (b *Backend) workflowListCount(qn, path string) (int, error) {
 	res, err := b.client.CallTool("ped_read_document", map[string]any{
 		"documentType": workflowDocType,
 		"documentName": qn,
-		"paths":        []string{"/flow/activities"},
+		"paths":        []string{path},
 	})
 	if err != nil {
 		return 0, err
@@ -212,12 +248,66 @@ func (b *Backend) GetWorkflow(id model.ID) (*workflows.Workflow, error) {
 	return b.reader.GetWorkflow(id)
 }
 
-// mapWorkflow maps the executor's Workflow onto the PED Workflows$Workflow content.
+// workflowConstructorTakesContext reports whether the connected server's
+// Workflows$Workflow constructor takes the context entity as `context` with a
+// plain-string workflowName and caption. Studio Pro 11.14 does, and rejects the
+// older shape outright — measured live: `"/context":"Expected reference (string),
+// got undefined","/workflowName":"Expected string, got object"`, so every workflow
+// create over MCP failed. Which release changed it is not established, so the
+// shape is read off the live constructor schema rather than a version number.
+// The probe doubles as the schema fetch PED asks for before a create.
+func (b *Backend) workflowConstructorTakesContext() bool {
+	if b.workflowCtorContext != nil {
+		return *b.workflowCtorContext
+	}
+	takes := false
+	if b.client != nil {
+		res, err := b.client.CallTool("ped_get_schema", map[string]any{"elementTypes": []string{workflowDocType}})
+		if err == nil && res != nil && !res.IsError {
+			takes = strings.Contains(res.Text, "context: Reference<'DomainModels$Entity'")
+			if b.schemaFetched == nil {
+				b.schemaFetched = map[string]bool{}
+			}
+			b.schemaFetched[workflowDocType] = true
+		}
+	}
+	b.workflowCtorContext = &takes
+	return takes
+}
+
+// mapWorkflow maps the executor's Workflow onto the PED Workflows$Workflow content
+// in the parameter-element shape.
 func (b *Backend) mapWorkflow(wf *workflows.Workflow) (map[string]any, error) {
+	return b.mapWorkflowContent(wf, false)
+}
+
+// mapWorkflowContent maps the executor's Workflow onto PED constructor content,
+// in the context shape (Studio Pro 11.14: `context`, `caption`, string
+// `workflowName`) or the parameter-element shape older servers take.
+func (b *Backend) mapWorkflowContent(wf *workflows.Workflow, contextShape bool) (map[string]any, error) {
 	flow, err := b.mapWorkflowFlow(wf.Flow)
 	if err != nil {
 		return nil, err
 	}
+	if contextShape {
+		title := wf.WorkflowName
+		if title == "" {
+			title = wf.Name
+		}
+		content := map[string]any{
+			"name":         wf.Name,
+			"caption":      title,
+			"workflowName": wf.WorkflowName,
+			"flow":         flow,
+		}
+		if wf.Parameter != nil {
+			content["context"] = wf.Parameter.EntityRef
+		}
+		if len(wf.EventHandlers) > 0 {
+			content["onWorkflowEvent"] = mapWorkflowEventHandlers(wf.EventHandlers)
+		}
+		return content, nil
+	}
 	title := wf.WorkflowName
 	if title == "" {
 		title = wf.Name
@@ -232,6 +322,9 @@ func (b *Backend) mapWorkflow(wf *workflows.Workflow) (map[string]any, error) {
 		"workflowDescription": mapWorkflowStringTemplate(wf.WorkflowDescription),
 		"workflowV2":          false,
 	}
+	if len(wf.EventHandlers) > 0 {
+		content["onWorkflowEvent"] = mapWorkflowEventHandlers(wf.EventHandlers)
+	}
 	if wf.Parameter != nil {
 		content["parameter"] = map[string]any{
 			"$Type":  "Workflows$Parameter",
@@ -296,8 +389,15 @@ func mapWorkflowActivity(a workflows.WorkflowActivity) (map[string]any, error) {
 		}
 		// PED's element type is CallMicroflowActivity (the on-disk BSON $Type is
 		// the older CallMicroflowTask — they differ).
+		// An AI agent task has the same PED shape under its own element type
+		// (ped_get_schema, Studio Pro 11.14: name, caption, microflow, outcomes,
+		// parameterMappings, boundaryEvents).
+		elementType := "Workflows$CallMicroflowActivity"
+		if act.IsAgent {
+			elementType = "Workflows$AIAgentTaskActivity"
+		}
 		m := map[string]any{
-			"$Type":             "Workflows$CallMicroflowActivity",
+			"$Type":             elementType,
 			"name":              act.Name,
 			"caption":           act.Caption,
 			"microflow":         act.Microflow,
@@ -414,7 +514,7 @@ func mapWorkflowActivity(a workflows.WorkflowActivity) (map[string]any, error) {
 				"pageReference":     act.Page,
 				"participiantInput": "AllTargetUsers",
 				"userTargeting":     mapUserTargeting(act.UserSource),
-				"onCreatedEvent":    map[string]any{"$Type": "Workflows$NoEvent"},
+				"onCreatedEvent":    mapOnCreatedEvent(act.OnCreated),
 				"outcomes":          vals,
 			}
 		} else {
@@ -431,7 +531,7 @@ func mapWorkflowActivity(a workflows.WorkflowActivity) (map[string]any, error) {
 				"taskDescription":            mapWorkflowStringTemplate(act.TaskDescription),
 				"dueDate":                    act.DueDate,
 				"userTargeting":              mapUserTargeting(act.UserSource),
-				"onCreatedEvent":             map[string]any{"$Type": "Workflows$NoEvent"},
+				"onCreatedEvent":             mapOnCreatedEvent(act.OnCreated),
 				"outcomes":                   outcomes,
 				"autoAssignSingleTargetUser": false,
 			}
@@ -445,6 +545,44 @@ func mapWorkflowActivity(a workflows.WorkflowActivity) (map[string]any, error) {
 	}
 }
 
+// mapOnCreatedEvent maps a user task's on-created microflow onto its PED element:
+// Workflows$MicroflowBasedEvent when one is set, Workflows$NoEvent otherwise. This
+// was hard-coded to NoEvent, so an on-created microflow written over MCP was
+// silently dropped.
+func mapOnCreatedEvent(microflow string) map[string]any {
+	if microflow == "" {
+		return map[string]any{"$Type": "Workflows$NoEvent"}
+	}
+	return map[string]any{"$Type": "Workflows$MicroflowBasedEvent", "microflow": microflow}
+}
+
+// mapWorkflowEventHandlers maps a workflow's event handlers onto PED
+// Workflows$WorkflowEventHandler elements. PED types description as
+// MinLength<1, 'MW0006'>: Studio Pro warns on a handler without one.
+func mapWorkflowEventHandlers(handlers []*workflows.WorkflowEventHandler) []any {
+	out := make([]any, 0, len(handlers))
+	for _, h := range handlers {
+		if h == nil {
+			continue
+		}
+		types := make([]any, 0, len(h.EventTypes))
+		for _, t := range h.EventTypes {
+			types = append(types, t)
+		}
+		out = append(out, map[string]any{
+			"$Type":         "Workflows$WorkflowEventHandler",
+			"description":   h.Description,
+			"documentation": h.Documentation,
+			"eventTypes":    types,
+			"microflowEventHandler": map[string]any{
+				"$Type":     "Workflows$MicroflowEventHandler",
+				"microflow": h.Microflow,
+			},
+		})
+	}
+	return out
+}
+
 // mapUserTargeting maps a user task's user source onto its pg targeting element.
 func mapUserTargeting(source workflows.UserSource) map[string]any {
 	switch s := source.(type) {
diff --git a/mdl/backend/mcp/workflow_constructor_test.go b/mdl/backend/mcp/workflow_constructor_test.go
new file mode 100644
index 0000000000..b08767c177
--- /dev/null
+++ b/mdl/backend/mcp/workflow_constructor_test.go
@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package mcp
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// Studio Pro 11.14's constructor, as ped_get_schema returned it live (trimmed to
+// the lines the probe reads).
+const workflowCtorSchema1114 = `{"kind":"constructor","schema":"constructor type 'Workflows$Workflow' = {\n $Type: 'Workflows$Workflow',\n name: string;\n flow?: Element<'Workflows$Flow'>;\n context: Reference<'DomainModels$Entity', 'qualified-name'>;\n onWorkflowEvent?: Element<'Workflows$WorkflowEventHandler'>[];\n caption?: string;\n workflowName?: string;\n}"}`
+
+// The shape is chosen from the live constructor schema, once per session: 11.14
+// takes `context` and rejects a `parameter` element, and the release that changed
+// it is not known, so a version gate would be a guess.
+func TestWorkflowConstructorShapeProbe(t *testing.T) {
+	schemaCalls := 0
+	f := newFakePED(t, func(name string, _ map[string]any) (string, bool) {
+		if name == "ped_get_schema" {
+			schemaCalls++
+			return workflowCtorSchema1114, false
+		}
+		return "SUCCESS", false
+	})
+	b := &Backend{client: f.connectClient(t)}
+	if !b.workflowConstructorTakesContext() || !b.workflowConstructorTakesContext() {
+		t.Fatal("an 11.14 constructor schema must select the context shape")
+	}
+	if schemaCalls != 1 {
+		t.Errorf("ped_get_schema called %d times, want 1 (cached)", schemaCalls)
+	}
+	if !b.schemaFetched[workflowDocType] {
+		t.Error("the probe must count as the schema fetch PED requires before a create")
+	}
+
+	old := newFakePED(t, func(name string, _ map[string]any) (string, bool) {
+		return `{"schemas":[{"elementType":"Workflows$Workflow","schema":{"properties":{"parameter":{}}}}]}`, false
+	})
+	if (&Backend{client: old.connectClient(t)}).workflowConstructorTakesContext() {
+		t.Error("a constructor without `context` must keep the parameter shape")
+	}
+}
+
+func TestMapWorkflowContent_ContextShape(t *testing.T) {
+	b := &Backend{}
+	wf := &workflows.Workflow{
+		Name:         "Approve",
+		WorkflowName: "Approve Order",
+		Parameter:    &workflows.WorkflowParameter{EntityRef: "M.OrderCtx"},
+		EventHandlers: []*workflows.WorkflowEventHandler{{
+			Description: "Audit", EventTypes: []string{"WorkflowCompleted"}, Microflow: "M.ACT_Audit",
+		}},
+	}
+	content, err := b.mapWorkflowContent(wf, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if content["context"] != "M.OrderCtx" || content["workflowName"] != "Approve Order" || content["caption"] != "Approve Order" {
+		t.Errorf("context shape = %+v", content)
+	}
+	for _, key := range []string{"parameter", "title", "workflowDescription", "documentation", "excluded", "workflowV2"} {
+		if _, ok := content[key]; ok {
+			t.Errorf("the 11.14 constructor does not take %q, but it was sent", key)
+		}
+	}
+	if hs, _ := content["onWorkflowEvent"].([]any); len(hs) != 1 {
+		t.Errorf("onWorkflowEvent = %v", content["onWorkflowEvent"])
+	}
+
+	legacy, err := b.mapWorkflowContent(wf, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, ok := legacy["parameter"]; !ok {
+		t.Error("the parameter shape must still send `parameter`")
+	}
+}
diff --git a/mdl/backend/mcp/workflow_handlers_test.go b/mdl/backend/mcp/workflow_handlers_test.go
new file mode 100644
index 0000000000..23b3c6f015
--- /dev/null
+++ b/mdl/backend/mcp/workflow_handlers_test.go
@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package mcp
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// The element types and field names below are Studio Pro 11.14's own
+// (ped_get_schema): an AI agent task is Workflows$AIAgentTaskActivity with the
+// call-microflow fields, a user task's onCreatedEvent is a MicroflowBasedEvent,
+// and a workflow carries onWorkflowEvent handlers. The mapper used to refuse the
+// first and hard-code NoEvent and no handlers for the other two, so a workflow
+// written over MCP silently lost its on-created microflows and handlers.
+func TestMapAIAgentTask(t *testing.T) {
+	agent := &workflows.CallMicroflowTask{IsAgent: true, Microflow: "M.InvokeAgent"}
+	agent.Name = "aiAgentTask1"
+	agent.Caption = "Classify"
+	agent.Outcomes = []workflows.ConditionOutcome{&workflows.VoidConditionOutcome{}}
+	m, err := mapWorkflowActivity(agent)
+	if err != nil {
+		t.Fatalf("mapWorkflowActivity(agent): %v", err)
+	}
+	if m["$Type"] != "Workflows$AIAgentTaskActivity" || m["microflow"] != "M.InvokeAgent" || m["name"] != "aiAgentTask1" {
+		t.Errorf("agent task = %+v", m)
+	}
+
+	plain := &workflows.CallMicroflowTask{Microflow: "M.Do"}
+	plain.Name = "callDo"
+	pm, err := mapWorkflowActivity(plain)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if pm["$Type"] != "Workflows$CallMicroflowActivity" {
+		t.Errorf("plain call microflow $Type = %v", pm["$Type"])
+	}
+}
+
+func TestMapUserTaskOnCreatedEvent(t *testing.T) {
+	for _, multi := range []bool{false, true} {
+		ut := &workflows.UserTask{IsMulti: multi, Page: "M.TaskPage", OnCreated: "M.ACT_Assign"}
+		ut.Name = "review"
+		ut.Outcomes = []*workflows.UserTaskOutcome{{Value: "Done"}}
+		m, err := mapWorkflowActivity(ut)
+		if err != nil {
+			t.Fatalf("multi=%v: %v", multi, err)
+		}
+		want := map[string]any{"$Type": "Workflows$MicroflowBasedEvent", "microflow": "M.ACT_Assign"}
+		if !reflect.DeepEqual(m["onCreatedEvent"], want) {
+			t.Errorf("multi=%v onCreatedEvent = %v, want %v", multi, m["onCreatedEvent"], want)
+		}
+
+		ut.OnCreated = ""
+		m, _ = mapWorkflowActivity(ut)
+		if !reflect.DeepEqual(m["onCreatedEvent"], map[string]any{"$Type": "Workflows$NoEvent"}) {
+			t.Errorf("multi=%v without on-created = %v, want NoEvent", multi, m["onCreatedEvent"])
+		}
+	}
+}
+
+func TestMapWorkflowEventHandlers(t *testing.T) {
+	b := &Backend{}
+	wf := &workflows.Workflow{
+		Name:      "W",
+		Parameter: &workflows.WorkflowParameter{EntityRef: "M.Ctx"},
+		EventHandlers: []*workflows.WorkflowEventHandler{{
+			Description: "Task audit",
+			EventTypes:  []string{"UserTaskStarted", "UserTaskEnded"},
+			Microflow:   "M.ACT_Audit",
+		}},
+	}
+	content, err := b.mapWorkflow(wf)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got, _ := content["onWorkflowEvent"].([]any)
+	if len(got) != 1 {
+		t.Fatalf("onWorkflowEvent = %v, want one handler", content["onWorkflowEvent"])
+	}
+	want := map[string]any{
+		"$Type":         "Workflows$WorkflowEventHandler",
+		"description":   "Task audit",
+		"documentation": "",
+		"eventTypes":    []any{"UserTaskStarted", "UserTaskEnded"},
+		"microflowEventHandler": map[string]any{
+			"$Type":     "Workflows$MicroflowEventHandler",
+			"microflow": "M.ACT_Audit",
+		},
+	}
+	if !reflect.DeepEqual(got[0], want) {
+		t.Errorf("handler = %v\nwant      %v", got[0], want)
+	}
+
+	none, _ := b.mapWorkflow(&workflows.Workflow{Name: "W"})
+	if _, ok := none["onWorkflowEvent"]; ok {
+		t.Error("a workflow without handlers must not send onWorkflowEvent")
+	}
+}
diff --git a/mdl/backend/mcp/workflow_test.go b/mdl/backend/mcp/workflow_test.go
index b41c887c86..d7287cdaf7 100644
--- a/mdl/backend/mcp/workflow_test.go
+++ b/mdl/backend/mcp/workflow_test.go
@@ -504,11 +504,15 @@ func TestWFSetActivityProperty(t *testing.T) {
 }
 
 func TestUpdateWorkflow_ReplacesFlowAndProperties(t *testing.T) {
-	f := newFakePED(t, func(name string, _ map[string]any) (string, bool) {
+	f := newFakePED(t, func(name string, args map[string]any) (string, bool) {
 		switch name {
 		case "ped_check_errors":
 			return "No errors found.", false
 		case "ped_read_document":
+			// The stored workflow has no event handlers.
+			if paths, _ := args["paths"].([]any); len(paths) == 1 && paths[0] == "/onWorkflowEvent" {
+				return `{"results":[{"path":"/onWorkflowEvent","result":[]}]}`, false
+			}
 			// The existing flow has 3 activities (Start, X, End).
 			return `{"results":[{"path":"/flow/activities","result":[
 				{"$Type":"Workflows$StartWorkflowActivity"},
diff --git a/mdl/backend/modelsdk/workflow_agent_test.go b/mdl/backend/modelsdk/workflow_agent_test.go
new file mode 100644
index 0000000000..b8e66fa0a7
--- /dev/null
+++ b/mdl/backend/modelsdk/workflow_agent_test.go
@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// An AI agent task is written as Workflows$AIAgentTaskActivity in the shape
+// ako/TestApp (Studio Pro 11.14.0) stores — Outcomes marker 3, ParameterMappings
+// and BoundaryEvents marker 2 — and reads back as an agent task, not as the
+// call-microflow activity it resembles.
+func TestCreateWorkflow_AIAgentTaskRoundTrip(t *testing.T) {
+	proj := copyFixture(t)
+	b := New()
+	if err := b.Connect(proj); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+	mod, err := b.GetModuleByName("MyFirstModule")
+	if err != nil || mod == nil {
+		t.Fatalf("GetModuleByName: %v", err)
+	}
+
+	agent := &workflows.CallMicroflowTask{
+		BaseWorkflowActivity: workflows.BaseWorkflowActivity{Name: "aiAgentTask1", Caption: "AI Agent Task"},
+		IsAgent:              true,
+		Microflow:            "MyFirstModule.InvokeAgent",
+		Outcomes:             []workflows.ConditionOutcome{&workflows.VoidConditionOutcome{Flow: &workflows.Flow{}}},
+		ParameterMappings:    []*workflows.ParameterMapping{{Parameter: "MyFirstModule.InvokeAgent.Ctx", Expression: "$WorkflowContext"}},
+	}
+	plain := &workflows.CallMicroflowTask{
+		BaseWorkflowActivity: workflows.BaseWorkflowActivity{Name: "plain", Caption: "Plain"},
+		Microflow:            "MyFirstModule.ACT_Plain",
+	}
+	wf := &workflows.Workflow{
+		ContainerID: mod.ID,
+		Name:        "ZzAgent",
+		Parameter:   &workflows.WorkflowParameter{EntityRef: "MyFirstModule.Ctx"},
+		Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+			&workflows.StartWorkflowActivity{BaseWorkflowActivity: workflows.BaseWorkflowActivity{Name: "Start"}},
+			agent,
+			plain,
+			&workflows.EndWorkflowActivity{BaseWorkflowActivity: workflows.BaseWorkflowActivity{Name: "End"}},
+		}},
+	}
+	if err := b.CreateWorkflow(wf); err != nil {
+		t.Fatalf("CreateWorkflow: %v", err)
+	}
+
+	b2 := New()
+	if err := b2.Connect(proj); err != nil {
+		t.Fatalf("reconnect: %v", err)
+	}
+	t.Cleanup(func() { _ = b2.Disconnect() })
+	all, err := b2.ListWorkflows()
+	if err != nil {
+		t.Fatalf("ListWorkflows: %v", err)
+	}
+	var got *workflows.Workflow
+	for _, w := range all {
+		if w.Name == "ZzAgent" {
+			got = w
+		}
+	}
+	if got == nil {
+		t.Fatal("workflow not found after reconnect")
+	}
+	kinds := map[string]bool{}
+	for _, a := range got.Flow.Activities {
+		if cm, ok := a.(*workflows.CallMicroflowTask); ok {
+			kinds[cm.Name] = cm.IsAgent
+			if cm.Name == "aiAgentTask1" && (cm.Microflow != "MyFirstModule.InvokeAgent" || len(cm.ParameterMappings) != 1 || len(cm.Outcomes) != 1) {
+				t.Errorf("agent task read back as %+v", cm)
+			}
+		}
+	}
+	if !kinds["aiAgentTask1"] || kinds["plain"] {
+		t.Errorf("IsAgent after read = %v, want aiAgentTask1 true and plain false", kinds)
+	}
+
+	raw, err := b2.GetRawUnit(got.ID)
+	if err != nil {
+		t.Fatalf("GetRawUnit: %v", err)
+	}
+	flow, _ := raw["Flow"].(map[string]any)
+	acts, _ := flow["Activities"].([]any)
+	var stored map[string]any
+	for _, a := range acts {
+		if m, ok := a.(map[string]any); ok && m["Name"] == "aiAgentTask1" {
+			stored = m
+		}
+	}
+	if stored == nil {
+		t.Fatal("agent task not in the stored flow")
+	}
+	if stored["$Type"] != "Workflows$AIAgentTaskActivity" {
+		t.Errorf("$Type = %v, want Workflows$AIAgentTaskActivity", stored["$Type"])
+	}
+	for key, want := range map[string]string{"Outcomes": "3", "ParameterMappings": "2", "BoundaryEvents": "2"} {
+		l, _ := stored[key].([]any)
+		if len(l) == 0 || fmt.Sprint(l[0]) != want {
+			t.Errorf("%s = %v, want marker %s", key, stored[key], want)
+		}
+	}
+}
diff --git a/mdl/backend/modelsdk/workflow_read.go b/mdl/backend/modelsdk/workflow_read.go
index b5dd4fb289..335fb394b9 100644
--- a/mdl/backend/modelsdk/workflow_read.go
+++ b/mdl/backend/modelsdk/workflow_read.go
@@ -147,6 +147,13 @@ func workflowActivityFromGen(el element.Element) workflows.WorkflowActivity {
 		t.Outcomes = conditionOutcomesFromGen(a.OutcomesItems())
 		t.ParameterMappings = microflowParamMappingsFromGen(a.ParameterMappingsItems())
 		return t
+	case *genWf.AIAgentTaskActivity:
+		t := &workflows.CallMicroflowTask{IsAgent: true, Microflow: a.MicroflowQualifiedName()}
+		setWfBase(&t.BaseWorkflowActivity, a.ID(), a.Name(), a.Caption(), a.Annotation(), "Workflows$AIAgentTaskActivity")
+		t.BoundaryEvents = boundaryEventsFromGen(a.BoundaryEventsItems())
+		t.Outcomes = conditionOutcomesFromGen(a.OutcomesItems())
+		t.ParameterMappings = microflowParamMappingsFromGen(a.ParameterMappingsItems())
+		return t
 	case *genWf.CallMicroflowActivity:
 		t := &workflows.CallMicroflowTask{Microflow: a.MicroflowQualifiedName()}
 		setWfBase(&t.BaseWorkflowActivity, a.ID(), a.Name(), a.Caption(), a.Annotation(), "Workflows$CallMicroflowActivity")
diff --git a/mdl/backend/modelsdk/workflow_write.go b/mdl/backend/modelsdk/workflow_write.go
index 6f815239e4..5a493bca03 100644
--- a/mdl/backend/modelsdk/workflow_write.go
+++ b/mdl/backend/modelsdk/workflow_write.go
@@ -19,6 +19,7 @@ func init() {
 	for _, t := range []string{
 		"Workflows$SingleUserTaskActivity", "Workflows$MultiUserTaskActivity",
 		"Workflows$CallMicroflowTask", "Workflows$CallMicroflowActivity",
+		"Workflows$AIAgentTaskActivity",
 		"Workflows$CallWorkflowActivity",
 		"Workflows$ExclusiveSplitActivity", "Workflows$ParallelSplitActivity",
 		"Workflows$JumpToActivity", "Workflows$WaitForTimerActivity",
@@ -57,8 +58,9 @@ func init() {
 		})
 	}
 	// Both the pre-11.9 CallMicroflowTask and the 11.9+ CallMicroflowActivity
-	// storage names share the same shape (see applyCallMicroflowStorageName).
-	for _, t := range []string{"Workflows$CallMicroflowTask", "Workflows$CallMicroflowActivity"} {
+	// storage names share the same shape (see applyCallMicroflowStorageName), and
+	// so does the 11.9+ AIAgentTaskActivity (ako/TestApp, 11.14.0).
+	for _, t := range []string{"Workflows$CallMicroflowTask", "Workflows$CallMicroflowActivity", "Workflows$AIAgentTaskActivity"} {
 		codec.RegisterTypeDefaults(t, codec.TypeDefaults{
 			MandatoryListMarkers: map[string]int32{"Outcomes": 3, "BoundaryEvents": 2, "ParameterMappings": 2},
 			NullFields:           []string{"Annotation"},
@@ -106,6 +108,7 @@ func init() {
 const (
 	callMicroflowTaskType     = "Workflows$CallMicroflowTask"
 	callMicroflowActivityType = "Workflows$CallMicroflowActivity"
+	aiAgentTaskActivityType   = "Workflows$AIAgentTaskActivity"
 )
 
 // useCallMicroflowActivityName reports whether the target project is Mendix 11.9+
@@ -356,7 +359,13 @@ func userTaskToGen(a *workflows.UserTask) element.Element {
 }
 
 func callMicroflowTaskToGen(a *workflows.CallMicroflowTask) element.Element {
-	g := newElem("Workflows$CallMicroflowTask", activityID(&a.BaseWorkflowActivity))
+	typeName := callMicroflowTaskType
+	if a.IsAgent {
+		// Same document shape; applyCallMicroflowStorageName renames only the
+		// call-microflow type, so this one is written as is.
+		typeName = aiAgentTaskActivityType
+	}
+	g := newElem(typeName, activityID(&a.BaseWorkflowActivity))
 	if a.Annotation != "" {
 		addPart(g, "Annotation", annotationElem(a.Annotation))
 	}
diff --git a/mdl/executor/cmd_alter_workflow.go b/mdl/executor/cmd_alter_workflow.go
index 97a7816542..76404bc160 100644
--- a/mdl/executor/cmd_alter_workflow.go
+++ b/mdl/executor/cmd_alter_workflow.go
@@ -28,6 +28,13 @@ func execAlterWorkflow(ctx *ExecContext, s *ast.AlterWorkflowStmt) error {
 		return err
 	}
 
+	if workflowUsesAgentTask(alterWorkflowAddedActivities(s)) {
+		if err := checkFeature(ctx, "workflows", "ai_agent_task", "call agent microflow",
+			"AI agent tasks need Mendix 11.9 or later — use `call microflow` on older projects"); err != nil {
+			return err
+		}
+	}
+
 	// Same exec-side guard as CREATE WORKFLOW: ALTER had no reference validation
 	// at all, so an inserted activity could name a microflow that exists nowhere
 	// and still be written (issue #943).
diff --git a/mdl/executor/cmd_workflows.go b/mdl/executor/cmd_workflows.go
index 4aa8714304..242be1f180 100644
--- a/mdl/executor/cmd_workflows.go
+++ b/mdl/executor/cmd_workflows.go
@@ -633,6 +633,21 @@ func formatCallMicroflowTask(a *workflows.CallMicroflowTask, indent string) []st
 		mf = "?"
 	}
 
+	verb := "call microflow"
+	if a.IsAgent {
+		verb = "call agent microflow"
+	}
+	// A caption the author set is emitted as `comment '…'`, which the grammar
+	// reads back into the caption. It used to be emitted only as a trailing
+	// `-- caption` comment, so describe → exec replaced it with the microflow's
+	// name. The derived default (the microflow's short name) carries nothing and
+	// stays a plain comment, as for jump and wait activities.
+	asAndComment := workflowActivityAsClause(a.Name, shortDocName(mf))
+	trailing := " -- " + caption
+	if a.Caption != "" && a.Caption != shortDocName(mf) {
+		asAndComment += " comment " + mdlQuoted(a.Caption)
+		trailing = ""
+	}
 	if len(a.ParameterMappings) > 0 {
 		var params []string
 		for _, pm := range a.ParameterMappings {
@@ -642,11 +657,10 @@ func formatCallMicroflowTask(a *workflows.CallMicroflowTask, indent string) []st
 			}
 			params = append(params, fmt.Sprintf("%s = %s", paramName, mdlQuoted(pm.Expression)))
 		}
-		lines = append(lines, fmt.Sprintf("%scall microflow %s%s with (%s) -- %s", indent, mf,
-			workflowActivityAsClause(a.Name, shortDocName(mf)), strings.Join(params, ", "), caption))
+		lines = append(lines, fmt.Sprintf("%s%s %s%s with (%s)%s", indent, verb, mf,
+			asAndComment, strings.Join(params, ", "), trailing))
 	} else {
-		lines = append(lines, fmt.Sprintf("%scall microflow %s%s -- %s", indent, mf,
-			workflowActivityAsClause(a.Name, shortDocName(mf)), caption))
+		lines = append(lines, fmt.Sprintf("%s%s %s%s%s", indent, verb, mf, asAndComment, trailing))
 	}
 
 	// Outcomes, then boundary events — the order the grammar requires
diff --git a/mdl/executor/cmd_workflows_write.go b/mdl/executor/cmd_workflows_write.go
index e7fd28eff9..7d88a2e764 100644
--- a/mdl/executor/cmd_workflows_write.go
+++ b/mdl/executor/cmd_workflows_write.go
@@ -74,6 +74,12 @@ func execCreateWorkflow(ctx *ExecContext, s *ast.CreateWorkflowStmt) error {
 			return err
 		}
 	}
+	if workflowUsesAgentTask(s.Activities) {
+		if err := checkFeature(ctx, "workflows", "ai_agent_task", "call agent microflow",
+			"AI agent tasks need Mendix 11.9 or later — use `call microflow` on older projects"); err != nil {
+			return err
+		}
+	}
 
 	if refErrors := validateWorkflowStatementRefs(ctx, s, nil); len(refErrors) > 0 {
 		return mdlerrors.NewValidationf("workflow '%s' has reference errors:\n  - %s",
@@ -443,7 +449,7 @@ func buildUserTask(n *ast.WorkflowUserTaskNode) *workflows.UserTask {
 }
 
 func buildCallMicroflowTask(n *ast.WorkflowCallMicroflowNode) *workflows.CallMicroflowTask {
-	task := &workflows.CallMicroflowTask{}
+	task := &workflows.CallMicroflowTask{IsAgent: n.Agent}
 	task.ID = model.ID(generateWorkflowUUID())
 	task.Name = n.Microflow.Name
 	task.Caption = n.Caption
diff --git a/mdl/executor/validate_workflow_agent.go b/mdl/executor/validate_workflow_agent.go
new file mode 100644
index 0000000000..a2d08af2ad
--- /dev/null
+++ b/mdl/executor/validate_workflow_agent.go
@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// Checks for the AI agent task (`call agent microflow`, Workflows$AIAgentTaskActivity).
+//
+// Measured on mxbuild 11.13.0 by writing each shape as a call-microflow activity
+// and switching only its $Type, so the two columns differ in nothing else:
+//
+//	agent microflow                         call microflow   AI agent task
+//	(Ctx), mapped                           0 errors         0 errors
+//	() — no parameters                      0 errors         CE1590 "Missing parameter"
+//	(Ctx, String), both mapped              0 errors         0 errors
+//	(System.Workflow)                       0 errors         0 errors
+//	returns Boolean, true/false outcomes    0 errors         0 errors
+//	returns an enumeration, value outcomes  0 errors         0 errors
+//	interrupting timer boundary event       0 errors         0 errors
+//
+// So an agent task is a call-microflow activity with one extra rule: its
+// microflow must take a parameter.
+package executor
+
+import (
+	"fmt"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+)
+
+// checkAgentMicroflow reports an AI agent task whose microflow takes no
+// parameters (CE1590). A microflow whose signature is unknown is left alone.
+func (c *workflowTaskSignatureChecker) checkAgentMicroflow(label, mfQN string) string {
+	if mfQN == "" || mfQN == "." {
+		return ""
+	}
+	sig, ok := c.flowSignature(mfQN)
+	if !ok || sig == nil || len(sig.Params) > 0 {
+		return ""
+	}
+	return fmt.Sprintf(
+		"%s: microflow %s takes no parameters — an AI agent task's microflow must take at least one, usually the "+
+			"workflow's context object mapped with `with (<Param> = '$WorkflowContext')`; the build fails CE1590",
+		label, mfQN)
+}
+
+// workflowUsesAgentTask reports whether any activity, at any depth, is an AI
+// agent task — what the Mendix 11.9 version gate applies to.
+func workflowUsesAgentTask(activities []ast.WorkflowActivityNode) bool {
+	found := false
+	walkWorkflowActivities(activities, func(a ast.WorkflowActivityNode) {
+		if cm, ok := a.(*ast.WorkflowCallMicroflowNode); ok && cm.Agent {
+			found = true
+		}
+	})
+	return found
+}
+
+func countAuthoredAgentTasks(activities []ast.WorkflowActivityNode) int {
+	n := 0
+	walkWorkflowActivities(activities, func(a ast.WorkflowActivityNode) {
+		if cm, ok := a.(*ast.WorkflowCallMicroflowNode); ok && cm.Agent {
+			n++
+		}
+	})
+	return n
+}
diff --git a/mdl/executor/validate_workflow_agent_test.go b/mdl/executor/validate_workflow_agent_test.go
new file mode 100644
index 0000000000..29212425eb
--- /dev/null
+++ b/mdl/executor/validate_workflow_agent_test.go
@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// Rows of the mxbuild spike (11.13.0): the one shape a call microflow accepts and
+// an AI agent task does not is a microflow with no parameters.
+func TestWorkflowAgentTask_MicroflowNeedsAParameter(t *testing.T) {
+	wf := func(body string) string {
+		return `create workflow M.W parameter $C: M.Ctx begin ` + body + ` end workflow;`
+	}
+	cases := []struct{ name, src, want string }{
+		{"agent microflow with parameters", wf(`call agent microflow M.OC_Good as ag with (pa = '$WorkflowTask', pb = '$WorkflowContext');`), ""},
+		{"agent microflow without parameters", wf(`call agent microflow M.OC_None as ag;`), "CE1590"},
+		// The control: the identical call as a plain call microflow builds.
+		{"plain call microflow without parameters", wf(`call microflow M.OC_None as cm;`), ""},
+		{"nested in an outcome", wf(`call agent microflow M.OC_Good as ag with (pa = '$WorkflowTask', pb = '$WorkflowContext') outcomes true -> { call agent microflow M.OC_None as nestedAgent; } false -> { };`), "CE1590"},
+		{"script microflow without parameters", `create microflow M.ScriptAgent () begin end;
+` + wf(`call agent microflow M.ScriptAgent as ag;`), "CE1590"},
+		{"alter insert", `alter workflow M.Stored insert after T call agent microflow M.OC_None as ag;`, "CE1590"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			got := checkScript(t, wfHandlerCtx(t, 11, 13, 0), c.src)
+			if c.want == "" {
+				if strings.Contains(got, "CE1590") {
+					t.Errorf("expected no CE1590, got:\n%s", got)
+				}
+				return
+			}
+			if !strings.Contains(got, c.want) {
+				t.Errorf("expected %s, got:\n%s", c.want, got)
+			}
+		})
+	}
+}
+
+// The AI agent task arrived with Mendix 11.9; the registry entry is what exec's
+// version gate reads.
+func TestWorkflowAgentTask_VersionGate(t *testing.T) {
+	if err := checkFeature(versionCtx(t, 11, 8, 0), "workflows", "ai_agent_task", "call agent microflow", "hint"); err == nil {
+		t.Error("11.8 must refuse an AI agent task")
+	}
+	if err := checkFeature(versionCtx(t, 11, 9, 0), "workflows", "ai_agent_task", "call agent microflow", "hint"); err != nil {
+		t.Errorf("11.9 must accept an AI agent task, got %v", err)
+	}
+	nested := parseWorkflowStmt(t, `create workflow M.W begin
+  call microflow M.A outcomes true -> { call agent microflow M.B; } false -> { };
+end workflow;`)
+	if !workflowUsesAgentTask(nested.Activities) {
+		t.Error("an agent task nested in an outcome must trip the version gate")
+	}
+	if workflowUsesAgentTask(parseWorkflowStmt(t, `create workflow M.W begin call microflow M.A; end workflow;`).Activities) {
+		t.Error("a plain call microflow must not trip the version gate")
+	}
+}
+
+// Describe output re-parses as an agent task — describe used to print one only as
+// a `-- [Workflows$AIAgentTaskActivity]` comment, which a rewrite then deleted.
+func TestWorkflowAgentTask_DescribeRoundTrips(t *testing.T) {
+	task := &workflows.CallMicroflowTask{
+		IsAgent:           true,
+		Microflow:         "workflow.InvokeAgent",
+		ParameterMappings: []*workflows.ParameterMapping{{Parameter: "workflow.InvokeAgent.workfow1context", Expression: "$WorkflowContext"}},
+	}
+	task.Name = "aiAgentTask1"
+	task.Caption = "AI Agent Task"
+	// Through the flow formatter, which places the statement terminator ahead of
+	// the trailing caption comment.
+	out := strings.Join(formatSingleActivity(task, "  "), "\n")
+	// The caption is authored (not the microflow's name), so it is described as a
+	// comment clause, which re-executes into the caption.
+	if !strings.Contains(out, "call agent microflow workflow.InvokeAgent as aiAgentTask1 comment 'AI Agent Task' with (workfow1context = '$WorkflowContext')") {
+		t.Fatalf("describe = %q", out)
+	}
+	stmt := parseWorkflowStmt(t, "create workflow M.W\nbegin\n"+out+"\nend workflow;")
+	cm, ok := stmt.Activities[0].(*ast.WorkflowCallMicroflowNode)
+	if !ok || !cm.Agent || cm.Name != "aiAgentTask1" {
+		t.Errorf("re-parsed = %+v", stmt.Activities[0])
+	}
+}
+
+// A statement restating the stored agent task loses nothing and must pass the
+// rewrite guard; the unrestated case is refused (TestWorkflowRewrite_RefusesDroppingStudioProOnlyState).
+func TestWorkflowRewrite_AllowsRestatedAgentTask(t *testing.T) {
+	stmt := parseWorkflowStmt(t, `create or modify workflow M.W parameter $C: M.Ctx
+begin
+  call agent microflow workflow.InvokeAgent as aiAgentTask1 with (workfow1context = '$WorkflowContext');
+  user task userTask1 'User Task' page M.P outcomes 'Good' { } 'Bad' { };
+  multi user task userTask2 'Multi' page M.P outcomes 'Fast' { } 'Furious' { };
+end workflow;`)
+	raw := studioProWorkflow(false, false, true, "ConsensusCompletionCriteria", true)
+	if err := checkNoDroppedWorkflowConstructs(rawWorkflowCtx(t, raw), "wf1", "M.W", stmt); err != nil {
+		t.Fatalf("a rewrite restating its agent task must be allowed, got %v", err)
+	}
+}
diff --git a/mdl/executor/validate_workflow_rewrite.go b/mdl/executor/validate_workflow_rewrite.go
index eff5ee2e54..4efe741f4f 100644
--- a/mdl/executor/validate_workflow_rewrite.go
+++ b/mdl/executor/validate_workflow_rewrite.go
@@ -48,8 +48,7 @@ func checkNoDroppedWorkflowConstructs(ctx *ExecContext, workflowID model.ID, qua
 
 	// Constructs MDL cannot express at all. A rebuild writes the default for
 	// each — measured on ako/TestApp (11.14.0): a completion rule becomes
-	// Consensus on the first outcome, and describe shows an AI agent task only as
-	// a comment — so a rewrite loses them without a word. Refused outright, like
+	// Consensus on the first outcome — so a rewrite loses them without a word. Refused outright, like
 	// an event sub-process, and every reason is listed at once.
 	var cannotExpress []string
 	if n := countEventSubProcesses(raw); n > 0 {
@@ -86,6 +85,15 @@ func checkNoDroppedWorkflowConstructs(ctx *ExecContext, workflowID model.ID, qua
 			qualifiedName, len(stored), authored, strings.Join(stored, "\n  - "), qualifiedName))
 	}
 
+	if stored, authored := rawAgentTasks(raw), countAuthoredAgentTasks(stmt.Activities); len(stored) > authored {
+		return mdlerrors.NewUnsupported(fmt.Sprintf(
+			"workflow %s has %d AI agent task(s) but this statement declares %d — rewriting it would delete the "+
+				"difference, along with each one's outcome flows:\n  - %s\n"+
+				"  Restate them (`call agent microflow …`), which `describe workflow %s` now emits, or use ALTER "+
+				"WORKFLOW to change one activity at a time.",
+			qualifiedName, len(stored), authored, strings.Join(stored, "\n  - "), qualifiedName))
+	}
+
 	// Ends inside branches. MDL could not state one until `end workflow`, and
 	// describe dropped them, so a rewrite from an older describe output would
 	// delete every one — and a branch that ended the workflow would silently
@@ -200,7 +208,7 @@ func countAuthoredBoundaryEvents(activities []ast.WorkflowActivityNode) int {
 }
 
 // studioProOnlyWorkflowState lists what a stored workflow holds that a rebuild
-// from MDL would reset: AI agent tasks, a workflow event handler subscribed to no
+// from MDL would reset: a workflow event handler subscribed to no
 // event types (the grammar has no empty list), and per activity a completion rule
 // other than the one mxcli writes.
 func studioProOnlyWorkflowState(raw map[string]any) []string {
@@ -221,11 +229,6 @@ func studioProOnlyWorkflowState(raw map[string]any) []string {
 		}
 	}
 	walkRawDocs(raw, func(d map[string]any) {
-		if t, _ := d["$Type"].(string); t == "Workflows$AIAgentTaskActivity" {
-			name, _ := d["Name"].(string)
-			out = append(out, fmt.Sprintf("AI agent task '%s', which describe shows only as a comment and it would delete", name))
-			return
-		}
 		out = append(out, rawActivityState(d)...)
 	})
 	return out
@@ -339,6 +342,19 @@ func rawHandlerLabel(h map[string]any) string {
 	return "running microflow " + orUnnamed(microflow)
 }
 
+// rawAgentTasks labels each stored AI agent task.
+func rawAgentTasks(raw map[string]any) []string {
+	var out []string
+	walkRawDocs(raw, func(d map[string]any) {
+		if t, _ := d["$Type"].(string); t == "Workflows$AIAgentTaskActivity" {
+			name, _ := d["Name"].(string)
+			mf, _ := d["Microflow"].(string)
+			out = append(out, fmt.Sprintf("AI agent task '%s' (microflow %s)", name, orUnnamed(mf)))
+		}
+	})
+	return out
+}
+
 // rawOnCreatedMicroflows labels each stored user task that runs an on-created
 // microflow.
 func rawOnCreatedMicroflows(raw map[string]any) []string {
diff --git a/mdl/executor/validate_workflow_task_signature.go b/mdl/executor/validate_workflow_task_signature.go
index 7c2c0fd7eb..f1064ca562 100644
--- a/mdl/executor/validate_workflow_task_signature.go
+++ b/mdl/executor/validate_workflow_task_signature.go
@@ -107,6 +107,10 @@ func newWorkflowTaskSignatureChecker(ctx *ExecContext, sc *scriptContext) *workf
 func (c *workflowTaskSignatureChecker) checkActivities(activities []ast.WorkflowActivityNode, contextEntity string) []string {
 	var errs []string
 	walkWorkflowActivities(activities, func(a ast.WorkflowActivityNode) {
+		if cm, ok := a.(*ast.WorkflowCallMicroflowNode); ok && cm.Agent {
+			errs = appendIfSet(errs, c.checkAgentMicroflow("AI agent task "+workflowCallMicroflowLabel(cm), cm.Microflow.String()))
+			return
+		}
 		n, ok := a.(*ast.WorkflowUserTaskNode)
 		if !ok {
 			return
diff --git a/mdl/executor/workflow_callmicroflow_caption_test.go b/mdl/executor/workflow_callmicroflow_caption_test.go
new file mode 100644
index 0000000000..420aea917b
--- /dev/null
+++ b/mdl/executor/workflow_callmicroflow_caption_test.go
@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// A call microflow's caption was described only as a trailing `-- caption`
+// comment, so describe → exec replaced an authored caption with the microflow's
+// name — found by the phase 2 end-to-end round trip, where `comment 'Summarise'`
+// came back as `-- ACT_Summarise`. An authored caption is now `comment '…'`, which
+// re-parses; the derived default is not echoed as one.
+func TestFormatCallMicroflow_CaptionRoundTrips(t *testing.T) {
+	cases := []struct {
+		name, caption, wantClause string
+		agent                     bool
+	}{
+		{"authored caption", "Summarise the order", "comment 'Summarise the order'", false},
+		{"authored caption on an agent task", "Classify", "comment 'Classify'", true},
+		{"quote escaped", "it's done", "comment 'it''s done'", false},
+		{"derived default is not a comment clause", "ACT_Summarise", "", false},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			task := &workflows.CallMicroflowTask{
+				IsAgent:           c.agent,
+				Microflow:         "M.ACT_Summarise",
+				ParameterMappings: []*workflows.ParameterMapping{{Parameter: "M.ACT_Summarise.Ctx", Expression: "$WorkflowContext"}},
+			}
+			task.Name = "step1"
+			task.Caption = c.caption
+			out := strings.Join(formatSingleActivity(task, "  "), "\n")
+
+			if c.wantClause == "" {
+				if strings.Contains(out, " comment ") {
+					t.Errorf("derived caption must not become a comment clause: %q", out)
+				}
+			} else if !strings.Contains(out, c.wantClause) {
+				t.Errorf("describe lacks %q: %q", c.wantClause, out)
+			}
+
+			stmt := parseWorkflowStmt(t, "create workflow M.W\nbegin\n"+out+"\nend workflow;")
+			cm, ok := stmt.Activities[0].(*ast.WorkflowCallMicroflowNode)
+			if !ok {
+				t.Fatalf("re-parsed %T from %q", stmt.Activities[0], out)
+			}
+			built := buildCallMicroflowTask(cm)
+			if built.Caption != c.caption || built.IsAgent != c.agent || built.Name != "step1" {
+				t.Errorf("re-executed caption %q agent %v name %q, want %q %v step1", built.Caption, built.IsAgent, built.Name, c.caption, c.agent)
+			}
+		})
+	}
+}
diff --git a/mdl/grammar/domains/MDLWorkflow.g4 b/mdl/grammar/domains/MDLWorkflow.g4
index 58f486d202..43a3a4e620 100644
--- a/mdl/grammar/domains/MDLWorkflow.g4
+++ b/mdl/grammar/domains/MDLWorkflow.g4
@@ -136,8 +136,14 @@ workflowUserTaskOutcome
     : STRING_LITERAL LBRACE workflowBody RBRACE
     ;
 
+/**
+ * `call agent microflow` is the AI agent task (Mendix 11.9+): stored as
+ * Workflows$AIAgentTaskActivity, the same shape as a call-microflow activity, and
+ * run by the workflow engine as an agent step. The microflow is where the agent is
+ * invoked.
+ */
 workflowCallMicroflowStmt
-    : CALL MICROFLOW qualifiedName (AS workflowActivityName)? (COMMENT STRING_LITERAL)?
+    : CALL AGENT? MICROFLOW qualifiedName (AS workflowActivityName)? (COMMENT STRING_LITERAL)?
       (WITH LPAREN workflowParameterMapping (COMMA workflowParameterMapping)* RPAREN)?
       (OUTCOMES workflowConditionOutcome+)?
       (BOUNDARY EVENT workflowBoundaryEventClause ((BOUNDARY EVENT)? workflowBoundaryEventClause)*)?
diff --git a/mdl/visitor/visitor_workflow.go b/mdl/visitor/visitor_workflow.go
index 642912f5d1..60b5959238 100644
--- a/mdl/visitor/visitor_workflow.go
+++ b/mdl/visitor/visitor_workflow.go
@@ -629,6 +629,7 @@ func buildWorkflowCallMicroflow(ctx parser.IWorkflowCallMicroflowStmtContext) *a
 	cmCtx := ctx.(*parser.WorkflowCallMicroflowStmtContext)
 	node := &ast.WorkflowCallMicroflowNode{
 		Name:      workflowActivityNameText(cmCtx.WorkflowActivityName()),
+		Agent:     cmCtx.AGENT() != nil,
 		Microflow: buildQualifiedName(cmCtx.QualifiedName()),
 	}
 
diff --git a/mdl/visitor/visitor_workflow_agent_test.go b/mdl/visitor/visitor_workflow_agent_test.go
new file mode 100644
index 0000000000..168f3afa60
--- /dev/null
+++ b/mdl/visitor/visitor_workflow_agent_test.go
@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package visitor
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+)
+
+// `call agent microflow` is the AI agent task; everything after AGENT is the
+// call-microflow statement, so name, comment, mappings and outcomes land the same.
+func TestWorkflowVisitor_CallAgentMicroflow(t *testing.T) {
+	stmt := buildWorkflowStmt(t, `create workflow M.W
+begin
+  call agent microflow M.InvokeAgent as aiAgentTask1 comment 'Classify' with (Request = '$WorkflowContext')
+    outcomes true -> { } false -> { };
+  call microflow M.Plain;
+end workflow;`)
+	if len(stmt.Activities) != 2 {
+		t.Fatalf("activities = %d, want 2", len(stmt.Activities))
+	}
+	agent, ok := stmt.Activities[0].(*ast.WorkflowCallMicroflowNode)
+	if !ok {
+		t.Fatalf("activity 0 is %T", stmt.Activities[0])
+	}
+	if !agent.Agent || agent.Name != "aiAgentTask1" || agent.Caption != "Classify" ||
+		agent.Microflow.String() != "M.InvokeAgent" || len(agent.ParameterMappings) != 1 || len(agent.Outcomes) != 2 {
+		t.Errorf("agent task = %+v", agent)
+	}
+	plain := stmt.Activities[1].(*ast.WorkflowCallMicroflowNode)
+	if plain.Agent {
+		t.Error("a plain call microflow must not be an agent task")
+	}
+}
diff --git a/sdk/mpr/parser_workflow.go b/sdk/mpr/parser_workflow.go
index b08498572c..298e75488d 100644
--- a/sdk/mpr/parser_workflow.go
+++ b/sdk/mpr/parser_workflow.go
@@ -206,12 +206,17 @@ var workflowActivityParsers map[string]func(map[string]any) workflows.WorkflowAc
 
 func init() {
 	workflowActivityParsers = map[string]func(map[string]any) workflows.WorkflowActivity{
-		"Workflows$EndWorkflowActivity":         func(r map[string]any) workflows.WorkflowActivity { return parseEndWorkflowActivity(r) },
-		"Workflows$UserTask":                    func(r map[string]any) workflows.WorkflowActivity { return parseUserTask(r) },
-		"Workflows$SingleUserTaskActivity":      func(r map[string]any) workflows.WorkflowActivity { return parseUserTask(r) },
-		"Workflows$MultiUserTaskActivity":       func(r map[string]any) workflows.WorkflowActivity { return parseMultiUserTask(r) },
-		"Workflows$CallMicroflowTask":           func(r map[string]any) workflows.WorkflowActivity { return parseCallMicroflowTask(r) },
-		"Workflows$CallMicroflowActivity":       func(r map[string]any) workflows.WorkflowActivity { return parseCallMicroflowTask(r) },
+		"Workflows$EndWorkflowActivity":    func(r map[string]any) workflows.WorkflowActivity { return parseEndWorkflowActivity(r) },
+		"Workflows$UserTask":               func(r map[string]any) workflows.WorkflowActivity { return parseUserTask(r) },
+		"Workflows$SingleUserTaskActivity": func(r map[string]any) workflows.WorkflowActivity { return parseUserTask(r) },
+		"Workflows$MultiUserTaskActivity":  func(r map[string]any) workflows.WorkflowActivity { return parseMultiUserTask(r) },
+		"Workflows$CallMicroflowTask":      func(r map[string]any) workflows.WorkflowActivity { return parseCallMicroflowTask(r) },
+		"Workflows$CallMicroflowActivity":  func(r map[string]any) workflows.WorkflowActivity { return parseCallMicroflowTask(r) },
+		"Workflows$AIAgentTaskActivity": func(r map[string]any) workflows.WorkflowActivity {
+			t := parseCallMicroflowTask(r)
+			t.IsAgent = true
+			return t
+		},
 		"Workflows$CallWorkflowActivity":        func(r map[string]any) workflows.WorkflowActivity { return parseCallWorkflowActivity(r) },
 		"Workflows$ExclusiveSplitActivity":      func(r map[string]any) workflows.WorkflowActivity { return parseExclusiveSplitActivity(r) },
 		"Workflows$ParallelSplitActivity":       func(r map[string]any) workflows.WorkflowActivity { return parseParallelSplitActivity(r) },
diff --git a/sdk/mpr/workflow_agent_test.go b/sdk/mpr/workflow_agent_test.go
new file mode 100644
index 0000000000..6e27dd8dac
--- /dev/null
+++ b/sdk/mpr/workflow_agent_test.go
@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package mpr
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// The legacy engine is being retired, but it must not turn an AI agent task into
+// a plain call microflow on the way through: same document shape, agent $Type.
+func TestWorkflowAgentTask_LegacySerializeAndParse(t *testing.T) {
+	doc := serializeCallMicroflowTask(&workflows.CallMicroflowTask{IsAgent: true, Microflow: "M.InvokeAgent"})
+	if got := getBSONField(doc, "$Type"); got != "Workflows$AIAgentTaskActivity" {
+		t.Errorf("$Type = %v, want Workflows$AIAgentTaskActivity", got)
+	}
+	plain := serializeCallMicroflowTask(&workflows.CallMicroflowTask{Microflow: "M.Plain"})
+	if got := getBSONField(plain, "$Type"); got != "Workflows$CallMicroflowTask" {
+		t.Errorf("plain $Type = %v", got)
+	}
+
+	act := parseWorkflowActivity(map[string]any{
+		"$Type":     "Workflows$AIAgentTaskActivity",
+		"Name":      "aiAgentTask1",
+		"Microflow": "M.InvokeAgent",
+	})
+	cm, ok := act.(*workflows.CallMicroflowTask)
+	if !ok || !cm.IsAgent || cm.Microflow != "M.InvokeAgent" {
+		t.Errorf("parsed = %#v", act)
+	}
+}
diff --git a/sdk/mpr/writer_workflow.go b/sdk/mpr/writer_workflow.go
index 310f8c94a1..b4a34acda9 100644
--- a/sdk/mpr/writer_workflow.go
+++ b/sdk/mpr/writer_workflow.go
@@ -533,9 +533,13 @@ func serializeUserTaskOutcome(outcome *workflows.UserTaskOutcome) bson.D {
 }
 
 func serializeCallMicroflowTask(a *workflows.CallMicroflowTask) bson.D {
+	typeName := "Workflows$CallMicroflowTask"
+	if a.IsAgent {
+		typeName = "Workflows$AIAgentTaskActivity" // same shape, 11.9+
+	}
 	doc := bson.D{
 		{Key: "$ID", Value: idToBsonBinary(activityID(&a.BaseWorkflowActivity))},
-		{Key: "$Type", Value: "Workflows$CallMicroflowTask"},
+		{Key: "$Type", Value: typeName},
 	}
 
 	// Annotation
diff --git a/sdk/versions/mendix-11.yaml b/sdk/versions/mendix-11.yaml
index 3c58255858..e9f2b03288 100644
--- a/sdk/versions/mendix-11.yaml
+++ b/sdk/versions/mendix-11.yaml
@@ -180,6 +180,10 @@ features:
       min_version: "9.0.0"
     user_task:
       min_version: "9.0.0"
+    ai_agent_task:
+      min_version: "11.9.0"
+      mdl: "CALL AGENT MICROFLOW Module.InvokeAgent WITH (Param = '$WorkflowContext')"
+      notes: "Workflows$AIAgentTaskActivity, introduced when Mendix 11.9 split MicroflowBasedActivity into CallMicroflowActivity + AIAgentTaskActivity. Absent from the 11.6 mxbuild, present from 11.10."
     event_handlers:
       min_version: "10.7.0"
       mdl: "CREATE WORKFLOW … ON WORKFLOW EVENTS (…) MICROFLOW Module.Handler AS '…'"
diff --git a/sdk/workflows/workflow.go b/sdk/workflows/workflow.go
index 7f56036c4d..07738658f7 100644
--- a/sdk/workflows/workflow.go
+++ b/sdk/workflows/workflow.go
@@ -153,6 +153,11 @@ func (a *SystemTask) ActivityType() string { return "SystemTask" }
 // CallMicroflowTask represents a call-microflow activity in a workflow.
 type CallMicroflowTask struct {
 	BaseWorkflowActivity
+	// IsAgent marks an AI agent task (Workflows$AIAgentTaskActivity, Mendix
+	// 11.9+). It stores exactly the call-microflow shape under a different
+	// $Type, so it is this type with a flag rather than a type of its own —
+	// every walker, validator and catalog edge applies to it unchanged.
+	IsAgent           bool                `json:"isAgent,omitempty"`
 	Microflow         string              `json:"microflow,omitempty"` // Qualified name of the microflow to call
 	Outcomes          []ConditionOutcome  `json:"outcomes,omitempty"`  // Condition-based outcomes
 	ParameterMappings []*ParameterMapping `json:"parameterMappings,omitempty"`

From 3b4df7c1519b00dfe1a03aafdf3a046ba7693f79 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 15 Sep 2026 06:07:16 +0000
Subject: [PATCH 07/24] refactor(api): route the fluent API through the backend
 abstraction
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

api/ imported mdl/backend ZERO times. It was not "dependent on the legacy
backend" — it bypassed the abstraction entirely, holding a concrete *mpr.Writer
handed to api.New. That is why AddAttribute and UpdateAttribute sat
unimplemented on the codec engine: api/ was their only caller and it did not
call them through a backend value.

api.New now takes a backend.FullBackend, with an api.Open convenience for the
common case. The builder surface is untouched, so this is not a breaking change
to anything but the constructor — and nothing in the repository imports the
package, so the blast radius in-tree is its own tests. The gain is not tidiness:
the same fluent builders now run against any backend, including a live Studio
Pro over MCP, which was unreachable while the package held a concrete writer.
Open owns the connection it makes; a backend passed to New belongs to the caller
and Close leaves it alone.

AddAttribute and UpdateAttribute are implemented on the codec backend and struck
off unreachableUnimplemented, which failed loudly when they became reachable —
exactly what that pin is for. Two properties are worth the tests they get: the
attribute keeps its stored $ID (the runtime keys on identity), and the list keeps
its order. The second is not free — the generated list offers only Append and
Remove, so an in-place replace means rebuilding it, and the naive
remove-then-add moves the edited attribute to the bottom of the entity. Control:
breaking the rebuild fails the order test.

THE SUITE THAT SHOULD HAVE VERIFIED ALL THIS HAD ONLY EVER SKIPPED. api/'s ten
integration tests pointed at ../mx-test-projects/test-source-app, which is not in
the repository, so every one of them skipped on every machine and in CI since
they were written — the #808 shape, and it meant `go test ./api/` passing said
nothing about a refactor that rewrote every call site in the package. They now
run against the committed testdata/expr-checker fixture the codec backend's own
tests use, and a missing fixture is FATAL rather than a skip, because a committed
fixture's absence is a broken checkout rather than an optional dependency. Ten
tests, zero skips, all passing against the codec engine.

First step of Phase 3 of docs/plans/2026-09-14-retire-legacy-engine.md.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hifgRSawfaRWXS44YKtSJ
---
 .../fix-issue/findings/mdl-backend.jsonl      |   1 +
 CLAUDE.md                                     |  17 +-
 api/api.go                                    |  96 +++++---
 api/api_integration_test.go                   | 120 ++++-----
 api/domainmodels.go                           |  42 ++--
 api/enumerations.go                           |  14 +-
 api/helpers.go                                |   4 +-
 api/microflows.go                             |   8 +-
 api/modules.go                                |   6 +-
 api/pages.go                                  |  12 +-
 mdl/backend/modelsdk/domainmodel_alter.go     | 103 ++++++++
 .../domainmodel_attribute_alter_test.go       | 229 ++++++++++++++++++
 .../unimplemented_reachability_test.go        |  11 +-
 13 files changed, 516 insertions(+), 147 deletions(-)
 create mode 100644 mdl/backend/modelsdk/domainmodel_attribute_alter_test.go

diff --git a/.claude/skills/fix-issue/findings/mdl-backend.jsonl b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
index 71727447b8..b1e4d2a0a0 100644
--- a/.claude/skills/fix-issue/findings/mdl-backend.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
@@ -95,3 +95,4 @@
 {"area": "mdl/backend", "date": "2026-09-12", "symptom": "The modelsdk (default) engine leaves 19 of FullBackend's 276 methods to the errUnimplemented stub, which tells the user to \"rerun with MXCLI_ENGINE=legacy\" — the engine being retired. Nineteen unported methods reads as nineteen reasons legacy has to stay shipped and tested", "cause": "Seventeen of the nineteen cannot be reached at all: they are interface surface that only the MPR backend's own delegation and callers holding a concrete *mpr.Reader / *mpr.Writer (api/, examples/, cmd/mxcli commands that open a reader directly) ever touch, so the stub can never fire. The two that ARE reachable — GetRawUnitByName and ParseMicroflowBSON, four call sites in mdl/executor/cmd_microflows_builder.go — were invisible because each is a fast path with a working slow-path fallback: the stub errored, the code fell through to an O(n) module walk, and the result was identical", "file": "`mdl/backend/modelsdk/raw_lookup.go` (new), `mdl/backend/modelsdk/unimplemented_reachability_test.go` (new), `scripts/backend-reachability.sh` (new)", "insight": "**Grep cannot answer \"is this interface method reachable\" and the compiler can.** `b.reader.GetRawUnitByName(...)` inside the MPR backend and `ctx.Backend.GetRawUnitByName(...)` in the executor are indistinguishable to a regex, and receiver names vary, so a grep-based count said all nineteen had callers. Deleting one method from its interface at a time and rebuilding gives a yes/no per method with no judgement involved: 17 DEAD, 2 LIVE. Slow (one `go build ./...` each, minutes for the set) but decisive — script it, commit it, and pin its OUTPUT in a test rather than re-running it in CI. **A fallback hides an unimplemented method completely.** Nothing was broken and no test failed, because the fast path's failure was indistinguishable from a cache miss; the only symptom was work being done twice. Look for `if x, err := …; err == nil` fast paths when auditing what an engine cannot do. **Measure the speedup before claiming one**: restoring the fast path made no measurable difference (620ms vs 608ms over three runs on a 138-microflow project, within noise), because `mxcli exec` runs `check` first and check's own helpers load ListMicroflows anyway — so the cache the slow path builds is already warm. The value here is the removal of the errUnimplemented cliff, not speed", "refs": []}
 {"area": "mdl/backend", "date": "2026-09-11", "symptom": "`ALTER PAGE REPLACE`/`INSERT` inside a data view bound `datasource: selection <list>` re-scopes the new widget's attribute binding to the OUTER data view's entity (**CE1613** \"The selected attribute 'Mod.Outer.Attr' no longer exists\"), and inside a Gallery/DataGrid 2 sourced by a **microflow/nanoflow** drops it entirely (**CE0402** \"No value specified\", `describe` shows `ContentParams: [{1} = <unbound>]`). `mxcli check --references` and `exec` both report success; `CREATE PAGE` binds the same widget in the same position correctly", "cause": "The mutator resolved a widget's scope in TWO walks that each knew a different subset of the ten Forms$*Source kinds. `Forms$ListenTargetSource` carries no EntityRef at all \u2014 only the listen target's NAME \u2014 so the entity walk saw no source on the selection data view and left the context at the enclosing one. The flow walk (`findNearestDataSourceDoc`) read only a widget's TOP-LEVEL `DataSource` key, so a pluggable list \u2014 whose source sits at `Object.Properties[datasource].Value.DataSource` \u2014 contributed nothing, and its `Objects[].Properties[].Value.Widgets` descent (the one the entity walk gained in #935) was missing too", "file": "`mdl/backend/pagemutator/mutator.go` (`resolveSourceScope`/`resolveSourceScopeVia`, `listenTargetDataSource`, `widgetOwnDataSourceDoc`, `pluggableDataSourceDoc`; `EnclosingEntity`/`EnclosingEntityForChildren`/`EnclosingDataSourceFlow` now share the one walk `findNearestDataSourceDoc`, and `findEnclosingEntityContext` + its two helpers are deleted)", "insight": "**Count the source kinds before fixing one.** `generated/metamodel/types.go`'s `DataSource is implemented by` list closes the set at ten, and they divide exactly three ways \u2014 seven carry an EntityRef, two are flows, one (ListenTarget) borrows the scope of the widget it names \u2014 so one resolver can be complete, where three successive per-kind patches (FINDINGS #55 association+flow, #935 pluggable, this one) each left a hole. **A nearer source that resolves to no entity must SHADOW the outer one**: inheriting is what wrote the wrong entity, and it also mis-scoped a flow-sourced list nested in an entity-bound data view \u2014 a case the report did not name and the old code got wrong. The listen target is found by a shape-independent search for \"a document with this Name that has a data source\", which is what makes it work when the target is a pluggable widget keeping its source three levels inside its Object; a visited-set guards a hand-written listen cycle. **Measurement trap: a CE1613 SUPPRESSES the CE0402s in the same `mx check` run** \u2014 the first reading said mxbuild tolerated the unbound parameter, and the CE0402s only appeared once the re-scoped binding was fixed, so count bindings in `describe`, not errors. The issue's own second repro (a Gallery over a DATABASE source) no longer reproduced \u2014 #935 had fixed it \u2014 and the live defect was its flow-sourced variant, so re-measure a report against main before trusting its class. Tests `mdl/backend/pagemutator/mutator_selection_source_test.go` (7, incl. dangling/cyclic listen targets and the shadowing control); repro `mdl-examples/bug-tests/1076-alter-page-selection-and-flow-scope.mdl` \u2014 2 \u00d7 CE1613 + 3 unbound before, 0 errors after, on mxbuild 11.10.0. Each half proven load-bearing by stubbing it alone and rebuilding the CLI", "refs": ["mendixlabs/mxcli#1076", "#55", "#935"], "ce": ["CE0402", "CE1613"]}
 {"area": "mdl/backend", "date": "2026-09-15", "symptom": "On the default engine, `describe workflow` printed `wait for notification x;` without its boundary events (and their handler flows); the legacy engine described them. A describe -> exec round trip lost them.", "cause": "workflowActivityFromGen's typed switch had no case for *genWf.WaitForNotificationActivity, so it fell to workflowSimpleActivityFromGen, which reads only Name and Caption from raw BSON. That path's comment said the wait activities 'have no genWf struct' — true once, stale by the time gen gained WaitForNotificationActivity with BoundaryEventsItems().", "fix": "Typed case reading boundaryEventsFromGen(a.BoundaryEventsItems()), like the five other activities that carry boundary events.", "file": "mdl/backend/modelsdk/workflow_read.go", "insight": "A fallback path documented as 'for types gen does not model' silently keeps catching a type after gen starts modelling it; the reader then under-reads without any error. When gen is re-vendored, grep the typed switches for types that newly have structs. The bug surfaced only because a probe described what it had just written — reading back your own write, per activity type, is the cheap check."}
+{"area":"mdl/backend","date":"2026-09-15","symptom":"AddAttribute and UpdateAttribute were unimplemented on the default engine, so api/ could only work on the retired legacy one — and api/'s whole integration suite reported green while verifying nothing","cause":"api/ imported mdl/backend zero times: it held a concrete *mpr.Writer and bypassed the backend abstraction, so the two methods had no caller through a backend value and were never ported.","file":"api/api.go","fix":"api.New takes a backend.FullBackend (plus an api.Open convenience that owns its connection); the two methods are implemented on the codec backend and struck off unreachableUnimplemented.","insight":"unreachableUnimplemented is a CENSUS OF WHO BYPASSES THE ABSTRACTION, not dead interface surface. Read its reason column as a map and it names api/, the MCP backend, and the cmd/mxcli commands holding a concrete reader; a method is on it BECAUSE such a caller exists and unreachable BECAUSE that caller does not use a backend value. So the list shrinks by closing a bypass, never by deleting methods — and the pin fails loudly when you do, which is how it should be used. Two traps in the port itself. (1) The generated gen list offers only Append and Remove, so replacing an element in place means rebuilding the list; the naive remove-then-add moves the edited attribute to the bottom of the entity, which is a diff on every edit — control: break the rebuild and the order test catches it. (2) THE SUITE THAT WOULD HAVE VERIFIED THE PORT HAD ONLY EVER SKIPPED. api/'s integration tests pointed at ../mx-test-projects/test-source-app, which is not in the repository, so all ten skipped on every machine and in CI since they were written (the #808 shape). `go test ./api/` passing said nothing. Repointed at the committed testdata/expr-checker fixture the codec backend's own tests use, and made a missing fixture FATAL rather than a skip, since a committed fixture's absence is a broken checkout. Before trusting a suite to verify a refactor, check it is not skipping."}
diff --git a/CLAUDE.md b/CLAUDE.md
index 0433a4818e..4db6796754 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -526,11 +526,13 @@ defer writer.Close()
 The `api/` package provides a simplified, fluent API inspired by Mendix Web Extensibility Model API:
 
 ```go
-modelAPI := api.New(writer)
-module, _ := modelAPI.Modules.GetModule("MyModule")
-modelAPI.SetModule(module)
+a, err := api.Open("/path/to/project.mpr")   // or api.New(b) over any backend
+defer a.Close()
 
-entity, _ := modelAPI.DomainModels.CreateEntity("Customer").
+module, _ := a.Modules.GetModule("MyModule")
+a.SetModule(module)
+
+entity, _ := a.DomainModels.CreateEntity("Customer").
     persistent().
     WithStringAttribute("Name", 100).
     WithIntegerAttribute("Age").
@@ -539,6 +541,13 @@ entity, _ := modelAPI.DomainModels.CreateEntity("Customer").
 
 Available namespaces: `DomainModels`, `enumerations`, `microflows`, `pages`, `modules`
 
+It takes a **`backend.FullBackend`, not a `*mpr.Writer`** — it used to hold a concrete legacy
+writer and so bypassed the backend abstraction entirely, which is why `AddAttribute` and
+`UpdateAttribute` sat unimplemented on the codec engine with `api/` as their only caller. The
+practical gain is that the same builders now run against any backend, including a live Studio Pro
+over MCP, which was unreachable before. `Open` owns the connection it makes; a backend passed to
+`New` belongs to the caller and `Close` leaves it alone.
+
 ## Code Style Guidelines
 
 - Follow standard Go conventions (`go fmt`, `go vet`)
diff --git a/api/api.go b/api/api.go
index 0c5c5e30e4..dc64431711 100644
--- a/api/api.go
+++ b/api/api.go
@@ -5,38 +5,58 @@
 // This API is inspired by the Mendix Web Extensibility Model API and provides
 // a simplified interface on top of the low-level SDK types.
 //
+// # Opening a project
+//
+// For the common case, let the package open the project itself:
+//
+//	a, err := api.Open("app.mpr")
+//	defer a.Close()
+//
+// For anything else — a project already open, a different engine, or a live
+// Studio Pro session — hand it a backend:
+//
+//	a := api.New(someBackend)
+//
+// # Why a backend rather than a writer
+//
+// This package used to take a concrete `*mpr.Writer`, which tied it to one
+// storage implementation and meant it did not benefit from anything the backend
+// abstraction ([ADR-0002]) provides. Taking a `backend.FullBackend` instead is
+// what lets the same fluent builders run against the codec engine, against a
+// live Studio Pro over MCP, or against a test double — none of which were
+// reachable before.
+//
 // Example usage:
 //
-//	writer, _ := mpr.NewWriter("app.mpr")
-//	defer writer.Close()
+//	a, _ := api.Open("app.mpr")
+//	defer a.Close()
 //
-//	api := api.New(writer)
+//	module, _ := a.GetModule("MyModule")
+//	a.SetModule(module)
 //
-//	// Create an entity
-//	entity, _ := api.DomainModels.CreateEntity("Customer").
-//	    InModule(module).
+//	entity, _ := a.DomainModels.CreateEntity("Customer").
 //	    Persistent().
 //	    WithStringAttribute("Name", 100).
 //	    Build()
 //
-//	// Create a page
-//	page, _ := api.Pages.CreatePage("Customer_Edit").
-//	    InModule(module).
-//	    WithTitle("Edit Customer").
-//	    Build()
+// [ADR-0002]: ../docs/13-decisions/0002-backend-abstraction.md
 package api
 
 import (
+	"github.com/mendixlabs/mxcli/mdl/backend"
+	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
 	"github.com/mendixlabs/mxcli/model"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
 )
 
 // ModelAPI is the main entry point for the high-level API.
 // It provides access to domain-specific APIs for pages, domain models,
 // microflows, and enumerations.
 type ModelAPI struct {
-	writer *mpr.Writer
-	reader *mpr.Reader
+	backend backend.FullBackend
+
+	// owned is true when Open created the backend, so Close should disconnect
+	// it. A backend handed to New belongs to the caller and is left alone.
+	owned bool
 
 	// Current module context (optional)
 	currentModule *model.Module
@@ -49,33 +69,47 @@ type ModelAPI struct {
 	Modules      *ModulesAPI
 }
 
-// New creates a new ModelAPI instance for the given writer.
-func New(writer *mpr.Writer) *ModelAPI {
-	api := &ModelAPI{
-		writer: writer,
-		reader: writer.Reader(),
-	}
-
-	// Initialize domain-specific APIs
+// New creates a ModelAPI over an already-connected backend.
+//
+// The backend's lifetime belongs to the caller: Close does not disconnect it.
+// Use Open instead if you want the project opened and closed for you.
+func New(b backend.FullBackend) *ModelAPI {
+	api := &ModelAPI{backend: b}
 	api.Pages = &PagesAPI{api: api}
 	api.DomainModels = &DomainModelsAPI{api: api}
 	api.Microflows = &MicroflowsAPI{api: api}
 	api.Enumerations = &EnumerationsAPI{api: api}
 	api.Modules = &ModulesAPI{api: api}
-
 	return api
 }
 
-// Writer returns the underlying writer.
-func (api *ModelAPI) Writer() *mpr.Writer {
-	return api.writer
+// Open opens a Mendix project for reading and writing through the default
+// engine, and returns a ModelAPI over it.
+//
+// The returned ModelAPI owns the connection; call Close when done.
+func Open(path string) (*ModelAPI, error) {
+	b := modelsdkbackend.New()
+	if err := b.Connect(path); err != nil {
+		return nil, err
+	}
+	api := New(b)
+	api.owned = true
+	return api, nil
 }
 
-// Reader returns the underlying reader.
-func (api *ModelAPI) Reader() *mpr.Reader {
-	return api.reader
+// Close releases the project if this ModelAPI opened it, and is a no-op for a
+// backend handed to New.
+func (api *ModelAPI) Close() error {
+	if !api.owned || api.backend == nil {
+		return nil
+	}
+	return api.backend.Disconnect()
 }
 
+// Backend returns the underlying backend, for callers that need an operation
+// the fluent API does not cover.
+func (api *ModelAPI) Backend() backend.FullBackend { return api.backend }
+
 // SetModule sets the current module context.
 // When set, builders will use this module by default.
 func (api *ModelAPI) SetModule(module *model.Module) *ModelAPI {
@@ -90,10 +124,10 @@ func (api *ModelAPI) CurrentModule() *model.Module {
 
 // GetModule retrieves a module by name.
 func (api *ModelAPI) GetModule(name string) (*model.Module, error) {
-	return api.reader.GetModuleByName(name)
+	return api.backend.GetModuleByName(name)
 }
 
 // ListModules returns all modules in the project.
 func (api *ModelAPI) ListModules() ([]*model.Module, error) {
-	return api.reader.ListModules()
+	return api.backend.ListModules()
 }
diff --git a/api/api_integration_test.go b/api/api_integration_test.go
index d878ce7803..365aa73e9a 100644
--- a/api/api_integration_test.go
+++ b/api/api_integration_test.go
@@ -7,15 +7,22 @@ import (
 	"os"
 	"path/filepath"
 	"testing"
-
-	"github.com/mendixlabs/mxcli/sdk/mpr"
 )
 
-// sourceProject is the pristine source project directory.
-const sourceProject = "../mx-test-projects/test-source-app"
+// The fixture these tests run against.
+//
+// They used to point at `../mx-test-projects/test-source-app`, which is not in
+// the repository — so every one of them SKIPPED, on every machine and in CI,
+// and had done since they were written. A suite that has only ever skipped is
+// the #808 failure mode: it reports green and verifies nothing, which is how
+// the whole package went un-exercised while it was ported off sdk/mpr.
+//
+// testdata/expr-checker is committed and is what the codec backend's own tests
+// use (mdl/backend/modelsdk's copyFixture), so these now run everywhere those do.
+const sourceProject = "../testdata/expr-checker"
 
 // sourceProjectMPR is the MPR filename inside the source project.
-const sourceProjectMPR = "test-source.mpr"
+const sourceProjectMPR = "minimal.mpr"
 
 // copyTestProject copies the source project to a temp directory and returns the MPR path.
 func copyTestProject(t *testing.T) string {
@@ -26,7 +33,9 @@ func copyTestProject(t *testing.T) string {
 		t.Fatalf("Failed to resolve source project path: %v", err)
 	}
 	if _, err := os.Stat(srcDir); os.IsNotExist(err) {
-		t.Skipf("Source project not found: %s", srcDir)
+		// Deliberately fatal, not a skip: this fixture is committed, so its
+		// absence is a broken checkout rather than an optional dependency.
+		t.Fatalf("Source project not found: %s", srcDir)
 	}
 
 	destDir := t.TempDir()
@@ -38,11 +47,14 @@ func copyTestProject(t *testing.T) string {
 		t.Fatalf("Failed to copy MPR file: %v", err)
 	}
 
-	// Copy the mprcontents directory tree
+	// Copy the mprcontents directory tree if the fixture is MPR v2. A v1
+	// project is a single file and has none.
 	srcContents := filepath.Join(srcDir, "mprcontents")
-	destContents := filepath.Join(destDir, "mprcontents")
-	if err := copyDir(srcContents, destContents); err != nil {
-		t.Fatalf("Failed to copy mprcontents: %v", err)
+	if _, err := os.Stat(srcContents); err == nil {
+		destContents := filepath.Join(destDir, "mprcontents")
+		if err := copyDir(srcContents, destContents); err != nil {
+			t.Fatalf("Failed to copy mprcontents: %v", err)
+		}
 	}
 
 	return destMPR
@@ -100,32 +112,24 @@ func copyDir(src, dst string) error {
 func TestIntegration_OpenProject(t *testing.T) {
 	projectPath := copyTestProject(t)
 
-	reader, err := mpr.Open(projectPath)
+	a, err := Open(projectPath)
 	if err != nil {
 		t.Fatalf("Failed to open project: %v", err)
 	}
-	defer reader.Close()
+	defer a.Close()
 
-	t.Logf("Opened project: %s (Mendix %s)", reader.Path(), reader.ProjectVersion())
+	t.Logf("Opened project (Mendix %s)", a.Backend().ProjectVersion())
 }
 
 // TestIntegration_ListModules tests listing modules from a real project
 func TestIntegration_ListModules(t *testing.T) {
 	projectPath := copyTestProject(t)
 
-	reader, err := mpr.Open(projectPath)
+	api, err := Open(projectPath)
 	if err != nil {
 		t.Fatalf("Failed to open project: %v", err)
 	}
-	defer reader.Close()
-
-	writer, err := mpr.NewWriter(projectPath)
-	if err != nil {
-		t.Fatalf("Failed to open project for writing: %v", err)
-	}
-	defer writer.Close()
-
-	api := New(writer)
+	defer api.Close()
 
 	modules, err := api.ListModules()
 	if err != nil {
@@ -146,13 +150,11 @@ func TestIntegration_ListModules(t *testing.T) {
 func TestIntegration_GetModule(t *testing.T) {
 	projectPath := copyTestProject(t)
 
-	writer, err := mpr.NewWriter(projectPath)
+	api, err := Open(projectPath)
 	if err != nil {
 		t.Fatalf("Failed to open project: %v", err)
 	}
-	defer writer.Close()
-
-	api := New(writer)
+	defer api.Close()
 
 	// First list modules to find one
 	modules, err := api.ListModules()
@@ -182,13 +184,11 @@ func TestIntegration_GetModule(t *testing.T) {
 func TestIntegration_DomainModels_GetEntity(t *testing.T) {
 	projectPath := copyTestProject(t)
 
-	writer, err := mpr.NewWriter(projectPath)
+	api, err := Open(projectPath)
 	if err != nil {
 		t.Fatalf("Failed to open project: %v", err)
 	}
-	defer writer.Close()
-
-	api := New(writer)
+	defer api.Close()
 
 	// List modules first
 	modules, err := api.ListModules()
@@ -198,7 +198,7 @@ func TestIntegration_DomainModels_GetEntity(t *testing.T) {
 
 	// Find entities in the domain model
 	for _, module := range modules {
-		dm, err := api.Reader().GetDomainModel(module.ID)
+		dm, err := api.Backend().GetDomainModel(module.ID)
 		if err != nil {
 			continue
 		}
@@ -229,16 +229,14 @@ func TestIntegration_DomainModels_GetEntity(t *testing.T) {
 func TestIntegration_Pages_GetPage(t *testing.T) {
 	projectPath := copyTestProject(t)
 
-	writer, err := mpr.NewWriter(projectPath)
+	api, err := Open(projectPath)
 	if err != nil {
 		t.Fatalf("Failed to open project: %v", err)
 	}
-	defer writer.Close()
-
-	api := New(writer)
+	defer api.Close()
 
 	// List all pages
-	pages, err := api.Reader().ListPages()
+	pages, err := api.Backend().ListPages()
 	if err != nil {
 		t.Fatalf("Failed to list pages: %v", err)
 	}
@@ -282,16 +280,14 @@ func TestIntegration_Pages_GetPage(t *testing.T) {
 func TestIntegration_Microflows_GetMicroflow(t *testing.T) {
 	projectPath := copyTestProject(t)
 
-	writer, err := mpr.NewWriter(projectPath)
+	api, err := Open(projectPath)
 	if err != nil {
 		t.Fatalf("Failed to open project: %v", err)
 	}
-	defer writer.Close()
-
-	api := New(writer)
+	defer api.Close()
 
 	// List all microflows
-	microflows, err := api.Reader().ListMicroflows()
+	microflows, err := api.Backend().ListMicroflows()
 	if err != nil {
 		t.Fatalf("Failed to list microflows: %v", err)
 	}
@@ -334,16 +330,14 @@ func TestIntegration_Microflows_GetMicroflow(t *testing.T) {
 func TestIntegration_Enumerations_GetEnumeration(t *testing.T) {
 	projectPath := copyTestProject(t)
 
-	writer, err := mpr.NewWriter(projectPath)
+	api, err := Open(projectPath)
 	if err != nil {
 		t.Fatalf("Failed to open project: %v", err)
 	}
-	defer writer.Close()
-
-	api := New(writer)
+	defer api.Close()
 
 	// List all enumerations
-	enums, err := api.Reader().ListEnumerations()
+	enums, err := api.Backend().ListEnumerations()
 	if err != nil {
 		t.Fatalf("Failed to list enumerations: %v", err)
 	}
@@ -390,13 +384,11 @@ func TestIntegration_Enumerations_GetEnumeration(t *testing.T) {
 func TestIntegration_CreateEntity(t *testing.T) {
 	projectPath := copyTestProject(t)
 
-	writer, err := mpr.NewWriter(projectPath)
+	api, err := Open(projectPath)
 	if err != nil {
-		t.Fatalf("Failed to open temp project: %v", err)
+		t.Fatalf("Failed to open project: %v", err)
 	}
-	defer writer.Close()
-
-	api := New(writer)
+	defer api.Close()
 
 	// Get the first module
 	modules, err := api.ListModules()
@@ -448,13 +440,11 @@ func TestIntegration_CreateEntity(t *testing.T) {
 func TestIntegration_CreateEnumeration(t *testing.T) {
 	projectPath := copyTestProject(t)
 
-	writer, err := mpr.NewWriter(projectPath)
+	api, err := Open(projectPath)
 	if err != nil {
-		t.Fatalf("Failed to open temp project: %v", err)
+		t.Fatalf("Failed to open project: %v", err)
 	}
-	defer writer.Close()
-
-	api := New(writer)
+	defer api.Close()
 
 	modules, err := api.ListModules()
 	if err != nil {
@@ -504,13 +494,11 @@ func TestIntegration_CreateEnumeration(t *testing.T) {
 func TestIntegration_CreateMicroflow(t *testing.T) {
 	projectPath := copyTestProject(t)
 
-	writer, err := mpr.NewWriter(projectPath)
+	api, err := Open(projectPath)
 	if err != nil {
-		t.Fatalf("Failed to open temp project: %v", err)
+		t.Fatalf("Failed to open project: %v", err)
 	}
-	defer writer.Close()
-
-	api := New(writer)
+	defer api.Close()
 
 	modules, err := api.ListModules()
 	if err != nil {
@@ -559,13 +547,11 @@ func TestIntegration_CreateMicroflow(t *testing.T) {
 func TestIntegration_EntityBuilder_WithModule(t *testing.T) {
 	projectPath := copyTestProject(t)
 
-	writer, err := mpr.NewWriter(projectPath)
+	api, err := Open(projectPath)
 	if err != nil {
-		t.Fatalf("Failed to open temp project: %v", err)
+		t.Fatalf("Failed to open project: %v", err)
 	}
-	defer writer.Close()
-
-	api := New(writer)
+	defer api.Close()
 
 	modules, err := api.ListModules()
 	if err != nil {
diff --git a/api/domainmodels.go b/api/domainmodels.go
index 602f280276..32e0b34065 100644
--- a/api/domainmodels.go
+++ b/api/domainmodels.go
@@ -51,13 +51,13 @@ func (dm *DomainModelsAPI) GetEntity(qualifiedName string) (*domainmodel.Entity,
 	qn := ParseQualifiedName(qualifiedName)
 
 	// Get the module
-	module, err := dm.api.reader.GetModuleByName(qn.ModuleName)
+	module, err := dm.api.backend.GetModuleByName(qn.ModuleName)
 	if err != nil {
 		return nil, fmt.Errorf("module not found: %s", qn.ModuleName)
 	}
 
 	// Get the domain model
-	domainModel, err := dm.api.reader.GetDomainModel(module.ID)
+	domainModel, err := dm.api.backend.GetDomainModel(module.ID)
 	if err != nil {
 		return nil, fmt.Errorf("domain model not found for module: %s", qn.ModuleName)
 	}
@@ -77,13 +77,13 @@ func (dm *DomainModelsAPI) GetAssociation(qualifiedName string) (*domainmodel.As
 	qn := ParseQualifiedName(qualifiedName)
 
 	// Get the module
-	module, err := dm.api.reader.GetModuleByName(qn.ModuleName)
+	module, err := dm.api.backend.GetModuleByName(qn.ModuleName)
 	if err != nil {
 		return nil, fmt.Errorf("module not found: %s", qn.ModuleName)
 	}
 
 	// Get the domain model
-	domainModel, err := dm.api.reader.GetDomainModel(module.ID)
+	domainModel, err := dm.api.backend.GetDomainModel(module.ID)
 	if err != nil {
 		return nil, fmt.Errorf("domain model not found for module: %s", qn.ModuleName)
 	}
@@ -123,13 +123,13 @@ func (dm *DomainModelsAPI) ModifyAttribute(attr *domainmodel.Attribute) *Attribu
 // RemoveAttribute removes an attribute from an entity.
 func (dm *DomainModelsAPI) RemoveAttribute(entity *domainmodel.Entity, attrName string) error {
 	// Find the module containing this entity
-	modules, err := dm.api.reader.ListModules()
+	modules, err := dm.api.backend.ListModules()
 	if err != nil {
 		return err
 	}
 
 	for _, module := range modules {
-		domainModel, err := dm.api.reader.GetDomainModel(module.ID)
+		domainModel, err := dm.api.backend.GetDomainModel(module.ID)
 		if err != nil {
 			continue
 		}
@@ -139,7 +139,7 @@ func (dm *DomainModelsAPI) RemoveAttribute(entity *domainmodel.Entity, attrName
 				// Find and remove the attribute
 				for i, attr := range e.Attributes {
 					if attr.Name == attrName {
-						return dm.api.writer.DeleteAttribute(domainModel.ID, entity.ID, attr.ID)
+						return dm.api.backend.DeleteAttribute(domainModel.ID, entity.ID, attr.ID)
 					}
 					_ = i // unused but needed for iteration
 				}
@@ -404,7 +404,7 @@ func (b *EntityBuilder) Build() (*domainmodel.Entity, error) {
 	}
 
 	// Get domain model
-	domainModel, err := b.api.api.reader.GetDomainModel(module.ID)
+	domainModel, err := b.api.api.backend.GetDomainModel(module.ID)
 	if err != nil {
 		return nil, fmt.Errorf("failed to get domain model: %w", err)
 	}
@@ -438,7 +438,7 @@ func (b *EntityBuilder) Build() (*domainmodel.Entity, error) {
 	b.entity.Attributes = b.attributes
 
 	// Create the entity
-	err = b.api.api.writer.CreateEntity(domainModel.ID, b.entity)
+	err = b.api.api.backend.CreateEntity(domainModel.ID, b.entity)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create entity: %w", err)
 	}
@@ -560,7 +560,7 @@ func (b *AssociationBuilder) Build() (*domainmodel.Association, error) {
 	}
 
 	// Get domain model
-	domainModel, err := b.api.api.reader.GetDomainModel(module.ID)
+	domainModel, err := b.api.api.backend.GetDomainModel(module.ID)
 	if err != nil {
 		return nil, fmt.Errorf("failed to get domain model: %w", err)
 	}
@@ -589,7 +589,7 @@ func (b *AssociationBuilder) Build() (*domainmodel.Association, error) {
 	}
 
 	// Create the association
-	err = b.api.api.writer.CreateAssociation(domainModel.ID, b.association)
+	err = b.api.api.backend.CreateAssociation(domainModel.ID, b.association)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create association: %w", err)
 	}
@@ -705,13 +705,13 @@ func (b *AttributeBuilder) Build() (*domainmodel.Attribute, error) {
 	}
 
 	// Find the domain model containing this entity
-	modules, err := b.api.api.reader.ListModules()
+	modules, err := b.api.api.backend.ListModules()
 	if err != nil {
 		return nil, err
 	}
 
 	for _, module := range modules {
-		domainModel, err := b.api.api.reader.GetDomainModel(module.ID)
+		domainModel, err := b.api.api.backend.GetDomainModel(module.ID)
 		if err != nil {
 			continue
 		}
@@ -719,7 +719,7 @@ func (b *AttributeBuilder) Build() (*domainmodel.Attribute, error) {
 		for _, e := range domainModel.Entities {
 			if e.ID == b.entity.ID {
 				// Add the attribute
-				err = b.api.api.writer.AddAttribute(domainModel.ID, b.entity.ID, b.attr)
+				err = b.api.api.backend.AddAttribute(domainModel.ID, b.entity.ID, b.attr)
 				if err != nil {
 					return nil, fmt.Errorf("failed to add attribute: %w", err)
 				}
@@ -754,13 +754,13 @@ func (m *AttributeModifier) Required() *AttributeModifier {
 // Apply saves the modifications.
 func (m *AttributeModifier) Apply() error {
 	// Find the domain model and entity containing this attribute
-	modules, err := m.api.api.reader.ListModules()
+	modules, err := m.api.api.backend.ListModules()
 	if err != nil {
 		return err
 	}
 
 	for _, module := range modules {
-		domainModel, err := m.api.api.reader.GetDomainModel(module.ID)
+		domainModel, err := m.api.api.backend.GetDomainModel(module.ID)
 		if err != nil {
 			continue
 		}
@@ -768,7 +768,7 @@ func (m *AttributeModifier) Apply() error {
 		for _, entity := range domainModel.Entities {
 			for _, attr := range entity.Attributes {
 				if attr.ID == m.attr.ID {
-					return m.api.api.writer.UpdateAttribute(domainModel.ID, entity.ID, m.attr)
+					return m.api.api.backend.UpdateAttribute(domainModel.ID, entity.ID, m.attr)
 				}
 			}
 		}
@@ -819,13 +819,13 @@ func (m *EntityBatchModifier) RemoveAttribute(name string) *EntityBatchModifier
 // Apply executes all batch operations.
 func (m *EntityBatchModifier) Apply() error {
 	// Find the domain model containing this entity
-	modules, err := m.api.api.reader.ListModules()
+	modules, err := m.api.api.backend.ListModules()
 	if err != nil {
 		return err
 	}
 
 	for _, module := range modules {
-		domainModel, err := m.api.api.reader.GetDomainModel(module.ID)
+		domainModel, err := m.api.api.backend.GetDomainModel(module.ID)
 		if err != nil {
 			continue
 		}
@@ -836,14 +836,14 @@ func (m *EntityBatchModifier) Apply() error {
 				for _, op := range m.ops {
 					switch op.opType {
 					case "add":
-						if err := m.api.api.writer.AddAttribute(domainModel.ID, entity.ID, op.attr); err != nil {
+						if err := m.api.api.backend.AddAttribute(domainModel.ID, entity.ID, op.attr); err != nil {
 							return fmt.Errorf("failed to add attribute %s: %w", op.name, err)
 						}
 					case "remove":
 						// Find attribute by name
 						for _, attr := range entity.Attributes {
 							if attr.Name == op.name {
-								if err := m.api.api.writer.DeleteAttribute(domainModel.ID, entity.ID, attr.ID); err != nil {
+								if err := m.api.api.backend.DeleteAttribute(domainModel.ID, entity.ID, attr.ID); err != nil {
 									return fmt.Errorf("failed to remove attribute %s: %w", op.name, err)
 								}
 								break
diff --git a/api/enumerations.go b/api/enumerations.go
index 611a139317..d79fb9fc36 100644
--- a/api/enumerations.go
+++ b/api/enumerations.go
@@ -35,13 +35,13 @@ func (e *EnumerationsAPI) GetEnumeration(qualifiedName string) (*model.Enumerati
 	qn := ParseQualifiedName(qualifiedName)
 
 	// List all enumerations and find by module/name
-	enums, err := e.api.reader.ListEnumerations()
+	enums, err := e.api.backend.ListEnumerations()
 	if err != nil {
 		return nil, err
 	}
 
 	// Get the module to match container ID
-	module, err := e.api.reader.GetModuleByName(qn.ModuleName)
+	module, err := e.api.backend.GetModuleByName(qn.ModuleName)
 	if err != nil {
 		return nil, fmt.Errorf("module not found: %s", qn.ModuleName)
 	}
@@ -77,7 +77,7 @@ func (e *EnumerationsAPI) RemoveValue(enum *model.Enumeration, valueName string)
 			// Remove from slice
 			enum.Values = append(enum.Values[:i], enum.Values[i+1:]...)
 			// Update the enumeration
-			return e.api.writer.UpdateEnumeration(enum)
+			return e.api.backend.UpdateEnumeration(enum)
 		}
 	}
 	return fmt.Errorf("value not found: %s", valueName)
@@ -108,7 +108,7 @@ func (e *EnumerationsAPI) ReorderValues(enum *model.Enumeration, order []string)
 	}
 
 	enum.Values = newValues
-	return e.api.writer.UpdateEnumeration(enum)
+	return e.api.backend.UpdateEnumeration(enum)
 }
 
 // EnumerationBuilder builds a new enumeration with fluent API.
@@ -175,7 +175,7 @@ func (b *EnumerationBuilder) Build() (*model.Enumeration, error) {
 	b.enum.ContainerID = module.ID
 
 	// Create the enumeration
-	err := b.api.api.writer.CreateEnumeration(b.enum)
+	err := b.api.api.backend.CreateEnumeration(b.enum)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create enumeration: %w", err)
 	}
@@ -225,7 +225,7 @@ func (b *EnumValueBuilder) Build() (*model.EnumerationValue, error) {
 	b.enum.Values = append(b.enum.Values, b.value)
 
 	// Update the enumeration
-	err := b.api.api.writer.UpdateEnumeration(b.enum)
+	err := b.api.api.backend.UpdateEnumeration(b.enum)
 	if err != nil {
 		return nil, fmt.Errorf("failed to update enumeration: %w", err)
 	}
@@ -256,5 +256,5 @@ func (m *EnumValueModifier) WithCaption(caption string) *EnumValueModifier {
 
 // Apply saves the modifications.
 func (m *EnumValueModifier) Apply() error {
-	return m.api.api.writer.UpdateEnumeration(m.enum)
+	return m.api.api.backend.UpdateEnumeration(m.enum)
 }
diff --git a/api/helpers.go b/api/helpers.go
index 01c01d7ae7..5195bcbedf 100644
--- a/api/helpers.go
+++ b/api/helpers.go
@@ -5,13 +5,13 @@ package api
 import (
 	"strings"
 
+	"github.com/mendixlabs/mxcli/mdl/types"
 	"github.com/mendixlabs/mxcli/model"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
 )
 
 // generateID creates a new unique ID for a model element.
 func generateID() model.ID {
-	return model.ID(mpr.GenerateID())
+	return model.ID(types.GenerateID())
 }
 
 // QualifiedName represents a fully qualified name (Module.Element).
diff --git a/api/microflows.go b/api/microflows.go
index 1fad3c850a..f5da87feef 100644
--- a/api/microflows.go
+++ b/api/microflows.go
@@ -34,13 +34,13 @@ func (m *MicroflowsAPI) GetMicroflow(qualifiedName string) (*microflows.Microflo
 	qn := ParseQualifiedName(qualifiedName)
 
 	// List all microflows and find by module/name
-	allMicroflows, err := m.api.reader.ListMicroflows()
+	allMicroflows, err := m.api.backend.ListMicroflows()
 	if err != nil {
 		return nil, err
 	}
 
 	// Get the module to match container ID
-	module, err := m.api.reader.GetModuleByName(qn.ModuleName)
+	module, err := m.api.backend.GetModuleByName(qn.ModuleName)
 	if err != nil {
 		return nil, fmt.Errorf("module not found: %s", qn.ModuleName)
 	}
@@ -56,7 +56,7 @@ func (m *MicroflowsAPI) GetMicroflow(qualifiedName string) (*microflows.Microflo
 
 // FindMicroflowsWithEntity finds all microflows that have parameters of a given entity type.
 func (m *MicroflowsAPI) FindMicroflowsWithEntity(entityName string) ([]*microflows.Microflow, error) {
-	allMicroflows, err := m.api.reader.ListMicroflows()
+	allMicroflows, err := m.api.backend.ListMicroflows()
 	if err != nil {
 		return nil, err
 	}
@@ -264,7 +264,7 @@ func (b *MicroflowBuilder) Build() (*microflows.Microflow, error) {
 	}
 
 	// Create the microflow
-	err := b.api.api.writer.CreateMicroflow(b.microflow)
+	err := b.api.api.backend.CreateMicroflow(b.microflow)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create microflow: %w", err)
 	}
diff --git a/api/modules.go b/api/modules.go
index 41724a979f..5338c2c4b8 100644
--- a/api/modules.go
+++ b/api/modules.go
@@ -13,15 +13,15 @@ type ModulesAPI struct {
 
 // List returns all modules in the project.
 func (m *ModulesAPI) List() ([]*model.Module, error) {
-	return m.api.reader.ListModules()
+	return m.api.backend.ListModules()
 }
 
 // Get retrieves a module by name.
 func (m *ModulesAPI) Get(name string) (*model.Module, error) {
-	return m.api.reader.GetModuleByName(name)
+	return m.api.backend.GetModuleByName(name)
 }
 
 // GetByID retrieves a module by ID.
 func (m *ModulesAPI) GetByID(id model.ID) (*model.Module, error) {
-	return m.api.reader.GetModule(id)
+	return m.api.backend.GetModule(id)
 }
diff --git a/api/pages.go b/api/pages.go
index 41a9d540c0..debd162008 100644
--- a/api/pages.go
+++ b/api/pages.go
@@ -34,13 +34,13 @@ func (p *PagesAPI) GetPage(qualifiedName string) (*pages.Page, error) {
 	qn := ParseQualifiedName(qualifiedName)
 
 	// List all pages and find by module/name
-	allPages, err := p.api.reader.ListPages()
+	allPages, err := p.api.backend.ListPages()
 	if err != nil {
 		return nil, err
 	}
 
 	// Get the module to match container ID
-	module, err := p.api.reader.GetModuleByName(qn.ModuleName)
+	module, err := p.api.backend.GetModuleByName(qn.ModuleName)
 	if err != nil {
 		return nil, fmt.Errorf("module not found: %s", qn.ModuleName)
 	}
@@ -59,13 +59,13 @@ func (p *PagesAPI) GetLayout(qualifiedName string) (*pages.Layout, error) {
 	qn := ParseQualifiedName(qualifiedName)
 
 	// List all layouts and find by module/name
-	layouts, err := p.api.reader.ListLayouts()
+	layouts, err := p.api.backend.ListLayouts()
 	if err != nil {
 		return nil, err
 	}
 
 	// Get the module to match container ID
-	module, err := p.api.reader.GetModuleByName(qn.ModuleName)
+	module, err := p.api.backend.GetModuleByName(qn.ModuleName)
 	if err != nil {
 		return nil, fmt.Errorf("module not found: %s", qn.ModuleName)
 	}
@@ -81,7 +81,7 @@ func (p *PagesAPI) GetLayout(qualifiedName string) (*pages.Layout, error) {
 
 // FindPagesWithEntity finds all pages that reference a given entity.
 func (p *PagesAPI) FindPagesWithEntity(entityName string) ([]*pages.Page, error) {
-	allPages, err := p.api.reader.ListPages()
+	allPages, err := p.api.backend.ListPages()
 	if err != nil {
 		return nil, err
 	}
@@ -351,7 +351,7 @@ func (b *PageBuilder) Build() (*pages.Page, error) {
 	}
 
 	// Create the page
-	err := b.api.api.writer.CreatePage(b.page)
+	err := b.api.api.backend.CreatePage(b.page)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create page: %w", err)
 	}
diff --git a/mdl/backend/modelsdk/domainmodel_alter.go b/mdl/backend/modelsdk/domainmodel_alter.go
index 6d7cd8ec5f..d50c75e06d 100644
--- a/mdl/backend/modelsdk/domainmodel_alter.go
+++ b/mdl/backend/modelsdk/domainmodel_alter.go
@@ -399,3 +399,106 @@ func (b *Backend) SetDomainModelAnnotations(domainModelID model.ID, annotations
 	}
 	return b.persistDM(domainModelID, gdm)
 }
+
+// entityIsExternal reports whether a stored entity is an external (OData) one,
+// whose attributes carry mapped remote values rather than plain Mendix types.
+//
+// CreateEntity derives this from the semantic model it is given; here the entity
+// already exists, so it is read back off the stored document. Getting it wrong
+// would write a plain attribute into an external entity, which mxbuild accepts
+// and Studio Pro then shows with an empty remote mapping.
+func entityIsExternal(ent *genDm.Entity) bool {
+	src := ent.Source()
+	if src == nil {
+		return false
+	}
+	return src.TypeName() == "Rest$ODataRemoteEntitySource" ||
+		src.TypeName() == "DatabaseConnector$DatabaseRemoteEntitySource"
+}
+
+// AddAttribute appends an attribute to an existing entity.
+//
+// Implemented for the api/ package, which is its only caller: ALTER ENTITY
+// reaches the same result through the mutator. Until api/ was routed through the
+// backend abstraction this method was on FullBackend with no caller that used a
+// backend value, which is why it sat unimplemented here (see
+// unimplemented_reachability_test.go).
+func (b *Backend) AddAttribute(domainModelID, entityID model.ID, attr *domainmodel.Attribute) error {
+	if b.writer == nil {
+		return fmt.Errorf("AddAttribute: not connected for writing")
+	}
+	if attr == nil {
+		return fmt.Errorf("AddAttribute: nil attribute")
+	}
+	dm, err := b.loadDomainModelGen(domainModelID)
+	if err != nil {
+		return err
+	}
+	ent := findGenEntity(dm, entityID)
+	if ent == nil {
+		return fmt.Errorf("entity not found: %s", entityID)
+	}
+	for _, el := range ent.AttributesItems() {
+		if a, ok := el.(*genDm.Attribute); ok && a.Name() == attr.Name {
+			return fmt.Errorf("attribute %q already exists on entity %s", attr.Name, entityID)
+		}
+	}
+	ent.AddAttributes(attributeToGen(attr, entityIsExternal(ent)))
+	return b.persistDM(domainModelID, dm)
+}
+
+// UpdateAttribute replaces an existing attribute in place.
+//
+// Replaces rather than merges: the caller hands a whole Attribute, so a field it
+// leaves zero is a field it means to clear. Merging would make "set no
+// documentation" indistinguishable from "leave the documentation alone", and the
+// legacy writer this replaces did not merge either.
+//
+// The attribute keeps its stored $ID. Minting a fresh one would make the runtime
+// treat it as a different attribute — see CLAUDE.md on GUIDs and identity — and
+// would churn every reference to it in the same document.
+func (b *Backend) UpdateAttribute(domainModelID, entityID model.ID, attr *domainmodel.Attribute) error {
+	if b.writer == nil {
+		return fmt.Errorf("UpdateAttribute: not connected for writing")
+	}
+	if attr == nil {
+		return fmt.Errorf("UpdateAttribute: nil attribute")
+	}
+	dm, err := b.loadDomainModelGen(domainModelID)
+	if err != nil {
+		return err
+	}
+	ent := findGenEntity(dm, entityID)
+	if ent == nil {
+		return fmt.Errorf("entity not found: %s", entityID)
+	}
+	items := ent.AttributesItems()
+	idx := -1
+	for i, el := range items {
+		if string(el.ID()) == string(attr.ID) {
+			idx = i
+			break
+		}
+	}
+	if idx < 0 {
+		return fmt.Errorf("attribute not found: %s", attr.ID)
+	}
+
+	next := attributeToGen(attr, entityIsExternal(ent))
+	next.SetID(items[idx].ID())
+
+	// The generated list offers only Append and Remove, so an in-place replace
+	// means rebuilding it. Order is worth the rebuild: it is the order Studio
+	// Pro shows the attributes in, and appending instead would move the edited
+	// one to the bottom of every entity anyone touches.
+	replacement := make([]element.Element, len(items))
+	copy(replacement, items)
+	replacement[idx] = next
+	for i := len(items) - 1; i >= 0; i-- {
+		ent.RemoveAttributes(i)
+	}
+	for _, el := range replacement {
+		ent.AddAttributes(el)
+	}
+	return b.persistDM(domainModelID, dm)
+}
diff --git a/mdl/backend/modelsdk/domainmodel_attribute_alter_test.go b/mdl/backend/modelsdk/domainmodel_attribute_alter_test.go
new file mode 100644
index 0000000000..195c9ccd71
--- /dev/null
+++ b/mdl/backend/modelsdk/domainmodel_attribute_alter_test.go
@@ -0,0 +1,229 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+// AddAttribute / UpdateAttribute were the two FullBackend methods the codec
+// engine left to the stub. They were unreachable — and so unimplemented — only
+// because api/ was their sole caller and api/ held a concrete sdk/mpr writer
+// instead of a backend. Routing api/ through the abstraction is what makes them
+// reachable, so they are implemented and pinned here.
+//
+// The properties worth pinning are the ones a rebuild gets wrong by default:
+// the attribute keeps its stored $ID (the runtime keys on identity, see
+// CLAUDE.md), and the list keeps its order (the generated list offers only
+// Append and Remove, so a naive replace moves the edited attribute to the end).
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/model"
+
+	"github.com/mendixlabs/mxcli/sdk/domainmodel"
+)
+
+// entityWithAttributes creates a scratch entity and returns the ids needed to
+// mutate it, so each test starts from a known shape rather than from whatever
+// the fixture happens to carry.
+func entityWithAttributes(t *testing.T, b *Backend, names ...string) (dmID, entID string) {
+	t.Helper()
+	mod, err := b.GetModuleByName("MyFirstModule")
+	if err != nil || mod == nil {
+		t.Fatalf("GetModuleByName: %v", err)
+	}
+	dms, err := b.ListDomainModels()
+	if err != nil {
+		t.Fatalf("ListDomainModels: %v", err)
+	}
+	for _, dm := range dms {
+		if dm.ContainerID == mod.ID {
+			dmID = string(dm.ID)
+			break
+		}
+	}
+	if dmID == "" {
+		t.Fatal("no domain model in MyFirstModule")
+	}
+
+	ent := &domainmodel.Entity{Name: "ZzAttrHost", Persistable: true}
+	for _, n := range names {
+		ent.Attributes = append(ent.Attributes, &domainmodel.Attribute{
+			Name: n, Type: &domainmodel.StringAttributeType{Length: 200},
+		})
+	}
+	if err := b.CreateEntity(model.ID(dmID), ent); err != nil {
+		t.Fatalf("CreateEntity: %v", err)
+	}
+	dm, err := b.GetDomainModel(mod.ID)
+	if err != nil {
+		t.Fatalf("GetDomainModel: %v", err)
+	}
+	for _, e := range dm.Entities {
+		if e.Name == "ZzAttrHost" {
+			return dmID, string(e.ID)
+		}
+	}
+	t.Fatal("created entity not found on read-back")
+	return "", ""
+}
+
+func attrNames(t *testing.T, b *Backend, entID string) []string {
+	t.Helper()
+	mod, _ := b.GetModuleByName("MyFirstModule")
+	dm, err := b.GetDomainModel(mod.ID)
+	if err != nil {
+		t.Fatalf("GetDomainModel: %v", err)
+	}
+	for _, e := range dm.Entities {
+		if string(e.ID) == entID {
+			var out []string
+			for _, a := range e.Attributes {
+				out = append(out, a.Name)
+			}
+			return out
+		}
+	}
+	t.Fatalf("entity %s not found", entID)
+	return nil
+}
+
+func TestAddAttribute_AppendsAndPersists(t *testing.T) {
+	b := New()
+	if err := b.Connect(copyFixture(t)); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	dmID, entID := entityWithAttributes(t, b, "Alpha", "Beta")
+	err := b.AddAttribute(model.ID(dmID), model.ID(entID), &domainmodel.Attribute{
+		Name: "Gamma", Type: &domainmodel.IntegerAttributeType{},
+	})
+	if err != nil {
+		t.Fatalf("AddAttribute: %v", err)
+	}
+	if got, want := attrNames(t, b, entID), []string{"Alpha", "Beta", "Gamma"}; !sameStrings(got, want) {
+		t.Errorf("attributes = %v, want %v", got, want)
+	}
+}
+
+// A duplicate name is refused rather than written. Two attributes of one name is
+// a model Studio Pro cannot show and mxbuild rejects late, so the backend is the
+// cheaper place to say no.
+func TestAddAttribute_RefusesDuplicateName(t *testing.T) {
+	b := New()
+	if err := b.Connect(copyFixture(t)); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	dmID, entID := entityWithAttributes(t, b, "Alpha")
+	err := b.AddAttribute(model.ID(dmID), model.ID(entID), &domainmodel.Attribute{
+		Name: "Alpha", Type: &domainmodel.IntegerAttributeType{},
+	})
+	if err == nil {
+		t.Fatal("adding a second attribute named Alpha was accepted")
+	}
+	if got := attrNames(t, b, entID); len(got) != 1 {
+		t.Errorf("a refused add still changed the entity: %v", got)
+	}
+}
+
+// THE identity property. An attribute's $ID is what the runtime keys on; minting
+// a fresh one on edit makes it a different attribute and churns every reference.
+func TestUpdateAttribute_KeepsStoredID(t *testing.T) {
+	b := New()
+	if err := b.Connect(copyFixture(t)); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	dmID, entID := entityWithAttributes(t, b, "Alpha", "Beta")
+	mod, _ := b.GetModuleByName("MyFirstModule")
+	dm, _ := b.GetDomainModel(mod.ID)
+	var before *domainmodel.Attribute
+	for _, e := range dm.Entities {
+		if string(e.ID) == entID {
+			before = e.Attributes[0]
+		}
+	}
+	if before == nil {
+		t.Fatal("fixture entity has no attributes")
+	}
+
+	edited := *before
+	edited.Type = &domainmodel.IntegerAttributeType{}
+	if err := b.UpdateAttribute(model.ID(dmID), model.ID(entID), &edited); err != nil {
+		t.Fatalf("UpdateAttribute: %v", err)
+	}
+
+	dm2, _ := b.GetDomainModel(mod.ID)
+	for _, e := range dm2.Entities {
+		if string(e.ID) != entID {
+			continue
+		}
+		if string(e.Attributes[0].ID) != string(before.ID) {
+			t.Errorf("attribute $ID changed on update: %s -> %s — the runtime keys on this",
+				before.ID, e.Attributes[0].ID)
+		}
+		if got := e.Attributes[0].Type.GetTypeName(); got != (&domainmodel.IntegerAttributeType{}).GetTypeName() {
+			t.Errorf("the edit did not land: type = %s", got)
+		}
+	}
+}
+
+// The generated list has only Append and Remove, so the implementation rebuilds
+// it. Without that, an edited attribute jumps to the bottom of the entity — a
+// diff on every edit and a reordered entity in Studio Pro.
+func TestUpdateAttribute_PreservesOrder(t *testing.T) {
+	b := New()
+	if err := b.Connect(copyFixture(t)); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	dmID, entID := entityWithAttributes(t, b, "Alpha", "Beta", "Gamma")
+	mod, _ := b.GetModuleByName("MyFirstModule")
+	dm, _ := b.GetDomainModel(mod.ID)
+	var middle *domainmodel.Attribute
+	for _, e := range dm.Entities {
+		if string(e.ID) == entID {
+			middle = e.Attributes[1] // Beta
+		}
+	}
+	edited := *middle
+	edited.Type = &domainmodel.BooleanAttributeType{}
+	if err := b.UpdateAttribute(model.ID(dmID), model.ID(entID), &edited); err != nil {
+		t.Fatalf("UpdateAttribute: %v", err)
+	}
+
+	if got, want := attrNames(t, b, entID), []string{"Alpha", "Beta", "Gamma"}; !sameStrings(got, want) {
+		t.Errorf("attribute order = %v, want %v — the edited one moved", got, want)
+	}
+}
+
+func TestUpdateAttribute_UnknownAttributeIsAnError(t *testing.T) {
+	b := New()
+	if err := b.Connect(copyFixture(t)); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	dmID, entID := entityWithAttributes(t, b, "Alpha")
+	err := b.UpdateAttribute(model.ID(dmID), model.ID(entID), &domainmodel.Attribute{
+		Name: "Nope", Type: &domainmodel.StringAttributeType{Length: 200},
+	})
+	if err == nil {
+		t.Fatal("updating an attribute that does not exist was accepted")
+	}
+}
+
+func sameStrings(a, b []string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
diff --git a/mdl/backend/modelsdk/unimplemented_reachability_test.go b/mdl/backend/modelsdk/unimplemented_reachability_test.go
index b92e67ea6c..fb8be07d81 100644
--- a/mdl/backend/modelsdk/unimplemented_reachability_test.go
+++ b/mdl/backend/modelsdk/unimplemented_reachability_test.go
@@ -10,6 +10,15 @@
 // one method from its interface at a time and rebuilds — grep cannot tell
 // `b.reader.X()` inside the MPR backend from `ctx.Backend.X()` in the executor.
 //
+// Read the reason column as a MAP and it names the places that hold a concrete
+// sdk/mpr reader or writer instead of a backend value — api/, the MCP backend,
+// and the cmd/mxcli commands that do so deliberately. A method is on this list
+// *because* such a caller exists and unreachable *because* that caller does not
+// use a backend. So the list shrinks by closing a bypass, not by deleting
+// interface surface: AddAttribute and UpdateAttribute left it when api/ was
+// routed through the abstraction, which made them reachable and therefore worth
+// implementing. See docs/plans/2026-09-14-retire-legacy-engine.md, Phase 3.
+//
 // This test does not repeat that measurement (a build per method takes minutes).
 // It pins its OUTPUT: the set of methods *Backend leaves to the stub must be
 // exactly the set measured unreachable. A new stub, or a rename that drops an
@@ -35,8 +44,6 @@ import (
 // and cmd/mxcli commands that open a reader directly) — none of which route
 // through this engine.
 var unreachableUnimplemented = map[string]string{
-	"AddAttribute":             "api/ and examples/ call it on the sdk writer; ALTER ENTITY goes through the mutator",
-	"UpdateAttribute":          "same as AddAttribute",
 	"GetDomainModelByID":       "the MPR and MCP backends call it on their own reader",
 	"ExportJSON":               "examples/read_project calls it on the sdk reader",
 	"FindCustomWidgetType":     "cmd/mxcli/cmd_extract_templates.go holds a concrete reader",

From 60bfd359d5524d8f9ab61eef141c7b47067f3cba Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 15 Sep 2026 06:30:08 +0000
Subject: [PATCH 08/24] Point the MCP backend's local reads at the codec
 backend
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MCP opens the project read-only and sends writes to Studio Pro, so it needs
a semantic reader — and it held a concrete *mpr.Reader for one, because the
codec backend did not offer three of the reads it takes: GetDomainModelByID,
GetWorkflow and ListNavigationDocuments. That is the entire reason those three
sat on FullBackend with no caller through a backend value; the reachability
pin names MCP for each.

Implements them in mdl/backend/modelsdk/mcp_bypass_reads.go. Each is a
re-keying or a widening of a read this package already does, so all three share
their conversion (domainModelFromGen, workflowFromGen, navProfileFromGen) with
their siblings — workflowFromGen is extracted from ListWorkflows for this, so a
single-item read cannot drift from the same item in a listing.

Adds Backend.ConnectReadOnly: Connect opens ReadOnly:false and would lock the
file Studio Pro owns, which is the one thing MCP must not do.

Connect had no test — 190 in the package, not one called it — so the swap would
have landed unverified with the suite green. connect_reads_test.go covers it,
with two controls: reverting ConnectReadOnly makes the write-refusal test fail
with the reported symptom, and a companion test shows the same write succeeds
read-write, so the refusal is not incidental. The workflow read seeds a workflow
first; the fixture has none, so looping over the listing would have passed
without calling GetWorkflow at all.

Step 2 of Phase 3 in docs/plans/2026-09-14-retire-legacy-engine.md. Five methods
struck off unreachableUnimplemented across this and the api/ port.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hifgRSawfaRWXS44YKtSJ
---
 .../fix-issue/findings/mdl-backend.jsonl      |   1 +
 mdl/backend/mcp/backend.go                    |  19 +-
 mdl/backend/mcp/connect_reads_test.go         | 248 ++++++++++++++++++
 mdl/backend/modelsdk/backend.go               |  18 ++
 mdl/backend/modelsdk/mcp_bypass_reads.go      | 105 ++++++++
 .../unimplemented_reachability_test.go        |   8 +-
 mdl/backend/modelsdk/workflow_read.go         |  59 +++--
 7 files changed, 423 insertions(+), 35 deletions(-)
 create mode 100644 mdl/backend/mcp/connect_reads_test.go
 create mode 100644 mdl/backend/modelsdk/mcp_bypass_reads.go

diff --git a/.claude/skills/fix-issue/findings/mdl-backend.jsonl b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
index b1e4d2a0a0..18f550f371 100644
--- a/.claude/skills/fix-issue/findings/mdl-backend.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
@@ -96,3 +96,4 @@
 {"area": "mdl/backend", "date": "2026-09-11", "symptom": "`ALTER PAGE REPLACE`/`INSERT` inside a data view bound `datasource: selection <list>` re-scopes the new widget's attribute binding to the OUTER data view's entity (**CE1613** \"The selected attribute 'Mod.Outer.Attr' no longer exists\"), and inside a Gallery/DataGrid 2 sourced by a **microflow/nanoflow** drops it entirely (**CE0402** \"No value specified\", `describe` shows `ContentParams: [{1} = <unbound>]`). `mxcli check --references` and `exec` both report success; `CREATE PAGE` binds the same widget in the same position correctly", "cause": "The mutator resolved a widget's scope in TWO walks that each knew a different subset of the ten Forms$*Source kinds. `Forms$ListenTargetSource` carries no EntityRef at all \u2014 only the listen target's NAME \u2014 so the entity walk saw no source on the selection data view and left the context at the enclosing one. The flow walk (`findNearestDataSourceDoc`) read only a widget's TOP-LEVEL `DataSource` key, so a pluggable list \u2014 whose source sits at `Object.Properties[datasource].Value.DataSource` \u2014 contributed nothing, and its `Objects[].Properties[].Value.Widgets` descent (the one the entity walk gained in #935) was missing too", "file": "`mdl/backend/pagemutator/mutator.go` (`resolveSourceScope`/`resolveSourceScopeVia`, `listenTargetDataSource`, `widgetOwnDataSourceDoc`, `pluggableDataSourceDoc`; `EnclosingEntity`/`EnclosingEntityForChildren`/`EnclosingDataSourceFlow` now share the one walk `findNearestDataSourceDoc`, and `findEnclosingEntityContext` + its two helpers are deleted)", "insight": "**Count the source kinds before fixing one.** `generated/metamodel/types.go`'s `DataSource is implemented by` list closes the set at ten, and they divide exactly three ways \u2014 seven carry an EntityRef, two are flows, one (ListenTarget) borrows the scope of the widget it names \u2014 so one resolver can be complete, where three successive per-kind patches (FINDINGS #55 association+flow, #935 pluggable, this one) each left a hole. **A nearer source that resolves to no entity must SHADOW the outer one**: inheriting is what wrote the wrong entity, and it also mis-scoped a flow-sourced list nested in an entity-bound data view \u2014 a case the report did not name and the old code got wrong. The listen target is found by a shape-independent search for \"a document with this Name that has a data source\", which is what makes it work when the target is a pluggable widget keeping its source three levels inside its Object; a visited-set guards a hand-written listen cycle. **Measurement trap: a CE1613 SUPPRESSES the CE0402s in the same `mx check` run** \u2014 the first reading said mxbuild tolerated the unbound parameter, and the CE0402s only appeared once the re-scoped binding was fixed, so count bindings in `describe`, not errors. The issue's own second repro (a Gallery over a DATABASE source) no longer reproduced \u2014 #935 had fixed it \u2014 and the live defect was its flow-sourced variant, so re-measure a report against main before trusting its class. Tests `mdl/backend/pagemutator/mutator_selection_source_test.go` (7, incl. dangling/cyclic listen targets and the shadowing control); repro `mdl-examples/bug-tests/1076-alter-page-selection-and-flow-scope.mdl` \u2014 2 \u00d7 CE1613 + 3 unbound before, 0 errors after, on mxbuild 11.10.0. Each half proven load-bearing by stubbing it alone and rebuilding the CLI", "refs": ["mendixlabs/mxcli#1076", "#55", "#935"], "ce": ["CE0402", "CE1613"]}
 {"area": "mdl/backend", "date": "2026-09-15", "symptom": "On the default engine, `describe workflow` printed `wait for notification x;` without its boundary events (and their handler flows); the legacy engine described them. A describe -> exec round trip lost them.", "cause": "workflowActivityFromGen's typed switch had no case for *genWf.WaitForNotificationActivity, so it fell to workflowSimpleActivityFromGen, which reads only Name and Caption from raw BSON. That path's comment said the wait activities 'have no genWf struct' — true once, stale by the time gen gained WaitForNotificationActivity with BoundaryEventsItems().", "fix": "Typed case reading boundaryEventsFromGen(a.BoundaryEventsItems()), like the five other activities that carry boundary events.", "file": "mdl/backend/modelsdk/workflow_read.go", "insight": "A fallback path documented as 'for types gen does not model' silently keeps catching a type after gen starts modelling it; the reader then under-reads without any error. When gen is re-vendored, grep the typed switches for types that newly have structs. The bug surfaced only because a probe described what it had just written — reading back your own write, per activity type, is the cheap check."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"AddAttribute and UpdateAttribute were unimplemented on the default engine, so api/ could only work on the retired legacy one — and api/'s whole integration suite reported green while verifying nothing","cause":"api/ imported mdl/backend zero times: it held a concrete *mpr.Writer and bypassed the backend abstraction, so the two methods had no caller through a backend value and were never ported.","file":"api/api.go","fix":"api.New takes a backend.FullBackend (plus an api.Open convenience that owns its connection); the two methods are implemented on the codec backend and struck off unreachableUnimplemented.","insight":"unreachableUnimplemented is a CENSUS OF WHO BYPASSES THE ABSTRACTION, not dead interface surface. Read its reason column as a map and it names api/, the MCP backend, and the cmd/mxcli commands holding a concrete reader; a method is on it BECAUSE such a caller exists and unreachable BECAUSE that caller does not use a backend value. So the list shrinks by closing a bypass, never by deleting methods — and the pin fails loudly when you do, which is how it should be used. Two traps in the port itself. (1) The generated gen list offers only Append and Remove, so replacing an element in place means rebuilding the list; the naive remove-then-add moves the edited attribute to the bottom of the entity, which is a diff on every edit — control: break the rebuild and the order test catches it. (2) THE SUITE THAT WOULD HAVE VERIFIED THE PORT HAD ONLY EVER SKIPPED. api/'s integration tests pointed at ../mx-test-projects/test-source-app, which is not in the repository, so all ten skipped on every machine and in CI since they were written (the #808 shape). `go test ./api/` passing said nothing. Repointed at the committed testdata/expr-checker fixture the codec backend's own tests use, and made a missing fixture FATAL rather than a skip, since a committed fixture's absence is a broken checkout. Before trusting a suite to verify a refactor, check it is not skipping."}
+{"area":"mdl/backend","date":"2026-09-15","symptom":"The MCP backend held a concrete *mpr.Reader for its local reads, keeping three methods (GetDomainModelByID, GetWorkflow, ListNavigationDocuments) on FullBackend with no caller through a backend value — and 190 tests in the package, not one of which called Connect, so swapping the reader underneath it would have landed unverified with the suite green.","cause":"Those three reads had no codec-backend implementation, so MCP could not compose a backend and kept a legacy reader instead. Each was a re-keying or widening of a read the package already did, not new decoding.","file":"mdl/backend/mcp/backend.go","fix":"Implemented the three on the codec backend (mdl/backend/modelsdk/mcp_bypass_reads.go), sharing domainModelFromGen / workflowFromGen / navProfileFromGen with their siblings; added Backend.ConnectReadOnly and pointed MCP's reader field at backend.FullBackend. Wrote mdl/backend/mcp/connect_reads_test.go — the first test to call Connect at all.","insight":"A test can be vacuous in two different ways in one file, and the second is the one you miss. The read-only assertion SKIPPED (MyFirstModule has no entities), which the runner prints — so it was obvious. The GetWorkflow assertion looped over the listing and the fixture has ZERO workflows, so the loop body never ran and the test reported PASS having called nothing. Same failure class as #808, but silent. The fixes differ by shape: for the skip, pick a probe needing nothing pre-existing (CreateEntity, not AddAttribute); for the empty loop, SEED the thing through a read-write backend, then reconnect read-only and assert a specific named item is in the listing BEFORE fetching it — that guard is what converts a future vacuous pass into a failure. Cheapest way to find both: print the counts a test loops over before trusting it. MCP's read-only constraint also has a real control: revert ConnectReadOnly to Connect and the write-refusal test fails with the reported symptom, and the companion TestConnect_TheSameWriteSucceedsReadWrite proves the probe write is not failing for an unrelated reason."}
diff --git a/mdl/backend/mcp/backend.go b/mdl/backend/mcp/backend.go
index a7046bd9fb..6c50cd9298 100644
--- a/mdl/backend/mcp/backend.go
+++ b/mdl/backend/mcp/backend.go
@@ -8,11 +8,11 @@ import (
 	"time"
 
 	"github.com/mendixlabs/mxcli/mdl/backend"
+	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
 	"github.com/mendixlabs/mxcli/mdl/types"
 	"github.com/mendixlabs/mxcli/model"
 	"github.com/mendixlabs/mxcli/sdk/domainmodel"
 	"github.com/mendixlabs/mxcli/sdk/microflows"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
 	"github.com/mendixlabs/mxcli/sdk/pages"
 	"github.com/mendixlabs/mxcli/sdk/workflows"
 )
@@ -41,7 +41,7 @@ type Backend struct {
 	tracer *backend.Tracer
 
 	client *Client
-	reader *mpr.Reader
+	reader backend.FullBackend
 	path   string
 	server ServerInfo
 
@@ -185,19 +185,24 @@ func (b *Backend) WithConcord(cfg ConcordConfig) *Backend {
 // Connect opens the local .mpr read-only (for reads/enumeration) and completes
 // the MCP handshake with Studio Pro (for writes).
 func (b *Backend) Connect(path string) error {
-	r, err := mpr.Open(path) // read-only: never lock the file Studio Pro owns
-	if err != nil {
+	// Read-only: never lock the file Studio Pro owns. This is the codec engine
+	// rather than a concrete sdk/mpr reader — MCP holding one of those was the
+	// reason GetDomainModelByID, GetWorkflow and ListNavigationDocuments sat on
+	// FullBackend with no caller through a backend value. See Phase 3 of
+	// docs/plans/2026-09-14-retire-legacy-engine.md.
+	r := modelsdkbackend.New()
+	if err := r.ConnectReadOnly(path); err != nil {
 		return fmt.Errorf("open local project %q: %w", path, err)
 	}
 	c, err := NewClient(ClientOptions{URL: b.mcpURL, Dial: b.dial})
 	if err != nil {
-		r.Close()
+		_ = r.Disconnect()
 		return err
 	}
 	c.trace = b.tracer
 	si, err := c.Initialize()
 	if err != nil {
-		r.Close()
+		_ = r.Disconnect()
 		return fmt.Errorf("connect to MCP server %q: %w", b.mcpURL, err)
 	}
 	b.reader = r
@@ -256,7 +261,7 @@ func (b *Backend) Disconnect() error {
 		}
 	}
 	if b.reader != nil {
-		err := b.reader.Close()
+		err := b.reader.Disconnect()
 		b.reader = nil
 		b.client = nil
 		b.concord = nil
diff --git a/mdl/backend/mcp/connect_reads_test.go b/mdl/backend/mcp/connect_reads_test.go
new file mode 100644
index 0000000000..95641aec34
--- /dev/null
+++ b/mdl/backend/mcp/connect_reads_test.go
@@ -0,0 +1,248 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package mcp
+
+// Connect had no test at all — 190 tests in this package and not one called it —
+// so the reader swap underneath it (a concrete sdk/mpr reader to a read-only
+// codec backend, Phase 3 of docs/plans/2026-09-14-retire-legacy-engine.md) would
+// have landed unverified with the suite green. That is the same shape as the
+// api/ integration suite that had only ever skipped.
+//
+// These exercise the half of the backend that reads the local .mpr. The write
+// half goes over MCP to Studio Pro and is covered by the fakePED tests around it.
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/domainmodel"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// localProject copies the committed fixture the codec backend's own tests use,
+// so these run everywhere those do.
+func localProject(t *testing.T) string {
+	t.Helper()
+	dst := t.TempDir()
+	if err := os.CopyFS(dst, os.DirFS("../../../testdata/expr-checker")); err != nil {
+		t.Fatalf("copy fixture: %v", err)
+	}
+	return filepath.Join(dst, "minimal.mpr")
+}
+
+// connected returns a Backend wired to a fake Studio Pro and the local fixture.
+func connected(t *testing.T) *Backend {
+	t.Helper()
+	ped := newFakePED(t, func(string, map[string]any) (string, bool) { return "{}", false })
+	b := New(ped.srv.URL+"/mcp", "")
+	if err := b.Connect(localProject(t)); err != nil {
+		t.Fatalf("Connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+	return b
+}
+
+// The reads MCP takes from the local project, through the backend it now
+// composes rather than a reader it owns.
+func TestConnect_LocalReadsWork(t *testing.T) {
+	b := connected(t)
+
+	mods, err := b.ListModules()
+	if err != nil {
+		t.Fatalf("ListModules: %v", err)
+	}
+	if len(mods) == 0 {
+		t.Fatal("ListModules returned nothing — the local project was not read")
+	}
+
+	mod, err := b.GetModuleByName("MyFirstModule")
+	if err != nil || mod == nil {
+		t.Fatalf("GetModuleByName: %v", err)
+	}
+	if _, err := b.GetDomainModel(mod.ID); err != nil {
+		t.Errorf("GetDomainModel: %v", err)
+	}
+	if _, err := b.ListMicroflows(); err != nil {
+		t.Errorf("ListMicroflows: %v", err)
+	}
+	if _, err := b.ListPages(); err != nil {
+		t.Errorf("ListPages: %v", err)
+	}
+}
+
+// The three methods that existed on FullBackend only because MCP called them on
+// its own reader. Each is now served by the composed backend.
+func TestConnect_TheThreeFormerBypassReads(t *testing.T) {
+	b := connected(t)
+
+	mod, err := b.GetModuleByName("MyFirstModule")
+	if err != nil || mod == nil {
+		t.Fatalf("GetModuleByName: %v", err)
+	}
+	dm, err := b.GetDomainModel(mod.ID)
+	if err != nil {
+		t.Fatalf("GetDomainModel: %v", err)
+	}
+
+	// GetDomainModelByID — the same document, keyed by its own id rather than
+	// by its module's.
+	byID, err := b.GetDomainModelByID(dm.ID)
+	if err != nil {
+		t.Fatalf("GetDomainModelByID: %v", err)
+	}
+	if byID.ID != dm.ID {
+		t.Errorf("GetDomainModelByID returned %s, want %s", byID.ID, dm.ID)
+	}
+
+	// ListNavigationDocuments — a project has one, and the list must contain it.
+	navs, err := b.ListNavigationDocuments()
+	if err != nil {
+		t.Fatalf("ListNavigationDocuments: %v", err)
+	}
+	if len(navs) == 0 {
+		t.Error("ListNavigationDocuments returned nothing; the fixture has a navigation document")
+	}
+
+	// GetWorkflow — see TestConnect_GetWorkflowReadsASeededWorkflow. The fixture
+	// carries none, so asserting over the listing here would pass vacuously.
+	if _, err := b.ListWorkflows(); err != nil {
+		t.Errorf("ListWorkflows: %v", err)
+	}
+}
+
+// GetWorkflow against a workflow that actually exists. The committed fixture has
+// zero, so a loop over the listing would have passed without calling the method
+// at all — the same vacuous-green shape as a suite that only ever skips. One is
+// seeded through a read-write backend first, then read back through the
+// read-only one MCP composes.
+func TestConnect_GetWorkflowReadsASeededWorkflow(t *testing.T) {
+	path := localProject(t)
+
+	rw := modelsdkbackend.New()
+	if err := rw.Connect(path); err != nil {
+		t.Fatalf("Connect (read-write): %v", err)
+	}
+	mod, err := rw.GetModuleByName("MyFirstModule")
+	if err != nil || mod == nil {
+		t.Fatalf("GetModuleByName: %v", err)
+	}
+	seeded := &workflows.Workflow{ContainerID: mod.ID, Name: "ZzSeededWorkflow"}
+	if err := rw.CreateWorkflow(seeded); err != nil {
+		t.Fatalf("CreateWorkflow: %v", err)
+	}
+	if err := rw.Disconnect(); err != nil {
+		t.Fatalf("Disconnect (read-write): %v", err)
+	}
+
+	ped := newFakePED(t, func(string, map[string]any) (string, bool) { return "{}", false })
+	b := New(ped.srv.URL+"/mcp", "")
+	if err := b.Connect(path); err != nil {
+		t.Fatalf("Connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	wfs, err := b.ListWorkflows()
+	if err != nil {
+		t.Fatalf("ListWorkflows: %v", err)
+	}
+	var listed *workflows.Workflow
+	for _, w := range wfs {
+		if w.Name == "ZzSeededWorkflow" {
+			listed = w
+		}
+	}
+	if listed == nil {
+		t.Fatalf("the seeded workflow is not in the listing (%d workflows) — the "+
+			"rest of this test would be measuring nothing", len(wfs))
+	}
+
+	got, err := b.GetWorkflow(listed.ID)
+	if err != nil {
+		t.Fatalf("GetWorkflow(%s): %v", listed.ID, err)
+	}
+	if got.Name != listed.Name || got.ID != listed.ID {
+		t.Errorf("GetWorkflow = %s/%q, listing says %s/%q — the two decoders disagree",
+			got.ID, got.Name, listed.ID, listed.Name)
+	}
+
+	// A miss is an error, not (nil, nil): callers branch on the error, and a nil
+	// document reads as "exists but is empty".
+	if _, err := b.GetWorkflow(model.ID("00000000-0000-0000-0000-00000000dead")); err == nil {
+		t.Error("GetWorkflow on an unknown id returned no error")
+	}
+}
+
+// THE constraint the comment in Connect states: MCP must not lock the file
+// Studio Pro owns. The composed backend is connected read-only, so it has no
+// writer and a write through it is refused rather than reaching disk.
+//
+// CreateEntity is the probe because it needs nothing already in the fixture —
+// an attribute-level write would skip on MyFirstModule, which has no entities,
+// and a test that only ever skips proves nothing (#808).
+func TestConnect_LocalBackendIsReadOnly(t *testing.T) {
+	b := connected(t)
+
+	mod, err := b.GetModuleByName("MyFirstModule")
+	if err != nil || mod == nil {
+		t.Fatalf("GetModuleByName: %v", err)
+	}
+	dm, err := b.GetDomainModel(mod.ID)
+	if err != nil {
+		t.Fatalf("GetDomainModel: %v", err)
+	}
+
+	// Reach past the MCP write path to the local backend directly: a write there
+	// must fail, because that backend was opened read-only.
+	err = b.reader.CreateEntity(dm.ID, &domainmodel.Entity{
+		Name: "ZzReadOnlyProbe", Persistable: true,
+	})
+	if err == nil {
+		t.Fatal("a write through the local backend succeeded — it is not read-only, " +
+			"and MCP would be locking the project Studio Pro has open")
+	}
+}
+
+// The control for the test above. Without it, that test passes against a
+// CreateEntity that refuses this entity for some unrelated reason — which is
+// indistinguishable from the read-only guard working.
+func TestConnect_TheSameWriteSucceedsReadWrite(t *testing.T) {
+	rw := modelsdkbackend.New()
+	if err := rw.Connect(localProject(t)); err != nil {
+		t.Fatalf("Connect (read-write): %v", err)
+	}
+	t.Cleanup(func() { _ = rw.Disconnect() })
+
+	mod, err := rw.GetModuleByName("MyFirstModule")
+	if err != nil || mod == nil {
+		t.Fatalf("GetModuleByName: %v", err)
+	}
+	dm, err := rw.GetDomainModel(mod.ID)
+	if err != nil {
+		t.Fatalf("GetDomainModel: %v", err)
+	}
+	if err := rw.CreateEntity(dm.ID, &domainmodel.Entity{
+		Name: "ZzReadOnlyProbe", Persistable: true,
+	}); err != nil {
+		t.Fatalf("the probe write failed read-write too (%v) — the read-only test "+
+			"above is not measuring the read-only guard", err)
+	}
+}
+
+// A second Disconnect must not panic: Connect/Disconnect are driven by the CLI's
+// lifecycle and a double teardown is cheap to get wrong.
+func TestConnect_DisconnectIsIdempotent(t *testing.T) {
+	ped := newFakePED(t, func(string, map[string]any) (string, bool) { return "{}", false })
+	b := New(ped.srv.URL+"/mcp", "")
+	if err := b.Connect(localProject(t)); err != nil {
+		t.Fatalf("Connect: %v", err)
+	}
+	if err := b.Disconnect(); err != nil {
+		t.Fatalf("first Disconnect: %v", err)
+	}
+	if err := b.Disconnect(); err != nil {
+		t.Errorf("second Disconnect: %v", err)
+	}
+}
diff --git a/mdl/backend/modelsdk/backend.go b/mdl/backend/modelsdk/backend.go
index 2bbdc73877..a12d49e6ef 100644
--- a/mdl/backend/modelsdk/backend.go
+++ b/mdl/backend/modelsdk/backend.go
@@ -100,6 +100,24 @@ func (b *Backend) Connect(path string) error {
 	return nil
 }
 
+// ConnectReadOnly opens a project for reading only, leaving the writer nil.
+//
+// For a caller that must not take a lock on a file something else owns — the MCP
+// backend reads the local .mpr while Studio Pro has it open, and sends its writes
+// to Studio Pro rather than to disk. Every write method here already guards on a
+// nil writer, so a write attempted through a read-only backend is refused with
+// "not connected for writing" rather than silently locking the project.
+func (b *Backend) ConnectReadOnly(path string) error {
+	r, err := mmpr.OpenWithOptions(path, mmpr.OpenOptions{ReadOnly: true})
+	if err != nil {
+		return err
+	}
+	b.reader = r
+	b.writer = nil
+	b.path = path
+	return nil
+}
+
 // Disconnect closes the modelsdk reader.
 func (b *Backend) Disconnect() error {
 	if b.reader == nil {
diff --git a/mdl/backend/modelsdk/mcp_bypass_reads.go b/mdl/backend/modelsdk/mcp_bypass_reads.go
new file mode 100644
index 0000000000..4e334e0d51
--- /dev/null
+++ b/mdl/backend/modelsdk/mcp_bypass_reads.go
@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+// The three reads the MCP backend used to take from its own sdk/mpr reader.
+//
+// MCP opens the local project read-only and sends writes to Studio Pro, so it
+// needs a semantic reader — and it held a concrete `*mpr.Reader` for one because
+// the codec backend did not offer these three. That is the whole reason they sat
+// on FullBackend with no caller through a backend value
+// (unimplemented_reachability_test.go names MCP for each). Implementing them is
+// what lets MCP compose this backend instead, which is step 2 of Phase 3 in
+// docs/plans/2026-09-14-retire-legacy-engine.md.
+//
+// Each is a re-keying or a widening of a read this package already does, not new
+// decoding: the conversions (domainModelFromGen, workflowFromGen,
+// navProfileFromGen) are shared with their siblings, so a fix to any of them
+// reaches all callers rather than one.
+
+import (
+	"fmt"
+
+	genDm "github.com/mendixlabs/mxcli/modelsdk/gen/domainmodels"
+	genNav "github.com/mendixlabs/mxcli/modelsdk/gen/navigation"
+	genWf "github.com/mendixlabs/mxcli/modelsdk/gen/workflows"
+	"github.com/mendixlabs/mxcli/modelsdk/mprread"
+
+	"github.com/mendixlabs/mxcli/mdl/types"
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/domainmodel"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// GetDomainModelByID reads a domain model by its own unit id.
+//
+// GetDomainModel keys by MODULE id; this keys by the document's. Both exist
+// because a caller that already holds a domain model's id should not have to
+// find its module first — which is exactly what MCP does.
+//
+// The System module's virtual domain model is deliberately NOT served here,
+// unlike in GetDomainModel: it is injected rather than stored, so it has no unit
+// id to look up and any id that reached this function came from a real document.
+func (b *Backend) GetDomainModelByID(id model.ID) (*domainmodel.DomainModel, error) {
+	units, err := mprread.ListUnitsWithContainer[*genDm.DomainModel](b.reader)
+	if err != nil {
+		return nil, err
+	}
+	for _, u := range units {
+		if model.ID(u.Element.ID()) == id {
+			dm := domainModelFromGen(u.Element, u.ContainerID)
+			b.populateViewEntityOql([]*domainmodel.DomainModel{dm})
+			return dm, nil
+		}
+	}
+	// Match the legacy contract: a miss is an error, not (nil, nil). Callers
+	// branch on the error; a nil document reads as "exists but is empty".
+	return nil, fmt.Errorf("domain model not found: %s", id)
+}
+
+// GetWorkflow reads one workflow by unit id.
+//
+// Shares workflowFromGen with ListWorkflows rather than decoding again, so the
+// two cannot disagree about what a workflow is — the drift that makes a
+// single-item read return something subtly different from the same item in a
+// listing.
+func (b *Backend) GetWorkflow(id model.ID) (*workflows.Workflow, error) {
+	units, err := mprread.ListUnitsWithContainer[*genWf.Workflow](b.reader)
+	if err != nil {
+		return nil, err
+	}
+	for _, u := range units {
+		if model.ID(u.Element.ID()) == id {
+			return workflowFromGen(u.Element, model.ID(u.ContainerID)), nil
+		}
+	}
+	return nil, fmt.Errorf("workflow not found: %s", id)
+}
+
+// ListNavigationDocuments returns every navigation document in the project.
+//
+// A project has exactly one in every version shipped so far, which is why
+// GetNavigation takes units[0] — but the model permits a list, and MCP asks for
+// the list. Returning all of them keeps this honest about the storage rather
+// than about the convention; GetNavigation keeps its first-one shortcut, since
+// changing that is a separate decision with its own callers.
+func (b *Backend) ListNavigationDocuments() ([]*types.NavigationDocument, error) {
+	units, err := mprread.ListUnitsWithContainer[*genNav.NavigationDocument](b.reader)
+	if err != nil {
+		return nil, err
+	}
+	out := make([]*types.NavigationDocument, 0, len(units))
+	for _, u := range units {
+		g := u.Element
+		nav := &types.NavigationDocument{ContainerID: model.ID(u.ContainerID)}
+		nav.ID = model.ID(g.ID())
+		nav.TypeName = "Navigation$NavigationDocument"
+		for _, profEl := range g.ProfilesItems() {
+			if p := navProfileFromGen(profEl); p != nil {
+				nav.Profiles = append(nav.Profiles, p)
+			}
+		}
+		out = append(out, nav)
+	}
+	return out, nil
+}
diff --git a/mdl/backend/modelsdk/unimplemented_reachability_test.go b/mdl/backend/modelsdk/unimplemented_reachability_test.go
index fb8be07d81..a23bc7fe1c 100644
--- a/mdl/backend/modelsdk/unimplemented_reachability_test.go
+++ b/mdl/backend/modelsdk/unimplemented_reachability_test.go
@@ -19,6 +19,11 @@
 // routed through the abstraction, which made them reachable and therefore worth
 // implementing. See docs/plans/2026-09-14-retire-legacy-engine.md, Phase 3.
 //
+// Struck off so far, each by closing the bypass rather than by deleting surface:
+// AddAttribute and UpdateAttribute (api/ routed through the abstraction), then
+// GetDomainModelByID, GetWorkflow and ListNavigationDocuments (the MCP backend
+// composing this one for its reads).
+//
 // This test does not repeat that measurement (a build per method takes minutes).
 // It pins its OUTPUT: the set of methods *Backend leaves to the stub must be
 // exactly the set measured unreachable. A new stub, or a rename that drops an
@@ -44,7 +49,6 @@ import (
 // and cmd/mxcli commands that open a reader directly) — none of which route
 // through this engine.
 var unreachableUnimplemented = map[string]string{
-	"GetDomainModelByID":       "the MPR and MCP backends call it on their own reader",
 	"ExportJSON":               "examples/read_project calls it on the sdk reader",
 	"FindCustomWidgetType":     "cmd/mxcli/cmd_extract_templates.go holds a concrete reader",
 	"FindAllCustomWidgetTypes": "reached only via the reader, inside modelsdk/mpr itself",
@@ -52,8 +56,6 @@ var unreachableUnimplemented = map[string]string{
 	"GetUnitTypes":             "no caller at all outside the MPR delegation",
 	"ListAllUnitIDs":           "cmd/mxcli/diag.go holds a concrete reader; infrastructure_write.go uses b.reader",
 	"ListRawUnits":             "the bson dump/discover/describe commands hold a concrete reader",
-	"ListNavigationDocuments":  "the MCP backend and sdk/mpr call it on their own reader",
-	"GetWorkflow":              "the MCP backend calls it on its own reader",
 	"UpdateLayout":             "ALTER LAYOUT goes through the page mutator, not this method",
 	"SerializeWidget":          "the child serializer is a separate type (codecChildSerializer), not Backend",
 	"SerializeClientAction":    "same as SerializeWidget",
diff --git a/mdl/backend/modelsdk/workflow_read.go b/mdl/backend/modelsdk/workflow_read.go
index b5dd4fb289..45af10db05 100644
--- a/mdl/backend/modelsdk/workflow_read.go
+++ b/mdl/backend/modelsdk/workflow_read.go
@@ -31,35 +31,44 @@ func (b *Backend) ListWorkflows() ([]*workflows.Workflow, error) {
 	}
 	out := make([]*workflows.Workflow, 0, len(units))
 	for _, u := range units {
-		g := u.Element
-		w := &workflows.Workflow{
-			ContainerID:         model.ID(u.ContainerID),
-			Name:                g.Name(),
-			Documentation:       g.Documentation(),
-			ExportLevel:         g.ExportLevel(),
-			Excluded:            g.Excluded(),
-			OverviewPage:        g.OverviewPageQualifiedName(),
-			DueDate:             g.DueDate(),
-			WorkflowName:        workflowTemplateText(g.WorkflowName()),
-			WorkflowDescription: workflowTemplateText(g.WorkflowDescription()),
-		}
-		w.ID = model.ID(g.ID())
-		w.TypeName = "Workflows$Workflow"
-		w.Annotation = annotationText(g.Annotation())
-		if p, ok := g.Parameter().(*genWf.Parameter); ok && p != nil {
-			wp := &workflows.WorkflowParameter{EntityRef: p.EntityQualifiedName()}
-			wp.ID = model.ID(p.ID())
-			w.Parameter = wp
-		}
-		if f, ok := g.Flow().(*genWf.Flow); ok && f != nil {
-			w.Flow = workflowFlowFromGen(f)
-		}
-		w.EventHandlers = workflowEventHandlersFromGen(g.OnWorkflowEventItems())
-		out = append(out, w)
+		out = append(out, workflowFromGen(u.Element, model.ID(u.ContainerID)))
 	}
 	return out, nil
 }
 
+// workflowFromGen converts one gen workflow to the semantic type.
+//
+// Extracted from ListWorkflows so GetWorkflow can share it: a single-item read
+// that decodes separately from the listing is free to drift from it, and that
+// drift shows up as the same workflow looking different depending on which call
+// fetched it.
+func workflowFromGen(g *genWf.Workflow, containerID model.ID) *workflows.Workflow {
+	w := &workflows.Workflow{
+		ContainerID:         containerID,
+		Name:                g.Name(),
+		Documentation:       g.Documentation(),
+		ExportLevel:         g.ExportLevel(),
+		Excluded:            g.Excluded(),
+		OverviewPage:        g.OverviewPageQualifiedName(),
+		DueDate:             g.DueDate(),
+		WorkflowName:        workflowTemplateText(g.WorkflowName()),
+		WorkflowDescription: workflowTemplateText(g.WorkflowDescription()),
+	}
+	w.ID = model.ID(g.ID())
+	w.TypeName = "Workflows$Workflow"
+	w.Annotation = annotationText(g.Annotation())
+	if p, ok := g.Parameter().(*genWf.Parameter); ok && p != nil {
+		wp := &workflows.WorkflowParameter{EntityRef: p.EntityQualifiedName()}
+		wp.ID = model.ID(p.ID())
+		w.Parameter = wp
+	}
+	if f, ok := g.Flow().(*genWf.Flow); ok && f != nil {
+		w.Flow = workflowFlowFromGen(f)
+	}
+	w.EventHandlers = workflowEventHandlersFromGen(g.OnWorkflowEventItems())
+	return w
+}
+
 // workflowEventHandlersFromGen converts a workflow's OnWorkflowEvent handlers.
 func workflowEventHandlersFromGen(items []element.Element) []*workflows.WorkflowEventHandler {
 	var out []*workflows.WorkflowEventHandler

From 5feb4b8e0e8a7d609e4a445e00db59b5308f4b8f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 15 Sep 2026 06:51:13 +0000
Subject: [PATCH 09/24] fix(layout): enforce the placeholder rule mxbuild
 actually applies
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A layout whose placeholder is not named `Main` passed `mxcli check -p
--references` AND `mxcli exec` ("Created layout"), then failed the build
with CE0848 — with no DROP LAYOUT to undo it (mendixlabs/mxcli#1063).

The rule, measured on Mendix 11.12.1 against a layout NO PAGE USES, so
none of it depends on a page binding to the layout:

  placeholder Main               -> 0 errors
  placeholder Main + Content     -> 0 errors  (extra names are fine)
  placeholder Content            -> CE0848 "No placeholder with the name
                                    'Main' found. There should be exactly one."
  placeholder Main + Main        -> CE0849 + CE0495
  placeholder Main + Side + Side -> CE0495 "Duplicate name 'Side'."

So there are two independent halves, and CE0495 shows the second is not
about Main at all: placeholder names must be unique, whatever they are.

The root cause was a documented belief rather than an oversight. CLAUDE.md
said "Which placeholder is 'main' is a naming convention (22 of 22 name one
`Main`; a page binds by qualified name anyway)", the layouts skill said "the
convention is the mechanism", and the write-time guard implemented exactly
that: hasAnyPlaceholder accepted any placeholder under any name. The check
that existed matched the docs, which is why looking for a missing guard would
never have found this — the rationale was what needed verifying.

The rule now lives once, in types.CheckLayoutPlaceholderNames over bare
names, and is applied by both `mxcli check` (MDL081 for the Main rule,
MDL082 for duplicates, in the project-free pass so CI reaches it) and the
writer. Two copies in two currencies is how a resolver drifts.

An error rather than a warning: unlike MDL078 nothing here is a snapshot of
a Mendix asset that a later version might extend, so a flagged layout cannot
build today.

Verified end to end on mxbuild 11.12.1: the reporter's script is now refused
at check time (exit 1) and writes nothing, and `Main` + `Side` builds at 0
errors. Control: stubbing the shared rule to always-OK makes both the
executor and writer tests fail with the reported symptom.

Refs: mendixlabs/mxcli#1063

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017s476QkXr9CFMvKspVzcvu
---
 .../modelsdk/layout_placeholder_guard_test.go |  67 ++++++++
 mdl/backend/modelsdk/layout_write.go          |  76 ++++++---
 mdl/executor/validate_layout_placeholders.go  | 161 ++++++++++++++++++
 .../validate_layout_placeholders_test.go      | 152 +++++++++++++++++
 mdl/executor/validate_program.go              |   6 +
 mdl/types/layout_placeholders.go              |  69 ++++++++
 6 files changed, 509 insertions(+), 22 deletions(-)
 create mode 100644 mdl/backend/modelsdk/layout_placeholder_guard_test.go
 create mode 100644 mdl/executor/validate_layout_placeholders.go
 create mode 100644 mdl/executor/validate_layout_placeholders_test.go
 create mode 100644 mdl/types/layout_placeholders.go

diff --git a/mdl/backend/modelsdk/layout_placeholder_guard_test.go b/mdl/backend/modelsdk/layout_placeholder_guard_test.go
new file mode 100644
index 0000000000..30913f134b
--- /dev/null
+++ b/mdl/backend/modelsdk/layout_placeholder_guard_test.go
@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/sdk/pages"
+)
+
+// The write-time guard used to ask only "is there A placeholder?", under any
+// name — a faithful implementation of mxcli's own docs, which called the name
+// `Main` a convention. mxbuild validates it as a rule (mendixlabs/mxcli#1063),
+// so the guard let through exactly the document that fails CE0848.
+//
+// This asserts on layoutToGen, the single choke point every layout CREATE goes
+// through, so the refusal cannot be bypassed by a caller that skips `mxcli check`.
+func TestLayoutToGen_PlaceholderRule(t *testing.T) {
+	cases := []struct {
+		name    string
+		phs     []string
+		wantErr string
+	}{
+		{name: "exactly one Main builds", phs: []string{"Main"}},
+		{name: "extra names alongside Main are fine", phs: []string{"Main", "Side"}},
+		{name: "no Main", phs: []string{"Content"}, wantErr: "CE0848"},
+		{name: "no placeholder at all", phs: nil, wantErr: "CE0848"},
+		{name: "two Mains", phs: []string{"Main", "Main"}, wantErr: "CE0849"},
+		{name: "duplicate other name", phs: []string{"Main", "Side", "Side"}, wantErr: "CE0495"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := layoutToGen(layoutWith(tc.phs...))
+			if tc.wantErr == "" {
+				if err != nil {
+					t.Fatalf("a layout that builds was refused: %v", err)
+				}
+				return
+			}
+			if err == nil {
+				t.Fatalf("placeholders %v were accepted", tc.phs)
+			}
+			if !strings.Contains(err.Error(), tc.wantErr) {
+				t.Errorf("error %q does not cite %s", err, tc.wantErr)
+			}
+		})
+	}
+}
+
+// layoutWith builds a layout whose placeholders sit inside a scroll container
+// region, the shape a real layout has.
+func layoutWith(names ...string) *pages.Layout {
+	region := &pages.ScrollContainerRegion{Slot: pages.ScrollSlotCenter}
+	for _, n := range names {
+		ph := &pages.LayoutPlaceholder{}
+		ph.Name = n
+		region.Widgets = append(region.Widgets, ph)
+	}
+	sc := &pages.ScrollContainer{Regions: []*pages.ScrollContainerRegion{region}}
+	sc.Name = "layoutContainer"
+	return &pages.Layout{
+		Name:       "App_X",
+		LayoutType: "Responsive",
+		Widgets:    []pages.Widget{sc},
+	}
+}
diff --git a/mdl/backend/modelsdk/layout_write.go b/mdl/backend/modelsdk/layout_write.go
index 90eaf28347..7e42f53d52 100644
--- a/mdl/backend/modelsdk/layout_write.go
+++ b/mdl/backend/modelsdk/layout_write.go
@@ -4,7 +4,9 @@ package modelsdkbackend
 
 import (
 	"fmt"
+	"strings"
 
+	"github.com/mendixlabs/mxcli/mdl/types"
 	"github.com/mendixlabs/mxcli/model"
 	"github.com/mendixlabs/mxcli/modelsdk/codec"
 	"github.com/mendixlabs/mxcli/modelsdk/element"
@@ -67,13 +69,13 @@ func layoutToGen(l *pages.Layout) (*genPg.Layout, error) {
 	// document carries the same ten keys Studio Pro writes.
 	out.SetExcluded(false)
 
-	// A layout with no placeholder can host no page: there is nowhere for the
-	// page's content to go, and the page's Forms$FormCallArgument has nothing to
-	// name. No Atlas layout is shaped that way and no page could use one, so it
-	// is refused rather than written and discovered later.
-	if !hasAnyPlaceholder(l.Widgets) {
-		return nil, fmt.Errorf("layout %q declares no placeholder: a page's content has nowhere to go. "+
-			"Add `placeholder Main` to the region that should hold page content", l.Name)
+	// mxbuild requires EXACTLY ONE placeholder named `Main`, and unique names
+	// besides. This guard used to ask only whether there was A placeholder under
+	// any name — which is what mxcli's docs claimed the rule was — so it wrote
+	// the very document that fails CE0848 (mendixlabs/mxcli#1063). The rule is
+	// shared with `mxcli check` rather than restated, so the two cannot drift.
+	if err := checkLayoutPlaceholders(l); err != nil {
+		return nil, err
 	}
 
 	content, err := layoutContentToGen(l)
@@ -114,31 +116,61 @@ func layoutContentToGen(l *pages.Layout) (element.Element, error) {
 }
 
 // hasAnyPlaceholder walks the tree for a Forms$Placeholder.
-func hasAnyPlaceholder(widgets []pages.Widget) bool {
+// checkLayoutPlaceholders applies the rule mxbuild enforces, citing the CE
+// number the author would otherwise meet a whole build later — and, until
+// DROP LAYOUT existed, with no way to undo the document mxcli had just written.
+func checkLayoutPlaceholders(l *pages.Layout) error {
+	names := layoutPlaceholderNames(l.Widgets, nil)
+	issue, mains, dups := types.CheckLayoutPlaceholderNames(names)
+	switch issue {
+	case types.LayoutPlaceholderNoMain:
+		have := "declares no placeholder at all"
+		if len(names) > 0 {
+			have = fmt.Sprintf("declares only %s", quoteNames(names))
+		}
+		return fmt.Errorf("layout %q %s: mxbuild fails this with CE0848 "+
+			"(\"No placeholder with the name 'Main' found. There should be exactly one.\"). "+
+			"Add `placeholder Main` to the region that should hold page content", l.Name, have)
+	case types.LayoutPlaceholderManyMains:
+		return fmt.Errorf("layout %q declares %d placeholders named %q: mxbuild fails this with "+
+			"CE0849 (\"Multiple placeholders with name 'Main' found. There can be only one.\")",
+			l.Name, mains, types.MainPlaceholderName)
+	case types.LayoutPlaceholderDuplicateName:
+		return fmt.Errorf("layout %q declares more than one placeholder named %s: mxbuild fails "+
+			"this with CE0495 (\"Duplicate name '%s'.\") — a page binds to a placeholder as "+
+			"Module.Layout.<Name>, which cannot pick between two that share it",
+			l.Name, quoteNames(dups), dups[0])
+	}
+	return nil
+}
+
+func quoteNames(names []string) string {
+	q := make([]string, len(names))
+	for i, n := range names {
+		q[i] = fmt.Sprintf("%q", n)
+	}
+	return strings.Join(q, ", ")
+}
+
+// layoutPlaceholderNames collects placeholder names anywhere in the tree, in
+// document order — a real layout nests them inside a scroll container's regions.
+func layoutPlaceholderNames(widgets []pages.Widget, acc []string) []string {
 	for _, w := range widgets {
 		switch x := w.(type) {
 		case *pages.LayoutPlaceholder:
-			return true
+			acc = append(acc, x.Name)
 		case *pages.ScrollContainer:
 			for _, r := range x.Regions {
-				if hasAnyPlaceholder(r.Widgets) {
-					return true
-				}
-			}
-			if hasAnyPlaceholder(x.Widgets) {
-				return true
+				acc = layoutPlaceholderNames(r.Widgets, acc)
 			}
+			acc = layoutPlaceholderNames(x.Widgets, acc)
 		case *pages.Container:
-			if hasAnyPlaceholder(x.Widgets) {
-				return true
-			}
+			acc = layoutPlaceholderNames(x.Widgets, acc)
 		case *pages.GroupBox:
-			if hasAnyPlaceholder(x.Widgets) {
-				return true
-			}
+			acc = layoutPlaceholderNames(x.Widgets, acc)
 		}
 	}
-	return false
+	return acc
 }
 
 func platformWord(native bool) string {
diff --git a/mdl/executor/validate_layout_placeholders.go b/mdl/executor/validate_layout_placeholders.go
new file mode 100644
index 0000000000..fde7b5cff9
--- /dev/null
+++ b/mdl/executor/validate_layout_placeholders.go
@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/mdl/linter"
+	"github.com/mendixlabs/mxcli/mdl/types"
+)
+
+// mainPlaceholderName is the name mxbuild requires exactly one of. It is not a
+// choice mxcli makes — see validateLayoutPlaceholders.
+const mainPlaceholderName = "Main"
+
+// validateLayoutPlaceholders (MDL081, MDL082) enforces the placeholder rule
+// mxbuild applies to every layout.
+//
+// # This is a rule, not a convention
+//
+// mxcli's own docs said otherwise — "Which placeholder is 'main' is a naming
+// convention (22 of 22 name one `Main`; a page binds by qualified name anyway)"
+// — and the write-time guard was written to match that belief: it accepted any
+// placeholder under any name. The belief is wrong. Measured on Mendix 11.12.1,
+// against a layout NO PAGE USES, so none of it depends on a page binding:
+//
+//	placeholder Content            → [error] [CE0848] "No placeholder with the
+//	                                 name 'Main' found. There should be exactly one."
+//	placeholder Main               → 0 errors
+//	placeholder Main + Content     → 0 errors
+//	placeholder Main + Main        → [CE0849] "Multiple placeholders with name
+//	                                 'Main' found. There can be only one."
+//	                                 + [CE0495] "Duplicate name 'Main'."
+//	placeholder Main + Side + Side → [CE0495] "Duplicate name 'Side'."
+//
+// So the rule has two independent halves, and CE0495 shows the second is not
+// about Main at all: placeholder names must be unique, whatever they are.
+//
+// # Why check has to carry it
+//
+// Nothing between the author and mxbuild resolves a placeholder name. The
+// reported script (mendixlabs/mxcli#1063) passed `mxcli check -p --references`
+// AND `mxcli exec`, reported "Created layout", and failed CE0848 a whole build
+// later — with no `DROP LAYOUT` to undo it. The layout is fully described by the
+// statement, so this needs no project and runs in the project-free pass, which
+// is what puts it in CI.
+//
+// # An error, not a warning
+//
+// Unlike MDL078, nothing here is a snapshot of a Mendix asset that a future
+// version might extend: CE0848 and CE0495 are structural and were measured, so
+// a flagged layout cannot build today. `exec` refuses it rather than writing a
+// document whose only remedy is a verb that had to be added alongside this.
+func validateLayoutPlaceholders(stmt ast.Statement) []linter.Violation {
+	layout, ok := stmt.(*ast.CreateLayoutStmt)
+	if !ok {
+		// A page's `placeholder X { … }` FILLS a layout's slot rather than
+		// declaring one, so none of this applies to it.
+		return nil
+	}
+
+	names := layoutPlaceholderNames(layout.Widgets, nil)
+	qn := layout.Name.String()
+	loc := linter.Location{
+		Module:       layout.Name.Module,
+		DocumentType: "layout",
+		DocumentName: layout.Name.Name,
+	}
+
+	issue, mains, dups := types.CheckLayoutPlaceholderNames(names)
+
+	var out []linter.Violation
+
+	// Reported before the Main rule: a braced placeholder is not counted above
+	// (the visitor drops it), so leading with "declares no placeholder named
+	// Main" would contradict a script that plainly says `placeholder Main { }`.
+	if len(layout.BracedPlaceholders) > 0 {
+		out = append(out, linter.Violation{
+			RuleID:   "MDL083",
+			Severity: linter.SeverityError,
+			Location: loc,
+			Message: fmt.Sprintf(
+				"layout '%s' writes %s with a `{ … }` body. In a layout a placeholder is "+
+					"DECLARED and carries nothing; the braced form is the page-side spelling "+
+					"that FILLS one, and it is dropped here — leaving the layout with no "+
+					"placeholder at all",
+				qn, quoteList(layout.BracedPlaceholders)),
+			Suggestion: fmt.Sprintf(
+				"drop the braces: `placeholder %s`. Widgets go in the region around it, "+
+					"not inside it.", layout.BracedPlaceholders[0]),
+		})
+	}
+
+	switch issue {
+	case types.LayoutPlaceholderNoMain:
+		out = append(out, linter.Violation{
+			RuleID:   "MDL081",
+			Severity: linter.SeverityError,
+			Location: loc,
+			Message: fmt.Sprintf(
+				"layout '%s' declares %s, so mxbuild fails it with CE0848 "+
+					"(\"No placeholder with the name 'Main' found. There should be exactly one.\")",
+				qn, describePlaceholders(names)),
+			Suggestion: "name the placeholder that holds page content `placeholder Main`. " +
+				"Extra placeholders under other names are fine — only the Main one is required.",
+		})
+	case types.LayoutPlaceholderManyMains:
+		out = append(out, linter.Violation{
+			RuleID:   "MDL081",
+			Severity: linter.SeverityError,
+			Location: loc,
+			Message: fmt.Sprintf(
+				"layout '%s' declares %d placeholders named 'Main', so mxbuild fails it with CE0849 "+
+					"(\"Multiple placeholders with name 'Main' found. There can be only one.\")",
+				qn, mains),
+			Suggestion: "keep one `placeholder Main` and rename the others — a page binds to " +
+				"each by name as Module.Layout.<Name>, so the names are its API.",
+		})
+	case types.LayoutPlaceholderDuplicateName:
+		out = append(out, linter.Violation{
+			RuleID:   "MDL082",
+			Severity: linter.SeverityError,
+			Location: loc,
+			Message: fmt.Sprintf(
+				"layout '%s' declares more than one placeholder named %s, so mxbuild fails it "+
+					"with CE0495 (\"Duplicate name '%s'.\")",
+				qn, quoteList(dups), dups[0]),
+			Suggestion: "give each placeholder a distinct name: a page binds to one as " +
+				"Module.Layout.<Name>, which cannot pick between two that share it.",
+		})
+	}
+	return out
+}
+
+// layoutPlaceholderNames collects placeholder names anywhere in the tree, in
+// document order. A real layout nests them inside a scroll container's regions,
+// so a walk that stopped at the top level would see none of them.
+func layoutPlaceholderNames(widgets []*ast.WidgetV3, acc []string) []string {
+	for _, w := range widgets {
+		if w == nil {
+			continue
+		}
+		if strings.EqualFold(w.Type, "placeholder") {
+			acc = append(acc, w.Name)
+		}
+		acc = layoutPlaceholderNames(w.Children, acc)
+	}
+	return acc
+}
+
+// describePlaceholders renders what the layout does declare, so the message
+// distinguishes "you named it something else" from "you declared none" — two
+// different mistakes behind the same CE0848.
+func describePlaceholders(names []string) string {
+	if len(names) == 0 {
+		return "no placeholders at all"
+	}
+	return "only " + quoteList(names)
+}
diff --git a/mdl/executor/validate_layout_placeholders_test.go b/mdl/executor/validate_layout_placeholders_test.go
new file mode 100644
index 0000000000..b5c0848132
--- /dev/null
+++ b/mdl/executor/validate_layout_placeholders_test.go
@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+)
+
+// A layout's placeholder structure is a RULE mxbuild validates, not the naming
+// convention mxcli's docs claimed (mendixlabs/mxcli#1063). Measured on 11.12.1
+// against a layout no page uses, so none of this depends on a page binding:
+//
+//	placeholder Content            → CE0848 "No placeholder with the name 'Main'
+//	                                 found. There should be exactly one."
+//	placeholder Main               → 0 errors
+//	placeholder Main + Content     → 0 errors  (extra placeholders are fine)
+//	placeholder Main + Main        → CE0849 + CE0495
+//	placeholder Main + Side + Side → CE0495 "Duplicate name 'Side'."
+//
+// Before this rule, every one of those passed `mxcli check` AND `mxcli exec`,
+// and the author found out a whole build later.
+func TestValidateLayoutPlaceholders(t *testing.T) {
+	cases := []struct {
+		name       string
+		names      []string
+		wantRule   string
+		wantPhrase string
+	}{{
+		name:  "exactly one Main is the shape that builds",
+		names: []string{"Main"},
+	}, {
+		name:  "extra placeholders alongside Main are fine",
+		names: []string{"Main", "Content", "Side"},
+	}, {
+		// The reported case.
+		name:       "no Main at all",
+		names:      []string{"Content"},
+		wantRule:   "MDL081",
+		wantPhrase: "CE0848",
+	}, {
+		name:       "two Mains",
+		names:      []string{"Main", "Main"},
+		wantRule:   "MDL081",
+		wantPhrase: "CE0849",
+	}, {
+		// Uniqueness is general, not Main-specific — CE0495 fires on any repeat.
+		name:       "duplicate non-Main name",
+		names:      []string{"Main", "Side", "Side"},
+		wantRule:   "MDL082",
+		wantPhrase: "Side",
+	}}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := validateLayoutPlaceholders(layoutWithPlaceholders(tc.names...))
+			if tc.wantRule == "" {
+				if len(got) != 0 {
+					t.Fatalf("a layout that builds was flagged: %+v", got)
+				}
+				return
+			}
+			if len(got) == 0 {
+				t.Fatalf("names %v produced no violation", tc.names)
+			}
+			if got[0].RuleID != tc.wantRule {
+				t.Errorf("RuleID = %q, want %q", got[0].RuleID, tc.wantRule)
+			}
+			if !strings.Contains(got[0].Message, tc.wantPhrase) {
+				t.Errorf("message %q does not mention %q", got[0].Message, tc.wantPhrase)
+			}
+			// The message has to name the layout, because a script that creates
+			// several is the normal case and mxbuild's own error names it.
+			if !strings.Contains(got[0].Message, "Mod.App_X") {
+				t.Errorf("message %q does not name the layout", got[0].Message)
+			}
+		})
+	}
+}
+
+// A layout with NO placeholder at all was already refused, but only at write
+// time. It must now be reported by check, with the same rule as a missing Main —
+// it IS a missing Main.
+func TestValidateLayoutPlaceholders_NoneAtAll(t *testing.T) {
+	got := validateLayoutPlaceholders(layoutWithPlaceholders())
+	if len(got) == 0 || got[0].RuleID != "MDL081" {
+		t.Fatalf("a layout with no placeholder was not flagged as MDL081: %+v", got)
+	}
+}
+
+// CONTROL: the rule must not fire on a PAGE. A page's `placeholder X { … }`
+// blocks FILL a layout's slots — they do not declare them, and a page naming one
+// `Content` is correct and common.
+func TestValidateLayoutPlaceholders_IgnoresPages(t *testing.T) {
+	page := &ast.CreatePageStmtV3{
+		Name:         ast.QualifiedName{Module: "Mod", Name: "P"},
+		Placeholders: []*ast.PagePlaceholderV3{{Name: "Content"}},
+	}
+	if got := validateLayoutPlaceholders(page); len(got) != 0 {
+		t.Errorf("a page was flagged by a layout rule: %+v", got)
+	}
+}
+
+// layoutWithPlaceholders builds a layout whose placeholders sit one region deep,
+// which is where a real layout puts them — the walk must not stop at the top
+// level of the body.
+func layoutWithPlaceholders(names ...string) *ast.CreateLayoutStmt {
+	region := &ast.WidgetV3{Type: "region", Name: "center"}
+	for _, n := range names {
+		region.Children = append(region.Children, &ast.WidgetV3{Type: "placeholder", Name: n})
+	}
+	return &ast.CreateLayoutStmt{
+		Name: ast.QualifiedName{Module: "Mod", Name: "App_X"},
+		Widgets: []*ast.WidgetV3{{
+			Type:     "scrollcontainer",
+			Name:     "layoutContainer",
+			Children: []*ast.WidgetV3{region},
+		}},
+	}
+}
+
+// A layout DECLARES a placeholder with a bare `placeholder Main`; the braced
+// form `placeholder Main { … }` is the PAGE-side spelling, which fills a slot
+// rather than declaring one. The visitor drops the braced form from a layout's
+// widget tree, so the reported script (mendixlabs/mxcli#1063) passed check,
+// reached exec, created the module, and only then failed with "declares no
+// placeholder" — a message that contradicts what the author had written.
+//
+// Reaching for page syntax here is the obvious mistake: every other widget in a
+// layout takes a body, and `alter page` uses the braced form for real.
+func TestValidateLayoutPlaceholders_BracedFormIsRejected(t *testing.T) {
+	stmt := layoutWithPlaceholders("Main")
+	stmt.BracedPlaceholders = []string{"Main"}
+
+	got := validateLayoutPlaceholders(stmt)
+	if len(got) == 0 {
+		t.Fatal("a braced placeholder in a layout was accepted")
+	}
+	if got[0].RuleID != "MDL083" {
+		t.Errorf("RuleID = %q, want MDL083", got[0].RuleID)
+	}
+	if !strings.Contains(got[0].Message, "Main") {
+		t.Errorf("message %q does not name the placeholder", got[0].Message)
+	}
+	// The remedy is the whole point: the author wrote something that looks
+	// right, so the message has to show the form that works.
+	if !strings.Contains(got[0].Suggestion, "placeholder Main") {
+		t.Errorf("suggestion %q does not show the bodiless form", got[0].Suggestion)
+	}
+}
diff --git a/mdl/executor/validate_program.go b/mdl/executor/validate_program.go
index 5cd7346d5d..05da7e2f9f 100644
--- a/mdl/executor/validate_program.go
+++ b/mdl/executor/validate_program.go
@@ -57,6 +57,12 @@ func ValidateProgram(prog *ast.Program, projectPath string) []linter.Violation {
 		// menu items, which share one AST node so they cannot diverge.
 		violations = append(violations, validateMenuItemIcons(stmt)...)
 		violations = append(violations, validateGlyphCodes(stmt)...)
+		// A layout must declare exactly one placeholder named `Main`, with unique
+		// names (MDL081/MDL082). mxbuild validates this — CE0848/CE0849/CE0495 —
+		// and nothing before it resolves a placeholder name, so the reported
+		// script passed check AND exec and failed a build later
+		// (mendixlabs/mxcli#1063).
+		violations = append(violations, validateLayoutPlaceholders(stmt)...)
 		// A page with parameters and a Url must name each parameter in it (CE5601).
 		if pageStmt, ok := stmt.(*ast.CreatePageStmtV3); ok {
 			violations = append(violations, ValidatePageURLParameters(pageStmt)...)
diff --git a/mdl/types/layout_placeholders.go b/mdl/types/layout_placeholders.go
new file mode 100644
index 0000000000..e7e2d0bfab
--- /dev/null
+++ b/mdl/types/layout_placeholders.go
@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package types
+
+import "sort"
+
+// MainPlaceholderName is the name mxbuild requires exactly one of on every
+// layout. It is not a convention mxcli picked — see LayoutPlaceholderProblem.
+const MainPlaceholderName = "Main"
+
+// LayoutPlaceholderIssue identifies which half of the placeholder rule a layout
+// breaks. The two are independent: a layout can satisfy the Main rule and still
+// repeat another name.
+type LayoutPlaceholderIssue int
+
+const (
+	// LayoutPlaceholdersOK means the names build.
+	LayoutPlaceholdersOK LayoutPlaceholderIssue = iota
+	// LayoutPlaceholderNoMain → CE0848.
+	LayoutPlaceholderNoMain
+	// LayoutPlaceholderManyMains → CE0849 (and CE0495).
+	LayoutPlaceholderManyMains
+	// LayoutPlaceholderDuplicateName → CE0495, on a name other than Main.
+	LayoutPlaceholderDuplicateName
+)
+
+// CheckLayoutPlaceholderNames applies the rule mxbuild enforces on every layout,
+// measured on Mendix 11.12.1 against a layout NO PAGE USES — so none of it
+// depends on a page binding to the layout:
+//
+//	"Content"                 → CE0848 "No placeholder with the name 'Main'
+//	                            found. There should be exactly one."
+//	"Main"                    → 0 errors
+//	"Main", "Content"         → 0 errors — extra placeholders are fine
+//	"Main", "Main"            → CE0849 + CE0495
+//	"Main", "Side", "Side"    → CE0495 "Duplicate name 'Side'."
+//
+// It lives here, on the bare names, because two callers in different currencies
+// have to agree: `mxcli check` reads the names off the AST, and the writer reads
+// them off the semantic model. Two copies of a three-line rule is how a resolver
+// drifts — the same mistake that let three icon vocabularies disagree in
+// mendixlabs/mxcli#1059.
+//
+// mains is how many are named Main; dups lists the repeated names, sorted.
+func CheckLayoutPlaceholderNames(names []string) (issue LayoutPlaceholderIssue, mains int, dups []string) {
+	seen := map[string]int{}
+	for _, n := range names {
+		seen[n]++
+		if n == MainPlaceholderName {
+			mains++
+		}
+	}
+	for n, c := range seen {
+		if c > 1 {
+			dups = append(dups, n)
+		}
+	}
+	sort.Strings(dups)
+
+	switch {
+	case mains == 0:
+		return LayoutPlaceholderNoMain, mains, dups
+	case mains > 1:
+		return LayoutPlaceholderManyMains, mains, dups
+	case len(dups) > 0:
+		return LayoutPlaceholderDuplicateName, mains, dups
+	}
+	return LayoutPlaceholdersOK, mains, dups
+}

From ba2c8459d43ab9d049539471ed71856df4b08607 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 15 Sep 2026 06:51:26 +0000
Subject: [PATCH 10/24] fix(layout): report a braced placeholder instead of
 dropping it silently
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`placeholder Main { }` inside a CREATE LAYOUT passed `mxcli check`, then
failed at exec with `layout "X" declares no placeholder` — a message that
flatly contradicts a script which plainly says `placeholder Main`. The
failed exec had already created the module (mendixlabs/mxcli#1063).

One grammar rule serves two opposite jobs, told apart by shape rather than
by context: `if c.LBRACE() == nil` makes a bodiless placeholder a
DECLARATION widget, while the braced form is routed to
buildPagePlaceholdersV3 — the page-side job of FILLING a layout's slot. In
a layout there is no such job, so the braced form was dropped on the floor
and the layout ended up with zero placeholders.

When one parse rule is disambiguated by shape, the wrong shape has no error
path by construction: it silently means the other thing. Reaching for the
braced form here is also the natural mistake, since every other layout
element takes a body and `alter page` uses it for real. DESCRIBE emits the
bodiless form, so round-tripping never produces this and no test covered it.

The Builder now carries `inLayout`, saved and restored around the layout
body build because the same body builder serves pages, and collects the
dropped names into CreateLayoutStmt.BracedPlaceholders for MDL083 to report
at check time. The braced form is still dropped — recording it is a
diagnostic, not a decision to start honouring it.

Verified: the reported script is refused at check time and no longer creates
the module on the way to failing. Controls: a page's braced placeholder must
still fill its slot, and a layout's bodiless form must still produce a real
widget.

Refs: mendixlabs/mxcli#1063

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017s476QkXr9CFMvKspVzcvu
---
 mdl/ast/ast_page_v3.go                        |  9 ++
 mdl/visitor/visitor.go                        | 10 +++
 .../visitor_layout_placeholder_test.go        | 90 +++++++++++++++++++
 mdl/visitor/visitor_page_v3.go                | 16 ++++
 4 files changed, 125 insertions(+)
 create mode 100644 mdl/visitor/visitor_layout_placeholder_test.go

diff --git a/mdl/ast/ast_page_v3.go b/mdl/ast/ast_page_v3.go
index 39cde3ce6a..650c832c79 100644
--- a/mdl/ast/ast_page_v3.go
+++ b/mdl/ast/ast_page_v3.go
@@ -93,6 +93,15 @@ type CreateLayoutStmt struct {
 	DocumentationSet bool // see mendixlabs/mxcli#1018: absent preserves, empty clears
 	IsReplace        bool
 	IsModify         bool
+
+	// BracedPlaceholders names the `placeholder X { … }` blocks written inside
+	// this layout. A layout DECLARES a placeholder with the bodiless form; the
+	// braced form is the page-side spelling that FILLS one, and the visitor
+	// drops it from the widget tree. Recording the names here is what lets the
+	// checker say so, instead of the write failing later with "declares no
+	// placeholder" — which contradicts what the author wrote
+	// (mendixlabs/mxcli#1063).
+	BracedPlaceholders []string
 }
 
 func (s *CreateLayoutStmt) isStatement() {}
diff --git a/mdl/visitor/visitor.go b/mdl/visitor/visitor.go
index dd07a7c78a..f20b39c753 100644
--- a/mdl/visitor/visitor.go
+++ b/mdl/visitor/visitor.go
@@ -467,6 +467,16 @@ type Builder struct {
 	// documentAnnotations collects every `@name` written before a CREATE, with
 	// the kind of document it was on — see ExitCreateStatement.
 	documentAnnotations []ast.DocumentAnnotation
+
+	// inLayout is set while a CREATE LAYOUT body is being built. The page body
+	// builder serves both documents and cannot otherwise tell which it is in,
+	// and a `placeholder X { … }` means opposite things in the two: in a page it
+	// FILLS a layout's slot, in a layout it is a mistake for the bodiless
+	// declaration. See buildLayoutV3 (mendixlabs/mxcli#1063).
+	inLayout bool
+	// layoutBracedPlaceholders collects the braced placeholder names seen while
+	// inLayout, at any depth, for the checker to report.
+	layoutBracedPlaceholders []string
 }
 
 // NewBuilder creates a new AST builder.
diff --git a/mdl/visitor/visitor_layout_placeholder_test.go b/mdl/visitor/visitor_layout_placeholder_test.go
new file mode 100644
index 0000000000..6763ee7263
--- /dev/null
+++ b/mdl/visitor/visitor_layout_placeholder_test.go
@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package visitor
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+)
+
+// A layout's `placeholder X { … }` is dropped from the widget tree — it is the
+// page-side spelling. Recording the names is what lets `mxcli check` explain
+// that, instead of the write failing later with a message that contradicts the
+// script (mendixlabs/mxcli#1063).
+func TestBuildLayoutV3_RecordsBracedPlaceholders(t *testing.T) {
+	src := `create layout Mod.App_X (layouttype: 'Responsive') {
+  scrollcontainer layoutContainer { region center { placeholder Main { } } }
+}`
+	l := buildOneLayout(t, src)
+	if len(l.BracedPlaceholders) != 1 || l.BracedPlaceholders[0] != "Main" {
+		t.Fatalf("BracedPlaceholders = %v, want [Main]", l.BracedPlaceholders)
+	}
+	// It must STILL be absent from the widget tree: recording it is a diagnostic,
+	// not a decision to start honouring the braced form.
+	if n := countPlaceholders(l.Widgets); n != 0 {
+		t.Errorf("a braced placeholder became %d real placeholder widget(s)", n)
+	}
+}
+
+// CONTROL: the bodiless form is the one that works, and must be untouched —
+// no recording, and a real placeholder widget in the tree.
+func TestBuildLayoutV3_BodilessFormIsUnaffected(t *testing.T) {
+	src := `create layout Mod.App_X (layouttype: 'Responsive') {
+  scrollcontainer layoutContainer { region center { placeholder Main } }
+}`
+	l := buildOneLayout(t, src)
+	if len(l.BracedPlaceholders) != 0 {
+		t.Errorf("a bodiless placeholder was recorded as braced: %v", l.BracedPlaceholders)
+	}
+	if n := countPlaceholders(l.Widgets); n != 1 {
+		t.Errorf("got %d placeholder widgets, want 1", n)
+	}
+}
+
+// CONTROL: a PAGE's braced placeholder fills a layout slot and is correct. The
+// layout-only recording must not reach it — pages are built by the same body
+// function, which is why this is worth pinning.
+func TestBuildPageV3_BracedPlaceholderStillFillsASlot(t *testing.T) {
+	src := `create page Mod.P (Title: 'T') {
+  placeholder Content { textbox tb (Caption: 'x') }
+}`
+	prog, errs := Build(src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	page, ok := prog.Statements[0].(*ast.CreatePageStmtV3)
+	if !ok {
+		t.Fatalf("got %T, want *ast.CreatePageStmtV3", prog.Statements[0])
+	}
+	if len(page.Placeholders) != 1 || page.Placeholders[0].Name != "Content" {
+		t.Fatalf("page placeholders = %+v, want one named Content", page.Placeholders)
+	}
+	if len(page.Placeholders[0].Widgets) != 1 {
+		t.Errorf("the placeholder's widgets were dropped: %+v", page.Placeholders[0])
+	}
+}
+
+func buildOneLayout(t *testing.T, src string) *ast.CreateLayoutStmt {
+	t.Helper()
+	prog, errs := Build(src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	l, ok := prog.Statements[0].(*ast.CreateLayoutStmt)
+	if !ok {
+		t.Fatalf("got %T, want *ast.CreateLayoutStmt", prog.Statements[0])
+	}
+	return l
+}
+
+func countPlaceholders(ws []*ast.WidgetV3) int {
+	n := 0
+	for _, w := range ws {
+		if w.Type == "placeholder" {
+			n++
+		}
+		n += countPlaceholders(w.Children)
+	}
+	return n
+}
diff --git a/mdl/visitor/visitor_page_v3.go b/mdl/visitor/visitor_page_v3.go
index cb22afcaca..34eb94f906 100644
--- a/mdl/visitor/visitor_page_v3.go
+++ b/mdl/visitor/visitor_page_v3.go
@@ -385,6 +385,15 @@ func buildPageBodyV3(ctx parser.IPageBodyV3Context, b *Builder) []*ast.WidgetV3
 					Name:       placeholderBlockName(c),
 					Properties: map[string]any{},
 				})
+			} else if b != nil && b.inLayout {
+				// Still dropped — the braced form declares nothing. But in a
+				// LAYOUT it is a mistake rather than the page-side job, so the
+				// name is recorded for the checker to report against. Without
+				// this the layout silently ends up with no placeholder and the
+				// write fails with a message that contradicts the script
+				// (mendixlabs/mxcli#1063).
+				b.layoutBracedPlaceholders = append(b.layoutBracedPlaceholders,
+					placeholderBlockName(c))
 			}
 		}
 	}
@@ -1855,7 +1864,14 @@ func (b *Builder) buildLayoutV3(ctx *parser.CreateLayoutStatementContext) *ast.C
 		stmt.Properties = holder.Properties
 	}
 	if bodyCtx := ctx.PageBodyV3(); bodyCtx != nil {
+		// Saved and restored rather than just set: the flag steers the shared
+		// page-body builder, and leaving it on would make the next page in the
+		// script report its own (correct) placeholder blocks as layout mistakes.
+		prevIn, prevBraced := b.inLayout, b.layoutBracedPlaceholders
+		b.inLayout, b.layoutBracedPlaceholders = true, nil
 		stmt.Widgets = buildPageBodyV3(bodyCtx, b)
+		stmt.BracedPlaceholders = b.layoutBracedPlaceholders
+		b.inLayout, b.layoutBracedPlaceholders = prevIn, prevBraced
 	}
 	return stmt
 }

From 284fa6b1a01ed7a4388f6eba2d517d193d09a169 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 15 Sep 2026 06:51:39 +0000
Subject: [PATCH 11/24] feat(layout): add DROP LAYOUT
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Layouts were the only document mxcli could create and alter but not delete
(mendixlabs/mxcli#1063). Every other doctype has a DROP — pages, snippets,
microflows, entities, queues, rules, folders — and the gap bit hardest on a
layout mxcli itself had just written badly: the reported script created a
layout that fails the build, and there was no headless way to remove it.

This is wiring, not new capability. DeleteLayout already existed and worked
on both engines, and is exercised on every CREATE OR REPLACE LAYOUT, whose
replace half is a delete followed by a create. Only the grammar alternative,
AST node, visitor branch and executor were missing.

Pages still bound to the layout are named in a warning and the drop
proceeds, rather than being refused. Three reasons, in order of weight:
no other DROP in mxcli refuses on dependents; drop-then-recreate under the
same name is how a layout is corrected, with the pages rebinding by
qualified name (verified end to end — back to 0 errors); and the order of
statements in a script is the author's business.

The warning is load-bearing because of what the pages then do. Measured on
11.12.1, dropping a layout one page was bound to:

  [error] [CE1613] "The selected layout 'MyFirstModule.App_Mine' no longer
                    exists." at Page 'MyFirstModule.Home_Web'
  [error] [CE1613] "The selected placeholder 'MyFirstModule.App_Mine.Main'
                    no longer exists." at Content for placeholder 'Main'

Both name the page end and never the layout that was removed, so an
unwarned drop surfaces a build later attributed to a document the author did
not touch. The warning names the pages and gives the `alter pages … where
layout =` repoint.

Control: a page bound to a different layout must not appear in the warning,
an unused layout must produce none at all, and removing the warning makes
the test fail with a bare "Dropped layout" line.

Refs: mendixlabs/mxcli#1063

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017s476QkXr9CFMvKspVzcvu
---
 mdl/ast/ast_page.go                   |  11 +++
 mdl/executor/cmd_layouts_drop.go      | 113 ++++++++++++++++++++++
 mdl/executor/cmd_layouts_drop_test.go | 133 ++++++++++++++++++++++++++
 mdl/executor/register_stubs.go        |   3 +
 mdl/executor/registry_test.go         |   1 +
 mdl/executor/stmt_summary.go          |   2 +
 mdl/executor/validate_duplicates.go   |   2 +
 mdl/grammar/MDLParser.g4              |   1 +
 mdl/visitor/visitor_entity.go         |   4 +
 9 files changed, 270 insertions(+)
 create mode 100644 mdl/executor/cmd_layouts_drop.go
 create mode 100644 mdl/executor/cmd_layouts_drop_test.go

diff --git a/mdl/ast/ast_page.go b/mdl/ast/ast_page.go
index e54e27d308..13a82abde4 100644
--- a/mdl/ast/ast_page.go
+++ b/mdl/ast/ast_page.go
@@ -42,6 +42,17 @@ type DropPageStmt struct {
 
 func (s *DropPageStmt) isStatement() {}
 
+// DropLayoutStmt represents: DROP LAYOUT Module.Name
+//
+// Layouts were the only document mxcli could create and alter but not delete, so
+// a layout written by mistake — the CE0848 shape in mendixlabs/mxcli#1063 was
+// exactly that — had no headless remedy at all.
+type DropLayoutStmt struct {
+	Name QualifiedName
+}
+
+func (s *DropLayoutStmt) isStatement() {}
+
 // DropSnippetStmt represents: DROP SNIPPET Module.Name
 type DropSnippetStmt struct {
 	Name QualifiedName
diff --git a/mdl/executor/cmd_layouts_drop.go b/mdl/executor/cmd_layouts_drop.go
new file mode 100644
index 0000000000..49d02fd81c
--- /dev/null
+++ b/mdl/executor/cmd_layouts_drop.go
@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// Package executor - DROP LAYOUT command
+package executor
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	mdlerrors "github.com/mendixlabs/mxcli/mdl/errors"
+)
+
+// execDropLayout handles DROP LAYOUT statements.
+//
+// Layouts were the only document mxcli could create and alter but not delete
+// (mendixlabs/mxcli#1063): every other doctype — pages, snippets, microflows,
+// entities, queues, rules, folders — has a DROP. The backend could already do
+// it (DeleteLayout is what CREATE OR REPLACE LAYOUT uses for the replace half),
+// so only the verb was missing, and its absence was worst exactly when it was
+// needed: a layout written by mistake failed the build and could not be removed
+// headlessly.
+//
+// # Pages that still use it are WARNED about, not refused
+//
+// This follows what the rest of mxcli's DROPs do — none of them refuse on
+// dependents — and matches how a layout is normally replaced: drop, then create
+// the corrected one under the same name, with the pages still bound by qualified
+// name and rebinding to the new document. Refusing would break that, and the
+// order in a script is the author's business.
+//
+// The warning matters because of what the pages then do. Measured on 11.12.1,
+// dropping a layout one page was bound to:
+//
+//	[error] [CE1613] "The selected layout 'MyFirstModule.App_Mine' no longer
+//	                  exists." at Page 'MyFirstModule.Home_Web'
+//	[error] [CE1613] "The selected placeholder 'MyFirstModule.App_Mine.Main' no
+//	                  longer exists." at Content for placeholder 'Main'
+//
+// Both name the PAGE end, never the layout that was removed — so without this
+// warning the drop is silent and its consequence surfaces a build later,
+// attributed to a document the author did not touch.
+func execDropLayout(ctx *ExecContext, s *ast.DropLayoutStmt) error {
+	if !ctx.ConnectedForWrite() {
+		return mdlerrors.NewNotConnectedWrite()
+	}
+
+	layouts, err := ctx.Backend.ListLayouts()
+	if err != nil {
+		return mdlerrors.NewBackend("list layouts", err)
+	}
+
+	for _, l := range layouts {
+		modID := getModuleID(ctx, l.ContainerID)
+		if getModuleName(ctx, modID) != s.Name.Module || l.Name != s.Name.Name {
+			continue
+		}
+
+		// Collected BEFORE the delete: afterwards the layout is gone and the
+		// pages' references resolve to nothing, so there would be no way to
+		// name them.
+		if users := pagesUsingLayout(ctx, s.Name.String()); len(users) > 0 {
+			fmt.Fprintf(ctx.Output,
+				"Warning: %d page(s) still use layout %s and will fail to build (CE1613) "+
+					"until they are repointed: %s\n",
+				len(users), s.Name.String(), joinUpTo(users, 10))
+			fmt.Fprintf(ctx.Output,
+				"  Repoint them with `alter pages set layout = <Module.Layout> where layout = %s`, "+
+					"or re-create %s.\n", s.Name.String(), s.Name.String())
+		}
+
+		if err := ctx.Backend.DeleteLayout(l.ID); err != nil {
+			return mdlerrors.NewBackend("delete layout", err)
+		}
+		invalidateHierarchy(ctx)
+		fmt.Fprintf(ctx.Output, "Dropped layout %s\n", s.Name.String())
+		return nil
+	}
+
+	return mdlerrors.NewNotFound("layout", s.Name.String())
+}
+
+// pagesUsingLayout returns the qualified names of pages bound to the layout,
+// sorted. A page that cannot be read is skipped rather than guessed at: the
+// warning exists to be trusted, and naming a page that is not affected is worse
+// than the silence this replaces.
+func pagesUsingLayout(ctx *ExecContext, layoutQN string) []string {
+	allPages, err := ctx.Backend.ListPages()
+	if err != nil {
+		return nil
+	}
+	var out []string
+	for _, p := range allPages {
+		name, err := ctx.Backend.PageLayoutName(p.ID)
+		if err != nil || name != layoutQN {
+			continue
+		}
+		modName := getModuleName(ctx, getModuleID(ctx, p.ContainerID))
+		out = append(out, modName+"."+p.Name)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// joinUpTo keeps the warning readable when a layout is used by the whole app —
+// repointing is a bulk operation, so the full list is noise past the first few.
+func joinUpTo(names []string, max int) string {
+	if len(names) <= max {
+		return strings.Join(names, ", ")
+	}
+	return fmt.Sprintf("%s and %d more", strings.Join(names[:max], ", "), len(names)-max)
+}
diff --git a/mdl/executor/cmd_layouts_drop_test.go b/mdl/executor/cmd_layouts_drop_test.go
new file mode 100644
index 0000000000..f4e1be9e6b
--- /dev/null
+++ b/mdl/executor/cmd_layouts_drop_test.go
@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/mdl/backend/mock"
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/pages"
+)
+
+// Layouts were the only document mxcli could create and alter but not delete
+// (mendixlabs/mxcli#1063), which bit hardest when a layout mxcli had just
+// written turned out not to build.
+func TestExecDropLayout(t *testing.T) {
+	ctx, mb, deleted := dropLayoutCtx(t, nil)
+	err := execDropLayout(ctx, &ast.DropLayoutStmt{
+		Name: ast.QualifiedName{Module: "MyModule", Name: "App_Mine"},
+	})
+	if err != nil {
+		t.Fatalf("execDropLayout: %v", err)
+	}
+	if *deleted != model.ID("lay-1") {
+		t.Errorf("deleted %q, want lay-1", *deleted)
+	}
+	if out := ctx.Output.(*strings.Builder).String(); !strings.Contains(out, "Dropped layout MyModule.App_Mine") {
+		t.Errorf("output %q does not confirm the drop", out)
+	}
+	_ = mb
+}
+
+// Pages still bound to the layout are WARNED about, not refused — mxcli's other
+// DROPs do not refuse on dependents either, and drop-then-recreate under the
+// same name is how a layout is corrected (verified end to end on 11.12.1: the
+// pages go back to 0 errors). But the consequence of leaving it dropped is
+// CE1613 on the PAGE, which names no layout at all, so the drop must not be
+// silent.
+func TestExecDropLayout_WarnsAboutPagesStillUsingIt(t *testing.T) {
+	ctx, _, _ := dropLayoutCtx(t, map[model.ID]string{
+		model.ID("pg-1"): "MyModule.App_Mine",
+		model.ID("pg-2"): "MyModule.App_Mine",
+		model.ID("pg-3"): "Atlas_Core.Atlas_Default", // on another layout: must not appear
+	})
+	if err := execDropLayout(ctx, &ast.DropLayoutStmt{
+		Name: ast.QualifiedName{Module: "MyModule", Name: "App_Mine"},
+	}); err != nil {
+		t.Fatalf("execDropLayout: %v", err)
+	}
+
+	out := ctx.Output.(*strings.Builder).String()
+	if !strings.Contains(out, "Warning:") || !strings.Contains(out, "CE1613") {
+		t.Errorf("output %q does not warn about the pages", out)
+	}
+	for _, want := range []string{"2 page(s)", "MyModule.Home", "MyModule.Detail"} {
+		if !strings.Contains(out, want) {
+			t.Errorf("output %q does not mention %q", out, want)
+		}
+	}
+	// A page on a DIFFERENT layout is unaffected and naming it would make the
+	// warning untrustworthy.
+	if strings.Contains(out, "MyModule.Other") {
+		t.Errorf("output %q names a page bound to another layout", out)
+	}
+	// It is still a drop, not a refusal.
+	if !strings.Contains(out, "Dropped layout") {
+		t.Errorf("output %q refused the drop instead of warning", out)
+	}
+}
+
+// CONTROL: no dependents, no warning — otherwise the warning is noise that gets
+// ignored on the run where it matters.
+func TestExecDropLayout_QuietWhenNothingUsesIt(t *testing.T) {
+	ctx, _, _ := dropLayoutCtx(t, nil)
+	if err := execDropLayout(ctx, &ast.DropLayoutStmt{
+		Name: ast.QualifiedName{Module: "MyModule", Name: "App_Mine"},
+	}); err != nil {
+		t.Fatalf("execDropLayout: %v", err)
+	}
+	if out := ctx.Output.(*strings.Builder).String(); strings.Contains(out, "Warning:") {
+		t.Errorf("an unused layout produced a warning: %q", out)
+	}
+}
+
+func TestExecDropLayout_UnknownLayout(t *testing.T) {
+	ctx, _, _ := dropLayoutCtx(t, nil)
+	err := execDropLayout(ctx, &ast.DropLayoutStmt{
+		Name: ast.QualifiedName{Module: "MyModule", Name: "NoSuch"},
+	})
+	if err == nil || !strings.Contains(err.Error(), "NoSuch") {
+		t.Fatalf("err = %v, want a not-found naming the layout", err)
+	}
+}
+
+// dropLayoutCtx wires a project with one layout (MyModule.App_Mine) and three
+// pages, each bound to whatever pageLayouts says.
+func dropLayoutCtx(t *testing.T, pageLayouts map[model.ID]string) (*ExecContext, *mock.MockBackend, *model.ID) {
+	t.Helper()
+	mod := &model.Module{
+		BaseElement: model.BaseElement{ID: model.ID("mod-own")},
+		Name:        "MyModule",
+	}
+	lay := &pages.Layout{Name: "App_Mine"}
+	lay.ID = model.ID("lay-1")
+	lay.ContainerID = mod.ID
+
+	mkPage := func(id, name string) *pages.Page {
+		p := &pages.Page{Name: name}
+		p.ID = model.ID(id)
+		p.ContainerID = mod.ID
+		return p
+	}
+	allPages := []*pages.Page{
+		mkPage("pg-1", "Home"), mkPage("pg-2", "Detail"), mkPage("pg-3", "Other"),
+	}
+
+	var deleted model.ID
+	mb := &mock.MockBackend{
+		IsConnectedFunc: func() bool { return true },
+		ListModulesFunc: func() ([]*model.Module, error) { return []*model.Module{mod}, nil },
+		ListLayoutsFunc: func() ([]*pages.Layout, error) { return []*pages.Layout{lay}, nil },
+		ListPagesFunc:   func() ([]*pages.Page, error) { return allPages, nil },
+		PageLayoutNameFunc: func(id model.ID) (string, error) {
+			return pageLayouts[id], nil
+		},
+		DeleteLayoutFunc: func(id model.ID) error { deleted = id; return nil },
+	}
+	ctx, _ := newMockCtx(t, withBackend(mb), withHierarchy(mkHierarchy(mod)))
+	ctx.Output = &strings.Builder{}
+	return ctx, mb, &deleted
+}
diff --git a/mdl/executor/register_stubs.go b/mdl/executor/register_stubs.go
index c68378a8de..8180c48475 100644
--- a/mdl/executor/register_stubs.go
+++ b/mdl/executor/register_stubs.go
@@ -118,6 +118,9 @@ func registerPageHandlers(r *Registry) {
 	r.Register(&ast.CreateSnippetStmtV3{}, func(ctx *ExecContext, stmt ast.Statement) error {
 		return execCreateSnippetV3(ctx, stmt.(*ast.CreateSnippetStmtV3))
 	})
+	r.Register(&ast.DropLayoutStmt{}, func(ctx *ExecContext, stmt ast.Statement) error {
+		return execDropLayout(ctx, stmt.(*ast.DropLayoutStmt))
+	})
 	r.Register(&ast.CreateLayoutStmt{}, func(ctx *ExecContext, stmt ast.Statement) error {
 		return execCreateLayout(ctx, stmt.(*ast.CreateLayoutStmt))
 	})
diff --git a/mdl/executor/registry_test.go b/mdl/executor/registry_test.go
index 98d0cabeb3..f420785df0 100644
--- a/mdl/executor/registry_test.go
+++ b/mdl/executor/registry_test.go
@@ -265,6 +265,7 @@ func allKnownStatements() []ast.Statement {
 		&ast.DropODataClientStmt{},
 		&ast.DropODataServiceStmt{},
 		&ast.DropPageStmt{},
+		&ast.DropLayoutStmt{},
 		&ast.DropPublishedRestServiceStmt{},
 		&ast.DropQueueStmt{},
 		&ast.DropRegularExpressionStmt{},
diff --git a/mdl/executor/stmt_summary.go b/mdl/executor/stmt_summary.go
index a5a3892500..362f916039 100644
--- a/mdl/executor/stmt_summary.go
+++ b/mdl/executor/stmt_summary.go
@@ -75,6 +75,8 @@ func stmtSummary(stmt ast.Statement) string {
 		return fmt.Sprintf("create snippet %s", s.Name)
 	case *ast.CreateLayoutStmt:
 		return fmt.Sprintf("create layout %s", s.Name)
+	case *ast.DropLayoutStmt:
+		return fmt.Sprintf("drop layout %s", s.Name)
 	case *ast.DropSnippetStmt:
 		return fmt.Sprintf("drop snippet %s", s.Name)
 
diff --git a/mdl/executor/validate_duplicates.go b/mdl/executor/validate_duplicates.go
index 05c09ccac7..77c77ead21 100644
--- a/mdl/executor/validate_duplicates.go
+++ b/mdl/executor/validate_duplicates.go
@@ -177,6 +177,8 @@ func stmtDropInfo(stmt ast.Statement) (docType, name string) {
 		return "rule", s.Name.String()
 	case *ast.DropPageStmt:
 		return "page", s.Name.String()
+	case *ast.DropLayoutStmt:
+		return "layout", s.Name.String()
 	case *ast.DropSnippetStmt:
 		return "snippet", s.Name.String()
 	case *ast.DropJavaActionStmt:
diff --git a/mdl/grammar/MDLParser.g4 b/mdl/grammar/MDLParser.g4
index ac1d861121..7d4caa818d 100644
--- a/mdl/grammar/MDLParser.g4
+++ b/mdl/grammar/MDLParser.g4
@@ -429,6 +429,7 @@ dropStatement
     | DROP NANOFLOW qualifiedName
     | DROP RULE qualifiedName
     | DROP PAGE qualifiedName
+    | DROP LAYOUT qualifiedName
     | DROP SNIPPET qualifiedName
     | DROP MENU_KW qualifiedName
     | DROP MODULE qualifiedName
diff --git a/mdl/visitor/visitor_entity.go b/mdl/visitor/visitor_entity.go
index 96aa7d5cb7..1b1858e257 100644
--- a/mdl/visitor/visitor_entity.go
+++ b/mdl/visitor/visitor_entity.go
@@ -860,6 +860,10 @@ func (b *Builder) ExitDropStatement(ctx *parser.DropStatementContext) {
 		b.statements = append(b.statements, &ast.DropPageStmt{
 			Name: buildQualifiedName(names[0]),
 		})
+	} else if ctx.LAYOUT() != nil {
+		b.statements = append(b.statements, &ast.DropLayoutStmt{
+			Name: buildQualifiedName(names[0]),
+		})
 	} else if ctx.SNIPPET() != nil {
 		b.statements = append(b.statements, &ast.DropSnippetStmt{
 			Name: buildQualifiedName(names[0]),

From 884a2bfae06562549c0ad2896cee94022bcb8924 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 15 Sep 2026 06:51:48 +0000
Subject: [PATCH 12/24] docs(layout): correct the claim that `Main` is a naming
 convention
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CLAUDE.md said "Which placeholder is 'main' is a naming convention (22 of 22
name one `Main`; a page binds by qualified name anyway)" and the layouts
skill said "the convention is the mechanism". mxbuild validates it as a rule,
measured on 11.12.1 against a layout no page uses: CE0848 with no Main,
CE0849 with two, CE0495 on any repeated name.

That sentence is why the write-time guard accepted any placeholder under any
name, so correcting it is part of the fix rather than housekeeping — the code
matched the docs exactly, and the docs were wrong.

Also documents DROP LAYOUT and the declared-vs-filled placeholder
distinction (MDL083) across the same set: CHANGELOG, the layouts skill,
MDL_QUICK_REFERENCE, `mxcli syntax` (new layout.drop topic), a bug-test
example, and three findings records.

Refs: mendixlabs/mxcli#1063

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017s476QkXr9CFMvKspVzcvu
---
 .../fix-issue/findings/mdl-executor.jsonl     |  2 +
 .../fix-issue/findings/mdl-visitor.jsonl      |  1 +
 .claude/skills/mendix/write-layouts/SKILL.md  | 49 ++++++++++++++--
 CHANGELOG.md                                  | 14 +++++
 CLAUDE.md                                     |  2 +-
 cmd/mxcli/syntax/features_page.go             | 36 ++++++++++--
 docs/01-project/MDL_QUICK_REFERENCE.md        |  2 +
 .../1063-layout-placeholder-rules.mdl         | 58 +++++++++++++++++++
 8 files changed, 153 insertions(+), 11 deletions(-)
 create mode 100644 mdl-examples/bug-tests/1063-layout-placeholder-rules.mdl

diff --git a/.claude/skills/fix-issue/findings/mdl-executor.jsonl b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
index aa9de8b26f..29cfe45e2a 100644
--- a/.claude/skills/fix-issue/findings/mdl-executor.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
@@ -618,3 +618,5 @@
 {"area": "mdl/executor", "date": "2026-09-14", "symptom": "A workflow user task whose task page takes the context entity instead of System.WorkflowUserTask (CE7412), takes no parameters (CE7410), or whose targeting microflow does not take exactly System.Workflow plus the context entity (CE6677) passed `mxcli check` AND `check --references`, was written by exec, and failed only under the native mx check. Reported in a team briefing on building workflows from MDL as two of the reasons 'a green CLI check is not evidence for workflows'.", "cause": "validateWorkflowReferences resolved the user task's page and targeting microflow by NAME only — it reported a document that does not exist, never one that exists with the wrong signature. Neither signature was in `mxcli syntax workflow` either, so authors had nothing to copy.", "fix": "validate_workflow_task_signature.go checks both signatures from the script's own definitions first (scriptContext now records page parameter entities and entity generalizations, beside flowParams) and then the project, for CREATE WORKFLOW (incl. nested and multi-user tasks) and ALTER WORKFLOW (inserted tasks, SET ACTIVITY PAGE / TARGETING MICROFLOW, context entity read off the stored workflow). Wired into validateWorkflowStatementRefs / validateAlterWorkflowRefs. check --references reports before anything is written; exec calls the same function at the workflow statement, so the workflow is never written but earlier statements in the script already are. Gated on Mendix 11, where it is measured.", "file": "mdl/executor/validate_workflow_task_signature.go", "insight": "Measure the CLEAN edges before writing a refusal — three of the nine rows would have been false refusals from a plausible reading of the error text: a task page MAY take extra parameters besides WorkflowUserTask, a targeting microflow MAY take its two parameters in either order, and its context parameter MAY be a generalization of the context entity (but not a specialization). Since exec refuses on a check error, a false refusal is a blocker. Where the inheritance chain leaves what can be resolved (a script entity extending something unknown), return 'not proven' rather than a mismatch. Also a harness caveat worth keeping: the control run that stubbed the version gate first reported 0 failures because the harness only counted `--- FAIL` lines containing '/', i.e. subtests; the gate test is top-level. A silent control is a claim about the harness before it is a claim about the test. And run `make test-integration` before pushing a reference-path rule: the unit suite gates the rule on a mock project with no version, so it never fired there, while the integration round-trip tests exec against a real 11.x project — and their shared helper created task pages with no parameters and targeting microflows with none, which CI refused. Those fixtures had never been built; the rule was right, they were repaired."}
 {"area": "mdl/executor", "date": "2026-09-14", "symptom": "An `exec` / `check --references` error on a CREATE WORKFLOW statement ends with 'hint: M.W is defined later in this script — move its create statement before this one', naming the failing workflow itself (or a workflow already created earlier in the script).", "cause": "annotateForwardRef draws candidate names from scriptContext.allNames (which includes workflows) and excludes the statement's own name and already-created names via scriptContext.has — which checked modules, entities, enumerations, microflows, nanoflows, pages, snippets and code actions but NOT workflows. A parallel list that drifted from the one it filters.", "fix": "scriptContext.has also answers for sc.workflows.", "file": "mdl/executor/validate.go", "insight": "Two lists over the same kinds (allNames and has) with nothing tying them together — the same drift shape as collectDefinitions/collectSingle. The misfire only became visible once an error routinely named its own workflow, i.e. a new rule surfaced a latent bug in how every rule's message is decorated. When adding a document kind to scriptContext, check every method that enumerates kinds, not just the collector."}
 {"area": "mdl/executor", "date": "2026-09-14", "symptom": "On the **legacy** engine (MXCLI_ENGINE=legacy), `create or modify workflow` that does not restate stored event handlers / boundary events / nested Ends / AI agent tasks / completion rules is written (\"Created workflow\") and deletes them, while the default modelsdk engine refuses the same statement with the guard-don't-drop list", "cause": "The workflow rewrite guards walk `ctx.Backend.GetRawUnit` with type switches on `map[string]any` / `[]any`. The legacy backend decodes with mongo-driver v1 `bson.Unmarshal` into map[string]any, which yields nested documents as map[string]any but ARRAYS AS `primitive.A` — a named type a `case []any` does not match. So every guard saw no list at all (measured with a probe: `OnWorkflowEvent primitive.A`, `Flow map[string]interface {}`). The modelsdk reader normalizes to plain slices (`modelsdk/mpr/reader_raw.go normalizeBSONValue`), which is why only legacy was blind", "file": "`mdl/executor/validate_workflow_rewrite.go` (`plainRawUnit`, applied in `checkNoDroppedWorkflowConstructs` and `validateAlterReplaceKeepsStudioProState`)", "insight": "A guard tested only with hand-built `[]any` fixtures proves nothing about the legacy engine: build the fixture, then `bson.Marshal` + `bson.Unmarshal` into map[string]any to get the shape legacy's GetRawUnit really returns (`legacyShaped` in validate_workflow_rewrite_legacy_test.go). Normalized in the guard, not in MprBackend.GetRawUnit, because catalog (`builder_regularexpressions.go`) asserts `bson.A` on raw units. Found only by running the e2e rewrite on BOTH engines — the modelsdk run was green. Other `[]any`-only raw walkers (REST body guard, queued-call guard) are suspects of the same class. Control: normalizer returning its input fails the legacy-shape tests"}
+{"area": "mdl/executor", "date": "2026-09-15", "symptom": "A layout created by mxcli whose placeholder is named anything but `Main` passes `mxcli check -p --references` AND `mxcli exec` (\"Created layout\"), then fails `mx check` with [CE0848] \"No placeholder with the name 'Main' found. There should be exactly one.\" \u2014 and there is no DROP LAYOUT to undo it", "cause": "The write-time guard (`hasAnyPlaceholder`, mdl/backend/modelsdk/layout_write.go) asked only whether SOME placeholder existed, under any name. That was a faithful implementation of mxcli's own documented belief: CLAUDE.md and the layouts skill both said the name was a naming convention (\"22 of 22 Atlas layouts follow it\"). mxbuild validates it as a rule. Nothing between the author and the builder resolves a placeholder name, so check had no rule to apply either.", "fix": "Rule measured first, then written once: mdl/types/layout_placeholders.go `CheckLayoutPlaceholderNames`, applied by BOTH mdl/executor/validate_layout_placeholders.go (MDL081/MDL082, project-free pass) and the writer guard. Docs corrected in the same commit.", "insight": "The bug was a DOCUMENTED BELIEF, not an oversight \u2014 which is why grepping the code for a missing check would never have found it: the check that existed matched the docs exactly. When a guard looks deliberate and cites a rationale, verify the RATIONALE against the tool, not the guard against the rationale. One 10-minute measurement (create the layout, run mx check) overturned a sentence that had been carried in CLAUDE.md through several features. Measure against a layout NO PAGE USES, or you cannot tell a layout rule from a page-binding rule \u2014 here it errors unconditionally, which is what makes it checkable with no project.", "controls": "Five shapes on mxbuild 11.12.1: Main\u21920; Main+Content\u21920 (so extra names are fine, and a rule demanding all-Main would have been wrong); Content\u2192CE0848; Main+Main\u2192CE0849+CE0495; Main+Side+Side\u2192CE0495 (so uniqueness is general, a second independent half of the rule).", "refs": "mendixlabs/mxcli#1063", "file": "mdl/types/layout_placeholders.go, mdl/executor/validate_layout_placeholders.go, mdl/backend/modelsdk/layout_write.go"}
+{"area": "mdl/executor", "date": "2026-09-15", "symptom": "`DROP LAYOUT Mod.Name` is a parse error. Layouts are the only doctype mxcli can create and alter but not delete, so a layout authored wrongly \u2014 including one mxcli itself just wrote \u2014 cannot be removed headlessly.", "cause": "Pure wiring gap. `DeleteLayout` existed and worked on BOTH engines and is exercised on every CREATE OR REPLACE LAYOUT (the replace half is a delete + create); only the grammar alternative, AST node, visitor branch and executor were missing.", "fix": "dropStatement alternative + ast.DropLayoutStmt + visitor branch + mdl/executor/cmd_layouts_drop.go, plus the stmt_summary and validate_duplicates switches. Pages still bound are named in a warning, not refused.", "insight": "Before designing a 'missing capability', check whether the backend already has it \u2014 here the delete was already on the write path, so the whole feature was four small wirings and the risk was near zero. The second question is what the DROP's dependency policy should be: mxcli has NO drop that refuses on dependents, and warn-not-refuse is also what makes drop-then-recreate work (pages rebind by qualified name \u2014 verified back to 0 errors). The warning is load-bearing because the consequence, CE1613, names the PAGE and never the layout that was removed.", "controls": "Dropping a layout one page used \u2192 2\u00d7 CE1613 naming the page; re-creating it under the same name \u2192 0 errors. A page bound to a DIFFERENT layout must not appear in the warning, and an unused layout must produce no warning at all.", "refs": "mendixlabs/mxcli#1063", "file": "mdl/executor/cmd_layouts_drop.go, mdl/grammar/MDLParser.g4, mdl/ast/ast_page.go, mdl/visitor/visitor_entity.go"}
diff --git a/.claude/skills/fix-issue/findings/mdl-visitor.jsonl b/.claude/skills/fix-issue/findings/mdl-visitor.jsonl
index 2d752c7d5b..9c40768ba2 100644
--- a/.claude/skills/fix-issue/findings/mdl-visitor.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-visitor.jsonl
@@ -29,3 +29,4 @@
 {"area": "mdl/visitor", "symptom": "`Height: n` on a domain-model annotation is a bare parse error (\"mismatched input 'Height' expecting {POSITION, CAPTION, WIDTH}\"), which reads like a missing mxcli feature and gets reported as one. Filed as a feature request to expose annotation height.", "cause": "Not an mxcli gap: Mendix stores no annotation height. DomainModels$Annotation has exactly Caption, ExportLevel, Location and Width, so the note auto-sizes to its caption and there is nowhere to write a height. Adding the property would mean inventing a key the platform does not have.", "file": "`mdl/visitor/visitor.go` (`looksLikeAnnotationProperty`, `annotationHeightRe`, the two branches in `enhanceErrorMessage`); syntax topic `cmd/mxcli/syntax/features_domain_model.go`; type doc `mdl/ast/ast_annotation.go`; tests `mdl/visitor/annotation_height_hint_test.go`.", "insight": "`generated/metamodel` alone CANNOT settle \"does this property exist\" — it is an 11.6.0 snapshot, and the report was against 11.12.2, so a property added later would be invisible to it. Four sources were needed and three of them are cheap: `mx dump-mpr` (Mendix's own serializer) emits the four keys on real projects; `mx convert -p` is the decisive one, because it rewrites the model through Mendix's OWN object model and would materialise a property that merely had a default and was not stored — it added nothing; and the published Model SDK's domainmodels.Annotation lists caption/exportLevel/location/width. An absent key in stored BSON proves nothing on its own (it may just be unwritten), which is why dump-mpr alone is not enough. When a feature cannot exist, the deliverable is a parse error that SAYS so and names the levers that do exist (Width changes the wrapping and therefore the height; `ALTER ENTITY … SET POSITION` moves what the note overlaps) — the reporter's real goal was reachable already. Key the hint on the `expecting {POSITION, CAPTION, WIDTH}` token set, not on the word \"Height\": a page widget's Height is valid MDL, and a name-keyed hint would misfire on it (control: TestWidgetHeightIsNotAnnotationHinted).", "refs": ["#1014"], "date": "2026-09-01"}
 {"area": "mdl/visitor", "date": "2026-09-08", "symptom": "`call microflow M.ACT with (Ctx = $WorkflowContext)` — an UNQUOTED value in a workflow parameter mapping — crashed the binary with SIGSEGV (nil pointer) in buildWorkflowCallMicroflow, on `check`, `check --references` and `exec` alike, with no diagnostic beyond the Go panic. Reported as mendixlabs/mxcli#1023.", "cause": "The grammar rule workflowParameterMapping requires STRING_LITERAL, but visitor.Build() walks the parse tree even when the parse FAILED (deliberately — that is what lets check report more than the first error). Under ANTLR error recovery the rule context exists with a nil STRING_LITERAL child, and the visitor read it unguarded. Same bug at the CALL WORKFLOW site.", "fix": "Factor both sites into buildWorkflowParameterMappings, nil-checking QualifiedName() and STRING_LITERAL() and skipping the mapping. The syntax error the listener already recorded ('mismatched input ... expecting STRING_LITERAL') becomes what the author sees.", "file": "mdl/visitor/visitor_workflow.go", "insight": "In this codebase a required grammar child is NOT a guarantee inside the visitor, because Build() walks a failed parse on purpose. Every ctx.X().GetText() on a required child is therefore a latent crash reachable from ordinary malformed input — grep 'STRING_LITERAL().GetText()' for the ones still unguarded. The other half of the finding is documentation-shaped: `mxcli syntax workflow call-microflow` omitted the WITH clause entirely, so an author had nothing to copy and reached for the bare-variable spelling used everywhere else in MDL. A crash on input the tool's own docs do not cover is a docs bug with a segfault attached."}
 {"area": "mdl/visitor", "date": "2026-09-07", "symptom": "`create or modify snippet M.S (params: { $T: Mod.\"Thing\" })` failed at execution with `failed to resolve entity Mod.\"Thing\": entity not found`, while the identical quoted form in a PAGE parameter resolved fine (ako/CapTrackV4 019).", "cause": "buildSnippetParameterListAsPage re-split the parse node's TEXT (`parseQualifiedName(dt.GetText())`), and GetText() returns the source verbatim, quotes included. The page path walks the parse tree, where buildQualifiedName unquotes each part via identifierOrKeywordText. Fixed by walking the tree; the dead duplicate buildSnippetParameters — a correct implementation nothing called — was removed.", "file": "`mdl/visitor/visitor_page_v3.go` (buildSnippetParameterListAsPage); `mdl/visitor/visitor_page.go` (removed buildSnippetParameters); tests `mdl/visitor/snippet_param_quoted_entity_test.go`", "insight": "GetText() on an ANTLR context is the source text, not the resolved value, so any conversion built on it silently keeps quoting, whitespace and casing that the tree-walking helpers strip. Grep for `parseQualifiedName(.*GetText())` when a name resolves in one statement and not in a sibling. The asymmetry is also the diagnosis: when two statements accept the same syntax and only one works, compare their VISITORS before their executors — here both executor paths were identical and called the same resolveEntity. Two copies of one conversion with one of them dead is how they drifted, so the dead one is deleted rather than fixed."}
+{"area": "mdl/visitor", "date": "2026-09-15", "symptom": "`placeholder Main { }` inside a CREATE LAYOUT passes `mxcli check`, then fails at exec with `layout \"X\" declares no placeholder` \u2014 a message that flatly contradicts the script, which says `placeholder Main`. The failed exec has already created the module.", "cause": "One grammar rule (placeholderBlockV3) serves two opposite jobs, told apart by shape: `if c.LBRACE() == nil` makes a bodiless placeholder a DECLARATION widget, and the braced form is routed to buildPagePlaceholdersV3 \u2014 the page-side job of FILLING a layout slot. In a layout there is no such job, so the braced form was dropped on the floor and the layout ended up with zero placeholders.", "fix": "Builder gained `inLayout` (saved/restored around the layout body build, since the same body builder serves pages) and collects the dropped names into ast.CreateLayoutStmt.BracedPlaceholders; MDL083 reports them at check time. The braced form is still dropped \u2014 recording it is a diagnostic, not a decision to honour it.", "insight": "When one parse rule serves two documents and is disambiguated by SHAPE rather than by context, the wrong shape has no error path by construction \u2014 it just silently means the other thing. The tell is a runtime message that contradicts the source text. Note the mistake is the natural one: every other layout element takes a body, and `alter page` uses the braced form for real, so the author is generalising correctly from the rest of the language. DESCRIBE emits the bodiless form, so round-tripping never produces it and no existing test covered it.", "controls": "A page's braced placeholder must still fill a slot (TestBuildPageV3_BracedPlaceholderStillFillsASlot) and a layout's bodiless form must still produce a real widget \u2014 the flag is save/restored precisely so a page later in the same script is not flagged.", "refs": "mendixlabs/mxcli#1063", "file": "mdl/visitor/visitor_page_v3.go, mdl/visitor/visitor.go, mdl/ast/ast_page_v3.go"}
diff --git a/.claude/skills/mendix/write-layouts/SKILL.md b/.claude/skills/mendix/write-layouts/SKILL.md
index ead970e3bc..77532e6c9e 100644
--- a/.claude/skills/mendix/write-layouts/SKILL.md
+++ b/.claude/skills/mendix/write-layouts/SKILL.md
@@ -42,6 +42,26 @@ before running it** — the comments name exactly what will be lost. To change a
 layout without that risk, use `ALTER LAYOUT`, which edits the stored document in
 place and leaves everything it was not asked to touch alone.
 
+### Removing a layout
+
+```sql
+DROP LAYOUT MyModule.App_Old;
+```
+
+Pages still bound to it are **named in a warning and the drop proceeds** — it is
+not refused. Left dropped, each of those pages fails the build with **CE1613**
+("The selected layout … no longer exists"), which names the *page* and never the
+layout, so repoint them first:
+
+```sql
+ALTER PAGES SET LAYOUT = MyModule.App_New WHERE LAYOUT = MyModule.App_Old;
+DROP LAYOUT MyModule.App_Old;
+```
+
+To *correct* a layout rather than remove it, re-create it under the same name
+(`CREATE OR REPLACE LAYOUT`): the pages stay bound by qualified name and rebind
+to the new document — verified end to end, the pages go back to 0 errors.
+
 ### Repointing pages
 
 A new layout that no page uses changes nothing:
@@ -171,17 +191,36 @@ section.
 - **A placeholder's name is API.** A page binds to it as
   `Module.Layout.<Name>`, stored as a qualified name. Renaming one unbinds every
   page that used it — the page still builds, and its content vanishes.
-- **Name one placeholder `Main`.** `Forms$Layout` has no property saying which
-  placeholder is the main one; the convention is the mechanism, and 22 of 22
-  Atlas layouts follow it.
+- **Exactly one placeholder must be named `Main` — this is a rule, not a
+  convention.** `Forms$Layout` has no property saying which placeholder is the
+  main one, but mxbuild validates the NAME. Measured on 11.12.1 against a layout
+  **no page uses**, so none of it depends on a page binding:
+
+  | Declares | mxbuild |
+  |---|---|
+  | `Main` | 0 errors |
+  | `Main` + `Content` | 0 errors — extra names are fine |
+  | `Content` only | **CE0848** "No placeholder with the name 'Main' found. There should be exactly one." |
+  | `Main` + `Main` | **CE0849** + CE0495 |
+  | `Main` + `Side` + `Side` | **CE0495** "Duplicate name 'Side'." — uniqueness is general |
+
+  `mxcli check` reports these as **MDL081** (the Main rule) and **MDL082**
+  (duplicate names). Earlier versions said this was a convention and checked
+  only that *some* placeholder existed, so a layout naming it anything else
+  passed `check` and `exec` and failed the build (mendixlabs/mxcli#1063).
 - **There is no `mainplaceholder:` property, on purpose.** `modelsdk/gen`
   declares `MainPlaceholderName` on `Layout` so the setter compiles, and mxbuild
   accepts the result — measured 0 errors. But `generated/metamodel` does not
   declare it and no Studio Pro layout carries it, and Studio Pro resolves every
   stored property against the type's list. Writing it gives you a layout that
   builds and cannot be opened.
-- **A layout must declare at least one placeholder.** Otherwise no page can use
-  it. Refused at write time.
+- **A placeholder is declared with NO body.** `placeholder Main { … }` is the
+  page-side spelling — in a page it *fills* a layout's slot; in a layout it
+  declares nothing and is dropped, leaving the layout with no placeholder at all.
+  Reaching for it here is the natural mistake, since every other layout element
+  takes a body. Reported as **MDL083**.
+- **A layout that declares no placeholder is refused at write time** as well as
+  at check time — no page could use it.
 - **The sidebar toggle, the menu bar's logo and Atlas's `Forms$Header` are not
   authorable.** A topbar layout that needs a collapsible sidebar therefore has to
   keep Atlas's, or do without the toggle — which is why `mxcli new` scaffolds a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 417f04afb0..1d45d45ed7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+
+- **`DROP LAYOUT Module.Name`** (mendixlabs/mxcli#1063) — layouts were the only document mxcli could create and alter but not delete. Every other doctype has a DROP, and the gap bit hardest on a layout mxcli itself had just written badly: the reported script created a layout that fails the build, and there was no headless way to remove it. The backend could already do it — `DeleteLayout` is what `CREATE OR REPLACE LAYOUT` uses for the replace half — so only the verb was missing.
+
+  Pages still bound to the layout are **named in a warning and the drop proceeds**, matching every other DROP in mxcli (none refuse on dependents) and matching how a layout is normally corrected: re-create it under the same name and the pages rebind by qualified name — verified end to end, back to 0 errors. Left dropped, each page fails **CE1613** "The selected layout … no longer exists", which names the *page* and never the layout, so the warning names the pages and gives the `alter pages … where layout =` repoint.
+
+### Fixed
+
+- **A layout whose placeholder is not named `Main` passed `check` AND `exec`, then failed the build** (mendixlabs/mxcli#1063). Exactly one placeholder must be named `Main` — measured on Mendix 11.12.1 against a layout **no page uses**, so it does not depend on a page binding: none → **CE0848**, two → **CE0849**, and a repeated name of any kind → **CE0495**. Extra placeholders under other names are fine. Now reported as **MDL081** (the Main rule) and **MDL082** (duplicate names) by `mxcli check` with no project needed, and refused by the writer.
+
+  The root cause was a documented belief, not an oversight: mxcli's own docs called the name a convention ("22 of 22 Atlas layouts follow it"), and the write-time guard implemented exactly that — it accepted any placeholder under any name. mxbuild validates it as a rule. The rule now lives once, in `types.CheckLayoutPlaceholderNames`, and is applied by both the checker and the writer so the two cannot drift; CLAUDE.md and the layouts skill are corrected.
+
+- **`placeholder Main { … }` in a layout passed `check`, then failed `exec` after creating the module** (mendixlabs/mxcli#1063). A layout *declares* a placeholder with no body; the braced form is the page-side spelling that *fills* one, and the visitor drops it — so the layout ended up with no placeholder at all and the write failed with "declares no placeholder", contradicting a script that plainly said `placeholder Main`. Reaching for page syntax here is the natural mistake, since every other layout element takes a body. Now reported as **MDL083** at check time, before anything is written.
+
 ## [0.22.0] - 2026-09-14
 
 Headline: **The gap between a model that validates and an app that works.** Almost everything fixed here was invisible to `mxcli check`, to `mx check` and to mxbuild — a workflow that loads, validates and then deadlocks at run time; a `describe` round trip that deletes what it just described; a widget spelling that storage drops — because in each case the model Mendix loaded was perfectly valid, just not the one that was written. Alongside that, offline synchronization, SOAP request bodies and a microflow's join points become authorable, closing three of the places where MDL could describe a model it could not write.
diff --git a/CLAUDE.md b/CLAUDE.md
index 0433a4818e..1c8739d0dc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -825,7 +825,7 @@ Full syntax tables for all MDL statements (microflows, pages, security, navigati
 - Microflows/Nanoflows with 60+ activity types, JavaScript action calls, nanoflow validation parity
 - Pages with 50+ widget types
 - ALTER PAGE/SNIPPET (SET, INSERT, DROP, REPLACE operations on widget trees)
-- Layouts (SHOW/DESCRIBE/CREATE [OR REPLACE] LAYOUT): the frame a page renders inside — the last document a page depends on that MDL could not write, which is why the topbar was out of reach. Four element types beyond a page's vocabulary: `scrollcontainer`, `region top|right|bottom|left|center` (five named slots, not a list), `placeholder`, `navigationtree`. `DESCRIBE LAYOUT` emits **re-executable MDL**, which makes describe → rename → exec the copy operation and is why there is no `COPY DOCUMENT` verb. Writing into a Marketplace module is **refused** — Mendix's own guidance is not to edit the supplied layouts, since an update replaces the module — which also required wiring `FromAppStore` enrichment into `GetModuleByName`/`GetModule` (it was populated only by `ListModules`, so the guard would have been inert). The document is pinned to the ten keys Studio Pro writes, identical across all 22 Atlas layouts on 11.13.0: `modelsdk/gen` offers seven placeholder properties on `Layout` (`MainPlaceholderName` and friends) that `generated/metamodel` does not declare and no real layout carries, and writing one gives a layout **mxbuild accepts at 0 errors and Studio Pro cannot open**. Which placeholder is "main" is a naming convention (22 of 22 name one `Main`; a page binds by qualified name anyway), so `layouttype` is the only header property and anything else is an error rather than an ignored key. The platform is inferred from the layout type — web (Responsive/Phone/Tablet/ModalPopup) and native (Default/Popup) are disjoint — so there is no `native:` flag. Authoring is modelsdk-only; legacy refuses. Verified in a browser, not just against `mx check`. `ALTER LAYOUT Module.Name { … }` takes the whole ALTER PAGE vocabulary (a layout's tree *is* a page's plus four element types) and edits the stored document, which is what makes it a capability rather than a convenience: **describe → rename → exec is only as complete as what MDL can spell** — measured, the copy of `Atlas_Core.Atlas_SideBar` loses both `Forms$SidebarToggleButton` widgets, and an `image` widget loses its image reference. A region has no `Name`, so it is addressed as `layoutContainer.top` (the dotted widgetRef that also serves DataGrid2 columns; `$Type` decides which), and only `INSERT INTO` takes one. Pages move onto a layout with `ALTER PAGE … SET Layout = X [MAP (Old AS New)]` or the bulk `ALTER PAGES [IN <mod>] SET LAYOUT = X [WHERE LAYOUT = Y]`, both of which **refuse a repoint that would leave a page bound to a placeholder the target does not declare** (checked *after* MAP, since MAP is the remedy) — mxbuild only catches that as CE1613 at the far end of a build. See `.claude/skills/mendix/write-layouts/SKILL.md` and `docs/11-proposals/PROPOSAL_authorable_layouts.md`
+- Layouts (SHOW/DESCRIBE/CREATE [OR REPLACE] LAYOUT): the frame a page renders inside — the last document a page depends on that MDL could not write, which is why the topbar was out of reach. Four element types beyond a page's vocabulary: `scrollcontainer`, `region top|right|bottom|left|center` (five named slots, not a list), `placeholder`, `navigationtree`. `DESCRIBE LAYOUT` emits **re-executable MDL**, which makes describe → rename → exec the copy operation and is why there is no `COPY DOCUMENT` verb. Writing into a Marketplace module is **refused** — Mendix's own guidance is not to edit the supplied layouts, since an update replaces the module — which also required wiring `FromAppStore` enrichment into `GetModuleByName`/`GetModule` (it was populated only by `ListModules`, so the guard would have been inert). The document is pinned to the ten keys Studio Pro writes, identical across all 22 Atlas layouts on 11.13.0: `modelsdk/gen` offers seven placeholder properties on `Layout` (`MainPlaceholderName` and friends) that `generated/metamodel` does not declare and no real layout carries, and writing one gives a layout **mxbuild accepts at 0 errors and Studio Pro cannot open**. Which placeholder is "main" is **a rule mxbuild enforces, not a convention** — `layouttype` is still the only header property, because `Forms$Layout` has no property for it, but the NAME is validated: measured on 11.12.1 against a layout **no page uses**, exactly one placeholder must be named `Main` (none → **CE0848**, two → **CE0849**) and placeholder names must be unique (**CE0495**); extra placeholders under other names are fine. mxcli reported none of this until #1063 — this file called it a convention and the write-time guard implemented that belief, accepting any placeholder under any name, so the reported script passed `check` AND `exec` and failed a build later with no `DROP LAYOUT` to undo it. The rule now lives once in `types.CheckLayoutPlaceholderNames` and is applied by both `mxcli check` (**MDL081**/**MDL082**) and the writer, because two copies in two currencies is how a resolver drifts. The platform is inferred from the layout type — web (Responsive/Phone/Tablet/ModalPopup) and native (Default/Popup) are disjoint — so there is no `native:` flag. Authoring is modelsdk-only; legacy refuses. Verified in a browser, not just against `mx check`. `DROP LAYOUT Module.Name` removes one — layouts were the only doctype mxcli could create and alter but not delete, which bit hardest on a layout mxcli itself had just written badly; pages still bound to it are **warned about and named, not refused** (matching every other DROP), because drop-then-recreate under the same name is how a layout is corrected and the pages rebind by qualified name — left dropped they fail **CE1613**, which names the *page* and never the layout. `ALTER LAYOUT Module.Name { … }` takes the whole ALTER PAGE vocabulary (a layout's tree *is* a page's plus four element types) and edits the stored document, which is what makes it a capability rather than a convenience: **describe → rename → exec is only as complete as what MDL can spell** — measured, the copy of `Atlas_Core.Atlas_SideBar` loses both `Forms$SidebarToggleButton` widgets, and an `image` widget loses its image reference. A placeholder is **declared** with no body; `placeholder X { … }` is the page-side spelling that *fills* a slot, and in a layout the visitor drops it — which used to leave the layout with no placeholder at all and fail the write with a message contradicting the script, so it is now **MDL083**. A region has no `Name`, so it is addressed as `layoutContainer.top` (the dotted widgetRef that also serves DataGrid2 columns; `$Type` decides which), and only `INSERT INTO` takes one. Pages move onto a layout with `ALTER PAGE … SET Layout = X [MAP (Old AS New)]` or the bulk `ALTER PAGES [IN <mod>] SET LAYOUT = X [WHERE LAYOUT = Y]`, both of which **refuse a repoint that would leave a page bound to a placeholder the target does not declare** (checked *after* MAP, since MAP is the remedy) — mxbuild only catches that as CE1613 at the far end of a build. See `.claude/skills/mendix/write-layouts/SKILL.md` and `docs/11-proposals/PROPOSAL_authorable_layouts.md`
 - Image widgets (IMAGE, STATICIMAGE, DYNAMICIMAGE) with Width/Height properties
 - Code generator for metamodel types
 - MDL CLI (`mxcli`) with ANTLR4 parser
diff --git a/cmd/mxcli/syntax/features_page.go b/cmd/mxcli/syntax/features_page.go
index 444953b44b..acd97a1e4c 100644
--- a/cmd/mxcli/syntax/features_page.go
+++ b/cmd/mxcli/syntax/features_page.go
@@ -385,11 +385,37 @@ CREATE PAGE Sales.Detail (Title: 'Detail', Layout: Atlas_Core.Atlas_Default) {
 			"  TITLE t (Content: 'Welcome')\n" +
 			"}\n\n" +
 			"-- A placeholder's name is API: a page references it as Module.Layout.<Name>,\n" +
-			"-- so renaming one unbinds every page that used it. Name one Main — that\n" +
-			"-- convention is how Mendix picks the main placeholder (every Atlas layout\n" +
-			"-- does), because Forms$Layout has no property for it. A layout must declare\n" +
-			"-- at least one placeholder or no page can use it.",
-		SeeAlso: []string{"layout.show", "page.create", "snippet"},
+			"-- so renaming one unbinds every page that used it.\n" +
+			"--\n" +
+			"-- EXACTLY ONE placeholder must be named Main. This is a rule mxbuild\n" +
+			"-- enforces, not a convention: a layout with none fails CE0848 and one\n" +
+			"-- with two fails CE0849 — even if no page uses the layout. Placeholder\n" +
+			"-- names must also be unique (CE0495). Extra placeholders under other\n" +
+			"-- names are fine. mxcli reports all three as MDL081/MDL082.\n" +
+			"--\n" +
+			"-- A placeholder is DECLARED with no body. `PLACEHOLDER Main { … }` is the\n" +
+			"-- page-side spelling that FILLS a slot; in a layout it declares nothing\n" +
+			"-- and is reported as MDL083.",
+		SeeAlso: []string{"layout.show", "layout.drop", "page.create", "snippet"},
+	})
+
+	Register(SyntaxFeature{
+		Path:    "layout.drop",
+		Summary: "DROP LAYOUT — remove a layout (warns about pages still bound to it)",
+		Keywords: []string{
+			"drop layout", "delete layout", "remove layout",
+		},
+		Syntax: "DROP LAYOUT Module.Name",
+		Example: "DROP LAYOUT MyModule.App_Old;\n\n" +
+			"-- Pages still bound to it are named in a warning, and the drop proceeds.\n" +
+			"-- Left dropped, each of those pages fails the build with CE1613 — which\n" +
+			"-- names the PAGE and never the layout, so repoint them first:\n" +
+			"ALTER PAGES SET LAYOUT = MyModule.App_New WHERE LAYOUT = MyModule.App_Old;\n" +
+			"DROP LAYOUT MyModule.App_Old;\n\n" +
+			"-- Or correct a layout in place by re-creating it under the same name:\n" +
+			"-- the pages stay bound by qualified name and rebind to the new document.\n" +
+			"-- (CREATE OR REPLACE LAYOUT does this in one statement.)",
+		SeeAlso: []string{"layout", "layout.alter", "layout.show"},
 	})
 
 	Register(SyntaxFeature{
diff --git a/docs/01-project/MDL_QUICK_REFERENCE.md b/docs/01-project/MDL_QUICK_REFERENCE.md
index e35ba60dad..4a34eee995 100644
--- a/docs/01-project/MDL_QUICK_REFERENCE.md
+++ b/docs/01-project/MDL_QUICK_REFERENCE.md
@@ -1399,6 +1399,8 @@ MDL uses explicit property declarations for pages:
 | List layouts | `show layouts [in module];` | |
 | Describe layout | `describe layout Module.Name;` | Round-trippable MDL — describe an Atlas layout, rename it, run it to get a copy in your own module |
 | Create layout | `create [or replace] layout Module.Name ( layouttype: 'X' ) { <widgets> };` | modelsdk engine only. Refused in a Marketplace module: an update replaces the module and the edit is gone |
+| Drop layout | `drop layout Module.Name;` | Pages still bound to it are named in a warning and the drop proceeds; left dropped they fail **CE1613**, which names the *page* |
+| Declare a placeholder | `placeholder Main` | **No body.** Exactly one must be named `Main` — mxbuild enforces it (**CE0848**/**CE0849**), and names must be unique (**CE0495**). `placeholder X { … }` is the page-side form and declares nothing (MDL083) |
 | Alter layout | `alter layout Module.Name { <alter-page operations> };` | Edits the stored document, so widgets MDL cannot spell survive. Refused for a Marketplace target |
 | Repoint one page | `alter page Module.Page { set Layout = Module.Layout [map (Old as New, …)]; };` | Rewrites the layout reference **and** every placeholder binding |
 | Repoint many pages | `alter pages [in <module>] set layout = Module.Layout [map (…)] [where layout = Module.Old];` | The migration form. Marketplace pages are skipped and named. A `where layout` that names no real layout is an error, not a 0-page success |
diff --git a/mdl-examples/bug-tests/1063-layout-placeholder-rules.mdl b/mdl-examples/bug-tests/1063-layout-placeholder-rules.mdl
new file mode 100644
index 0000000000..18d023fc2b
--- /dev/null
+++ b/mdl-examples/bug-tests/1063-layout-placeholder-rules.mdl
@@ -0,0 +1,58 @@
+-- mendixlabs/mxcli#1063 — layout placeholder rules, and DROP LAYOUT
+--
+-- Three defects, all of which let a broken layout through to the builder:
+--
+--   1. A layout whose placeholder is not named `Main` passed `mxcli check` AND
+--      `mxcli exec`, then failed `mx check` with CE0848. mxcli's docs called the
+--      name a convention; mxbuild validates it as a rule.
+--   2. `placeholder Main { … }` (the page-side spelling) passed check, then
+--      failed exec AFTER creating the module — with a message contradicting the
+--      script.
+--   3. There was no DROP LAYOUT, so neither mistake could be undone headlessly.
+--
+-- The rule, measured on Mendix 11.12.1 against a layout NO PAGE USES:
+--
+--   placeholder Main               → 0 errors
+--   placeholder Main + Content     → 0 errors  (extra names are fine)
+--   placeholder Content            → CE0848
+--   placeholder Main + Main        → CE0849 + CE0495
+--   placeholder Main + Side + Side → CE0495
+--
+-- Run: mxcli check mdl-examples/bug-tests/1063-layout-placeholder-rules.mdl
+--      (this file is the PASSING shape; the failing ones are commented below)
+
+CREATE OR REPLACE LAYOUT MyFirstModule.App_Probe1063 (
+  layouttype: 'Responsive',
+  class: 'layout-atlas'
+) {
+  SCROLLCONTAINER layoutContainer {
+    REGION center (Class: 'region-content') {
+      -- Declared, not filled: no body. Exactly one, named Main.
+      PLACEHOLDER Main
+      -- Extra placeholders under other names are fine.
+      PLACEHOLDER Side
+    }
+  }
+}
+
+-- Layouts are now removable. Pages still bound to one are named in a warning
+-- and the drop proceeds; left dropped they fail CE1613, which names the PAGE.
+DROP LAYOUT MyFirstModule.App_Probe1063;
+
+-- The three shapes mxcli now refuses, each with the CE number it would have hit:
+--
+-- MDL081 (CE0848) — no placeholder named Main:
+--   CREATE OR REPLACE LAYOUT M.A (layouttype: 'Responsive') {
+--     SCROLLCONTAINER sc { REGION center { PLACEHOLDER Content } } }
+--
+-- MDL081 (CE0849) — two of them:
+--   CREATE OR REPLACE LAYOUT M.B (layouttype: 'Responsive') {
+--     SCROLLCONTAINER sc { REGION center { PLACEHOLDER Main PLACEHOLDER Main } } }
+--
+-- MDL082 (CE0495) — a repeated name, Main or not:
+--   CREATE OR REPLACE LAYOUT M.C (layouttype: 'Responsive') {
+--     SCROLLCONTAINER sc { REGION center { PLACEHOLDER Main PLACEHOLDER Side PLACEHOLDER Side } } }
+--
+-- MDL083 — the page-side braced form, which declares nothing:
+--   CREATE OR REPLACE LAYOUT M.D (layouttype: 'Responsive') {
+--     SCROLLCONTAINER sc { REGION center { PLACEHOLDER Main { } } } }

From 3d3ca1f1ea8f803ae6b51e802500e0f4995f22e2 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 15 Sep 2026 07:00:57 +0000
Subject: [PATCH 13/24] Delete the legacy sdk/mpr backend and the flag
 selecting it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phases 1 and 2 of docs/plans/2026-09-14-retire-legacy-engine.md. The codec
engine has been the default since the 2026-06 cutover and nothing routes to
legacy any more; it was five files away from having no non-test importers.

Deleted: mdl/backend/mpr (the backend), mdl/enginecompare and the engine-diff
make target (a package that compares two engines), and the `bson compare`
command. Repointed mdl/repl, two examples and the test helpers at the codec
backend, and dropped the nightly matrix's engines leg.

--engine and MXCLI_ENGINE survive as a warning-only NO-OP rather than being
removed. Deleting the flag would fail a script pinning `legacy` at argument
parsing with "unknown flag", which says nothing about what changed; it now
warns once and runs. Verified both spellings warn and still execute.

Three things the plan did not anticipate, each invisible while two engines
existed and none caught by the compiler:

- errUnimplemented still told users to "rerun with MXCLI_ENGINE=legacy" — a
  runtime message naming a fallback that no longer exists is worse than none,
  because the user follows it into a second failure. It now asks for a report,
  which is what reaching it means.
- setupTestEnv defaulted to the LEGACY backend, so most of mdl/executor's
  integration tests were exercising the retired engine rather than the one
  users get. They run on the codec engine now — coverage that was always
  intended and had silently not been happening.
- TestODataService_EngineWriteParity compared two writers' key sets. The
  comparison is vacuous with one engine, so it is dropped and the property it
  was a means to is kept: a published OData service retains its role grants,
  which mx check reports as 0 errors either way. Renamed to match.

Kept deliberately: the doctype gate's engine matrix, at one entry. Its
selection still turns a stale MXCLI_TEST_ENGINES=legacy into a loud failure
rather than a gate that selects zero engines and reports success.

One test deleted: TestCustomHandlerLegacyRefuses, which asserted legacy's
refusal of a construct it could not serialize. The codec engine's positive
coverage of that construct is intact.

Gates: build, vet (incl. -tags integration), go test ./..., check-mdl (543
pass), check-findings. Executor integration suite green at 562s, down from
642s now that the doctype gate runs once instead of twice; mdl/backend, api,
marketplace and repl integration suites green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hifgRSawfaRWXS44YKtSJ
---
 .../fix-issue/findings/mdl-backend.jsonl      |    1 +
 .claude/skills/mendix/atlas-design/SKILL.md   |    7 +-
 .../skills/mendix/manage-navigation/SKILL.md  |    2 -
 .github/workflows/nightly.yml                 |   55 +-
 .github/workflows/push-test.yml               |   13 +-
 CLAUDE.md                                     |    2 +-
 Makefile                                      |   18 +-
 cmd/mxcli/cmd_bson.go                         |    6 +-
 cmd/mxcli/cmd_bson_compare.go                 |  158 ---
 cmd/mxcli/engine.go                           |   79 +-
 cmd/mxcli/main.go                             |   11 +-
 cmd/mxcli/marketplace/security_test.go        |   14 +-
 .../create-message-definition-collection.md   |    3 -
 docs-site/src/reference/navigation/menu.md    |    4 -
 docs-site/src/reference/page/alter-layout.md  |    2 -
 docs-site/src/reference/page/create-layout.md |    2 -
 docs-wiki/bug-patterns/engine-divergence.md   |    8 +
 .../11-proposals/PROPOSAL_backend_strategy.md |    7 +-
 .../plans/2026-06-05-adopt-modelsdk-engine.md |    5 +-
 docs/plans/2026-09-14-retire-legacy-engine.md |   70 +-
 examples/create_datagrid2_page/main.go        |    4 +-
 examples/create_nanoflow/main.go              |    4 +-
 mdl/backend/modelsdk/backend.go               |   36 +-
 mdl/backend/modelsdk/units.go                 |    8 +-
 .../modelsdk/widget_write_legacy_gaps.go      |    8 +-
 mdl/backend/mpr/backend.go                    | 1163 -----------------
 mdl/backend/mpr/convert.go                    |  420 ------
 mdl/backend/mpr/convert_roundtrip_test.go     |  639 ---------
 mdl/backend/mpr/convert_test.go               |  189 ---
 mdl/backend/mpr/datagrid_builder.go           |  155 ---
 mdl/backend/mpr/offline_sync_carry_test.go    |   55 -
 mdl/backend/mpr/page_mutator.go               |   59 -
 mdl/backend/mpr/widget_builder.go             |   82 --
 mdl/backend/mpr/workflow_mutator.go           |   46 -
 mdl/enginecompare/bsoncompare.go              |  250 ----
 mdl/enginecompare/compare.go                  |  105 --
 mdl/enginecompare/compare_test.go             |   76 --
 mdl/enginecompare/write_alter_test.go         |  187 ---
 mdl/enginecompare/write_assoc_drop_test.go    |   30 -
 mdl/enginecompare/write_assoc_test.go         |   36 -
 mdl/enginecompare/write_attr_test.go          |   35 -
 mdl/enginecompare/write_const_test.go         |   60 -
 mdl/enginecompare/write_enum_test.go          |   66 -
 mdl/enginecompare/write_gen_test.go           |   26 -
 mdl/enginecompare/write_index_test.go         |   58 -
 mdl/enginecompare/write_microflow_test.go     |  213 ---
 mdl/enginecompare/write_module_test.go        |   28 -
 mdl/enginecompare/write_move_test.go          |   64 -
 mdl/enginecompare/write_test.go               |   50 -
 mdl/enginecompare/write_valid_test.go         |   27 -
 mdl/enginecompare/write_view_test.go          |   26 -
 mdl/executor/mapping_customhandler_test.go    |   31 +-
 ...rity_test.go => odata_role_grants_test.go} |   97 +-
 mdl/executor/roundtrip_doctype_test.go        |   52 +-
 mdl/executor/roundtrip_helpers_test.go        |   16 +-
 mdl/executor/typecheck_test.go                |    4 +-
 mdl/repl/repl.go                              |   12 +-
 57 files changed, 278 insertions(+), 4606 deletions(-)
 delete mode 100644 cmd/mxcli/cmd_bson_compare.go
 delete mode 100644 mdl/backend/mpr/backend.go
 delete mode 100644 mdl/backend/mpr/convert.go
 delete mode 100644 mdl/backend/mpr/convert_roundtrip_test.go
 delete mode 100644 mdl/backend/mpr/convert_test.go
 delete mode 100644 mdl/backend/mpr/datagrid_builder.go
 delete mode 100644 mdl/backend/mpr/offline_sync_carry_test.go
 delete mode 100644 mdl/backend/mpr/page_mutator.go
 delete mode 100644 mdl/backend/mpr/widget_builder.go
 delete mode 100644 mdl/backend/mpr/workflow_mutator.go
 delete mode 100644 mdl/enginecompare/bsoncompare.go
 delete mode 100644 mdl/enginecompare/compare.go
 delete mode 100644 mdl/enginecompare/compare_test.go
 delete mode 100644 mdl/enginecompare/write_alter_test.go
 delete mode 100644 mdl/enginecompare/write_assoc_drop_test.go
 delete mode 100644 mdl/enginecompare/write_assoc_test.go
 delete mode 100644 mdl/enginecompare/write_attr_test.go
 delete mode 100644 mdl/enginecompare/write_const_test.go
 delete mode 100644 mdl/enginecompare/write_enum_test.go
 delete mode 100644 mdl/enginecompare/write_gen_test.go
 delete mode 100644 mdl/enginecompare/write_index_test.go
 delete mode 100644 mdl/enginecompare/write_microflow_test.go
 delete mode 100644 mdl/enginecompare/write_module_test.go
 delete mode 100644 mdl/enginecompare/write_move_test.go
 delete mode 100644 mdl/enginecompare/write_test.go
 delete mode 100644 mdl/enginecompare/write_valid_test.go
 delete mode 100644 mdl/enginecompare/write_view_test.go
 rename mdl/executor/{odata_engine_parity_test.go => odata_role_grants_test.go} (54%)

diff --git a/.claude/skills/fix-issue/findings/mdl-backend.jsonl b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
index 18f550f371..dd899e50fe 100644
--- a/.claude/skills/fix-issue/findings/mdl-backend.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
@@ -97,3 +97,4 @@
 {"area": "mdl/backend", "date": "2026-09-15", "symptom": "On the default engine, `describe workflow` printed `wait for notification x;` without its boundary events (and their handler flows); the legacy engine described them. A describe -> exec round trip lost them.", "cause": "workflowActivityFromGen's typed switch had no case for *genWf.WaitForNotificationActivity, so it fell to workflowSimpleActivityFromGen, which reads only Name and Caption from raw BSON. That path's comment said the wait activities 'have no genWf struct' — true once, stale by the time gen gained WaitForNotificationActivity with BoundaryEventsItems().", "fix": "Typed case reading boundaryEventsFromGen(a.BoundaryEventsItems()), like the five other activities that carry boundary events.", "file": "mdl/backend/modelsdk/workflow_read.go", "insight": "A fallback path documented as 'for types gen does not model' silently keeps catching a type after gen starts modelling it; the reader then under-reads without any error. When gen is re-vendored, grep the typed switches for types that newly have structs. The bug surfaced only because a probe described what it had just written — reading back your own write, per activity type, is the cheap check."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"AddAttribute and UpdateAttribute were unimplemented on the default engine, so api/ could only work on the retired legacy one — and api/'s whole integration suite reported green while verifying nothing","cause":"api/ imported mdl/backend zero times: it held a concrete *mpr.Writer and bypassed the backend abstraction, so the two methods had no caller through a backend value and were never ported.","file":"api/api.go","fix":"api.New takes a backend.FullBackend (plus an api.Open convenience that owns its connection); the two methods are implemented on the codec backend and struck off unreachableUnimplemented.","insight":"unreachableUnimplemented is a CENSUS OF WHO BYPASSES THE ABSTRACTION, not dead interface surface. Read its reason column as a map and it names api/, the MCP backend, and the cmd/mxcli commands holding a concrete reader; a method is on it BECAUSE such a caller exists and unreachable BECAUSE that caller does not use a backend value. So the list shrinks by closing a bypass, never by deleting methods — and the pin fails loudly when you do, which is how it should be used. Two traps in the port itself. (1) The generated gen list offers only Append and Remove, so replacing an element in place means rebuilding the list; the naive remove-then-add moves the edited attribute to the bottom of the entity, which is a diff on every edit — control: break the rebuild and the order test catches it. (2) THE SUITE THAT WOULD HAVE VERIFIED THE PORT HAD ONLY EVER SKIPPED. api/'s integration tests pointed at ../mx-test-projects/test-source-app, which is not in the repository, so all ten skipped on every machine and in CI since they were written (the #808 shape). `go test ./api/` passing said nothing. Repointed at the committed testdata/expr-checker fixture the codec backend's own tests use, and made a missing fixture FATAL rather than a skip, since a committed fixture's absence is a broken checkout. Before trusting a suite to verify a refactor, check it is not skipping."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"The MCP backend held a concrete *mpr.Reader for its local reads, keeping three methods (GetDomainModelByID, GetWorkflow, ListNavigationDocuments) on FullBackend with no caller through a backend value — and 190 tests in the package, not one of which called Connect, so swapping the reader underneath it would have landed unverified with the suite green.","cause":"Those three reads had no codec-backend implementation, so MCP could not compose a backend and kept a legacy reader instead. Each was a re-keying or widening of a read the package already did, not new decoding.","file":"mdl/backend/mcp/backend.go","fix":"Implemented the three on the codec backend (mdl/backend/modelsdk/mcp_bypass_reads.go), sharing domainModelFromGen / workflowFromGen / navProfileFromGen with their siblings; added Backend.ConnectReadOnly and pointed MCP's reader field at backend.FullBackend. Wrote mdl/backend/mcp/connect_reads_test.go — the first test to call Connect at all.","insight":"A test can be vacuous in two different ways in one file, and the second is the one you miss. The read-only assertion SKIPPED (MyFirstModule has no entities), which the runner prints — so it was obvious. The GetWorkflow assertion looped over the listing and the fixture has ZERO workflows, so the loop body never ran and the test reported PASS having called nothing. Same failure class as #808, but silent. The fixes differ by shape: for the skip, pick a probe needing nothing pre-existing (CreateEntity, not AddAttribute); for the empty loop, SEED the thing through a read-write backend, then reconnect read-only and assert a specific named item is in the listing BEFORE fetching it — that guard is what converts a future vacuous pass into a failure. Cheapest way to find both: print the counts a test loops over before trusting it. MCP's read-only constraint also has a real control: revert ConnectReadOnly to Connect and the write-refusal test fails with the reported symptom, and the companion TestConnect_TheSameWriteSucceedsReadWrite proves the probe write is not failing for an unrelated reason."}
+{"area":"mdl/backend","date":"2026-09-15","symptom":"Deleting the legacy sdk/mpr backend (mdl/backend/mpr) turned up three things the removal plan had not sized: a runtime error telling users to rerun on the engine that had just been deleted, an integration suite that had been exercising the retired engine rather than the default one, and a cross-engine parity test whose comparison became vacuous.","cause":"Each is a reference to the second engine that was invisible while two engines existed. errUnimplemented's message named MXCLI_ENGINE=legacy as the fallback; setupTestEnv in mdl/executor/roundtrip_helpers_test.go hardcoded mprbackend.New() as its default, so most of the package's integration tests ran on legacy; TestODataService_EngineWriteParity compared writer A's key set against writer B's.","file":"mdl/backend/modelsdk/backend.go","fix":"errUnimplemented now asks for a bug report instead of naming a fallback. setupTestEnv defaults to the codec backend. The parity test keeps its value assertion (a published OData service retains AllowedModuleRoles) and drops the comparison, renamed to match. --engine/MXCLI_ENGINE kept as a warning-only no-op; `bson compare` and mdl/enginecompare deleted.","insight":"Deleting one of two implementations is not finished when the code compiles — grep for the deleted thing in three places the compiler cannot reach. (1) RUNTIME STRINGS: an error message naming a removed fallback is strictly worse than no fallback, because the user follows it and gets a second failure; this one had been shipping the instruction 'rerun with MXCLI_ENGINE=legacy' from 19 generated stubs. (2) TEST DEFAULTS: a shared setup helper's hardcoded choice of implementation decides what a whole package actually covers, and here it silently pointed most of mdl/executor's integration tests at the engine being retired — deleting the other one moved them onto the default engine for the first time, which is coverage gained, not lost. (3) DIFFERENTIAL TESTS: a test that compares A to B has no meaning with one implementation, but the PROPERTY it was a means to usually does — for the OData one, that a service keeps its role grants, which mx check reports as 0 errors either way. Drop the comparison, keep the property, rename the file so the next reader is not misled. One counter-case worth noting: the doctype gate's engine MATRIX was kept at one entry rather than collapsed, because its selection function still converts a stale MXCLI_TEST_ENGINES=legacy into a loud failure instead of a gate that selects zero engines and reports success."}
diff --git a/.claude/skills/mendix/atlas-design/SKILL.md b/.claude/skills/mendix/atlas-design/SKILL.md
index 42d0ed1400..4c2bbf48e2 100644
--- a/.claude/skills/mendix/atlas-design/SKILL.md
+++ b/.claude/skills/mendix/atlas-design/SKILL.md
@@ -185,14 +185,11 @@ alter page Sales.CustomerOverview set cust_text22 (content: 'Customers');
 > `CATALOG.building_blocks`) **and** instantiation (`USE BUILDING BLOCK`) both work
 > today. `use building block` v1 is **deep-copy + optional `as <prefix>`**; configure
 > the copy afterwards with `alter page` (an inline override block is a proposed v1.1).
-> It runs on `MXCLI_ENGINE=legacy` today; modelsdk-engine support lands with that
-> engine's `ListBuildingBlocks`.
 
 **When to *mirror* instead.** *Mirroring* — reproducing a block's tree by hand with
 `create page`/`alter page` + the same classes and design properties (see below) — is
-the fallback: reach for it only to hand-tune a shape Atlas doesn't quite give you, or
-on the modelsdk engine before its building-block support lands. Otherwise prefer the
-one-line `use building block`.
+the fallback: reach for it only to hand-tune a shape Atlas doesn't quite give you.
+Otherwise prefer the one-line `use building block`.
 
 ---
 
diff --git a/.claude/skills/mendix/manage-navigation/SKILL.md b/.claude/skills/mendix/manage-navigation/SKILL.md
index 2c883b84c0..4a8889be02 100644
--- a/.claude/skills/mendix/manage-navigation/SKILL.md
+++ b/.claude/skills/mendix/manage-navigation/SKILL.md
@@ -442,8 +442,6 @@ export level are preserved, so menu widgets pointing at it keep working.
   image icon cannot be written by MDL; `describe` flags those on their own
   comment line rather than dropping them silently, so re-running the output
   loses that icon visibly.
-- **Authoring needs the default engine.** Under `MXCLI_ENGINE=legacy`,
-  create/modify/drop refuse rather than writing a differently-shaped document.
 
 ## Offline Profiles
 
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
index a683c27ecf..14a26cb786 100644
--- a/.github/workflows/nightly.yml
+++ b/.github/workflows/nightly.yml
@@ -14,20 +14,17 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        # `engines` is spelled out per entry rather than defaulted, so reading
-        # this block tells you where legacy runs without also knowing what an
-        # omitted key falls back to.
-        include:
-          - mendix-version: '10.24.24.119349'
-            engines: modelsdk
-          - mendix-version: '11.6.8'
-            engines: modelsdk
-          - mendix-version: '11.12.2'
-            engines: modelsdk
-          - mendix-version: '11.13.0'
-            engines: modelsdk
-          - mendix-version: '11.14.0'
-            engines: all
+        # There is one engine since the legacy sdk/mpr backend was deleted
+        # (docs/plans/2026-09-14-retire-legacy-engine.md), so the matrix is over
+        # Mendix versions alone. MXCLI_TEST_ENGINES is left unset: its default is
+        # every engine, and a name that no longer exists fails loudly rather than
+        # selecting nothing.
+        mendix-version:
+          - '10.24.24.119349'
+          - '11.6.8'
+          - '11.12.2'
+          - '11.13.0'
+          - '11.14.0'
       fail-fast: false
     name: test (Mendix ${{ matrix.mendix-version }})
     steps:
@@ -57,36 +54,8 @@ jobs:
       - name: Setup mxbuild ${{ matrix.mendix-version }}
         run: ./bin/mxcli setup mxbuild --version ${{ matrix.mendix-version }}
 
-      # The nightly is where legacy is verified — the per-push job runs modelsdk
-      # alone (push-test.yml) — but it no longer runs on every Mendix version.
-      #
-      # The engine matrix is most of what this step costs: each script is
-      # executed and handed to mxbuild once PER ENGINE (measured 588s -> 232s
-      # for modelsdk alone), so legacy was five sixths of the fleet's cost for a
-      # path nothing routes to any more. As of 2026-09-12 no mxcli feature falls
-      # back to it: the last four widget keywords are written by the codec engine
-      # and the last two reachable unimplemented backend methods are implemented
-      # (mdl/backend/modelsdk/unimplemented_reachability_test.go holds that
-      # measurement). Legacy is now strictly weaker — rules, menus, layouts,
-      # message definitions and regular expressions all refuse on it.
-      #
-      # It is narrowed rather than dropped, deliberately. `--engine legacy` is
-      # still a thing a user can type, and an engine that ships untested rots
-      # silently — the failure this repo has already had once (#808, an
-      # integration test that had only ever skipped). One version keeps the
-      # engine honest at a fifth of the cost; drop this line only together with
-      # the engine itself.
-      #
-      # Legacy's UNIT tests are unaffected and still run on every push: what
-      # narrows here is only the expensive exec + mxbuild loop.
-      #
-      # The engine set is in the step NAME as well as the env, because `go test`
-      # without -v discards a passing package's output, so TestMain's own notice
-      # never reaches a green log.
-      - name: "Integration tests (Mendix ${{ matrix.mendix-version }}, engines: ${{ matrix.engines }})"
+      - name: "Integration tests (Mendix ${{ matrix.mendix-version }})"
         run: make test-integration
-        env:
-          MXCLI_TEST_ENGINES: ${{ matrix.engines }}
         timeout-minutes: 30
 
   nightly:
diff --git a/.github/workflows/push-test.yml b/.github/workflows/push-test.yml
index 5f83682dce..e8876d3c9b 100644
--- a/.github/workflows/push-test.yml
+++ b/.github/workflows/push-test.yml
@@ -102,16 +102,11 @@ jobs:
         run: ./scripts/check-skill-mdl.sh ./bin/mxcli docs-site/src
       - name: Setup mxbuild
         run: ./bin/mxcli setup mxbuild --version 11.12.2
-      # Per-push, the gate runs the DEFAULT engine only. The doctype gate hands
-      # every script to mxbuild once per engine and mxbuild dominates the cost,
-      # so the second engine is roughly half of this step. The legacy engine is
-      # still shipped and still selectable (--engine legacy), so it is not
-      # untested: the nightly runs the full matrix, across every Mendix version.
-      # Drop this env to bring legacy back to every push.
-      - name: "Integration tests (engines: modelsdk)"
+      # One engine since the legacy sdk/mpr backend was deleted
+      # (docs/plans/2026-09-14-retire-legacy-engine.md), so there is no matrix to
+      # narrow here any more and MXCLI_TEST_ENGINES is left unset.
+      - name: Integration tests
         run: make test-integration
-        env:
-          MXCLI_TEST_ENGINES: modelsdk
         timeout-minutes: 30
       - name: Lint Go
         run: make lint-go
diff --git a/CLAUDE.md b/CLAUDE.md
index 4db6796754..13bb5bc623 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -614,7 +614,7 @@ New features that depend on a specific Mendix version must be version-gated:
 - [ ] **Skill updated** — `.claude/skills/version-awareness.md` updated if the feature has a workaround for older versions
 
 ### Backend abstraction compliance
-All executor code must go through the backend abstraction layer — the executor must never import `sdk/mpr` for write paths. See [ADR-0002: Backend Abstraction Layer](docs/13-decisions/0002-backend-abstraction.md) for the context and alternatives. The experimental `modelsdk` engine (behind `MXCLI_ENGINE`) routes **all** document types — domain models included — through the codec, not a codec/legacy hybrid; see [ADR-0004: Full codec engine](docs/13-decisions/0004-full-codec-engine.md). Where the codec path cannot yet reproduce a construct, the backend **refuses** the op rather than dropping data. The backend interface speaks the **semantic model**, not gen/BSON or AST types — gen+codec are the MPR backend's internal storage adapter, one of several (MPR, MCP/PED, a future storage format); see [ADR-0005](docs/13-decisions/0005-semantic-model-interface-currency.md). CREATE is model→gen; fidelity-sensitive ALTER uses backend-internal gen-mutation, not a model round-trip.
+All executor code must go through the backend abstraction layer — the executor must never import `sdk/mpr` for write paths. See [ADR-0002: Backend Abstraction Layer](docs/13-decisions/0002-backend-abstraction.md) for the context and alternatives. The codec (`modelsdk`) engine is the only local engine — the legacy `sdk/mpr` backend was deleted (`docs/plans/2026-09-14-retire-legacy-engine.md`), and `--engine`/`MXCLI_ENGINE` survive only as a warning-only no-op. It routes **all** document types — domain models included — through the codec, not a codec/legacy hybrid; see [ADR-0004: Full codec engine](docs/13-decisions/0004-full-codec-engine.md). Where the codec path cannot yet reproduce a construct, the backend **refuses** the op rather than dropping data. The backend interface speaks the **semantic model**, not gen/BSON or AST types — gen+codec are the MPR backend's internal storage adapter, one of several (MPR, MCP/PED, a future storage format); see [ADR-0005](docs/13-decisions/0005-semantic-model-interface-currency.md). CREATE is model→gen; fidelity-sensitive ALTER uses backend-internal gen-mutation, not a model round-trip.
 - [ ] **No `sdk/mpr` write imports in executor** — executor files must not call `sdk/mpr` writer/parser types directly; use `ctx.Backend.*` instead
 - [ ] **New backend methods on the interface** — any new data access or mutation goes in the appropriate interface in `mdl/backend/` (e.g., `DomainModelBackend`, `MicroflowBackend`), not as a direct SDK call
 - [ ] **MPR implementation in `mdl/backend/mpr/`** — the concrete implementation lives here; all BSON/reader/writer logic stays in this package
diff --git a/Makefile b/Makefile
index 054e1ead73..4bf9b66553 100644
--- a/Makefile
+++ b/Makefile
@@ -35,7 +35,7 @@ GO_BUILD_FLAGS = -trimpath
 # Clean version for VS Code extension (must be valid semver: major.minor.patch)
 VSCE_VERSION = $(shell echo "$(VERSION)" | sed 's/^v//; s/-.*//' | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$$' || echo "0.0.0")
 
-.PHONY: build build-debug size release clean test engine-diff test-mdl check-mdl check-skill-mdl check-findings check-wiki-pages digest-status check-tunnel-deps check-widget-versions grammar completions sync-skills sync-skill-packs sync-commands sync-lint-rules sync-changelog sync-all docs documentation docs-site docs-serve vscode-ext vscode-install source-tree sbom sbom-report lint lint-go lint-ts fmt fmt-check vet
+.PHONY: build build-debug size release clean test test-mdl check-mdl check-skill-mdl check-findings check-wiki-pages digest-status check-tunnel-deps check-widget-versions grammar completions sync-skills sync-skill-packs sync-commands sync-lint-rules sync-changelog sync-all docs documentation docs-site docs-serve vscode-ext vscode-install source-tree sbom sbom-report lint lint-go lint-ts fmt fmt-check vet
 
 # Helper: copy file only if content differs (avoids mtime updates that invalidate go build cache)
 # Usage: $(call copy-if-changed,src,dst)
@@ -167,12 +167,6 @@ release: clean grammar vscode-ext sync-all
 test: grammar sync-all
 	CGO_ENABLED=0 go test ./...
 
-# Dual-engine read-parity harness: run read queries through the legacy (sdk/mpr)
-# and modelsdk engines and diff the rendered output. The read-side of the
-# engine-adoption comparison gate (docs/plans/2026-06-05-adopt-modelsdk-engine.md).
-engine-diff: grammar
-	CGO_ENABLED=0 go test ./mdl/enginecompare/ -run TestReadParity -v
-
 # Check MDL syntax for all example scripts.
 #
 # Covers both doctype-tests/ (broad doctype demos) and bug-tests/ (per-PR
@@ -287,12 +281,10 @@ check-tunnel-deps:
 
 # Run integration tests (requires mx binary / mxbuild)
 #
-# The gate runs every doctype script through exec + mx check once PER ENGINE.
-# MXCLI_TEST_ENGINES narrows that matrix — `MXCLI_TEST_ENGINES=modelsdk make
-# test-integration` skips the legacy engine and takes roughly 60% off the
-# doctype gate (measured: 588s -> 232s). Unset means every engine, which is what
-# the nightly runs; the per-push CI job narrows it to modelsdk. An unrecognised
-# engine name is fatal rather than silently selecting nothing.
+# The gate runs every doctype script through exec + mx check once PER ENGINE,
+# and there is one engine since legacy was deleted. MXCLI_TEST_ENGINES is
+# therefore left unset everywhere; it survives only so that a stale
+# `MXCLI_TEST_ENGINES=legacy` is fatal rather than silently selecting nothing.
 test-integration:
 	CGO_ENABLED=0 go test -tags integration -count=1 -timeout 30m ./...
 
diff --git a/cmd/mxcli/cmd_bson.go b/cmd/mxcli/cmd_bson.go
index 0936ae0a92..86438470d4 100644
--- a/cmd/mxcli/cmd_bson.go
+++ b/cmd/mxcli/cmd_bson.go
@@ -7,13 +7,12 @@ import "github.com/spf13/cobra"
 var bsonCmd = &cobra.Command{
 	Use:   "bson",
 	Short: "BSON inspection and analysis tools",
-	Long: `Tools for analyzing, comparing, and discovering BSON field coverage
+	Long: `Tools for analyzing and discovering BSON field coverage
 in Mendix project files.
 
 Subcommands:
   dump      Dump raw BSON data as JSON or NDSL
-  discover  Analyze field coverage per $Type
-  compare   Diff two BSON objects`,
+  discover  Analyze field coverage per $Type`,
 }
 
 func init() {
@@ -22,5 +21,4 @@ func init() {
 	// Register subcommands
 	bsonCmd.AddCommand(bsonDumpCmd)
 	bsonCmd.AddCommand(discoverCmd)
-	bsonCmd.AddCommand(bsonCompareCmd)
 }
diff --git a/cmd/mxcli/cmd_bson_compare.go b/cmd/mxcli/cmd_bson_compare.go
deleted file mode 100644
index 230a88b370..0000000000
--- a/cmd/mxcli/cmd_bson_compare.go
+++ /dev/null
@@ -1,158 +0,0 @@
-package main
-
-import (
-	"fmt"
-	"os"
-
-	bsondebug "github.com/mendixlabs/mxcli/cmd/mxcli/bson"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
-	"github.com/spf13/cobra"
-	"go.mongodb.org/mongo-driver/bson"
-)
-
-var bsonCompareCmd = &cobra.Command{
-	Use:   "compare [name1] [name2]",
-	Short: "Compare two BSON objects for differences",
-	Long: `Compare two BSON objects from Mendix projects and display a structured diff.
-
-Supports same-project and cross-project comparison. By default, structural
-and layout fields ($ID, PersistentId, RelativeMiddlePoint, Size) are skipped.
-
-Examples:
-  # Compare two workflows in the same project
-  mxcli bson compare -p app.mpr --type workflow WF1 WF2
-
-  # Compare same workflow across two MPR files
-  mxcli bson compare -p app.mpr -p2 other.mpr --type workflow MyWorkflow
-
-  # Include structural fields in comparison
-  mxcli bson compare -p app.mpr --type workflow --all WF1 WF2
-`,
-	Args: cobra.RangeArgs(1, 2),
-	Run:  runBsonCompare,
-}
-
-func init() {
-	bsonCompareCmd.Flags().StringP("project", "p", "", "Path to first MPR project (required)")
-	bsonCompareCmd.Flags().String("p2", "", "Path to second MPR project (for cross-MPR comparison)")
-	bsonCompareCmd.Flags().String("type", "workflow", "Object type: workflow, page, microflow, nanoflow, enumeration, snippet, layout")
-	bsonCompareCmd.Flags().Bool("all", false, "Include structural/layout fields ($ID, PersistentId, etc.)")
-	bsonCompareCmd.Flags().String("format", "diff", "Output format: diff, ndsl")
-}
-
-func runBsonCompare(cmd *cobra.Command, args []string) {
-	projectPath, _ := cmd.Flags().GetString("project")
-	secondProject, _ := cmd.Flags().GetString("p2")
-	objectType, _ := cmd.Flags().GetString("type")
-	includeAll, _ := cmd.Flags().GetBool("all")
-
-	if projectPath == "" {
-		fmt.Fprintln(os.Stderr, "Error: --project (-p) is required")
-		os.Exit(1)
-	}
-
-	reader1, err := mpr.Open(projectPath)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "Error opening project: %v\n", err)
-		os.Exit(1)
-	}
-	defer reader1.Close()
-
-	var leftName, rightName string
-	var reader2 *mpr.Reader
-
-	switch len(args) {
-	case 2:
-		// Two names in the same (or different) project
-		leftName = args[0]
-		rightName = args[1]
-		if secondProject != "" {
-			reader2, err = mpr.Open(secondProject)
-			if err != nil {
-				fmt.Fprintf(os.Stderr, "Error opening second project: %v\n", err)
-				os.Exit(1)
-			}
-			defer reader2.Close()
-		}
-	case 1:
-		// One name, must have -p2 for cross-MPR comparison
-		if secondProject == "" {
-			fmt.Fprintln(os.Stderr, "Error: provide two names, or one name with -p2 for cross-MPR comparison")
-			os.Exit(1)
-		}
-		leftName = args[0]
-		rightName = args[0]
-		reader2, err = mpr.Open(secondProject)
-		if err != nil {
-			fmt.Fprintf(os.Stderr, "Error opening second project: %v\n", err)
-			os.Exit(1)
-		}
-		defer reader2.Close()
-	}
-
-	// If no second reader, use the first for both
-	rightReader := reader1
-	if reader2 != nil {
-		rightReader = reader2
-	}
-
-	// Fetch raw BSON
-	leftUnit, err := reader1.GetRawUnitByName(objectType, leftName)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "Error getting %s: %v\n", leftName, err)
-		os.Exit(1)
-	}
-
-	rightUnit, err := rightReader.GetRawUnitByName(objectType, rightName)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "Error getting %s: %v\n", rightName, err)
-		os.Exit(1)
-	}
-
-	// NDSL format: render both sides as normalized DSL for LLM-friendly comparison
-	format, _ := cmd.Flags().GetString("format")
-	if format == "ndsl" {
-		var leftDocD, rightDocD bson.D
-		if err := bson.Unmarshal(leftUnit.Contents, &leftDocD); err != nil {
-			fmt.Fprintf(os.Stderr, "Error parsing BSON for %s: %v\n", leftName, err)
-			os.Exit(1)
-		}
-		if err := bson.Unmarshal(rightUnit.Contents, &rightDocD); err != nil {
-			fmt.Fprintf(os.Stderr, "Error parsing BSON for %s: %v\n", rightName, err)
-			os.Exit(1)
-		}
-		fmt.Printf("=== LEFT: %s ===\n%s\n\n=== RIGHT: %s ===\n%s\n",
-			leftName, bsondebug.Render(leftDocD, 0),
-			rightName, bsondebug.Render(rightDocD, 0))
-		return
-	}
-
-	// Unmarshal to map[string]any
-	var leftDoc, rightDoc bson.M
-	if err := bson.Unmarshal(leftUnit.Contents, &leftDoc); err != nil {
-		fmt.Fprintf(os.Stderr, "Error parsing BSON for %s: %v\n", leftName, err)
-		os.Exit(1)
-	}
-	if err := bson.Unmarshal(rightUnit.Contents, &rightDoc); err != nil {
-		fmt.Fprintf(os.Stderr, "Error parsing BSON for %s: %v\n", rightName, err)
-		os.Exit(1)
-	}
-
-	// Compare
-	opts := bsondebug.CompareOptions{IncludeAll: includeAll}
-	diffs := bsondebug.Compare(leftDoc, rightDoc, opts)
-
-	// Print header
-	typeName := leftDoc["$Type"]
-	if typeName != nil {
-		fmt.Println(typeName)
-	}
-	if leftName == rightName {
-		fmt.Printf("  Comparing: %s (across two MPRs)\n\n", leftName)
-	} else {
-		fmt.Printf("  Comparing: %s vs %s\n\n", leftName, rightName)
-	}
-
-	// Print formatted output
-	fmt.Println(bsondebug.FormatDiffs(diffs))
-}
diff --git a/cmd/mxcli/engine.go b/cmd/mxcli/engine.go
index 2a131646ce..992d4ce567 100644
--- a/cmd/mxcli/engine.go
+++ b/cmd/mxcli/engine.go
@@ -10,63 +10,48 @@ import (
 	"github.com/mendixlabs/mxcli/mdl/backend"
 	mcpbackend "github.com/mendixlabs/mxcli/mdl/backend/mcp"
 	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
-	mprbackend "github.com/mendixlabs/mxcli/mdl/backend/mpr"
 )
 
-// engineKind selects which model engine backs the local FullBackend.
+// There is one local engine: the codec ("modelsdk") engine. The legacy sdk/mpr
+// backend it replaced is gone — see docs/plans/2026-09-14-retire-legacy-engine.md.
 //
-// This is the single selection seam for the engine swap described in
-// docs/plans/2026-06-05-adopt-modelsdk-engine.md. The codec engine ("modelsdk")
-// is now the default; "legacy" (sdk/mpr) remains an explicit fallback for the few
-// constructs the codec path doesn't yet write. SOAP `call web service` is no
-// longer among them — it was the last one this comment named, and the codec
-// engine now writes it at byte-parity with legacy (mdl/backend/modelsdk/
-// microflow_webservice_write.go).
-// "compare" is recognised so the contract is stable but still fails fast.
-type engineKind string
-
-const (
-	engineLegacy   engineKind = "legacy"   // sdk/mpr write path (explicit fallback)
-	engineModelSDK engineKind = "modelsdk" // roundtrip codec engine (default)
-	engineCompare  engineKind = "compare"  // run both engines, diff BSON (not yet wired)
-)
+// --engine and MXCLI_ENGINE survive as a NO-OP that warns, rather than being
+// removed outright, so a script or CI job pinning `legacy` keeps working and is
+// told once why its pin no longer means anything. Deleting the flag would fail
+// those runs at argument parsing with "unknown flag", which says nothing about
+// what changed or what to do. Remove the flag in a later release, once the
+// warning has had time to be seen.
+//
+// This is not the seam that selects the MCP backend: --mcp / --mcp-dial route
+// writes to a live Studio Pro independently of this flag, and always did.
 
 // globalEngineFlag holds the value of the --engine flag; it overrides the
 // MXCLI_ENGINE environment variable. Set in PersistentPreRun.
 var globalEngineFlag string
 
-// resolveEngine reads the active engine from --engine, then MXCLI_ENGINE,
-// defaulting to modelsdk. An unrecognised value is fatal so typos are loud.
-func resolveEngine() engineKind {
+// warnIfEngineRequested prints the deprecation once if the user asked for an
+// engine by name. Any value is accepted, including one that was never valid: the
+// point is to tell the user the setting is inert, and rejecting a typo in a
+// setting that no longer does anything would be a worse failure than ignoring it.
+func warnIfEngineRequested() {
 	v := strings.TrimSpace(globalEngineFlag)
+	from := "--engine"
 	if v == "" {
-		v = strings.TrimSpace(os.Getenv("MXCLI_ENGINE"))
+		v, from = strings.TrimSpace(os.Getenv("MXCLI_ENGINE")), "MXCLI_ENGINE"
 	}
-	switch engineKind(strings.ToLower(v)) {
-	case "", engineModelSDK:
-		return engineModelSDK
-	case engineLegacy:
-		return engineLegacy
-	case engineCompare:
-		return engineCompare
-	default:
-		fmt.Fprintf(os.Stderr, "mxcli: unknown MXCLI_ENGINE %q (expected: modelsdk, legacy, compare)\n", v)
-		os.Exit(2)
-		return engineModelSDK // unreachable
+	if v == "" || strings.EqualFold(v, "modelsdk") {
+		return
 	}
+	fmt.Fprintf(os.Stderr,
+		"mxcli: %s=%s is ignored — there is now one engine and it is always used.\n"+
+			"       The legacy sdk/mpr engine was removed; drop the setting from your scripts.\n",
+		from, v)
 }
 
-// newBackendFactory returns the FullBackend factory for the active engine.
-//
-// modelsdk (default) runs the codec engine: complete reads and writes, validated
-// at parity with legacy across the doctype suite. The legacy (sdk/mpr) engine is
-// the explicit fallback for the few constructs the codec path doesn't yet write
-// — select it with --engine legacy or
-// MXCLI_ENGINE=legacy. compare needs the run-both diff harness (not yet wired)
-// and fails fast. An unknown value was already rejected by resolveEngine.
+// newBackendFactory returns the FullBackend factory for this run.
 func newBackendFactory() func() backend.FullBackend {
-	// The MCP backend (live Studio Pro) is selected by --mcp / --mcp-dial,
-	// independent of MXCLI_ENGINE: writes route to Studio Pro, reads come from -p.
+	// The MCP backend (live Studio Pro) is selected by --mcp / --mcp-dial:
+	// writes route to Studio Pro, reads come from -p.
 	if globalMCPURL != "" {
 		url, dial := globalMCPURL, globalMCPDial
 		concordURL, concordDial := globalMCPConcord, globalMCPConcordDial
@@ -82,14 +67,6 @@ func newBackendFactory() func() backend.FullBackend {
 			return b
 		}
 	}
-	switch resolveEngine() {
-	case engineLegacy:
-		return func() backend.FullBackend { return mprbackend.New() }
-	case engineCompare:
-		fmt.Fprintln(os.Stderr, "mxcli: engine 'compare' requires the run-both diff harness (Phase 2 of "+
-			"docs/plans/2026-06-05-adopt-modelsdk-engine.md). Use 'modelsdk' (default) or 'legacy'.")
-		os.Exit(2)
-	}
-	// default: the codec (modelsdk) engine
+	warnIfEngineRequested()
 	return func() backend.FullBackend { return modelsdkbackend.New() }
 }
diff --git a/cmd/mxcli/main.go b/cmd/mxcli/main.go
index 5bdd8ef47d..a37f613177 100644
--- a/cmd/mxcli/main.go
+++ b/cmd/mxcli/main.go
@@ -163,11 +163,10 @@ Examples:
 			defer logger.Close()
 
 			r := repl.New(os.Stdin, os.Stdout)
-			// Honor MXCLI_ENGINE/--engine AND --mcp in interactive mode (the REPL
-			// defaulted to the legacy local .mpr backend and ignored both). The
-			// unified factory routes writes to the modelsdk engine or a live Studio
-			// Pro as configured. Must precede the auto-connect below, since CONNECT
-			// consumes the factory.
+			// Honor --mcp in interactive mode; the REPL ignored it and used its
+			// own local backend. The unified factory routes writes to the model
+			// engine or to a live Studio Pro as configured. Must precede the
+			// auto-connect below, since CONNECT consumes the factory.
 			r.SetBackendFactory(newBackendFactory())
 			r.SetTracer(mcpTracer())
 			r.SetLogger(logger)
@@ -317,7 +316,7 @@ func init() {
 	rootCmd.PersistentFlags().Bool("mcp-run", false, "After the command, start the app in Studio Pro via Concord (run_app) and print its URL (requires --mcp-concord)")
 	rootCmd.PersistentFlags().Bool("mcp-verbose", false, "Print each PED tool call the MCP backend makes (requires --mcp)")
 	rootCmd.PersistentFlags().Bool("mcp-trace", false, "Print each MDL command with the PED tool calls it makes (implies --mcp-verbose; requires --mcp)")
-	rootCmd.PersistentFlags().String("engine", "", "Model engine: modelsdk (default), legacy (fallback for unsupported writes). Overrides MXCLI_ENGINE.")
+	rootCmd.PersistentFlags().String("engine", "", "Deprecated and ignored: there is one model engine. Kept so scripts pinning the old one keep running.")
 	rootCmd.Flags().StringP("command", "c", "", "Execute MDL command(s) and exit")
 
 	// Check command flags
diff --git a/cmd/mxcli/marketplace/security_test.go b/cmd/mxcli/marketplace/security_test.go
index 1a57cce841..1325e0af05 100644
--- a/cmd/mxcli/marketplace/security_test.go
+++ b/cmd/mxcli/marketplace/security_test.go
@@ -11,21 +11,21 @@ import (
 
 	modelsdk "github.com/mendixlabs/mxcli"
 	"github.com/mendixlabs/mxcli/mdl/backend"
-	mprbackend "github.com/mendixlabs/mxcli/mdl/backend/mpr"
 	"go.mongodb.org/mongo-driver/bson"
 )
 
-// Both engines, because the reconcile they call is a separate implementation in
-// each (mdl/backend/modelsdk and sdk/mpr) and a marketplace update runs under
-// whichever --engine selects. A defect fixed in one of those parallel writers
-// stays latent in the other until something switches engines — which is how
-// mendixlabs/mxcli#1047 reached two engines at once.
+// This ran over both engines while the legacy sdk/mpr writer existed, because
+// the reconcile below was a separate implementation in each and a defect fixed
+// in one stayed latent in the other until something switched engines — which is
+// how mendixlabs/mxcli#1047 reached two engines at once. Legacy is gone
+// (docs/plans/2026-09-14-retire-legacy-engine.md), so that class of divergence
+// is gone with it and one entry remains. The loop is kept because these tests
+// read as a matrix and a second backend would otherwise have to reintroduce it.
 var engines = []struct {
 	name    string
 	backend func() backend.FullBackend
 }{
 	{"modelsdk", testBackend},
-	{"legacy", func() backend.FullBackend { return mprbackend.New() }},
 }
 
 // A marketplace update copies the incoming module's units in verbatim, so an
diff --git a/docs-site/src/reference/integration/create-message-definition-collection.md b/docs-site/src/reference/integration/create-message-definition-collection.md
index 934108c7a9..11d8d840a6 100644
--- a/docs-site/src/reference/integration/create-message-definition-collection.md
+++ b/docs-site/src/reference/integration/create-message-definition-collection.md
@@ -131,9 +131,6 @@ DROP MESSAGE DEFINITION COLLECTION module.Name;
 `DESCRIBE` emits re-executable MDL. `OR MODIFY` preserves the document UUID, so
 mappings bound to it keep resolving.
 
-Authoring requires the modelsdk engine; `MXCLI_ENGINE=legacy` refuses. Reading
-works on both.
-
 ## See Also
 
 [CREATE IMPORT MAPPING](create-import-mapping.md), [CREATE EXPORT MAPPING](create-export-mapping.md), [CREATE JSON STRUCTURE](create-json-structure.md)
diff --git a/docs-site/src/reference/navigation/menu.md b/docs-site/src/reference/navigation/menu.md
index 01fd650757..667f786664 100644
--- a/docs-site/src/reference/navigation/menu.md
+++ b/docs-site/src/reference/navigation/menu.md
@@ -124,10 +124,6 @@ line rather than dropping them silently:
 
 Re-running such output therefore loses that icon — visibly, not silently.
 
-**Authoring requires the default engine.** Under `MXCLI_ENGINE=legacy`,
-create/modify/drop refuse rather than writing a differently-shaped document. Reading
-(`DESCRIBE MENU`) works on both engines.
-
 ## See Also
 
 - [ALTER NAVIGATION](alter-navigation.md) — the menu inside a navigation profile
diff --git a/docs-site/src/reference/page/alter-layout.md b/docs-site/src/reference/page/alter-layout.md
index 0196f6edec..6bb19eef02 100644
--- a/docs-site/src/reference/page/alter-layout.md
+++ b/docs-site/src/reference/page/alter-layout.md
@@ -163,8 +163,6 @@ ALTER PAGE MyModule.Split {
 
 ## Notes
 
-- Layout authoring requires the default `modelsdk` engine; `--engine legacy`
-  refuses it.
 - `DESCRIBE LAYOUT` emits re-executable MDL, so it is the way to see what a
   layout currently contains before altering it.
 
diff --git a/docs-site/src/reference/page/create-layout.md b/docs-site/src/reference/page/create-layout.md
index 203060fcda..201a7ffa4a 100644
--- a/docs-site/src/reference/page/create-layout.md
+++ b/docs-site/src/reference/page/create-layout.md
@@ -192,8 +192,6 @@ CREATE PAGE MyModule.Dashboard
 - **A placeholder's name is API.** Pages bind to it as `Module.Layout.Name`.
   Renaming one unbinds every page that used it — those pages still build, and
   their content vanishes.
-- Layout authoring requires the default `modelsdk` engine; `--engine legacy`
-  refuses it.
 
 ## See Also
 
diff --git a/docs-wiki/bug-patterns/engine-divergence.md b/docs-wiki/bug-patterns/engine-divergence.md
index 567adbfa82..d5fecc29e9 100644
--- a/docs-wiki/bug-patterns/engine-divergence.md
+++ b/docs-wiki/bug-patterns/engine-divergence.md
@@ -12,6 +12,14 @@ sources:
 > ADR-0004 and framed in [[backend-abstraction]]; the per-field fixes live in the
 > findings. This page describes what goes wrong while two implementations exist.
 
+> **Historical, and deliberately kept.** The legacy `sdk/mpr` backend was deleted
+> in 2026-09 (docs/plans/2026-09-14-retire-legacy-engine.md), so no mxcli command
+> can hit this class today. The page stays because the *shape* outlives the pair:
+> the MCP/PED backend is a second implementation of the same interface, a third
+> storage format is anticipated by ADR-0005, and every lesson below is about what
+> happens when two implementations of one interface disagree. Read "the two
+> engines" as "any two backends".
+
 ## What this is
 
 The backend interface has two implementations — the legacy `sdk/mpr` writer and
diff --git a/docs/11-proposals/PROPOSAL_backend_strategy.md b/docs/11-proposals/PROPOSAL_backend_strategy.md
index 244d7124bb..1b94648bef 100644
--- a/docs/11-proposals/PROPOSAL_backend_strategy.md
+++ b/docs/11-proposals/PROPOSAL_backend_strategy.md
@@ -1,7 +1,12 @@
 ---
 title: Backend Strategy — adopt engalar's modelsdk base + multi-backend (MCP first)
-status: draft
+status: implemented
 date: 2026-05-31
+status-note: >
+  The modelsdk codec was adopted and is now the only local engine; the legacy sdk/mpr
+  backend this proposal treats as one of several was deleted by
+  docs/plans/2026-09-14-retire-legacy-engine.md. The multi-backend framing still holds —
+  MCP/PED is a live second backend — but read "legacy" here as history.
 author: Generated with Claude Code
 related:
   - PROPOSAL_mcp_backend
diff --git a/docs/plans/2026-06-05-adopt-modelsdk-engine.md b/docs/plans/2026-06-05-adopt-modelsdk-engine.md
index 7c501b7e7a..12219e65f1 100644
--- a/docs/plans/2026-06-05-adopt-modelsdk-engine.md
+++ b/docs/plans/2026-06-05-adopt-modelsdk-engine.md
@@ -1,7 +1,10 @@
 # Implementation Plan — Adopt the modelsdk engine on `main`, behind a feature flag with dual-engine comparison
 
 **Date:** 2026-06-05
-**Status:** Draft plan
+**Status:** Superseded — the engine was adopted and became the default; the legacy engine it was
+flagged against was then deleted by
+[`2026-09-14-retire-legacy-engine.md`](2026-09-14-retire-legacy-engine.md). Kept for the design
+record; the dual-engine and feature-flag machinery it describes no longer exists.
 **Implements:** the "vendor the engine into `main`" path from
 [`PROPOSAL_backend_strategy.md`](../11-proposals/PROPOSAL_backend_strategy.md) (Option 3 evolved
 into a sequencing plan) — *keep `main` canonical and our product surface intact; lift the one
diff --git a/docs/plans/2026-09-14-retire-legacy-engine.md b/docs/plans/2026-09-14-retire-legacy-engine.md
index 555d173c5a..fd25172b53 100644
--- a/docs/plans/2026-09-14-retire-legacy-engine.md
+++ b/docs/plans/2026-09-14-retire-legacy-engine.md
@@ -1,7 +1,11 @@
 # Implementation Plan — Retire the legacy engine
 
 **Date:** 2026-09-14
-**Status:** Draft plan
+**Status:** In progress — Phases 1, 2 and the api/ + MCP steps of Phase 3 have landed
+(2026-09-15). What remains is the rest of Phase 3 (the `cmd/mxcli` commands that hold a concrete
+`sdk/mpr` reader on purpose) and Phase 4 (the mongo-driver migration, which those gate).
+See [§7 What landed](#7-what-landed) for the record of what each phase actually did, including the
+two places the plan was wrong.
 **Continues:** [`2026-06-05-adopt-modelsdk-engine.md`](2026-06-05-adopt-modelsdk-engine.md), which
 stops at the cutover. That plan still reads as though `legacy` were the default; it is not, and has
 not been since the codec engine took over. This plan covers what the earlier one deferred to
@@ -229,3 +233,67 @@ expected to grow. Phase 3 is written to satisfy that rather than to migrate away
 4. Phase 3 is now sequenced in place (it was going to be a proposal until measuring it shrank it).
    Its first step — implementing the six methods the census attributes to `api/` and MCP — is
    independent of Phases 1–2 and could be done first or in parallel.
+
+---
+
+## 7. What landed
+
+Recorded as it happened, because two of the estimates in this plan turned out wrong in ways worth
+keeping.
+
+### Phase 3, out of order and smaller than sized (2026-09-15)
+
+Phase 3 was written as an `L` gated on "breaking a public API". Both were wrong, and the
+correction is the plan's main lesson:
+
+- **`api/` was one signature, not a rewrite.** It held a concrete `*mpr.Writer` and imported
+  `mdl/backend` zero times. Taking a `backend.FullBackend` instead (plus an `api.Open` that owns
+  its connection) routed the whole package through the abstraction, which made `AddAttribute` and
+  `UpdateAttribute` *reachable* and therefore worth implementing — the two methods the codec engine
+  had left to the stub because nothing called them through a backend value.
+- **`api/`'s integration suite had only ever skipped.** All ten tests pointed at a path that does
+  not exist in this repo, so `go test ./api/` was green and verified nothing — the #808 shape
+  again. Repointed at a committed fixture, with a missing fixture now fatal instead of a skip.
+- **The MCP backend composes this backend now.** It kept a concrete `*mpr.Reader` for three reads
+  the codec engine did not offer (`GetDomainModelByID`, `GetWorkflow`, `ListNavigationDocuments`);
+  implementing those let it hold a `backend.FullBackend` instead. It needed a new
+  `ConnectReadOnly`, because `Connect` opens read-write and MCP must not lock the file Studio Pro
+  owns.
+- **`Connect` had no test** — 190 in that package, not one called it — so the swap would have
+  landed unverified with the suite green. It has one now, with the read-only constraint proved by
+  a revert control.
+
+**The organising insight, which is the reusable part:** `unreachableUnimplemented` in
+`mdl/backend/modelsdk/unimplemented_reachability_test.go` is a **census of who bypasses the
+abstraction**, not dead interface surface. A method is on it *because* some caller reaches it while
+holding a concrete reader or writer, and unreachable *because* that caller does not use a backend
+value. So the list shrinks by closing a bypass, never by deleting methods. It went 11 entries
+lighter over these two steps (5 struck off), and what remains names exactly the work left in
+Phase 3: the `cmd/mxcli` bson/diag/extract-templates commands.
+
+### Phases 1 and 2 (2026-09-15)
+
+Went as written, at the sizes given. Three things the plan did not anticipate:
+
+- **`--engine` is a warning-only no-op, not a removal.** Deleting the flag would fail a script
+  pinning `legacy` at argument parsing with "unknown flag", which says nothing about what changed.
+  It now warns once and proceeds. `bson compare` was dropped outright, per the same decision round.
+- **`errUnimplemented` still told users to rerun on the deleted engine.** A runtime message
+  naming a fallback that no longer exists is worse than no fallback; it now asks for a bug report,
+  which is what reaching it actually means.
+- **`setupTestEnv` defaulted to the legacy engine**, so most of `mdl/executor`'s integration tests
+  were exercising the retired engine rather than the one users get. Deleting legacy moved them onto
+  the codec engine — coverage that was always intended and had silently not been happening.
+- **One integration test had to go, and it named itself.** `TestCustomHandlerLegacyRefuses`
+  asserted that the legacy backend *refuses* a custom import-mapping handler rather than writing
+  `CustomHandlerCall` as nil and dropping the microflow silently. With no legacy engine there is no
+  refusal to assert, and the construct's positive coverage on the codec engine is intact, so the
+  test was deleted rather than repointed. It was the only failure across the whole executor
+  integration suite after the switch — 562s green, down from 642s now that the doctype gate runs
+  once instead of twice.
+- **The cross-engine tests split two ways.** `TestODataService_EngineWriteParity` compared two
+  writers; with one engine the comparison is vacuous, so the differential half was dropped and the
+  property it was a means to (a published service keeps its role grants, invisible to `mx check`)
+  kept as a single-engine test. The doctype gate's engine matrix was *not* deleted: with one entry
+  it still turns a stale `MXCLI_TEST_ENGINES=legacy` into a loud failure instead of a gate that
+  runs nothing and reports success.
diff --git a/examples/create_datagrid2_page/main.go b/examples/create_datagrid2_page/main.go
index 705c7c3d18..335d870e27 100644
--- a/examples/create_datagrid2_page/main.go
+++ b/examples/create_datagrid2_page/main.go
@@ -23,7 +23,7 @@ import (
 	"strings"
 
 	"github.com/mendixlabs/mxcli/mdl/backend"
-	mprbackend "github.com/mendixlabs/mxcli/mdl/backend/mpr"
+	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
 	"github.com/mendixlabs/mxcli/mdl/executor"
 	"github.com/mendixlabs/mxcli/mdl/visitor"
 )
@@ -53,7 +53,7 @@ func main() {
 
 	// Create the MDL executor with stdout for output
 	exec := executor.New(os.Stdout)
-	exec.SetBackendFactory(func() backend.FullBackend { return mprbackend.New() })
+	exec.SetBackendFactory(func() backend.FullBackend { return modelsdkbackend.New() })
 
 	// Define the MDL script to create a page with DataGrid2
 	// Note: Adjust module name, entity name, and attributes to match your project
diff --git a/examples/create_nanoflow/main.go b/examples/create_nanoflow/main.go
index a741303d24..1add329feb 100644
--- a/examples/create_nanoflow/main.go
+++ b/examples/create_nanoflow/main.go
@@ -18,7 +18,7 @@ import (
 	"strings"
 
 	"github.com/mendixlabs/mxcli/mdl/backend"
-	mprbackend "github.com/mendixlabs/mxcli/mdl/backend/mpr"
+	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
 	"github.com/mendixlabs/mxcli/mdl/executor"
 	"github.com/mendixlabs/mxcli/mdl/visitor"
 )
@@ -39,7 +39,7 @@ func main() {
 
 	// Create the MDL executor with stdout for output
 	exec := executor.New(os.Stdout)
-	exec.SetBackendFactory(func() backend.FullBackend { return mprbackend.New() })
+	exec.SetBackendFactory(func() backend.FullBackend { return modelsdkbackend.New() })
 
 	// Define MDL script with several nanoflow examples
 	mdlScript := fmt.Sprintf(`
diff --git a/mdl/backend/modelsdk/backend.go b/mdl/backend/modelsdk/backend.go
index a12d49e6ef..77766aece4 100644
--- a/mdl/backend/modelsdk/backend.go
+++ b/mdl/backend/modelsdk/backend.go
@@ -1,17 +1,20 @@
 // SPDX-License-Identifier: Apache-2.0
 
-// Package modelsdkbackend is the modelsdk-engine implementation of
-// backend.FullBackend. It lives at a separate import path from the legacy
-// mdl/backend/mpr (mprbackend) package so both engines can be linked at once
-// and selected via the MXCLI_ENGINE seam (see cmd/mxcli/engine.go).
+// Package modelsdkbackend is the codec-engine implementation of
+// backend.FullBackend, and the only local engine there is: the legacy
+// mdl/backend/mpr package it was written to replace has been deleted
+// (docs/plans/2026-09-14-retire-legacy-engine.md). Reads and writes are both
+// complete; --engine and MXCLI_ENGINE survive as a warning-only no-op so that
+// scripts pinning the old engine keep working.
 //
-// Phase 1 (docs/plans/2026-06-05-adopt-modelsdk-engine.md) is a READ slice:
-// it embeds *mock.MockBackend so the full 27-interface FullBackend surface is
-// satisfied, and overrides only the connection + module read methods to drive
-// the real modelsdk codec engine. Un-overridden methods fall through to the
-// mock stubs (which return zero/nil and never panic). Write methods are NOT
-// implemented yet — callers must not rely on them persisting; the CLI prints a
-// read-only warning when this engine is selected.
+// It embeds the generated `unimplemented` (gen_unimplemented.go) so the whole
+// FullBackend surface is satisfied, and every method it has not ported fails
+// loudly with errUnimplemented rather than silently returning a zero value. The
+// set that still falls through is pinned by
+// unimplemented_reachability_test.go, which is worth reading as a map: each
+// entry is there because some caller reaches that method while holding a
+// concrete sdk/mpr reader instead of a backend value, so the list shrinks by
+// closing a bypass rather than by deleting interface surface.
 package modelsdkbackend
 
 import (
@@ -56,8 +59,17 @@ func New() *Backend {
 // errUnimplemented is the error every not-yet-ported FullBackend method returns
 // (via the generated unimplemented embed). Loud failure beats the silent no-op
 // the embedded mock used to give — see ADR-0005 "guard, don't silently drop".
+//
+// It used to end "rerun with MXCLI_ENGINE=legacy". That engine is gone, so the
+// message now asks for a report instead of naming a fallback that does not
+// exist: a user told to rerun on a deleted engine learns nothing and gets a
+// second failure. Reaching this at all is a bug rather than a known gap — the
+// set of methods that can is pinned by unimplemented_reachability_test.go and
+// measured to have no caller through a backend value.
 func errUnimplemented(method string) error {
-	return fmt.Errorf("modelsdk engine: %s not implemented yet — rerun with MXCLI_ENGINE=legacy", method)
+	return fmt.Errorf("mxcli: %s is not implemented on the model engine. "+
+		"This should be unreachable — please report it at "+
+		"https://github.com/mendixlabs/mxcli/issues with the command you ran", method)
 }
 
 // WriteStats reports how many unit writes reached storage versus how many were
diff --git a/mdl/backend/modelsdk/units.go b/mdl/backend/modelsdk/units.go
index 9bdc5bf1b7..d223f8968d 100644
--- a/mdl/backend/modelsdk/units.go
+++ b/mdl/backend/modelsdk/units.go
@@ -21,10 +21,10 @@ func (b *Backend) GetRawUnit(id model.ID) (map[string]any, error) {
 }
 
 // GetRawUnitBytes returns a unit's raw BSON. Both this and UpdateRawUnit already
-// existed on the reader/writer and are used throughout this package; they were simply
-// never exposed as Backend methods, so the embedded `unimplemented` stub answered and
-// every caller going through the interface got "not implemented yet — rerun with
-// MXCLI_ENGINE=legacy". That is what gated `mxcli widget sync --apply` to the legacy
+// existed on the reader/writer and are used throughout this package; they were
+// simply never exposed as Backend methods, so the embedded `unimplemented` stub
+// answered and every caller going through the interface was told to fall back to
+// the legacy engine. That is what gated `mxcli widget sync --apply` to that
 // engine while its read-only plan ran on both.
 func (b *Backend) GetRawUnitBytes(id model.ID) ([]byte, error) {
 	return b.reader.GetRawUnitBytes(string(id))
diff --git a/mdl/backend/modelsdk/widget_write_legacy_gaps.go b/mdl/backend/modelsdk/widget_write_legacy_gaps.go
index 328a5d8def..dc1042bbcc 100644
--- a/mdl/backend/modelsdk/widget_write_legacy_gaps.go
+++ b/mdl/backend/modelsdk/widget_write_legacy_gaps.go
@@ -9,10 +9,12 @@ import (
 	"github.com/mendixlabs/mxcli/sdk/pages"
 )
 
-// The last widgets that sent a user to `MXCLI_ENGINE=legacy`.
+// The last widgets that sent a user to the legacy engine, now deleted
+// (docs/plans/2026-09-14-retire-legacy-engine.md). Closing these was one of its
+// preconditions, which is why the file is named for them.
 //
-// Every "not yet supported by the modelsdk engine" message is a reason the
-// legacy engine has to stay shipped and tested. Measured against sdk/pages, the
+// Every "not yet supported by the modelsdk engine" message was a reason the
+// legacy engine had to stay shipped and tested. Measured against sdk/pages, the
 // reachable set was five, not the twenty-three a name-based scan suggests:
 // nineteen widget structs are never constructed by the executor at all, and two
 // of the three remaining data-source / client-action gaps (EntityPathSource,
diff --git a/mdl/backend/mpr/backend.go b/mdl/backend/mpr/backend.go
deleted file mode 100644
index 8b03cbadee..0000000000
--- a/mdl/backend/mpr/backend.go
+++ /dev/null
@@ -1,1163 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-// Package mprbackend provides the MprBackend implementation of
-// backend.FullBackend. The package name is "mprbackend" (not "mpr") to
-// avoid collision with the sdk/mpr package in import blocks.
-package mprbackend
-
-import (
-	"errors"
-	"fmt"
-
-	"github.com/mendixlabs/mxcli/mdl/backend"
-	"github.com/mendixlabs/mxcli/mdl/linter"
-	"github.com/mendixlabs/mxcli/mdl/types"
-	"github.com/mendixlabs/mxcli/model"
-	"github.com/mendixlabs/mxcli/sdk/agenteditor"
-	"github.com/mendixlabs/mxcli/sdk/domainmodel"
-	"github.com/mendixlabs/mxcli/sdk/javaactions"
-	"github.com/mendixlabs/mxcli/sdk/microflows"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
-	"github.com/mendixlabs/mxcli/sdk/pages"
-	"github.com/mendixlabs/mxcli/sdk/security"
-	"github.com/mendixlabs/mxcli/sdk/workflows"
-)
-
-var _ backend.FullBackend = (*MprBackend)(nil)
-var _ linter.LintReader = (*MprBackend)(nil)
-var _ backend.WriteStatsReporter = (*MprBackend)(nil)
-
-// MprBackend implements backend.FullBackend by delegating to mpr.Reader
-// and mpr.Writer.
-//
-// Methods that access reader or writer assume Connect() has been called.
-// Calling read/write methods before Connect() will panic with a nil
-// pointer dereference. The executor enforces connection state via
-// ConnectionBackend.IsConnected() before dispatching handlers.
-type MprBackend struct {
-	reader *mpr.Reader
-	writer *mpr.Writer
-	path   string
-}
-
-// New creates a new unconnected MprBackend. Call Connect(path) to open a project.
-func New() *MprBackend {
-	return &MprBackend{}
-}
-
-// Wrap creates an MprBackend that wraps an existing Writer (and its Reader).
-// This is used during migration when the Executor already owns the Writer
-// and we want to expose it through the Backend interface without opening
-// a second connection.
-func Wrap(writer *mpr.Writer, path string) *MprBackend {
-	return &MprBackend{
-		reader: writer.Reader(),
-		writer: writer,
-		path:   path,
-	}
-}
-
-// WriteStats reports how many unit writes reached storage versus how many were
-// elided as no-ops (ADR-0008). Zero before Connect, and after Disconnect the
-// writer is gone with its counters — a caller sampling across a statement holds
-// the connection open for both reads.
-func (b *MprBackend) WriteStats() backend.WriteStats {
-	if b.writer == nil {
-		return backend.WriteStats{}
-	}
-	offered, written := b.writer.WriteStats()
-	return backend.WriteStats{Offered: offered, Written: written}
-}
-
-// ---------------------------------------------------------------------------
-// ConnectionBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) Connect(path string) error {
-	w, err := mpr.NewWriter(path)
-	if err != nil {
-		return err
-	}
-	b.writer = w
-	b.reader = w.Reader()
-	b.path = path
-	return nil
-}
-
-func (b *MprBackend) Disconnect() error {
-	if b.writer == nil {
-		return nil
-	}
-	err := b.writer.Close()
-	b.writer = nil
-	b.reader = nil
-	b.path = ""
-	return err
-}
-
-func (b *MprBackend) IsConnected() bool { return b.writer != nil }
-func (b *MprBackend) Path() string      { return b.path }
-
-// MprReader returns the underlying *mpr.Reader for callers that still
-// require direct SDK access (e.g. linter rules). Prefer Backend methods
-// for new code.
-func (b *MprBackend) MprReader() *mpr.Reader { return b.reader }
-
-func (b *MprBackend) Version() types.MPRVersion { return convertMPRVersion(b.reader.Version()) }
-func (b *MprBackend) ProjectVersion() *types.ProjectVersion {
-	return b.reader.ProjectVersion()
-}
-func (b *MprBackend) GetMendixVersion() (string, error) { return b.reader.GetMendixVersion() }
-
-// Commit is a no-op — the MPR writer auto-commits on each write operation.
-func (b *MprBackend) Commit() error { return nil }
-
-// ---------------------------------------------------------------------------
-// ModuleBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListModules() ([]*model.Module, error)        { return b.reader.ListModules() }
-func (b *MprBackend) GetModule(id model.ID) (*model.Module, error) { return b.reader.GetModule(id) }
-func (b *MprBackend) GetModuleByName(name string) (*model.Module, error) {
-	return b.reader.GetModuleByName(name)
-}
-func (b *MprBackend) CreateModule(module *model.Module) error { return b.writer.CreateModule(module) }
-func (b *MprBackend) UpdateModule(module *model.Module) error { return b.writer.UpdateModule(module) }
-func (b *MprBackend) DeleteModule(id model.ID) error          { return b.writer.DeleteModule(id) }
-func (b *MprBackend) DeleteModuleWithCleanup(id model.ID, moduleName string) error {
-	return b.writer.DeleteModuleWithCleanup(id, moduleName)
-}
-
-// ---------------------------------------------------------------------------
-// ModuleSettingsBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListModuleSettings() ([]*types.ModuleSettings, error) {
-	return b.reader.ListModuleSettings()
-}
-func (b *MprBackend) GetModuleSettings(moduleID model.ID) (*types.ModuleSettings, error) {
-	return b.reader.GetModuleSettings(moduleID)
-}
-func (b *MprBackend) UpdateModuleSettings(ms *types.ModuleSettings) error {
-	return b.writer.UpdateModuleSettings(ms)
-}
-
-// ---------------------------------------------------------------------------
-// FolderBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListFolders() ([]*types.FolderInfo, error) {
-	return convertFolderInfoSlice(b.reader.ListFolders())
-}
-func (b *MprBackend) CreateFolder(folder *model.Folder) error { return b.writer.CreateFolder(folder) }
-func (b *MprBackend) DeleteFolder(id model.ID) error          { return b.writer.DeleteFolder(id) }
-func (b *MprBackend) MoveFolder(id model.ID, newContainerID model.ID) error {
-	return b.writer.MoveFolder(id, newContainerID)
-}
-
-// ---------------------------------------------------------------------------
-// DocumentPlacementBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) MoveDocument(unitID, containerID model.ID) error {
-	return b.writer.MoveDocument(unitID, containerID)
-}
-
-func (b *MprBackend) FindDocumentUnit(moduleName, name string) (*types.DocumentUnit, error) {
-	return b.writer.FindDocumentUnit(moduleName, name)
-}
-
-func (b *MprBackend) ListDocumentUnits() ([]*types.DocumentUnit, error) {
-	return b.writer.ListDocumentUnits()
-}
-
-// ---------------------------------------------------------------------------
-// DomainModelBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListDomainModels() ([]*domainmodel.DomainModel, error) {
-	return b.reader.ListDomainModels()
-}
-func (b *MprBackend) GetDomainModel(moduleID model.ID) (*domainmodel.DomainModel, error) {
-	return b.reader.GetDomainModel(moduleID)
-}
-func (b *MprBackend) GetDomainModelByID(id model.ID) (*domainmodel.DomainModel, error) {
-	return b.reader.GetDomainModelByID(id)
-}
-func (b *MprBackend) SetDomainModelAnnotations(domainModelID model.ID, annotations []*domainmodel.Annotation) error {
-	dm, err := b.GetDomainModelByID(domainModelID)
-	if err != nil {
-		return err
-	}
-	dm.Annotations = annotations
-	return b.writer.UpdateDomainModel(dm)
-}
-
-func (b *MprBackend) UpdateDomainModel(dm *domainmodel.DomainModel) error {
-	return b.writer.UpdateDomainModel(dm)
-}
-
-func (b *MprBackend) CreateEntity(domainModelID model.ID, entity *domainmodel.Entity) error {
-	return b.writer.CreateEntity(domainModelID, entity)
-}
-func (b *MprBackend) UpdateEntity(domainModelID model.ID, entity *domainmodel.Entity) error {
-	return b.writer.UpdateEntity(domainModelID, entity)
-}
-func (b *MprBackend) DeleteEntity(domainModelID model.ID, entityID model.ID) error {
-	return b.writer.DeleteEntity(domainModelID, entityID)
-}
-func (b *MprBackend) MoveEntity(entity *domainmodel.Entity, sourceDMID, targetDMID model.ID, sourceModuleName, targetModuleName string) ([]string, error) {
-	return b.writer.MoveEntity(entity, sourceDMID, targetDMID, sourceModuleName, targetModuleName)
-}
-
-func (b *MprBackend) AddAttribute(domainModelID model.ID, entityID model.ID, attr *domainmodel.Attribute) error {
-	return b.writer.AddAttribute(domainModelID, entityID, attr)
-}
-func (b *MprBackend) UpdateAttribute(domainModelID model.ID, entityID model.ID, attr *domainmodel.Attribute) error {
-	return b.writer.UpdateAttribute(domainModelID, entityID, attr)
-}
-func (b *MprBackend) DeleteAttribute(domainModelID model.ID, entityID model.ID, attrID model.ID) error {
-	return b.writer.DeleteAttribute(domainModelID, entityID, attrID)
-}
-
-func (b *MprBackend) CreateAssociation(domainModelID model.ID, assoc *domainmodel.Association) error {
-	return b.writer.CreateAssociation(domainModelID, assoc)
-}
-func (b *MprBackend) CreateCrossAssociation(domainModelID model.ID, ca *domainmodel.CrossModuleAssociation) error {
-	return b.writer.CreateCrossAssociation(domainModelID, ca)
-}
-func (b *MprBackend) DeleteAssociation(domainModelID model.ID, assocID model.ID) error {
-	return b.writer.DeleteAssociation(domainModelID, assocID)
-}
-func (b *MprBackend) DeleteCrossAssociation(domainModelID model.ID, assocID model.ID) error {
-	return b.writer.DeleteCrossAssociation(domainModelID, assocID)
-}
-
-func (b *MprBackend) CreateViewEntitySourceDocument(moduleID model.ID, moduleName, docName, oqlQuery, documentation string) (model.ID, error) {
-	return b.writer.CreateViewEntitySourceDocument(moduleID, moduleName, docName, oqlQuery, documentation)
-}
-func (b *MprBackend) DeleteViewEntitySourceDocument(id model.ID) error {
-	return b.writer.DeleteViewEntitySourceDocument(id)
-}
-func (b *MprBackend) DeleteViewEntitySourceDocumentByName(moduleName, docName string) error {
-	return b.writer.DeleteViewEntitySourceDocumentByName(moduleName, docName)
-}
-func (b *MprBackend) FindViewEntitySourceDocumentID(moduleName, docName string) (model.ID, error) {
-	return b.writer.FindViewEntitySourceDocumentID(moduleName, docName)
-}
-func (b *MprBackend) FindAllViewEntitySourceDocumentIDs(moduleName, docName string) ([]model.ID, error) {
-	return b.writer.FindAllViewEntitySourceDocumentIDs(moduleName, docName)
-}
-func (b *MprBackend) MoveViewEntitySourceDocument(sourceModuleName string, targetModuleID model.ID, docName string) error {
-	return b.writer.MoveViewEntitySourceDocument(sourceModuleName, targetModuleID, docName)
-}
-func (b *MprBackend) UpdateOqlQueriesForMovedEntity(oldQualifiedName, newQualifiedName string) (int, error) {
-	return b.writer.UpdateOqlQueriesForMovedEntity(oldQualifiedName, newQualifiedName)
-}
-func (b *MprBackend) UpdateEnumerationRefsInAllDomainModels(oldQualifiedName, newQualifiedName string) error {
-	return b.writer.UpdateEnumerationRefsInAllDomainModels(oldQualifiedName, newQualifiedName)
-}
-
-// ---------------------------------------------------------------------------
-// MicroflowBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListMicroflows() ([]*microflows.Microflow, error) {
-	return b.reader.ListMicroflows()
-}
-func (b *MprBackend) GetMicroflow(id model.ID) (*microflows.Microflow, error) {
-	return b.reader.GetMicroflow(id)
-}
-func (b *MprBackend) CreateMicroflow(mf *microflows.Microflow) error {
-	return b.writer.CreateMicroflow(mf)
-}
-func (b *MprBackend) UpdateMicroflow(mf *microflows.Microflow) error {
-	return b.writer.UpdateMicroflow(mf)
-}
-func (b *MprBackend) DeleteMicroflow(id model.ID) error { return b.writer.DeleteMicroflow(id) }
-func (b *MprBackend) MoveMicroflow(mf *microflows.Microflow) error {
-	return b.writer.MoveMicroflow(mf)
-}
-func (b *MprBackend) IsRule(qualifiedName string) (bool, error) {
-	return b.reader.IsRule(qualifiedName)
-}
-
-func (b *MprBackend) ListNanoflows() ([]*microflows.Nanoflow, error) {
-	return b.reader.ListNanoflows()
-}
-func (b *MprBackend) ListRules() ([]*microflows.Rule, error) {
-	return b.reader.ListRules()
-}
-func (b *MprBackend) GetRule(id model.ID) (*microflows.Rule, error) {
-	return b.reader.GetRule(id)
-}
-func (b *MprBackend) ParseMicroflowFromRaw(raw map[string]any, unitID, containerID model.ID) *microflows.Microflow {
-	return mpr.ParseMicroflowFromRaw(raw, unitID, containerID)
-}
-func (b *MprBackend) ParseMicroflowBSON(contents []byte, unitID, containerID model.ID) (*microflows.Microflow, error) {
-	return mpr.ParseMicroflowBSON(contents, unitID, containerID)
-}
-func (b *MprBackend) GetNanoflow(id model.ID) (*microflows.Nanoflow, error) {
-	return b.reader.GetNanoflow(id)
-}
-func (b *MprBackend) CreateNanoflow(nf *microflows.Nanoflow) error {
-	return b.writer.CreateNanoflow(nf)
-}
-func (b *MprBackend) UpdateNanoflow(nf *microflows.Nanoflow) error {
-	return b.writer.UpdateNanoflow(nf)
-}
-func (b *MprBackend) DeleteNanoflow(id model.ID) error { return b.writer.DeleteNanoflow(id) }
-func (b *MprBackend) MoveNanoflow(nf *microflows.Nanoflow) error {
-	return b.writer.MoveNanoflow(nf)
-}
-
-// Rule authoring is modelsdk-only, like menus: the legacy serializer has no
-// serializeRule, and a rule document is close enough to a microflow that a
-// half-written one would look valid. Reads are implemented above.
-func (b *MprBackend) CreateRule(*microflows.Rule) error {
-	return errors.New("creating a rule requires the modelsdk engine — rerun without MXCLI_ENGINE=legacy")
-}
-func (b *MprBackend) UpdateRule(*microflows.Rule) error {
-	return errors.New("modifying a rule requires the modelsdk engine — rerun without MXCLI_ENGINE=legacy")
-}
-func (b *MprBackend) DeleteRule(model.ID) error {
-	return errors.New("dropping a rule requires the modelsdk engine — rerun without MXCLI_ENGINE=legacy")
-}
-func (b *MprBackend) MoveRule(*microflows.Rule) error {
-	return errors.New("moving a rule requires the modelsdk engine — rerun without MXCLI_ENGINE=legacy")
-}
-
-// Message definition collections are authored through gen+codec only, as rules,
-// menus and layouts are. The legacy writer has no serializer for the document
-// and building one would duplicate a shape the codec already gets right
-// (ako/mxcli#272). Reading works on both engines.
-
-func (b *MprBackend) CreateMessageDefinitionCollection(*model.MessageDefinitionCollection) error {
-	return errors.New("creating a message definition collection requires the modelsdk engine — rerun without MXCLI_ENGINE=legacy")
-}
-
-func (b *MprBackend) UpdateMessageDefinitionCollection(*model.MessageDefinitionCollection) error {
-	return errors.New("modifying a message definition collection requires the modelsdk engine — rerun without MXCLI_ENGINE=legacy")
-}
-
-func (b *MprBackend) DeleteMessageDefinitionCollection(string) error {
-	return errors.New("dropping a message definition collection requires the modelsdk engine — rerun without MXCLI_ENGINE=legacy")
-}
-
-// ---------------------------------------------------------------------------
-// PageBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListPages() ([]*pages.Page, error)        { return b.reader.ListPages() }
-func (b *MprBackend) GetPage(id model.ID) (*pages.Page, error) { return b.reader.GetPage(id) }
-func (b *MprBackend) CreatePage(page *pages.Page) error        { return b.writer.CreatePage(page) }
-func (b *MprBackend) UpdatePage(page *pages.Page) error        { return b.writer.UpdatePage(page) }
-func (b *MprBackend) DeletePage(id model.ID) error             { return b.writer.DeletePage(id) }
-func (b *MprBackend) MovePage(page *pages.Page) error          { return b.writer.MovePage(page) }
-
-func (b *MprBackend) ListLayouts() ([]*pages.Layout, error)        { return b.reader.ListLayouts() }
-func (b *MprBackend) GetLayout(id model.ID) (*pages.Layout, error) { return b.reader.GetLayout(id) }
-func (b *MprBackend) CreateLayout(layout *pages.Layout) error      { return b.writer.CreateLayout(layout) }
-func (b *MprBackend) UpdateLayout(layout *pages.Layout) error      { return b.writer.UpdateLayout(layout) }
-func (b *MprBackend) DeleteLayout(id model.ID) error               { return b.writer.DeleteLayout(id) }
-
-func (b *MprBackend) ListSnippets() ([]*pages.Snippet, error) { return b.reader.ListSnippets() }
-func (b *MprBackend) CreateSnippet(snippet *pages.Snippet) error {
-	return b.writer.CreateSnippet(snippet)
-}
-func (b *MprBackend) UpdateSnippet(snippet *pages.Snippet) error {
-	return b.writer.UpdateSnippet(snippet)
-}
-func (b *MprBackend) DeleteSnippet(id model.ID) error          { return b.writer.DeleteSnippet(id) }
-func (b *MprBackend) MoveSnippet(snippet *pages.Snippet) error { return b.writer.MoveSnippet(snippet) }
-
-func (b *MprBackend) ListBuildingBlocks() ([]*pages.BuildingBlock, error) {
-	return b.reader.ListBuildingBlocks()
-}
-func (b *MprBackend) ListPageTemplates() ([]*pages.PageTemplate, error) {
-	return b.reader.ListPageTemplates()
-}
-
-// ---------------------------------------------------------------------------
-// EnumerationBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListEnumerations() ([]*model.Enumeration, error) {
-	return b.reader.ListEnumerations()
-}
-func (b *MprBackend) GetEnumeration(id model.ID) (*model.Enumeration, error) {
-	return b.reader.GetEnumeration(id)
-}
-func (b *MprBackend) CreateEnumeration(enum *model.Enumeration) error {
-	return b.writer.CreateEnumeration(enum)
-}
-func (b *MprBackend) UpdateEnumeration(enum *model.Enumeration) error {
-	return b.writer.UpdateEnumeration(enum)
-}
-func (b *MprBackend) MoveEnumeration(enum *model.Enumeration) error {
-	return b.writer.MoveEnumeration(enum)
-}
-func (b *MprBackend) DeleteEnumeration(id model.ID) error { return b.writer.DeleteEnumeration(id) }
-
-// ---------------------------------------------------------------------------
-// ConstantBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListConstants() ([]*model.Constant, error) { return b.reader.ListConstants() }
-func (b *MprBackend) GetConstant(id model.ID) (*model.Constant, error) {
-	return b.reader.GetConstant(id)
-}
-func (b *MprBackend) CreateConstant(constant *model.Constant) error {
-	return b.writer.CreateConstant(constant)
-}
-func (b *MprBackend) UpdateConstant(constant *model.Constant) error {
-	return b.writer.UpdateConstant(constant)
-}
-func (b *MprBackend) MoveConstant(constant *model.Constant) error {
-	return b.writer.MoveConstant(constant)
-}
-func (b *MprBackend) DeleteConstant(id model.ID) error { return b.writer.DeleteConstant(id) }
-
-// ---------------------------------------------------------------------------
-// SecurityBackend (ProjectSecurityBackend + ModuleSecurityBackend + EntityAccessBackend)
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) GetProjectSecurity() (*security.ProjectSecurity, error) {
-	return b.reader.GetProjectSecurity()
-}
-func (b *MprBackend) SetProjectSecurityLevel(unitID model.ID, level string) error {
-	return b.writer.SetProjectSecurityLevel(unitID, level)
-}
-func (b *MprBackend) SetProjectDemoUsersEnabled(unitID model.ID, enabled bool) error {
-	return b.writer.SetProjectDemoUsersEnabled(unitID, enabled)
-}
-
-// SetProjectGuestAccess toggles anonymous (guest) access.
-func (b *MprBackend) SetProjectGuestAccess(unitID model.ID, enabled bool, guestUserRole string) error {
-	return b.writer.SetProjectGuestAccess(unitID, enabled, guestUserRole)
-}
-func (b *MprBackend) AddUserRole(unitID model.ID, name string, moduleRoles []string, manageAllRoles bool) error {
-	return b.writer.AddUserRole(unitID, name, moduleRoles, manageAllRoles)
-}
-func (b *MprBackend) AlterUserRoleModuleRoles(unitID model.ID, userRoleName string, add bool, moduleRoles []string) error {
-	return b.writer.AlterUserRoleModuleRoles(unitID, userRoleName, add, moduleRoles)
-}
-func (b *MprBackend) RemoveUserRole(unitID model.ID, name string) error {
-	return b.writer.RemoveUserRole(unitID, name)
-}
-func (b *MprBackend) AddDemoUser(unitID model.ID, userName, password, entity string, userRoles []string) error {
-	return b.writer.AddDemoUser(unitID, userName, password, entity, userRoles)
-}
-func (b *MprBackend) RemoveDemoUser(unitID model.ID, userName string) error {
-	return b.writer.RemoveDemoUser(unitID, userName)
-}
-
-func (b *MprBackend) ListModuleSecurity() ([]*security.ModuleSecurity, error) {
-	return b.reader.ListModuleSecurity()
-}
-func (b *MprBackend) GetModuleSecurity(moduleID model.ID) (*security.ModuleSecurity, error) {
-	return b.reader.GetModuleSecurity(moduleID)
-}
-func (b *MprBackend) AddModuleRole(unitID model.ID, roleName, description string) error {
-	return b.writer.AddModuleRole(unitID, roleName, description)
-}
-func (b *MprBackend) RemoveModuleRole(unitID model.ID, roleName string) error {
-	return b.writer.RemoveModuleRole(unitID, roleName)
-}
-func (b *MprBackend) RemoveModuleRoleFromAllUserRoles(unitID model.ID, qualifiedRole string) (int, error) {
-	return b.writer.RemoveModuleRoleFromAllUserRoles(unitID, qualifiedRole)
-}
-
-func (b *MprBackend) UpdateAllowedRoles(unitID model.ID, roles []string) error {
-	return b.writer.UpdateAllowedRoles(unitID, roles)
-}
-func (b *MprBackend) UpdatePublishedRestServiceRoles(unitID model.ID, roles []string) error {
-	return b.writer.UpdatePublishedRestServiceRoles(unitID, roles)
-}
-func (b *MprBackend) RemoveFromAllowedRoles(unitID model.ID, roleName string) (bool, error) {
-	return b.writer.RemoveFromAllowedRoles(unitID, roleName)
-}
-func (b *MprBackend) AddEntityAccessRule(params backend.EntityAccessRuleParams) error {
-	return b.writer.AddEntityAccessRule(params.UnitID, params.EntityName, params.RoleNames, params.AllowCreate, params.AllowDelete, params.DefaultMemberAccess, params.XPathConstraint, unconvertEntityMemberAccessSlice(params.MemberAccesses))
-}
-func (b *MprBackend) RemoveEntityAccessRule(unitID model.ID, entityName string, roleNames []string) (int, error) {
-	return b.writer.RemoveEntityAccessRule(unitID, entityName, roleNames)
-}
-func (b *MprBackend) RevokeEntityMemberAccess(unitID model.ID, entityName string, roleNames []string, revocation types.EntityAccessRevocation) (int, error) {
-	return b.writer.RevokeEntityMemberAccess(unitID, entityName, roleNames, unconvertEntityAccessRevocation(revocation))
-}
-func (b *MprBackend) RemoveRoleFromAllEntities(unitID model.ID, roleName string) (int, error) {
-	return b.writer.RemoveRoleFromAllEntities(unitID, roleName)
-}
-func (b *MprBackend) ReconcileMemberAccesses(unitID model.ID, moduleName string) (int, error) {
-	return b.writer.ReconcileMemberAccesses(unitID, moduleName)
-}
-
-// ---------------------------------------------------------------------------
-// NavigationBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListNavigationDocuments() ([]*types.NavigationDocument, error) {
-	return convertNavDocSlice(b.reader.ListNavigationDocuments())
-}
-func (b *MprBackend) GetNavigation() (*types.NavigationDocument, error) {
-	return convertNavDocPtr(b.reader.GetNavigation())
-}
-func (b *MprBackend) UpdateNavigationProfile(navDocID model.ID, profileName string, spec types.NavigationProfileSpec) error {
-	return b.writer.UpdateNavigationProfile(navDocID, profileName, unconvertNavProfileSpec(spec))
-}
-
-// ---------------------------------------------------------------------------
-// ServiceBackend (OData + REST + BusinessEvent + DatabaseConnection + DataTransformer)
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListConsumedODataServices() ([]*model.ConsumedODataService, error) {
-	return b.reader.ListConsumedODataServices()
-}
-func (b *MprBackend) ListPublishedODataServices() ([]*model.PublishedODataService, error) {
-	return b.reader.ListPublishedODataServices()
-}
-func (b *MprBackend) CreateConsumedODataService(svc *model.ConsumedODataService) error {
-	return b.writer.CreateConsumedODataService(svc)
-}
-func (b *MprBackend) UpdateConsumedODataService(svc *model.ConsumedODataService) error {
-	return b.writer.UpdateConsumedODataService(svc)
-}
-func (b *MprBackend) DeleteConsumedODataService(id model.ID) error {
-	return b.writer.DeleteConsumedODataService(id)
-}
-func (b *MprBackend) CreatePublishedODataService(svc *model.PublishedODataService) error {
-	return b.writer.CreatePublishedODataService(svc)
-}
-func (b *MprBackend) UpdatePublishedODataService(svc *model.PublishedODataService) error {
-	return b.writer.UpdatePublishedODataService(svc)
-}
-func (b *MprBackend) DeletePublishedODataService(id model.ID) error {
-	return b.writer.DeletePublishedODataService(id)
-}
-
-func (b *MprBackend) ListConsumedRestServices() ([]*model.ConsumedRestService, error) {
-	return b.reader.ListConsumedRestServices()
-}
-func (b *MprBackend) ListPublishedRestServices() ([]*model.PublishedRestService, error) {
-	return b.reader.ListPublishedRestServices()
-}
-func (b *MprBackend) CreateConsumedRestService(svc *model.ConsumedRestService) error {
-	return b.writer.CreateConsumedRestService(svc)
-}
-func (b *MprBackend) UpdateConsumedRestService(svc *model.ConsumedRestService) error {
-	return b.writer.UpdateConsumedRestService(svc)
-}
-func (b *MprBackend) DeleteConsumedRestService(id model.ID) error {
-	return b.writer.DeleteConsumedRestService(id)
-}
-func (b *MprBackend) CreatePublishedRestService(svc *model.PublishedRestService) error {
-	return b.writer.CreatePublishedRestService(svc)
-}
-func (b *MprBackend) UpdatePublishedRestService(svc *model.PublishedRestService) error {
-	return b.writer.UpdatePublishedRestService(svc)
-}
-func (b *MprBackend) DeletePublishedRestService(id model.ID) error {
-	return b.writer.DeletePublishedRestService(id)
-}
-
-func (b *MprBackend) ListBusinessEventServices() ([]*model.BusinessEventService, error) {
-	return b.reader.ListBusinessEventServices()
-}
-func (b *MprBackend) CreateBusinessEventService(svc *model.BusinessEventService) error {
-	return b.writer.CreateBusinessEventService(svc)
-}
-func (b *MprBackend) UpdateBusinessEventService(svc *model.BusinessEventService) error {
-	return b.writer.UpdateBusinessEventService(svc)
-}
-func (b *MprBackend) DeleteBusinessEventService(id model.ID) error {
-	return b.writer.DeleteBusinessEventService(id)
-}
-
-func (b *MprBackend) ListDatabaseConnections() ([]*model.DatabaseConnection, error) {
-	return b.reader.ListDatabaseConnections()
-}
-func (b *MprBackend) CreateDatabaseConnection(conn *model.DatabaseConnection) error {
-	return b.writer.CreateDatabaseConnection(conn)
-}
-func (b *MprBackend) UpdateDatabaseConnection(conn *model.DatabaseConnection) error {
-	return b.writer.UpdateDatabaseConnection(conn)
-}
-func (b *MprBackend) MoveDatabaseConnection(conn *model.DatabaseConnection) error {
-	return b.writer.MoveDatabaseConnection(conn)
-}
-func (b *MprBackend) MoveJavaAction(ja *javaactions.JavaAction) error {
-	if ja == nil {
-		return errors.New("MoveJavaAction: nil java action")
-	}
-	return b.writer.MoveUnitByID(string(ja.ID), string(ja.ContainerID))
-}
-func (b *MprBackend) MovePublishedODataService(svc *model.PublishedODataService) error {
-	if svc == nil {
-		return errors.New("MovePublishedODataService: nil service")
-	}
-	return b.writer.MoveUnitByID(string(svc.ID), string(svc.ContainerID))
-}
-func (b *MprBackend) DeleteDatabaseConnection(id model.ID) error {
-	return b.writer.DeleteDatabaseConnection(id)
-}
-
-func (b *MprBackend) ListDataTransformers() ([]*model.DataTransformer, error) {
-	return b.reader.ListDataTransformers()
-}
-func (b *MprBackend) CreateDataTransformer(dt *model.DataTransformer) error {
-	return b.writer.CreateDataTransformer(dt)
-}
-func (b *MprBackend) UpdateDataTransformer(dt *model.DataTransformer) error {
-	return b.writer.UpdateDataTransformer(dt)
-}
-func (b *MprBackend) DeleteDataTransformer(id model.ID) error {
-	return b.writer.DeleteDataTransformer(id)
-}
-
-// ---------------------------------------------------------------------------
-// MappingBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListImportMappings() ([]*model.ImportMapping, error) {
-	return b.reader.ListImportMappings()
-}
-func (b *MprBackend) GetImportMappingByQualifiedName(moduleName, name string) (*model.ImportMapping, error) {
-	return b.reader.GetImportMappingByQualifiedName(moduleName, name)
-}
-func (b *MprBackend) CreateImportMapping(im *model.ImportMapping) error {
-	if err := refuseCustomHandler(importElementsCarryCustomHandler(im.Elements)); err != nil {
-		return err
-	}
-	return b.writer.CreateImportMapping(im)
-}
-func (b *MprBackend) UpdateImportMapping(im *model.ImportMapping) error {
-	if err := refuseCustomHandler(importElementsCarryCustomHandler(im.Elements)); err != nil {
-		return err
-	}
-	return b.writer.UpdateImportMapping(im)
-}
-func (b *MprBackend) DeleteImportMapping(id model.ID) error {
-	return b.writer.DeleteImportMapping(id)
-}
-func (b *MprBackend) MoveImportMapping(im *model.ImportMapping) error {
-	return b.writer.MoveImportMapping(im)
-}
-
-func (b *MprBackend) ListExportMappings() ([]*model.ExportMapping, error) {
-	return b.reader.ListExportMappings()
-}
-func (b *MprBackend) GetExportMappingByQualifiedName(moduleName, name string) (*model.ExportMapping, error) {
-	return b.reader.GetExportMappingByQualifiedName(moduleName, name)
-}
-func (b *MprBackend) CreateExportMapping(em *model.ExportMapping) error {
-	if err := refuseCustomHandler(exportElementsCarryCustomHandler(em.Elements)); err != nil {
-		return err
-	}
-	return b.writer.CreateExportMapping(em)
-}
-func (b *MprBackend) UpdateExportMapping(em *model.ExportMapping) error {
-	if err := refuseCustomHandler(exportElementsCarryCustomHandler(em.Elements)); err != nil {
-		return err
-	}
-	return b.writer.UpdateExportMapping(em)
-}
-func (b *MprBackend) DeleteExportMapping(id model.ID) error {
-	return b.writer.DeleteExportMapping(id)
-}
-func (b *MprBackend) MoveExportMapping(em *model.ExportMapping) error {
-	return b.writer.MoveExportMapping(em)
-}
-
-// ListXmlSchemas delegates to the reader — there is nothing to convert, since
-// the semantic type IS what the reader returns.
-func (b *MprBackend) ListXmlSchemas() ([]*types.XmlSchema, error) {
-	return b.reader.ListXmlSchemas()
-}
-
-func (b *MprBackend) ListJsonStructures() ([]*types.JsonStructure, error) {
-	return convertJsonStructureSlice(b.reader.ListJsonStructures())
-}
-func (b *MprBackend) GetJsonStructureByQualifiedName(moduleName, name string) (*types.JsonStructure, error) {
-	return convertJsonStructurePtr(b.reader.GetJsonStructureByQualifiedName(moduleName, name))
-}
-func (b *MprBackend) CreateJsonStructure(js *types.JsonStructure) error {
-	return b.writer.CreateJsonStructure(unconvertJsonStructure(js))
-}
-func (b *MprBackend) UpdateJsonStructure(js *types.JsonStructure) error {
-	return b.writer.UpdateJsonStructure(unconvertJsonStructure(js))
-}
-func (b *MprBackend) DeleteJsonStructure(id string) error {
-	return b.writer.DeleteJsonStructure(id)
-}
-
-// ---------------------------------------------------------------------------
-// JavaBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListJavaActions() ([]*types.JavaAction, error) {
-	return convertJavaActionSlice(b.reader.ListJavaActions())
-}
-func (b *MprBackend) ListJavaActionsFull() ([]*javaactions.JavaAction, error) {
-	return b.reader.ListJavaActionsFull()
-}
-func (b *MprBackend) ListJavaScriptActions() ([]*types.JavaScriptAction, error) {
-	return convertJavaScriptActionSlice(b.reader.ListJavaScriptActions())
-}
-func (b *MprBackend) ReadJavaActionByName(qualifiedName string) (*javaactions.JavaAction, error) {
-	return b.reader.ReadJavaActionByName(qualifiedName)
-}
-func (b *MprBackend) ReadJavaScriptActionByName(qualifiedName string) (*types.JavaScriptAction, error) {
-	return convertJavaScriptActionPtr(b.reader.ReadJavaScriptActionByName(qualifiedName))
-}
-func (b *MprBackend) CreateJavaAction(ja *javaactions.JavaAction) error {
-	return b.writer.CreateJavaAction(ja)
-}
-func (b *MprBackend) UpdateJavaAction(ja *javaactions.JavaAction) error {
-	return b.writer.UpdateJavaAction(ja)
-}
-func (b *MprBackend) DeleteJavaAction(id model.ID) error {
-	return b.writer.DeleteJavaAction(id)
-}
-func (b *MprBackend) WriteJavaSourceFile(moduleName, actionName string, javaCode string, params []*javaactions.JavaActionParameter, returnType javaactions.CodeActionReturnType, extraImports []string, extraCode string) error {
-	return b.writer.WriteJavaSourceFile(moduleName, actionName, javaCode, params, returnType, extraImports, extraCode)
-}
-func (b *MprBackend) DeleteJavaSourceFile(moduleName, actionName string) error {
-	return b.writer.DeleteJavaSourceFile(moduleName, actionName)
-}
-func (b *MprBackend) RenameJavaSourceFile(moduleName, oldName, newName string) error {
-	return b.writer.RenameJavaSourceFile(moduleName, oldName, newName)
-}
-func (b *MprBackend) CreateJavaScriptAction(jsa *types.JavaScriptAction) error {
-	return b.writer.CreateJavaScriptAction(jsa)
-}
-func (b *MprBackend) UpdateJavaScriptAction(jsa *types.JavaScriptAction) error {
-	return b.writer.UpdateJavaScriptAction(jsa)
-}
-func (b *MprBackend) DeleteJavaScriptAction(id model.ID) error {
-	return b.writer.DeleteJavaScriptAction(id)
-}
-func (b *MprBackend) WriteJavaScriptSourceFile(moduleName, actionName string, jsCode string, params []*types.JavaActionParameter, returnType types.CodeActionReturnType) error {
-	return b.writer.WriteJavaScriptSourceFile(moduleName, actionName, jsCode, params, returnType)
-}
-func (b *MprBackend) DeleteJavaScriptSourceFile(moduleName, actionName string) error {
-	return b.writer.DeleteJavaScriptSourceFile(moduleName, actionName)
-}
-func (b *MprBackend) RenameJavaScriptSourceFile(moduleName, oldName, newName string) error {
-	return b.writer.RenameJavaScriptSourceFile(moduleName, oldName, newName)
-}
-
-// ReadJavaSourceFile delegates to writer because the mpr SDK places this
-// read operation on Writer (it needs write-transaction access to the
-// contents directory).
-func (b *MprBackend) ReadJavaSourceFile(moduleName, actionName string) (string, error) {
-	return b.writer.ReadJavaSourceFile(moduleName, actionName)
-}
-
-// ---------------------------------------------------------------------------
-// WorkflowBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListWorkflows() ([]*workflows.Workflow, error) {
-	return b.reader.ListWorkflows()
-}
-func (b *MprBackend) GetWorkflow(id model.ID) (*workflows.Workflow, error) {
-	return b.reader.GetWorkflow(id)
-}
-func (b *MprBackend) CreateWorkflow(wf *workflows.Workflow) error {
-	return b.writer.CreateWorkflow(wf)
-}
-func (b *MprBackend) UpdateWorkflow(wf *workflows.Workflow) error {
-	return b.writer.UpdateWorkflow(wf)
-}
-func (b *MprBackend) DeleteWorkflow(id model.ID) error { return b.writer.DeleteWorkflow(id) }
-
-// ---------------------------------------------------------------------------
-// SettingsBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) GetProjectSettings() (*model.ProjectSettings, error) {
-	return b.reader.GetProjectSettings()
-}
-
-// UpdateProjectSettings writes the settings, EXCEPT a changed enabled-language
-// list: the legacy serializer writes DefaultLanguageCode and carries Languages
-// through from the stored document, so a language added or removed here would be
-// dropped in silence — the run reporting "Enabled language: ar_SD" and nothing
-// landing. Refuse instead (guard-don't-drop, ADR-0005), the same way rule and
-// menu authoring is refused rather than half-written.
-//
-// The comparison is against what is stored, so every other settings write still
-// works on this engine.
-func (b *MprBackend) UpdateProjectSettings(ps *model.ProjectSettings) error {
-	if b.languagesWouldChange(ps) {
-		return errors.New("changing the enabled languages requires the modelsdk engine — " +
-			"rerun without MXCLI_ENGINE=legacy (the legacy serializer carries the language list " +
-			"through unchanged, so the write would be silently dropped)")
-	}
-	return b.writer.UpdateProjectSettings(ps)
-}
-
-// languagesWouldChange reports whether ps carries a different enabled-language
-// list than the stored document. A read failure answers false: refusing on a
-// question that could not be asked would block settings writes that have nothing
-// to do with languages.
-func (b *MprBackend) languagesWouldChange(ps *model.ProjectSettings) bool {
-	if ps == nil || ps.Language == nil {
-		return false
-	}
-	stored, err := b.reader.GetProjectSettings()
-	if err != nil || stored == nil || stored.Language == nil {
-		return false
-	}
-	if len(stored.Language.Languages) != len(ps.Language.Languages) {
-		return true
-	}
-	for i, l := range ps.Language.Languages {
-		if stored.Language.Languages[i] != l {
-			return true
-		}
-	}
-	return false
-}
-
-// ---------------------------------------------------------------------------
-// ImageBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListImageCollections() ([]*types.ImageCollection, error) {
-	return convertImageCollectionSlice(b.reader.ListImageCollections())
-}
-func (b *MprBackend) CreateImageCollection(ic *types.ImageCollection) error {
-	return b.writer.CreateImageCollection(unconvertImageCollection(ic))
-}
-func (b *MprBackend) UpdateImageCollection(ic *types.ImageCollection) error {
-	return b.writer.UpdateImageCollection(unconvertImageCollection(ic))
-}
-func (b *MprBackend) DeleteImageCollection(id string) error {
-	return b.writer.DeleteImageCollection(id)
-}
-func (b *MprBackend) ListIconCollections() ([]*types.IconCollection, error) {
-	return b.reader.ListIconCollections()
-}
-
-// ---------------------------------------------------------------------------
-// QueueBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListQueues() ([]*types.Queue, error) {
-	return b.reader.ListQueues()
-}
-func (b *MprBackend) CreateQueue(q *types.Queue) error {
-	return b.writer.CreateQueue(q)
-}
-func (b *MprBackend) UpdateQueue(q *types.Queue) error {
-	return b.writer.UpdateQueue(q)
-}
-func (b *MprBackend) DeleteQueue(id string) error {
-	return b.writer.DeleteQueue(id)
-}
-
-// ---------------------------------------------------------------------------
-// ScheduledEventBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListScheduledEvents() ([]*model.ScheduledEvent, error) {
-	return b.reader.ListScheduledEvents()
-}
-func (b *MprBackend) GetScheduledEvent(id model.ID) (*model.ScheduledEvent, error) {
-	return b.reader.GetScheduledEvent(id)
-}
-func (b *MprBackend) CreateScheduledEvent(ev *model.ScheduledEvent) error {
-	return b.writer.CreateScheduledEvent(ev)
-}
-func (b *MprBackend) UpdateScheduledEvent(ev *model.ScheduledEvent) error {
-	return b.writer.UpdateScheduledEvent(ev)
-}
-func (b *MprBackend) DeleteScheduledEvent(id string) error {
-	return b.writer.DeleteScheduledEvent(id)
-}
-
-// ---------------------------------------------------------------------------
-// RegularExpressionBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListRegularExpressions() ([]*model.RegularExpression, error) {
-	return b.reader.ListRegularExpressions()
-}
-func (b *MprBackend) CreateRegularExpression(re *model.RegularExpression) error {
-	return b.writer.CreateRegularExpression(re)
-}
-func (b *MprBackend) UpdateRegularExpression(re *model.RegularExpression) error {
-	return b.writer.UpdateRegularExpression(re)
-}
-func (b *MprBackend) DeleteRegularExpression(id string) error {
-	return b.writer.DeleteRegularExpression(id)
-}
-
-// ---------------------------------------------------------------------------
-// RenameBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) UpdateQualifiedNameInAllUnits(oldName, newName string) (int, error) {
-	return b.writer.UpdateQualifiedNameInAllUnits(oldName, newName)
-}
-func (b *MprBackend) RenameReferences(oldName, newName string, dryRun bool) ([]types.RenameHit, error) {
-	return convertRenameHitSlice(b.writer.RenameReferences(oldName, newName, dryRun))
-}
-func (b *MprBackend) RenameDocumentByName(moduleName, oldName, newName string) error {
-	return b.writer.RenameDocumentByName(moduleName, oldName, newName)
-}
-
-// ---------------------------------------------------------------------------
-// RawUnitBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) GetRawUnit(id model.ID) (map[string]any, error) {
-	return b.reader.GetRawUnit(id)
-}
-func (b *MprBackend) GetRawUnitBytes(id model.ID) ([]byte, error) {
-	return b.reader.GetRawUnitBytes(id)
-}
-func (b *MprBackend) ListRawUnitsByType(typePrefix string) ([]*types.RawUnit, error) {
-	return convertRawUnitSlice(b.reader.ListRawUnitsByType(typePrefix))
-}
-func (b *MprBackend) ListRawUnits(objectType string) ([]*types.RawUnitInfo, error) {
-	return convertRawUnitInfoSlice(b.reader.ListRawUnits(objectType))
-}
-func (b *MprBackend) GetRawUnitByName(objectType, qualifiedName string) (*types.RawUnitInfo, error) {
-	return convertRawUnitInfoPtr(b.reader.GetRawUnitByName(objectType, qualifiedName))
-}
-func (b *MprBackend) GetRawMicroflowByName(qualifiedName string) ([]byte, error) {
-	return b.reader.GetRawMicroflowByName(qualifiedName)
-}
-func (b *MprBackend) UpdateRawUnit(unitID string, contents []byte) error {
-	return b.writer.UpdateRawUnit(unitID, contents)
-}
-
-// UpdateRawUnitOwningTranslations writes a unit whose contents already account
-// for every translation in it. The legacy writer has no separate reconcile
-// option, so this is UpdateRawUnit — which is correct here because the legacy
-// path does not carry translations onto a raw write in the first place.
-func (b *MprBackend) UpdateRawUnitOwningTranslations(unitID string, contents []byte) error {
-	return b.writer.UpdateRawUnit(unitID, contents)
-}
-
-// ---------------------------------------------------------------------------
-// MetadataBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListAllUnitIDs() ([]string, error) { return b.reader.ListAllUnitIDs() }
-func (b *MprBackend) ListUnits() ([]*types.UnitInfo, error) {
-	return convertUnitInfoSlice(b.reader.ListUnits())
-}
-func (b *MprBackend) GetUnitTypes() (map[string]int, error) { return b.reader.GetUnitTypes() }
-func (b *MprBackend) GetProjectRootID() (string, error)     { return b.reader.GetProjectRootID() }
-func (b *MprBackend) ContentsDir() string                   { return b.reader.ContentsDir() }
-func (b *MprBackend) ExportJSON() ([]byte, error)           { return b.reader.ExportJSON() }
-func (b *MprBackend) InvalidateCache()                      { b.reader.InvalidateCache() }
-
-// ---------------------------------------------------------------------------
-// WidgetBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) FindCustomWidgetType(widgetID string) (*types.RawCustomWidgetType, error) {
-	return convertRawCustomWidgetTypePtr(b.reader.FindCustomWidgetType(widgetID))
-}
-func (b *MprBackend) FindAllCustomWidgetTypes(widgetID string) ([]*types.RawCustomWidgetType, error) {
-	return convertRawCustomWidgetTypeSlice(b.reader.FindAllCustomWidgetTypes(widgetID))
-}
-
-// ---------------------------------------------------------------------------
-// AgentEditorBackend
-// ---------------------------------------------------------------------------
-
-func (b *MprBackend) ListAgentEditorModels() ([]*agenteditor.Model, error) {
-	return b.reader.ListAgentEditorModels()
-}
-func (b *MprBackend) ListAgentEditorKnowledgeBases() ([]*agenteditor.KnowledgeBase, error) {
-	return b.reader.ListAgentEditorKnowledgeBases()
-}
-func (b *MprBackend) ListAgentEditorConsumedMCPServices() ([]*agenteditor.ConsumedMCPService, error) {
-	return b.reader.ListAgentEditorConsumedMCPServices()
-}
-func (b *MprBackend) ListAgentEditorAgents() ([]*agenteditor.Agent, error) {
-	return b.reader.ListAgentEditorAgents()
-}
-func (b *MprBackend) CreateAgentEditorModel(m *agenteditor.Model) error {
-	return b.writer.CreateAgentEditorModel(m)
-}
-func (b *MprBackend) UpdateAgentEditorModel(m *agenteditor.Model) error {
-	return b.writer.UpdateAgentEditorModel(m)
-}
-func (b *MprBackend) DeleteAgentEditorModel(id string) error {
-	return b.writer.DeleteAgentEditorModel(id)
-}
-func (b *MprBackend) CreateAgentEditorKnowledgeBase(k *agenteditor.KnowledgeBase) error {
-	return b.writer.CreateAgentEditorKnowledgeBase(k)
-}
-func (b *MprBackend) UpdateAgentEditorKnowledgeBase(k *agenteditor.KnowledgeBase) error {
-	return b.writer.UpdateAgentEditorKnowledgeBase(k)
-}
-func (b *MprBackend) DeleteAgentEditorKnowledgeBase(id string) error {
-	return b.writer.DeleteAgentEditorKnowledgeBase(id)
-}
-func (b *MprBackend) CreateAgentEditorConsumedMCPService(c *agenteditor.ConsumedMCPService) error {
-	return b.writer.CreateAgentEditorConsumedMCPService(c)
-}
-func (b *MprBackend) UpdateAgentEditorConsumedMCPService(c *agenteditor.ConsumedMCPService) error {
-	return b.writer.UpdateAgentEditorConsumedMCPService(c)
-}
-func (b *MprBackend) DeleteAgentEditorConsumedMCPService(id string) error {
-	return b.writer.DeleteAgentEditorConsumedMCPService(id)
-}
-func (b *MprBackend) CreateAgentEditorAgent(a *agenteditor.Agent) error {
-	return b.writer.CreateAgentEditorAgent(a)
-}
-func (b *MprBackend) UpdateAgentEditorAgent(a *agenteditor.Agent) error {
-	return b.writer.UpdateAgentEditorAgent(a)
-}
-func (b *MprBackend) DeleteAgentEditorAgent(id string) error {
-	return b.writer.DeleteAgentEditorAgent(id)
-}
-
-// ---------------------------------------------------------------------------
-// PageMutationBackend — implemented in page_mutator.go
-// ---------------------------------------------------------------------------
-
-// OpenPageForMutation is implemented in page_mutator.go.
-
-// ---------------------------------------------------------------------------
-// WorkflowMutationBackend
-
-// OpenWorkflowForMutation is implemented in workflow_mutator.go.
-func (b *MprBackend) OpenWorkflowForMutation(unitID model.ID) (backend.WorkflowMutator, error) {
-	return b.openWorkflowForMutation(unitID)
-}
-
-// ---------------------------------------------------------------------------
-// WidgetSerializationBackend
-
-func (b *MprBackend) SerializeWidget(w pages.Widget) (any, error) {
-	return mpr.SerializeWidget(w), nil
-}
-
-func (b *MprBackend) SerializeClientAction(a pages.ClientAction) (any, error) {
-	return mpr.SerializeClientAction(a), nil
-}
-
-func (b *MprBackend) SerializeDataSource(ds pages.DataSource) (any, error) {
-	return mpr.SerializeCustomWidgetDataSource(ds), nil
-}
-
-// useCallMicroflowActivityName reports whether the target project is Mendix 11.9+
-// and therefore expects the CallMicroflowActivity workflow storage name (see
-// sdk/mpr.renameCallMicroflowTypeBSON and FINDINGS #39).
-func (b *MprBackend) useCallMicroflowActivityName() bool {
-	pv := b.ProjectVersion()
-	return pv != nil && pv.IsAtLeast(11, 9)
-}
-
-func (b *MprBackend) SerializeWorkflowActivity(a workflows.WorkflowActivity) (any, error) {
-	return mpr.SerializeWorkflowActivity(a, b.useCallMicroflowActivityName()), nil
-}
-
-func (b *MprBackend) ListMenuDocuments() ([]*types.MenuDocument, error) {
-	return b.reader.ListMenuDocuments()
-}
-func (b *MprBackend) GetMenuDocumentByQualifiedName(moduleName, name string) (*types.MenuDocument, error) {
-	return b.reader.GetMenuDocumentByQualifiedName(moduleName, name)
-}
-
-// Menu-document writes are implemented on the modelsdk engine only. The legacy
-// writer builds menu items by hand with typed-array marker 1, which does not
-// match what Studio Pro stores in a menu document (3) — rather than ship a
-// second, differently-shaped writer, this refuses so the caller is told plainly.
-func (b *MprBackend) CreateMenuDocument(md *types.MenuDocument) error {
-	return errors.New("creating a menu requires the modelsdk engine — rerun without MXCLI_ENGINE=legacy")
-}
-func (b *MprBackend) UpdateMenuDocument(md *types.MenuDocument) error {
-	return errors.New("modifying a menu requires the modelsdk engine — rerun without MXCLI_ENGINE=legacy")
-}
-func (b *MprBackend) DeleteMenuDocument(id model.ID) error {
-	return errors.New("dropping a menu requires the modelsdk engine — rerun without MXCLI_ENGINE=legacy")
-}
-
-// ListMessageDefinitionCollections is not implemented on the legacy engine.
-//
-// The document has no legacy parser, and authoring a mapping over a message
-// definition (#263) is modelsdk-only for that reason — the codec models the
-// whole exposed tree already. Refuse rather than return an empty list: an empty
-// one reads as "this project has no message definitions", which would make the
-// executor report a real reference as unresolvable.
-func (b *MprBackend) ListMessageDefinitionCollections() ([]*model.MessageDefinitionCollection, error) {
-	return nil, errors.New("message definitions are not readable on the legacy engine — " +
-		"run without --engine legacy (the modelsdk engine is the default)")
-}
-
-// The legacy serializers write CustomHandlerCall as a hard-coded nil, so a
-// mapping whose object handling is Custom (#264) would be written WITHOUT its
-// microflow — a silent drop of the thing the statement was about. Refuse
-// instead (ADR-0005 guard-don't-drop); the modelsdk engine, which is the
-// default, writes it.
-func refuseCustomHandler(carries bool) error {
-	if !carries {
-		return nil
-	}
-	return errors.New("custom object handling (`by <microflow>`) requires the modelsdk engine — " +
-		"rerun without MXCLI_ENGINE=legacy")
-}
-
-func importElementsCarryCustomHandler(elems []*model.ImportMappingElement) bool {
-	for _, e := range elems {
-		if e == nil {
-			continue
-		}
-		if e.CustomHandler != nil || importElementsCarryCustomHandler(e.Children) {
-			return true
-		}
-	}
-	return false
-}
-
-func exportElementsCarryCustomHandler(elems []*model.ExportMappingElement) bool {
-	for _, e := range elems {
-		if e == nil {
-			continue
-		}
-		if e.CustomHandler != nil || exportElementsCarryCustomHandler(e.Children) {
-			return true
-		}
-	}
-	return false
-}
-
-// LayoutPlaceholders returns the placeholder names a layout declares. Shared
-// with the modelsdk engine: the walk is over the stored document, not over
-// either engine's element types.
-func (b *MprBackend) LayoutPlaceholders(id model.ID) ([]string, error) {
-	raw, err := b.reader.GetRawUnit(id)
-	if err != nil {
-		return nil, err
-	}
-	return backend.LayoutPlaceholderNames(raw), nil
-}
-
-// PageLayoutName returns the qualified name of the layout a page renders inside.
-func (b *MprBackend) PageLayoutName(id model.ID) (string, error) {
-	raw, err := b.reader.GetRawUnit(id)
-	if err != nil {
-		return "", err
-	}
-	return backend.PageLayoutNameFromRaw(raw), nil
-}
-
-// AddNavigationProfile is modelsdk-only. Creating a profile means writing a
-// fourteen-key Navigation$NavigationProfile whose shape is pinned against a
-// Studio Pro reference (see the modelsdk implementation); the legacy writer has
-// no such path, and a profile assembled from a guess is exactly the failure that
-// builds clean and will not open in Studio Pro. Refuse rather than approximate.
-func (b *MprBackend) AddNavigationProfile(_ model.ID, name string) error {
-	return fmt.Errorf("creating navigation profile %q needs the modelsdk engine "+
-		"(run without MXCLI_ENGINE=legacy)", name)
-}
diff --git a/mdl/backend/mpr/convert.go b/mdl/backend/mpr/convert.go
deleted file mode 100644
index 77a661ea38..0000000000
--- a/mdl/backend/mpr/convert.go
+++ /dev/null
@@ -1,420 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-package mprbackend
-
-import (
-	"github.com/mendixlabs/mxcli/mdl/types"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
-)
-
-// ---------------------------------------------------------------------------
-// Conversion helpers: sdk/mpr -> mdl/types
-// ---------------------------------------------------------------------------
-
-func convertMPRVersion(v mpr.MPRVersion) types.MPRVersion { return types.MPRVersion(v) }
-
-func convertFolderInfoSlice(in []*mpr.FolderInfo, err error) ([]*types.FolderInfo, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	out := make([]*types.FolderInfo, len(in))
-	for i, f := range in {
-		out[i] = &types.FolderInfo{ID: f.ID, ContainerID: f.ContainerID, Name: f.Name}
-	}
-	return out, nil
-}
-
-func convertUnitInfoSlice(in []*mpr.UnitInfo, err error) ([]*types.UnitInfo, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	out := make([]*types.UnitInfo, len(in))
-	for i, u := range in {
-		out[i] = &types.UnitInfo{
-			ID: u.ID, ContainerID: u.ContainerID,
-			ContainmentName: u.ContainmentName, Type: u.Type,
-		}
-	}
-	return out, nil
-}
-
-func convertRenameHitSlice(in []mpr.RenameHit, err error) ([]types.RenameHit, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	out := make([]types.RenameHit, len(in))
-	for i, h := range in {
-		out[i] = types.RenameHit{UnitID: h.UnitID, UnitType: h.UnitType, Name: h.Name, Count: h.Count}
-	}
-	return out, nil
-}
-
-func convertRawUnitSlice(in []*mpr.RawUnit, err error) ([]*types.RawUnit, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	out := make([]*types.RawUnit, len(in))
-	for i, r := range in {
-		out[i] = &types.RawUnit{
-			ID: r.ID, ContainerID: r.ContainerID, Type: r.Type, Contents: r.Contents,
-		}
-	}
-	return out, nil
-}
-
-func convertRawUnitInfoSlice(in []*mpr.RawUnitInfo, err error) ([]*types.RawUnitInfo, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	out := make([]*types.RawUnitInfo, len(in))
-	for i, r := range in {
-		out[i] = &types.RawUnitInfo{
-			ID: r.ID, QualifiedName: r.QualifiedName, Type: r.Type,
-			ModuleName: r.ModuleName, Contents: r.Contents,
-		}
-	}
-	return out, nil
-}
-
-func convertRawUnitInfoPtr(in *mpr.RawUnitInfo, err error) (*types.RawUnitInfo, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	return &types.RawUnitInfo{
-		ID: in.ID, QualifiedName: in.QualifiedName, Type: in.Type,
-		ModuleName: in.ModuleName, Contents: in.Contents,
-	}, nil
-}
-
-func convertRawCustomWidgetTypePtr(in *mpr.RawCustomWidgetType, err error) (*types.RawCustomWidgetType, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	return &types.RawCustomWidgetType{
-		WidgetID: in.WidgetID, RawType: in.RawType, RawObject: in.RawObject,
-		UnitID: in.UnitID, UnitName: in.UnitName, WidgetName: in.WidgetName,
-	}, nil
-}
-
-func convertRawCustomWidgetTypeSlice(in []*mpr.RawCustomWidgetType, err error) ([]*types.RawCustomWidgetType, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	out := make([]*types.RawCustomWidgetType, len(in))
-	for i, w := range in {
-		out[i] = &types.RawCustomWidgetType{
-			WidgetID: w.WidgetID, RawType: w.RawType, RawObject: w.RawObject,
-			UnitID: w.UnitID, UnitName: w.UnitName, WidgetName: w.WidgetName,
-		}
-	}
-	return out, nil
-}
-
-func convertJavaActionSlice(in []*mpr.JavaAction, err error) ([]*types.JavaAction, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	out := make([]*types.JavaAction, len(in))
-	for i, ja := range in {
-		out[i] = &types.JavaAction{
-			BaseElement:   ja.BaseElement,
-			ContainerID:   ja.ContainerID,
-			Name:          ja.Name,
-			Documentation: ja.Documentation,
-			Excluded:      ja.Excluded,
-		}
-	}
-	return out, nil
-}
-
-func convertJavaScriptActionSlice(in []*mpr.JavaScriptAction, err error) ([]*types.JavaScriptAction, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	out := make([]*types.JavaScriptAction, len(in))
-	for i, jsa := range in {
-		out[i] = convertJavaScriptAction(jsa)
-	}
-	return out, nil
-}
-
-func convertJavaScriptActionPtr(in *mpr.JavaScriptAction, err error) (*types.JavaScriptAction, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	return convertJavaScriptAction(in), nil
-}
-
-func convertJavaScriptAction(in *mpr.JavaScriptAction) *types.JavaScriptAction {
-	return &types.JavaScriptAction{
-		BaseElement:             in.BaseElement,
-		ContainerID:             in.ContainerID,
-		Name:                    in.Name,
-		Documentation:           in.Documentation,
-		Platform:                in.Platform,
-		Excluded:                in.Excluded,
-		ExportLevel:             in.ExportLevel,
-		ActionDefaultReturnName: in.ActionDefaultReturnName,
-		ReturnType:              in.ReturnType,
-		Parameters:              in.Parameters,
-		TypeParameters:          in.TypeParameters,
-		MicroflowActionInfo:     in.MicroflowActionInfo,
-	}
-}
-
-func convertNavDocSlice(in []*mpr.NavigationDocument, err error) ([]*types.NavigationDocument, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	out := make([]*types.NavigationDocument, len(in))
-	for i, nd := range in {
-		out[i] = convertNavDoc(nd)
-	}
-	return out, nil
-}
-
-func convertNavDocPtr(in *mpr.NavigationDocument, err error) (*types.NavigationDocument, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	return convertNavDoc(in), nil
-}
-
-func convertNavDoc(in *mpr.NavigationDocument) *types.NavigationDocument {
-	nd := &types.NavigationDocument{
-		BaseElement: in.BaseElement,
-		ContainerID: in.ContainerID,
-		Name:        in.Name,
-	}
-	if in.Profiles != nil {
-		nd.Profiles = make([]*types.NavigationProfile, len(in.Profiles))
-		for i, p := range in.Profiles {
-			nd.Profiles[i] = convertNavProfile(p)
-		}
-	}
-	return nd
-}
-
-func convertNavProfile(in *mpr.NavigationProfile) *types.NavigationProfile {
-	p := &types.NavigationProfile{
-		Name:         in.Name,
-		Kind:         in.Kind,
-		IsNative:     in.IsNative,
-		LoginPage:    in.LoginPage,
-		NotFoundPage: in.NotFoundPage,
-	}
-	if in.HomePage != nil {
-		p.HomePage = &types.NavHomePage{Page: in.HomePage.Page, Microflow: in.HomePage.Microflow}
-	}
-	if in.RoleBasedHomePages != nil {
-		p.RoleBasedHomePages = make([]*types.NavRoleBasedHome, len(in.RoleBasedHomePages))
-		for i, rbh := range in.RoleBasedHomePages {
-			p.RoleBasedHomePages[i] = &types.NavRoleBasedHome{
-				UserRole: rbh.UserRole, Page: rbh.Page, Microflow: rbh.Microflow,
-			}
-		}
-	}
-	if in.MenuItems != nil {
-		p.MenuItems = make([]*types.NavMenuItem, len(in.MenuItems))
-		for i, mi := range in.MenuItems {
-			p.MenuItems[i] = convertNavMenuItem(mi)
-		}
-	}
-	p.ThrowPartialSyncError = in.ThrowPartialSyncError
-	if in.OfflineEntities != nil {
-		p.OfflineEntities = make([]*types.NavOfflineEntity, len(in.OfflineEntities))
-		for i, oe := range in.OfflineEntities {
-			p.OfflineEntities[i] = &types.NavOfflineEntity{
-				Entity: oe.Entity, SyncMode: oe.SyncMode, Constraint: oe.Constraint,
-				CompatibilityMode: oe.CompatibilityMode,
-			}
-		}
-	}
-	return p
-}
-
-func convertNavMenuItem(in *mpr.NavMenuItem) *types.NavMenuItem {
-	mi := &types.NavMenuItem{
-		Caption: in.Caption, Page: in.Page, Microflow: in.Microflow, ActionType: in.ActionType,
-		Icon: in.Icon, IconType: in.IconType, IconCode: in.IconCode,
-	}
-	if in.Items != nil {
-		mi.Items = make([]*types.NavMenuItem, len(in.Items))
-		for i, sub := range in.Items {
-			mi.Items[i] = convertNavMenuItem(sub)
-		}
-	}
-	return mi
-}
-
-// ---------------------------------------------------------------------------
-// Conversion helpers: mdl/types -> sdk/mpr (for write methods)
-// ---------------------------------------------------------------------------
-
-// unconvertNavProfileSpec is now a pass-through since mpr.NavigationProfileSpec
-// is aliased to types.NavigationProfileSpec.
-func unconvertNavProfileSpec(s types.NavigationProfileSpec) mpr.NavigationProfileSpec {
-	return s
-}
-
-func unconvertEntityMemberAccessSlice(in []types.EntityMemberAccess) []mpr.EntityMemberAccess {
-	if in == nil {
-		return nil
-	}
-	out := make([]mpr.EntityMemberAccess, len(in))
-	for i, ma := range in {
-		out[i] = mpr.EntityMemberAccess{
-			AttributeRef: ma.AttributeRef, AssociationRef: ma.AssociationRef, AccessRights: ma.AccessRights,
-		}
-	}
-	return out
-}
-
-func unconvertEntityAccessRevocation(in types.EntityAccessRevocation) mpr.EntityAccessRevocation {
-	return mpr.EntityAccessRevocation{
-		RevokeCreate:       in.RevokeCreate,
-		RevokeDelete:       in.RevokeDelete,
-		RevokeReadMembers:  in.RevokeReadMembers,
-		RevokeWriteMembers: in.RevokeWriteMembers,
-		RevokeReadAll:      in.RevokeReadAll,
-		RevokeWriteAll:     in.RevokeWriteAll,
-	}
-}
-
-func convertJsonStructureSlice(in []*mpr.JsonStructure, err error) ([]*types.JsonStructure, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	out := make([]*types.JsonStructure, len(in))
-	for i, js := range in {
-		out[i] = convertJsonStructure(js)
-	}
-	return out, nil
-}
-
-func convertJsonStructurePtr(in *mpr.JsonStructure, err error) (*types.JsonStructure, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	return convertJsonStructure(in), nil
-}
-
-func convertJsonStructure(in *mpr.JsonStructure) *types.JsonStructure {
-	js := &types.JsonStructure{
-		BaseElement:   in.BaseElement,
-		ContainerID:   in.ContainerID,
-		Name:          in.Name,
-		Documentation: in.Documentation,
-		JsonSnippet:   in.JsonSnippet,
-		Excluded:      in.Excluded,
-		ExportLevel:   in.ExportLevel,
-	}
-	if in.Elements != nil {
-		js.Elements = make([]*types.JsonElement, len(in.Elements))
-		for i, e := range in.Elements {
-			js.Elements[i] = convertJsonElement(e)
-		}
-	}
-	return js
-}
-
-func convertJsonElement(in *mpr.JsonElement) *types.JsonElement {
-	e := &types.JsonElement{
-		ExposedName: in.ExposedName, ExposedItemName: in.ExposedItemName,
-		Path: in.Path, ElementType: in.ElementType, PrimitiveType: in.PrimitiveType,
-		MinOccurs: in.MinOccurs, MaxOccurs: in.MaxOccurs, Nillable: in.Nillable,
-		IsDefaultType: in.IsDefaultType, MaxLength: in.MaxLength,
-		FractionDigits: in.FractionDigits, TotalDigits: in.TotalDigits,
-		OriginalValue: in.OriginalValue,
-	}
-	if in.Children != nil {
-		e.Children = make([]*types.JsonElement, len(in.Children))
-		for i, c := range in.Children {
-			e.Children[i] = convertJsonElement(c)
-		}
-	}
-	return e
-}
-
-func unconvertJsonStructure(in *types.JsonStructure) *types.JsonStructure {
-	js := &types.JsonStructure{
-		BaseElement:   in.BaseElement,
-		ContainerID:   in.ContainerID,
-		Name:          in.Name,
-		Documentation: in.Documentation,
-		JsonSnippet:   in.JsonSnippet,
-		Excluded:      in.Excluded,
-		ExportLevel:   in.ExportLevel,
-	}
-	if in.Elements != nil {
-		js.Elements = make([]*types.JsonElement, len(in.Elements))
-		for i, e := range in.Elements {
-			js.Elements[i] = unconvertJsonElement(e)
-		}
-	}
-	return js
-}
-
-func unconvertJsonElement(in *types.JsonElement) *types.JsonElement {
-	e := &types.JsonElement{
-		ExposedName: in.ExposedName, ExposedItemName: in.ExposedItemName,
-		Path: in.Path, ElementType: in.ElementType, PrimitiveType: in.PrimitiveType,
-		MinOccurs: in.MinOccurs, MaxOccurs: in.MaxOccurs, Nillable: in.Nillable,
-		IsDefaultType: in.IsDefaultType, MaxLength: in.MaxLength,
-		FractionDigits: in.FractionDigits, TotalDigits: in.TotalDigits,
-		OriginalValue: in.OriginalValue,
-	}
-	if in.Children != nil {
-		e.Children = make([]*types.JsonElement, len(in.Children))
-		for i, c := range in.Children {
-			e.Children[i] = unconvertJsonElement(c)
-		}
-	}
-	return e
-}
-
-func convertImageCollectionSlice(in []*mpr.ImageCollection, err error) ([]*types.ImageCollection, error) {
-	if err != nil || in == nil {
-		return nil, err
-	}
-	out := make([]*types.ImageCollection, len(in))
-	for i, ic := range in {
-		out[i] = convertImageCollection(ic)
-	}
-	return out, nil
-}
-
-func convertImageCollection(in *mpr.ImageCollection) *types.ImageCollection {
-	ic := &types.ImageCollection{
-		BaseElement:   in.BaseElement,
-		ContainerID:   in.ContainerID,
-		Name:          in.Name,
-		ExportLevel:   in.ExportLevel,
-		Documentation: in.Documentation,
-		Excluded:      in.Excluded,
-	}
-	if in.Images != nil {
-		ic.Images = make([]types.Image, len(in.Images))
-		for i, img := range in.Images {
-			ic.Images[i] = types.Image{ID: img.ID, Name: img.Name, Data: img.Data, Format: img.Format}
-		}
-	}
-	return ic
-}
-
-func unconvertImageCollection(in *types.ImageCollection) *types.ImageCollection {
-	ic := &types.ImageCollection{
-		BaseElement:   in.BaseElement,
-		ContainerID:   in.ContainerID,
-		Name:          in.Name,
-		ExportLevel:   in.ExportLevel,
-		Documentation: in.Documentation,
-	}
-	if in.Images != nil {
-		ic.Images = make([]types.Image, len(in.Images))
-		for i, img := range in.Images {
-			ic.Images[i] = types.Image{ID: img.ID, Name: img.Name, Data: img.Data, Format: img.Format}
-		}
-	}
-	return ic
-}
diff --git a/mdl/backend/mpr/convert_roundtrip_test.go b/mdl/backend/mpr/convert_roundtrip_test.go
deleted file mode 100644
index 0bb0432515..0000000000
--- a/mdl/backend/mpr/convert_roundtrip_test.go
+++ /dev/null
@@ -1,639 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-// convert_roundtrip_test.go — internal tests that exercise the actual
-// convert/unconvert functions with fully-populated structs to ensure
-// round-trip correctness and full field preservation.
-package mprbackend
-
-import (
-	"errors"
-	"reflect"
-	"testing"
-
-	"github.com/mendixlabs/mxcli/mdl/types"
-	"github.com/mendixlabs/mxcli/model"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
-	"go.mongodb.org/mongo-driver/bson"
-)
-
-var errTest = errors.New("test error")
-
-// ---------------------------------------------------------------------------
-// Forward conversions: sdk/mpr -> mdl/types
-// ---------------------------------------------------------------------------
-
-func TestConvertFolderInfoSlice(t *testing.T) {
-	in := []*mpr.FolderInfo{
-		{ID: model.ID("f1"), ContainerID: model.ID("c1"), Name: "Folder1"},
-		{ID: model.ID("f2"), ContainerID: model.ID("c2"), Name: "Folder2"},
-	}
-	out, err := convertFolderInfoSlice(in, nil)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(out) != 2 {
-		t.Fatalf("expected 2, got %d", len(out))
-	}
-	if out[0].ID != "f1" || out[0].Name != "Folder1" {
-		t.Errorf("field mismatch on [0]: %+v", out[0])
-	}
-	if out[1].ID != "f2" || out[1].ContainerID != "c2" {
-		t.Errorf("field mismatch on [1]: %+v", out[1])
-	}
-}
-
-func TestConvertFolderInfoSlice_ErrorPassthrough(t *testing.T) {
-	_, err := convertFolderInfoSlice(nil, errTest)
-	if err != errTest {
-		t.Errorf("expected errTest, got %v", err)
-	}
-}
-
-func TestConvertFolderInfoSlice_Nil(t *testing.T) {
-	out, err := convertFolderInfoSlice(nil, nil)
-	if err != nil || out != nil {
-		t.Errorf("expected (nil, nil), got (%v, %v)", out, err)
-	}
-}
-
-func TestConvertUnitInfoSlice(t *testing.T) {
-	in := []*mpr.UnitInfo{
-		{ID: model.ID("u1"), ContainerID: model.ID("c1"), ContainmentName: "units", Type: "Pages$Page"},
-	}
-	out, err := convertUnitInfoSlice(in, nil)
-	if err != nil || len(out) != 1 {
-		t.Fatalf("unexpected: out=%v err=%v", out, err)
-	}
-	if out[0].ContainmentName != "units" || out[0].Type != "Pages$Page" {
-		t.Errorf("field mismatch: %+v", out[0])
-	}
-}
-
-func TestConvertRenameHitSlice(t *testing.T) {
-	in := []mpr.RenameHit{
-		{UnitID: "u1", UnitType: "Page", Name: "MyPage", Count: 3},
-	}
-	out, err := convertRenameHitSlice(in, nil)
-	if err != nil || len(out) != 1 {
-		t.Fatalf("unexpected: out=%v err=%v", out, err)
-	}
-	if out[0].Count != 3 || out[0].Name != "MyPage" {
-		t.Errorf("field mismatch: %+v", out[0])
-	}
-}
-
-func TestConvertRawUnitSlice(t *testing.T) {
-	in := []*mpr.RawUnit{
-		{ID: model.ID("r1"), ContainerID: model.ID("c1"), Type: "Page", Contents: []byte{0x01}},
-	}
-	out, err := convertRawUnitSlice(in, nil)
-	if err != nil || len(out) != 1 {
-		t.Fatalf("unexpected: out=%v err=%v", out, err)
-	}
-	if len(out[0].Contents) != 1 || out[0].Contents[0] != 0x01 {
-		t.Errorf("contents mismatch: %+v", out[0])
-	}
-}
-
-func TestConvertRawUnitInfoSlice(t *testing.T) {
-	in := []*mpr.RawUnitInfo{
-		{ID: "r1", QualifiedName: "Mod.Page", Type: "Page", ModuleName: "Mod", Contents: []byte{0x02}},
-	}
-	out, err := convertRawUnitInfoSlice(in, nil)
-	if err != nil || len(out) != 1 {
-		t.Fatalf("unexpected: out=%v err=%v", out, err)
-	}
-	if out[0].QualifiedName != "Mod.Page" || out[0].ModuleName != "Mod" {
-		t.Errorf("field mismatch: %+v", out[0])
-	}
-}
-
-func TestConvertRawUnitInfoPtr(t *testing.T) {
-	in := &mpr.RawUnitInfo{ID: "r1", QualifiedName: "Q", Type: "T", ModuleName: "M", Contents: []byte{0x03}}
-	out, err := convertRawUnitInfoPtr(in, nil)
-	if err != nil || out == nil {
-		t.Fatalf("unexpected: out=%v err=%v", out, err)
-	}
-	if out.ID != "r1" {
-		t.Errorf("field mismatch: %+v", out)
-	}
-}
-
-func TestConvertRawCustomWidgetTypePtr(t *testing.T) {
-	in := &mpr.RawCustomWidgetType{
-		WidgetID: "w1", RawType: bson.D{{Key: "k", Value: "v"}}, RawObject: bson.D{{Key: "k2", Value: "v2"}},
-		UnitID: "u1", UnitName: "Unit", WidgetName: "Widget",
-	}
-	out, err := convertRawCustomWidgetTypePtr(in, nil)
-	if err != nil || out == nil {
-		t.Fatalf("unexpected: out=%v err=%v", out, err)
-	}
-	if out.WidgetID != "w1" || out.WidgetName != "Widget" {
-		t.Errorf("field mismatch: %+v", out)
-	}
-}
-
-func TestConvertRawCustomWidgetTypeSlice(t *testing.T) {
-	in := []*mpr.RawCustomWidgetType{
-		{WidgetID: "w1", UnitName: "U1"},
-		{WidgetID: "w2", UnitName: "U2"},
-	}
-	out, err := convertRawCustomWidgetTypeSlice(in, nil)
-	if err != nil || len(out) != 2 {
-		t.Fatalf("unexpected: out=%v err=%v", out, err)
-	}
-}
-
-func TestConvertJavaActionSlice(t *testing.T) {
-	in := []*mpr.JavaAction{
-		{BaseElement: model.BaseElement{ID: model.ID("j1")}, ContainerID: model.ID("c1"), Name: "MyJA", Documentation: "doc"},
-	}
-	out, err := convertJavaActionSlice(in, nil)
-	if err != nil || len(out) != 1 {
-		t.Fatalf("unexpected: out=%v err=%v", out, err)
-	}
-	if out[0].Name != "MyJA" || out[0].Documentation != "doc" {
-		t.Errorf("field mismatch: %+v", out[0])
-	}
-}
-
-func TestConvertJavaScriptAction_AllFields(t *testing.T) {
-	in := &mpr.JavaScriptAction{
-		BaseElement:             model.BaseElement{ID: model.ID("jsa1")},
-		ContainerID:             model.ID("c1"),
-		Name:                    "MyJSA",
-		Documentation:           "doc",
-		Platform:                "web",
-		Excluded:                true,
-		ExportLevel:             "Hidden",
-		ActionDefaultReturnName: "result",
-	}
-	out := convertJavaScriptAction(in)
-	if out.Name != "MyJSA" || out.Platform != "web" || !out.Excluded ||
-		out.ExportLevel != "Hidden" || out.ActionDefaultReturnName != "result" {
-		t.Errorf("field mismatch: %+v", out)
-	}
-}
-
-func TestConvertJavaScriptActionSlice(t *testing.T) {
-	in := []*mpr.JavaScriptAction{
-		{BaseElement: model.BaseElement{ID: model.ID("jsa1")}, Name: "JSA1"},
-	}
-	out, err := convertJavaScriptActionSlice(in, nil)
-	if err != nil || len(out) != 1 || out[0].Name != "JSA1" {
-		t.Errorf("unexpected: out=%v err=%v", out, err)
-	}
-}
-
-func TestConvertJavaScriptActionSlice_ErrorPassthrough(t *testing.T) {
-	_, err := convertJavaScriptActionSlice(nil, errTest)
-	if err != errTest {
-		t.Errorf("expected errTest, got %v", err)
-	}
-}
-
-func TestConvertJavaScriptActionPtr(t *testing.T) {
-	in := &mpr.JavaScriptAction{BaseElement: model.BaseElement{ID: model.ID("jsa1")}, Name: "JSA1"}
-	out, err := convertJavaScriptActionPtr(in, nil)
-	if err != nil || out == nil || out.Name != "JSA1" {
-		t.Errorf("unexpected: out=%v err=%v", out, err)
-	}
-}
-
-func TestConvertJavaScriptActionPtr_ErrorPassthrough(t *testing.T) {
-	_, err := convertJavaScriptActionPtr(nil, errTest)
-	if err != errTest {
-		t.Errorf("expected errTest, got %v", err)
-	}
-}
-
-func TestConvertNavDoc_FullyPopulated(t *testing.T) {
-	in := &mpr.NavigationDocument{
-		BaseElement: model.BaseElement{ID: model.ID("nd1")},
-		ContainerID: model.ID("c1"),
-		Name:        "Navigation",
-		Profiles: []*mpr.NavigationProfile{
-			{
-				Name: "Responsive", Kind: "Responsive", IsNative: false,
-				LoginPage: "Login", NotFoundPage: "NotFound",
-				HomePage: &mpr.NavHomePage{Page: "Home.Page", Microflow: "Home.MF"},
-				RoleBasedHomePages: []*mpr.NavRoleBasedHome{
-					{UserRole: "Admin", Page: "Admin.Home", Microflow: "Admin.MF"},
-				},
-				MenuItems: []*mpr.NavMenuItem{
-					{Caption: "Top", Page: "P1", ActionType: "OpenPage", Items: []*mpr.NavMenuItem{
-						{Caption: "Sub", Microflow: "MF1"},
-					}},
-				},
-				OfflineEntities: []*mpr.NavOfflineEntity{
-					{Entity: "Mod.Entity", SyncMode: "FullSync", Constraint: "[Amount > 0]"},
-				},
-			},
-		},
-	}
-
-	out := convertNavDoc(in)
-
-	if out.ID != "nd1" || out.Name != "Navigation" || out.ContainerID != "c1" {
-		t.Errorf("top-level mismatch: %+v", out)
-	}
-	if len(out.Profiles) != 1 {
-		t.Fatalf("expected 1 profile, got %d", len(out.Profiles))
-	}
-
-	p := out.Profiles[0]
-	if p.Name != "Responsive" || p.Kind != "Responsive" || p.IsNative {
-		t.Errorf("profile basic mismatch: %+v", p)
-	}
-	if p.LoginPage != "Login" || p.NotFoundPage != "NotFound" {
-		t.Errorf("profile page mismatch: login=%q notfound=%q", p.LoginPage, p.NotFoundPage)
-	}
-	if p.HomePage == nil || p.HomePage.Page != "Home.Page" || p.HomePage.Microflow != "Home.MF" {
-		t.Errorf("homepage mismatch: %+v", p.HomePage)
-	}
-	if len(p.RoleBasedHomePages) != 1 || p.RoleBasedHomePages[0].UserRole != "Admin" {
-		t.Errorf("role-based mismatch: %+v", p.RoleBasedHomePages)
-	}
-	if len(p.MenuItems) != 1 || p.MenuItems[0].Caption != "Top" {
-		t.Errorf("menu mismatch: %+v", p.MenuItems)
-	}
-	if len(p.MenuItems[0].Items) != 1 || p.MenuItems[0].Items[0].Caption != "Sub" {
-		t.Errorf("sub-menu mismatch: %+v", p.MenuItems[0].Items)
-	}
-	if len(p.OfflineEntities) != 1 || p.OfflineEntities[0].Constraint != "[Amount > 0]" {
-		t.Errorf("offline entities mismatch: %+v", p.OfflineEntities)
-	}
-}
-
-func TestConvertNavDocSlice(t *testing.T) {
-	in := []*mpr.NavigationDocument{
-		{BaseElement: model.BaseElement{ID: model.ID("nd1")}, Name: "Nav1"},
-	}
-	out, err := convertNavDocSlice(in, nil)
-	if err != nil || len(out) != 1 || out[0].Name != "Nav1" {
-		t.Errorf("unexpected: out=%v err=%v", out, err)
-	}
-}
-
-func TestConvertNavDocSlice_ErrorPassthrough(t *testing.T) {
-	_, err := convertNavDocSlice(nil, errTest)
-	if err != errTest {
-		t.Errorf("expected errTest, got %v", err)
-	}
-}
-
-func TestConvertNavDocPtr(t *testing.T) {
-	in := &mpr.NavigationDocument{BaseElement: model.BaseElement{ID: model.ID("nd1")}, Name: "Nav1"}
-	out, err := convertNavDocPtr(in, nil)
-	if err != nil || out == nil || out.Name != "Nav1" {
-		t.Errorf("unexpected: out=%v err=%v", out, err)
-	}
-}
-
-func TestConvertNavDocPtr_ErrorPassthrough(t *testing.T) {
-	_, err := convertNavDocPtr(nil, errTest)
-	if err != errTest {
-		t.Errorf("expected errTest, got %v", err)
-	}
-}
-
-func TestConvertJsonStructure_Recursive(t *testing.T) {
-	in := &mpr.JsonStructure{
-		BaseElement:   model.BaseElement{ID: model.ID("js1")},
-		ContainerID:   model.ID("c1"),
-		Name:          "MyJSON",
-		Documentation: "doc",
-		JsonSnippet:   `{"a":1}`,
-		Excluded:      true,
-		ExportLevel:   "Hidden",
-		Elements: []*mpr.JsonElement{
-			{
-				ExposedName: "Root", Path: "(Object)", ElementType: "Object",
-				PrimitiveType: "Unknown", MinOccurs: 1, MaxOccurs: 1,
-				Children: []*mpr.JsonElement{
-					{
-						ExposedName: "A", Path: "(Object)|a", ElementType: "Value",
-						PrimitiveType: "Integer", OriginalValue: "1",
-						MaxLength: 10, FractionDigits: 2, TotalDigits: 5,
-						Nillable: true, IsDefaultType: true,
-					},
-				},
-			},
-		},
-	}
-
-	out := convertJsonStructure(in)
-
-	if out.Name != "MyJSON" || out.Documentation != "doc" || out.JsonSnippet != `{"a":1}` ||
-		!out.Excluded || out.ExportLevel != "Hidden" {
-		t.Errorf("top-level mismatch: %+v", out)
-	}
-	if len(out.Elements) != 1 {
-		t.Fatalf("expected 1 element, got %d", len(out.Elements))
-	}
-	root := out.Elements[0]
-	if root.ExposedName != "Root" || root.MinOccurs != 1 {
-		t.Errorf("root mismatch: %+v", root)
-	}
-	if len(root.Children) != 1 {
-		t.Fatalf("expected 1 child, got %d", len(root.Children))
-	}
-	child := root.Children[0]
-	if child.PrimitiveType != "Integer" || child.OriginalValue != "1" ||
-		child.MaxLength != 10 || child.FractionDigits != 2 || child.TotalDigits != 5 ||
-		!child.Nillable || !child.IsDefaultType {
-		t.Errorf("child mismatch: %+v", child)
-	}
-}
-
-func TestConvertJsonStructureSlice(t *testing.T) {
-	in := []*mpr.JsonStructure{
-		{BaseElement: model.BaseElement{ID: model.ID("js1")}, Name: "JS1"},
-	}
-	out, err := convertJsonStructureSlice(in, nil)
-	if err != nil || len(out) != 1 || out[0].Name != "JS1" {
-		t.Errorf("unexpected: out=%v err=%v", out, err)
-	}
-}
-
-func TestConvertJsonStructureSlice_ErrorPassthrough(t *testing.T) {
-	_, err := convertJsonStructureSlice(nil, errTest)
-	if err != errTest {
-		t.Errorf("expected errTest, got %v", err)
-	}
-}
-
-func TestConvertJsonStructurePtr(t *testing.T) {
-	in := &mpr.JsonStructure{BaseElement: model.BaseElement{ID: model.ID("js1")}, Name: "JS1"}
-	out, err := convertJsonStructurePtr(in, nil)
-	if err != nil || out == nil || out.Name != "JS1" {
-		t.Errorf("unexpected: out=%v err=%v", out, err)
-	}
-}
-
-func TestConvertJsonStructurePtr_ErrorPassthrough(t *testing.T) {
-	_, err := convertJsonStructurePtr(nil, errTest)
-	if err != errTest {
-		t.Errorf("expected errTest, got %v", err)
-	}
-}
-
-func TestConvertImageCollection(t *testing.T) {
-	in := &mpr.ImageCollection{
-		BaseElement:   model.BaseElement{ID: model.ID("ic1")},
-		ContainerID:   model.ID("c1"),
-		Name:          "Images",
-		ExportLevel:   "Public",
-		Documentation: "img docs",
-		Images:        []mpr.Image{{ID: model.ID("i1"), Name: "logo.png", Data: []byte{0x89, 0x50}, Format: "png"}},
-	}
-	out := convertImageCollection(in)
-	if out.Name != "Images" || out.ExportLevel != "Public" || out.Documentation != "img docs" {
-		t.Errorf("top-level mismatch: %+v", out)
-	}
-	if len(out.Images) != 1 || out.Images[0].Name != "logo.png" || out.Images[0].Format != "png" {
-		t.Errorf("image mismatch: %+v", out.Images)
-	}
-}
-
-func TestConvertImageCollectionSlice(t *testing.T) {
-	in := []*mpr.ImageCollection{
-		{BaseElement: model.BaseElement{ID: model.ID("ic1")}, Name: "IC1"},
-	}
-	out, err := convertImageCollectionSlice(in, nil)
-	if err != nil || len(out) != 1 || out[0].Name != "IC1" {
-		t.Errorf("unexpected: out=%v err=%v", out, err)
-	}
-}
-
-func TestConvertImageCollectionSlice_ErrorPassthrough(t *testing.T) {
-	_, err := convertImageCollectionSlice(nil, errTest)
-	if err != errTest {
-		t.Errorf("expected errTest, got %v", err)
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Unconvert (write-path): mdl/types -> sdk/mpr
-// ---------------------------------------------------------------------------
-
-func TestUnconvertNavProfileSpec_FullyPopulated(t *testing.T) {
-	in := types.NavigationProfileSpec{
-		LoginPage:    "Login.Page",
-		NotFoundPage: "NotFound.Page",
-		HasMenu:      true,
-		HomePages: []types.NavHomePageSpec{
-			{IsPage: true, Target: "Home.Page", ForRole: ""},
-			{IsPage: false, Target: "Home.MF", ForRole: "Admin"},
-		},
-		MenuItems: []types.NavMenuItemSpec{
-			{Caption: "Top", Page: "P1", Items: []types.NavMenuItemSpec{
-				{Caption: "Sub", Microflow: "MF1"},
-			}},
-		},
-	}
-
-	out := unconvertNavProfileSpec(in)
-
-	if out.LoginPage != "Login.Page" || out.NotFoundPage != "NotFound.Page" || !out.HasMenu {
-		t.Errorf("top-level mismatch: %+v", out)
-	}
-	if len(out.HomePages) != 2 {
-		t.Fatalf("expected 2 home pages, got %d", len(out.HomePages))
-	}
-	if !out.HomePages[0].IsPage || out.HomePages[0].Target != "Home.Page" {
-		t.Errorf("homepage[0] mismatch: %+v", out.HomePages[0])
-	}
-	if out.HomePages[1].ForRole != "Admin" {
-		t.Errorf("homepage[1] mismatch: %+v", out.HomePages[1])
-	}
-	if len(out.MenuItems) != 1 || out.MenuItems[0].Caption != "Top" {
-		t.Errorf("menu mismatch: %+v", out.MenuItems)
-	}
-	if len(out.MenuItems[0].Items) != 1 || out.MenuItems[0].Items[0].Microflow != "MF1" {
-		t.Errorf("sub-menu mismatch: %+v", out.MenuItems[0].Items)
-	}
-}
-
-func TestUnconvertNavProfileSpec_NilSlices(t *testing.T) {
-	in := types.NavigationProfileSpec{LoginPage: "L"}
-	out := unconvertNavProfileSpec(in)
-	if out.HomePages != nil || out.MenuItems != nil {
-		t.Errorf("expected nil slices for nil input: HomePages=%v MenuItems=%v", out.HomePages, out.MenuItems)
-	}
-}
-
-func TestUnconvertNavMenuItemSpec_Isolated(t *testing.T) {
-	in := types.NavMenuItemSpec{
-		Caption:   "Parent",
-		Page:      "Page1",
-		Microflow: "MF1",
-		Items: []types.NavMenuItemSpec{
-			{Caption: "Child", Microflow: "MF2"},
-		},
-	}
-	// Since mpr.NavMenuItemSpec is aliased to types.NavMenuItemSpec,
-	// unconvert is now a pass-through. Verify the alias holds.
-	var out mpr.NavMenuItemSpec = in
-	if out.Caption != "Parent" || out.Page != "Page1" || out.Microflow != "MF1" {
-		t.Errorf("field mismatch: %+v", out)
-	}
-	if len(out.Items) != 1 || out.Items[0].Caption != "Child" || out.Items[0].Microflow != "MF2" {
-		t.Errorf("child mismatch: %+v", out.Items)
-	}
-}
-
-func TestUnconvertNavMenuItemSpec_NilItems(t *testing.T) {
-	in := types.NavMenuItemSpec{Caption: "Leaf"}
-	var out mpr.NavMenuItemSpec = in
-	if out.Items != nil {
-		t.Errorf("expected nil Items for leaf: %+v", out.Items)
-	}
-}
-
-func TestUnconvertEntityMemberAccessSlice(t *testing.T) {
-	in := []types.EntityMemberAccess{
-		{AttributeRef: "attr1", AssociationRef: "assoc1", AccessRights: "ReadWrite"},
-	}
-	out := unconvertEntityMemberAccessSlice(in)
-	if len(out) != 1 || out[0].AttributeRef != "attr1" || out[0].AccessRights != "ReadWrite" {
-		t.Errorf("mismatch: %+v", out)
-	}
-}
-
-func TestUnconvertEntityMemberAccessSlice_Nil(t *testing.T) {
-	if unconvertEntityMemberAccessSlice(nil) != nil {
-		t.Error("expected nil for nil input")
-	}
-}
-
-func TestUnconvertEntityAccessRevocation(t *testing.T) {
-	in := types.EntityAccessRevocation{
-		RevokeCreate:       true,
-		RevokeDelete:       true,
-		RevokeReadMembers:  []string{"attr1"},
-		RevokeWriteMembers: []string{"attr2"},
-		RevokeReadAll:      true,
-		RevokeWriteAll:     false,
-	}
-	out := unconvertEntityAccessRevocation(in)
-	if !out.RevokeCreate || !out.RevokeDelete || !out.RevokeReadAll || out.RevokeWriteAll {
-		t.Errorf("bool mismatch: %+v", out)
-	}
-	if len(out.RevokeReadMembers) != 1 || out.RevokeReadMembers[0] != "attr1" {
-		t.Errorf("read members mismatch: %+v", out.RevokeReadMembers)
-	}
-	if len(out.RevokeWriteMembers) != 1 || out.RevokeWriteMembers[0] != "attr2" {
-		t.Errorf("write members mismatch: %+v", out.RevokeWriteMembers)
-	}
-}
-
-func TestUnconvertJsonStructure_Recursive(t *testing.T) {
-	in := &types.JsonStructure{
-		BaseElement:   model.BaseElement{ID: model.ID("js1")},
-		ContainerID:   model.ID("c1"),
-		Name:          "MyJSON",
-		Documentation: "doc",
-		JsonSnippet:   `{"a":1}`,
-		Excluded:      true,
-		ExportLevel:   "Hidden",
-		Elements: []*types.JsonElement{
-			{
-				ExposedName: "Root", Path: "(Object)", ElementType: "Object",
-				Children: []*types.JsonElement{
-					{ExposedName: "A", PrimitiveType: "Integer", MaxLength: 10},
-				},
-			},
-		},
-	}
-
-	out := unconvertJsonStructure(in)
-
-	if out.Name != "MyJSON" || out.Documentation != "doc" || !out.Excluded {
-		t.Errorf("top-level mismatch: %+v", out)
-	}
-	if len(out.Elements) != 1 || out.Elements[0].ExposedName != "Root" {
-		t.Fatalf("element mismatch: %+v", out.Elements)
-	}
-	if len(out.Elements[0].Children) != 1 || out.Elements[0].Children[0].MaxLength != 10 {
-		t.Errorf("child mismatch: %+v", out.Elements[0].Children)
-	}
-}
-
-func TestUnconvertImageCollection(t *testing.T) {
-	in := &types.ImageCollection{
-		BaseElement:   model.BaseElement{ID: model.ID("ic1")},
-		ContainerID:   model.ID("c1"),
-		Name:          "Images",
-		ExportLevel:   "Public",
-		Documentation: "docs",
-		Images:        []types.Image{{ID: model.ID("i1"), Name: "logo.png", Data: []byte{0x89}, Format: "png"}},
-	}
-
-	out := unconvertImageCollection(in)
-
-	if out.Name != "Images" || out.ExportLevel != "Public" {
-		t.Errorf("top-level mismatch: %+v", out)
-	}
-	if len(out.Images) != 1 || out.Images[0].Name != "logo.png" || out.Images[0].Data[0] != 0x89 {
-		t.Errorf("image mismatch: %+v", out.Images)
-	}
-}
-
-// ============================================================================
-// Field-count drift assertions
-// ============================================================================
-//
-// These tests catch silent field drift: if a struct gains a new field but
-// the convert/unconvert function is not updated, the test fails.
-
-func assertFieldCount(t *testing.T, name string, v any, expected int) {
-	t.Helper()
-	actual := reflect.TypeOf(v).NumField()
-	if actual != expected {
-		t.Errorf("%s field count changed: expected %d, got %d — update convert.go and this test", name, expected, actual)
-	}
-}
-
-func TestFieldCountDrift(t *testing.T) {
-	// mpr → types pairs (manually copied in convert.go).
-	// If a struct gains a field, update the convert function AND this count.
-	assertFieldCount(t, "mpr.FolderInfo", mpr.FolderInfo{}, 3)
-	assertFieldCount(t, "types.FolderInfo", types.FolderInfo{}, 3)
-	assertFieldCount(t, "mpr.UnitInfo", mpr.UnitInfo{}, 4)
-	assertFieldCount(t, "types.UnitInfo", types.UnitInfo{}, 4)
-	assertFieldCount(t, "mpr.RenameHit", mpr.RenameHit{}, 4)
-	assertFieldCount(t, "types.RenameHit", types.RenameHit{}, 4)
-	assertFieldCount(t, "mpr.RawUnit", mpr.RawUnit{}, 4)
-	assertFieldCount(t, "types.RawUnit", types.RawUnit{}, 4)
-	assertFieldCount(t, "mpr.RawUnitInfo", mpr.RawUnitInfo{}, 5)
-	assertFieldCount(t, "types.RawUnitInfo", types.RawUnitInfo{}, 5)
-	assertFieldCount(t, "mpr.RawCustomWidgetType", mpr.RawCustomWidgetType{}, 6)
-	assertFieldCount(t, "types.RawCustomWidgetType", types.RawCustomWidgetType{}, 6)
-	// +1 each for Excluded (#914): reads must carry it so a rewrite does not
-	// clear the document's "Exclude from project" flag.
-	assertFieldCount(t, "mpr.JavaAction", mpr.JavaAction{}, 5)
-	assertFieldCount(t, "types.JavaAction", types.JavaAction{}, 5)
-	assertFieldCount(t, "mpr.JavaScriptAction", mpr.JavaScriptAction{}, 12)
-	assertFieldCount(t, "types.JavaScriptAction", types.JavaScriptAction{}, 12)
-	assertFieldCount(t, "mpr.NavigationDocument", mpr.NavigationDocument{}, 4)
-	assertFieldCount(t, "types.NavigationDocument", types.NavigationDocument{}, 4)
-	assertFieldCount(t, "mpr.JsonStructure", mpr.JsonStructure{}, 8)
-	assertFieldCount(t, "types.JsonStructure", types.JsonStructure{}, 8)
-	assertFieldCount(t, "mpr.JsonElement", mpr.JsonElement{}, 14)
-	assertFieldCount(t, "types.JsonElement", types.JsonElement{}, 14)
-	assertFieldCount(t, "mpr.ImageCollection", mpr.ImageCollection{}, 7)
-	assertFieldCount(t, "types.ImageCollection", types.ImageCollection{}, 7)
-	assertFieldCount(t, "mpr.EntityMemberAccess", mpr.EntityMemberAccess{}, 3)
-	assertFieldCount(t, "types.EntityMemberAccess", types.EntityMemberAccess{}, 3)
-	assertFieldCount(t, "mpr.EntityAccessRevocation", mpr.EntityAccessRevocation{}, 6)
-	assertFieldCount(t, "types.EntityAccessRevocation", types.EntityAccessRevocation{}, 6)
-	// Both are hand-copied in convertNavProfile and were unguarded: adding
-	// CompatibilityMode to NavOfflineEntity left this test passing while the
-	// new field was silently not carried, which is the exact drift the test
-	// exists to catch.
-	assertFieldCount(t, "mpr.NavigationProfile", mpr.NavigationProfile{}, 10)
-	assertFieldCount(t, "types.NavigationProfile", types.NavigationProfile{}, 10)
-	assertFieldCount(t, "mpr.NavOfflineEntity", mpr.NavOfflineEntity{}, 4)
-	assertFieldCount(t, "types.NavOfflineEntity", types.NavOfflineEntity{}, 4)
-}
diff --git a/mdl/backend/mpr/convert_test.go b/mdl/backend/mpr/convert_test.go
deleted file mode 100644
index 9d1d5d8213..0000000000
--- a/mdl/backend/mpr/convert_test.go
+++ /dev/null
@@ -1,189 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-// Package mprbackend_test verifies that the conversion layer between sdk/mpr
-// and mdl/types works correctly. Because sdk/mpr types are now type aliases to
-// mdl/types (e.g. mpr.JavaAction = types.JavaAction), the "convert" functions
-// are effectively deep-copy operations on the same type. This test file proves
-// the type system is consistent and conversions preserve all fields.
-package mprbackend_test
-
-import (
-	"testing"
-
-	"github.com/mendixlabs/mxcli/mdl/types"
-	"github.com/mendixlabs/mxcli/model"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
-)
-
-// TestTypeAliasesAreIdentical proves that sdk/mpr type aliases resolve to the
-// same Go types as mdl/types. If these assignments compile, the types are
-// identical — which is precisely what the conversion functions rely on.
-func TestTypeAliasesAreIdentical(t *testing.T) {
-	// Each assignment proves the alias: mpr.X == types.X
-	var _ *types.JavaAction = new(mpr.JavaAction)
-	var _ *types.JavaScriptAction = new(mpr.JavaScriptAction)
-	var _ *types.NavigationDocument = new(mpr.NavigationDocument)
-	var _ *types.NavigationProfile = new(mpr.NavigationProfile)
-	var _ *types.NavHomePage = new(mpr.NavHomePage)
-	var _ *types.NavRoleBasedHome = new(mpr.NavRoleBasedHome)
-	var _ *types.NavMenuItem = new(mpr.NavMenuItem)
-	var _ *types.NavOfflineEntity = new(mpr.NavOfflineEntity)
-	var _ *types.JsonStructure = new(mpr.JsonStructure)
-	var _ *types.JsonElement = new(mpr.JsonElement)
-	var _ *types.ImageCollection = new(mpr.ImageCollection)
-	var _ *types.FolderInfo = new(mpr.FolderInfo)
-	var _ *types.UnitInfo = new(mpr.UnitInfo)
-	var _ *types.RawUnit = new(mpr.RawUnit)
-	var _ *types.ProjectVersion = new(mpr.ProjectVersion)
-
-	// Slices are also interchangeable
-	var typesSlice []*types.FolderInfo
-	var mprSlice []*mpr.FolderInfo = typesSlice
-	_ = mprSlice
-
-	var typesJSSlice []*types.JavaScriptAction
-	var mprJSSlice []*mpr.JavaScriptAction = typesJSSlice
-	_ = mprJSSlice
-}
-
-// TestFolderInfoSlicePassthrough verifies that a []*mpr.FolderInfo value can
-// be used where []*types.FolderInfo is expected, because they are the same type.
-func TestFolderInfoSlicePassthrough(t *testing.T) {
-	folders := []*mpr.FolderInfo{
-		{ID: model.ID("f1"), ContainerID: model.ID("c1"), Name: "Module"},
-		{ID: model.ID("f2"), ContainerID: model.ID("c2"), Name: "Resources"},
-	}
-
-	// This compiles because mpr.FolderInfo = types.FolderInfo
-	var typesFolders []*types.FolderInfo = folders
-	if len(typesFolders) != 2 {
-		t.Fatalf("expected 2 folders, got %d", len(typesFolders))
-	}
-	if typesFolders[0].Name != "Module" {
-		t.Errorf("expected Module, got %q", typesFolders[0].Name)
-	}
-}
-
-// TestNavigationDocumentFieldPreservation verifies that all fields survive
-// when a NavigationDocument created via mpr alias is accessed via types.
-func TestNavigationDocumentFieldPreservation(t *testing.T) {
-	doc := &mpr.NavigationDocument{
-		ContainerID: model.ID("c1"),
-		Name:        "Navigation",
-		Profiles: []*mpr.NavigationProfile{
-			{
-				Name:     "Responsive",
-				Kind:     "Responsive",
-				IsNative: false,
-				HomePage: &mpr.NavHomePage{Page: "MyFirstModule.Home"},
-				RoleBasedHomePages: []*mpr.NavRoleBasedHome{
-					{UserRole: "Admin", Page: "Admin.Dashboard"},
-				},
-				MenuItems: []*mpr.NavMenuItem{
-					{Caption: "Home", Page: "Home"},
-				},
-				OfflineEntities: []*mpr.NavOfflineEntity{
-					{Entity: "MyModule.Task", SyncMode: "FullSync"},
-				},
-			},
-		},
-	}
-
-	// Access through types — compiles because they're the same type
-	var typesDoc *types.NavigationDocument = doc
-	if typesDoc.Name != "Navigation" {
-		t.Errorf("expected Navigation, got %q", typesDoc.Name)
-	}
-	if len(typesDoc.Profiles) != 1 {
-		t.Fatalf("expected 1 profile, got %d", len(typesDoc.Profiles))
-	}
-	p := typesDoc.Profiles[0]
-	if p.Kind != "Responsive" {
-		t.Errorf("expected Responsive, got %q", p.Kind)
-	}
-	if p.HomePage.Page != "MyFirstModule.Home" {
-		t.Errorf("expected home page, got %q", p.HomePage.Page)
-	}
-	if len(p.RoleBasedHomePages) != 1 {
-		t.Errorf("expected 1 role-based home, got %d", len(p.RoleBasedHomePages))
-	}
-	if len(p.MenuItems) != 1 {
-		t.Errorf("expected 1 menu item, got %d", len(p.MenuItems))
-	}
-	if len(p.OfflineEntities) != 1 {
-		t.Errorf("expected 1 offline entity, got %d", len(p.OfflineEntities))
-	}
-}
-
-// TestJsonStructureFieldPreservation verifies JsonStructure + recursive
-// JsonElement children survive alias crossing.
-func TestJsonStructureFieldPreservation(t *testing.T) {
-	js := &mpr.JsonStructure{
-		ContainerID:   model.ID("m1"),
-		Name:          "MyJson",
-		Documentation: "Test json structure",
-		JsonSnippet:   `{"a":1}`,
-		Elements: []*mpr.JsonElement{
-			{
-				ExposedName:   "Root",
-				Path:          "(Object)",
-				ElementType:   "Object",
-				PrimitiveType: "Unknown",
-				Children: []*mpr.JsonElement{
-					{
-						ExposedName:   "A",
-						Path:          "(Object)|a",
-						ElementType:   "Value",
-						PrimitiveType: "Integer",
-						OriginalValue: "1",
-					},
-				},
-			},
-		},
-	}
-
-	var typesJS *types.JsonStructure = js
-	if typesJS.Name != "MyJson" {
-		t.Errorf("expected MyJson, got %q", typesJS.Name)
-	}
-	if len(typesJS.Elements) != 1 {
-		t.Fatalf("expected 1 element, got %d", len(typesJS.Elements))
-	}
-	root := typesJS.Elements[0]
-	if len(root.Children) != 1 {
-		t.Fatalf("expected 1 child, got %d", len(root.Children))
-	}
-	child := root.Children[0]
-	if child.PrimitiveType != "Integer" {
-		t.Errorf("expected Integer, got %q", child.PrimitiveType)
-	}
-	if child.OriginalValue != "1" {
-		t.Errorf("expected original value '1', got %q", child.OriginalValue)
-	}
-}
-
-// TestImageCollectionFieldPreservation verifies ImageCollection + Image.
-func TestImageCollectionFieldPreservation(t *testing.T) {
-	ic := &mpr.ImageCollection{
-		ContainerID: model.ID("m1"),
-		Name:        "Images",
-		Images: []mpr.Image{
-			{ID: model.ID("i1"), Name: "logo.png", Format: "png", Data: []byte{0x89, 0x50}},
-		},
-	}
-
-	var typesIC *types.ImageCollection = ic
-	if typesIC.Name != "Images" {
-		t.Errorf("expected Images, got %q", typesIC.Name)
-	}
-	if len(typesIC.Images) != 1 {
-		t.Fatalf("expected 1 image, got %d", len(typesIC.Images))
-	}
-	img := typesIC.Images[0]
-	if img.Name != "logo.png" {
-		t.Errorf("expected logo.png, got %q", img.Name)
-	}
-	if len(img.Data) != 2 {
-		t.Errorf("expected 2 bytes, got %d", len(img.Data))
-	}
-}
diff --git a/mdl/backend/mpr/datagrid_builder.go b/mdl/backend/mpr/datagrid_builder.go
deleted file mode 100644
index 5ddecdade8..0000000000
--- a/mdl/backend/mpr/datagrid_builder.go
+++ /dev/null
@@ -1,155 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-package mprbackend
-
-import (
-	"log"
-
-	"go.mongodb.org/mongo-driver/bson"
-
-	"github.com/mendixlabs/mxcli/mdl/backend"
-	"github.com/mendixlabs/mxcli/mdl/bsonutil"
-	"github.com/mendixlabs/mxcli/mdl/types"
-	"github.com/mendixlabs/mxcli/model"
-	"github.com/mendixlabs/mxcli/sdk/pages"
-	"github.com/mendixlabs/mxcli/sdk/widgets"
-)
-
-// BuildFilterWidget builds a filter widget for DataGrid2.
-func (b *MprBackend) BuildFilterWidget(spec backend.FilterWidgetSpec, projectPath string) (pages.Widget, error) {
-	bsonD := b.buildFilterWidgetBSON(spec.WidgetID, spec.FilterName, projectPath)
-
-	// Wrap the BSON in a CustomWidget
-	w := &pages.CustomWidget{
-		BaseWidget: pages.BaseWidget{
-			BaseElement: model.BaseElement{
-				ID:       model.ID(types.GenerateID()),
-				TypeName: "CustomWidgets$CustomWidget",
-			},
-			Name: spec.FilterName,
-		},
-		Editable:  "Always",
-		RawObject: getBsonField(bsonD, "Object"),
-		RawType:   getBsonField(bsonD, "Type"),
-	}
-	return w, nil
-}
-
-// ===========================================================================
-// Filter widget BSON construction
-// ===========================================================================
-
-func (b *MprBackend) buildFilterWidgetBSON(widgetID, filterName string, projectPath string) bson.D {
-	rawType, rawObject, _, _, err := widgets.GetTemplateFullBSON(widgetID, types.GenerateID, projectPath)
-	if err != nil || rawType == nil {
-		if err != nil {
-			log.Printf("warning: failed to load template for widget %s: %v; using minimal fallback", widgetID, err)
-		}
-		return b.buildMinimalFilterWidgetBSON(widgetID, filterName)
-	}
-
-	// A complete CustomWidget BSON requires Appearance, ConditionalEditability/
-	// VisibilitySettings, LabelTemplate, and TabIndex alongside Type/Object.
-	// Omitting Appearance triggers CE0463 ("definition of this widget has
-	// changed") because Studio Pro requires every CustomWidget to carry the
-	// full Forms$Page widget envelope, not just the inner widget-specific
-	// payload. See docs/mpr-bson-shapes.md for reference.
-	return bson.D{
-		{Key: "$ID", Value: bsonutil.NewIDBsonBinary()},
-		{Key: "$Type", Value: "CustomWidgets$CustomWidget"},
-		{Key: "Appearance", Value: defaultEmptyAppearance()},
-		{Key: "ConditionalEditabilitySettings", Value: nil},
-		{Key: "ConditionalVisibilitySettings", Value: nil},
-		{Key: "Editable", Value: "Always"},
-		{Key: "LabelTemplate", Value: nil},
-		{Key: "Name", Value: filterName},
-		{Key: "Object", Value: rawObject},
-		{Key: "TabIndex", Value: int32(0)},
-		{Key: "Type", Value: rawType},
-	}
-}
-
-// defaultEmptyAppearance returns the Forms$Appearance BSON for a widget that
-// has no class, style, or design properties — matches what Studio Pro emits.
-func defaultEmptyAppearance() bson.D {
-	return bson.D{
-		{Key: "$ID", Value: bsonutil.NewIDBsonBinary()},
-		{Key: "$Type", Value: "Forms$Appearance"},
-		{Key: "Class", Value: ""},
-		{Key: "DesignProperties", Value: bson.A{int32(3)}},
-		{Key: "DynamicClasses", Value: ""},
-		{Key: "Style", Value: ""},
-	}
-}
-
-func (b *MprBackend) buildMinimalFilterWidgetBSON(widgetID, filterName string) bson.D {
-	typeID := types.GenerateID()
-	objectTypeID := types.GenerateID()
-	objectID := types.GenerateID()
-
-	var widgetTypeName string
-	switch widgetID {
-	case pages.WidgetIDDataGridTextFilter:
-		widgetTypeName = "Text filter"
-	case pages.WidgetIDDataGridNumberFilter:
-		widgetTypeName = "Number filter"
-	case pages.WidgetIDDataGridDateFilter:
-		widgetTypeName = "Date filter"
-	case pages.WidgetIDDataGridDropdownFilter:
-		widgetTypeName = "Drop-down filter"
-	default:
-		widgetTypeName = "Text filter"
-	}
-
-	return bson.D{
-		{Key: "$ID", Value: bsonutil.NewIDBsonBinary()},
-		{Key: "$Type", Value: "CustomWidgets$CustomWidget"},
-		{Key: "Appearance", Value: defaultEmptyAppearance()},
-		{Key: "ConditionalEditabilitySettings", Value: nil},
-		{Key: "ConditionalVisibilitySettings", Value: nil},
-		{Key: "Editable", Value: "Always"},
-		{Key: "LabelTemplate", Value: nil},
-		{Key: "Name", Value: filterName},
-		{Key: "Object", Value: bson.D{
-			{Key: "$ID", Value: bsonutil.IDToBsonBinary(objectID)},
-			{Key: "$Type", Value: "CustomWidgets$WidgetObject"},
-			{Key: "Properties", Value: bson.A{int32(2)}},
-			{Key: "TypePointer", Value: bsonutil.IDToBsonBinary(objectTypeID)},
-		}},
-		{Key: "TabIndex", Value: int32(0)},
-		{Key: "Type", Value: bson.D{
-			{Key: "$ID", Value: bsonutil.IDToBsonBinary(typeID)},
-			{Key: "$Type", Value: "CustomWidgets$CustomWidgetType"},
-			{Key: "HelpUrl", Value: ""},
-			{Key: "ObjectType", Value: bson.D{
-				{Key: "$ID", Value: bsonutil.IDToBsonBinary(objectTypeID)},
-				{Key: "$Type", Value: "CustomWidgets$WidgetObjectType"},
-				{Key: "PropertyTypes", Value: bson.A{int32(2)}},
-			}},
-			{Key: "OfflineCapable", Value: true},
-			{Key: "StudioCategory", Value: "Data Controls"},
-			{Key: "StudioProCategory", Value: "Data controls"},
-			{Key: "SupportedPlatform", Value: "Web"},
-			{Key: "WidgetDescription", Value: ""},
-			{Key: "WidgetId", Value: widgetID},
-			{Key: "WidgetName", Value: widgetTypeName},
-			{Key: "WidgetNeedsEntityContext", Value: false},
-			{Key: "WidgetPluginWidget", Value: true},
-		}},
-	}
-}
-
-// ===========================================================================
-// BSON field helpers
-// ===========================================================================
-
-func getBsonField(d bson.D, key string) bson.D {
-	for _, elem := range d {
-		if elem.Key == key {
-			if nested, ok := elem.Value.(bson.D); ok {
-				return nested
-			}
-		}
-	}
-	return nil
-}
diff --git a/mdl/backend/mpr/offline_sync_carry_test.go b/mdl/backend/mpr/offline_sync_carry_test.go
deleted file mode 100644
index 575c5bb5a6..0000000000
--- a/mdl/backend/mpr/offline_sync_carry_test.go
+++ /dev/null
@@ -1,55 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-package mprbackend
-
-import (
-	"testing"
-
-	"github.com/mendixlabs/mxcli/sdk/mpr"
-)
-
-// The properties Studio Pro writes on a web profile's offline entity config,
-// measured against ako/TestApp's TabletOffline profile: seven configs spanning
-// all six sync modes.
-//
-// CompatibilityMode is why this test exists. The semantic model carried three
-// of the four written properties, so it was read and discarded — and a write
-// path built on that model would have dropped it the way `create or modify
-// entity` dropped access rules. Nothing else would have said so: the document
-// stays valid, and `mx check` reports 0 errors either way.
-func TestOfflineEntityConfigCarriesEveryStoredProperty(t *testing.T) {
-	// One case per observed sync mode, so a mode that stops round-tripping is
-	// named rather than hidden in a total.
-	cases := []*mpr.NavOfflineEntity{
-		{Entity: "Mappings.Customer", SyncMode: "Never"},
-		{Entity: "Pages.Bus", SyncMode: "All"},
-		{Entity: "Rules.BusinessRule", SyncMode: "Online"},
-		{Entity: "Rules.RuleAction", SyncMode: "Constrained",
-			Constraint: "[\n  (\n    contains(ActionValue, '''abc''')\n  )\n]"},
-		{Entity: "Rules.RuleCategory", SyncMode: "None"},
-		{Entity: "Rules.RuleExecutionLog", SyncMode: "NoneAndPreserveData"},
-		{Entity: "System.Language", SyncMode: "All"},
-		// Not present in any reference config — every one carries false — but
-		// carrying only the false case would prove nothing about a bool.
-		{Entity: "Mod.Compat", SyncMode: "All", CompatibilityMode: true},
-	}
-
-	for _, want := range cases {
-		t.Run(want.Entity+"/"+want.SyncMode, func(t *testing.T) {
-			in := &mpr.NavigationDocument{
-				Name: "Navigation",
-				Profiles: []*mpr.NavigationProfile{{
-					Name: "TabletOffline", Kind: "TabletOffline",
-					OfflineEntities: []*mpr.NavOfflineEntity{want},
-				}},
-			}
-			out := convertNavDoc(in)
-			if len(out.Profiles) != 1 || len(out.Profiles[0].OfflineEntities) != 1 {
-				t.Fatalf("profile or config lost in conversion: %+v", out)
-			}
-			if got := *out.Profiles[0].OfflineEntities[0]; got != *want {
-				t.Errorf("conversion dropped a property:\n got %+v\nwant %+v", got, *want)
-			}
-		})
-	}
-}
diff --git a/mdl/backend/mpr/page_mutator.go b/mdl/backend/mpr/page_mutator.go
deleted file mode 100644
index b417c51ccc..0000000000
--- a/mdl/backend/mpr/page_mutator.go
+++ /dev/null
@@ -1,59 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-package mprbackend
-
-import (
-	"fmt"
-
-	"go.mongodb.org/mongo-driver/bson"
-
-	"github.com/mendixlabs/mxcli/mdl/backend"
-	"github.com/mendixlabs/mxcli/mdl/backend/pagemutator"
-	"github.com/mendixlabs/mxcli/mdl/backend/widgetobj"
-	"github.com/mendixlabs/mxcli/model"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
-	"github.com/mendixlabs/mxcli/sdk/pages"
-)
-
-// OpenPageForMutation loads a page/snippet/layout unit and returns a PageMutator
-// backed by the shared pagemutator package. The mutator is engine-agnostic (pure
-// bson.D tree manipulation); the MPR-specific steps — child serialization, the
-// DataGrid2 column builder, and persisting the unit — are wired through
-// mprPageDeps.
-func (b *MprBackend) OpenPageForMutation(unitID model.ID) (backend.PageMutator, error) {
-	rawBytes, err := b.reader.GetRawUnitBytes(unitID)
-	if err != nil {
-		return nil, fmt.Errorf("load raw unit bytes: %w", err)
-	}
-	var rawData bson.D
-	if err := bson.Unmarshal(rawBytes, &rawData); err != nil {
-		return nil, fmt.Errorf("unmarshal unit BSON: %w", err)
-	}
-	return pagemutator.New(rawData, unitID, &mprPageDeps{backend: b}), nil
-}
-
-// mprPageDeps implements pagemutator.Deps for the MPR backend, delegating to the
-// sdk/mpr serializers, the DataGrid2 column builder, and the raw-unit writer.
-type mprPageDeps struct{ backend *MprBackend }
-
-var _ pagemutator.Deps = (*mprPageDeps)(nil)
-
-func (d *mprPageDeps) SerializeWidget(w pages.Widget) bson.D {
-	return mpr.SerializeWidget(w)
-}
-
-func (d *mprPageDeps) SerializeClientAction(a pages.ClientAction) bson.D {
-	return mpr.SerializeClientAction(a)
-}
-
-func (d *mprPageDeps) SerializeCustomWidgetDataSource(ds pages.DataSource) bson.D {
-	return mpr.SerializeCustomWidgetDataSource(ds)
-}
-
-func (d *mprPageDeps) BuildDataGrid2Column(col *backend.DataGridColumnSpec, columnObjectTypeID string, columnPropertyIDs map[string]pages.PropertyTypeIDEntry) (bson.D, error) {
-	return widgetobj.BuildDataGrid2Column(mprChildSerializer{}, col, columnObjectTypeID, columnPropertyIDs), nil
-}
-
-func (d *mprPageDeps) SaveUnit(unitID string, contents []byte) error {
-	return d.backend.writer.UpdateRawUnit(unitID, contents)
-}
diff --git a/mdl/backend/mpr/widget_builder.go b/mdl/backend/mpr/widget_builder.go
deleted file mode 100644
index baa2910370..0000000000
--- a/mdl/backend/mpr/widget_builder.go
+++ /dev/null
@@ -1,82 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-package mprbackend
-
-import (
-	"go.mongodb.org/mongo-driver/bson"
-
-	"github.com/mendixlabs/mxcli/mdl/backend"
-	"github.com/mendixlabs/mxcli/mdl/backend/widgetobj"
-	"github.com/mendixlabs/mxcli/mdl/types"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
-	"github.com/mendixlabs/mxcli/sdk/pages"
-	"github.com/mendixlabs/mxcli/sdk/widgets"
-)
-
-// The pluggable-widget object builder now lives in the engine-agnostic
-// mdl/backend/widgetobj package. This file keeps only the MprBackend-specific
-// glue: loading templates from sdk/widgets, the legacy child serializer, and the
-// opaque-serialization helpers.
-
-// mprChildSerializer routes the builder's child-content serialization through the
-// legacy sdk/mpr serializers (byte-identical to before the extraction).
-type mprChildSerializer struct{}
-
-func (mprChildSerializer) SerializeWidget(w pages.Widget) bson.D { return mpr.SerializeWidget(w) }
-func (mprChildSerializer) SerializeClientAction(a pages.ClientAction) bson.D {
-	return mpr.SerializeClientAction(a)
-}
-func (mprChildSerializer) SerializeCustomWidgetDataSource(ds pages.DataSource) bson.D {
-	return mpr.SerializeCustomWidgetDataSource(ds)
-}
-
-// LoadWidgetTemplate loads a widget template by ID and returns a builder.
-func (b *MprBackend) LoadWidgetTemplate(widgetID string, projectPath string) (backend.WidgetObjectBuilder, error) {
-	embeddedType, embeddedObject, embeddedIDs, objectTypeID, err :=
-		widgets.GetTemplateFullBSON(widgetID, types.GenerateID, projectPath)
-	if err != nil {
-		return nil, err
-	}
-	if embeddedType == nil || embeddedObject == nil {
-		return nil, nil
-	}
-	return widgetobj.New(widgetID, embeddedType, embeddedObject,
-		convertPropertyTypeIDs(embeddedIDs), objectTypeID, mprChildSerializer{}), nil
-}
-
-// SerializeWidgetToOpaque converts a domain Widget to opaque BSON form.
-func (b *MprBackend) SerializeWidgetToOpaque(w pages.Widget) any {
-	return mpr.SerializeWidget(w)
-}
-
-// SerializeDataSourceToOpaque converts a domain DataSource to opaque BSON form.
-func (b *MprBackend) SerializeDataSourceToOpaque(ds pages.DataSource) any {
-	return mpr.SerializeCustomWidgetDataSource(ds)
-}
-
-// BuildCreateAttributeObject creates an attribute object for filter widgets.
-func (b *MprBackend) BuildCreateAttributeObject(attributePath string, objectTypeID, propertyTypeID, valueTypeID string) (any, error) {
-	return widgetobj.CreateAttributeObject(attributePath, objectTypeID, propertyTypeID, valueTypeID)
-}
-
-// convertPropertyTypeIDs maps the sdk/widgets template's property-type IDs to the
-// pages form the builder uses.
-func convertPropertyTypeIDs(src map[string]widgets.PropertyTypeIDEntry) map[string]pages.PropertyTypeIDEntry {
-	result := make(map[string]pages.PropertyTypeIDEntry)
-	for k, v := range src {
-		entry := pages.PropertyTypeIDEntry{
-			PropertyTypeID: v.PropertyTypeID,
-			ValueTypeID:    v.ValueTypeID,
-			DefaultValue:   v.DefaultValue,
-			ValueType:      v.ValueType,
-			Required:       v.Required,
-			ObjectTypeID:   v.ObjectTypeID,
-		}
-		if len(v.NestedPropertyIDs) > 0 {
-			entry.NestedPropertyIDs = convertPropertyTypeIDs(v.NestedPropertyIDs)
-			entry.NestedKeyOrder = append([]string(nil), v.NestedKeyOrder...)
-		}
-		result[k] = entry
-	}
-	return result
-}
diff --git a/mdl/backend/mpr/workflow_mutator.go b/mdl/backend/mpr/workflow_mutator.go
deleted file mode 100644
index 7bac8489ae..0000000000
--- a/mdl/backend/mpr/workflow_mutator.go
+++ /dev/null
@@ -1,46 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-package mprbackend
-
-import (
-	"fmt"
-
-	"go.mongodb.org/mongo-driver/bson"
-
-	"github.com/mendixlabs/mxcli/mdl/backend"
-	"github.com/mendixlabs/mxcli/mdl/backend/wfmutator"
-	"github.com/mendixlabs/mxcli/model"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
-	"github.com/mendixlabs/mxcli/sdk/workflows"
-)
-
-// openWorkflowForMutation loads a workflow unit and returns a WorkflowMutator
-// backed by the shared wfmutator package. The mutation logic is engine-agnostic
-// (pure bson.D tree manipulation over the unit's raw bytes); the two
-// storage-specific steps — serializing a new activity to bson.D and persisting
-// the unit — are wired through mprWorkflowDeps.
-func (b *MprBackend) openWorkflowForMutation(unitID model.ID) (backend.WorkflowMutator, error) {
-	rawBytes, err := b.reader.GetRawUnitBytes(unitID)
-	if err != nil {
-		return nil, fmt.Errorf("load raw unit bytes: %w", err)
-	}
-	var rawData bson.D
-	if err := bson.Unmarshal(rawBytes, &rawData); err != nil {
-		return nil, fmt.Errorf("unmarshal workflow BSON: %w", err)
-	}
-	return wfmutator.New(rawData, unitID, &mprWorkflowDeps{backend: b}), nil
-}
-
-// mprWorkflowDeps implements wfmutator.Deps for the MPR backend, delegating to
-// the sdk/mpr activity serializer and the raw-unit writer.
-type mprWorkflowDeps struct{ backend *MprBackend }
-
-var _ wfmutator.Deps = (*mprWorkflowDeps)(nil)
-
-func (d *mprWorkflowDeps) SerializeWorkflowActivity(a workflows.WorkflowActivity) bson.D {
-	return mpr.SerializeWorkflowActivity(a, d.backend.useCallMicroflowActivityName())
-}
-
-func (d *mprWorkflowDeps) SaveUnit(unitID string, contents []byte) error {
-	return d.backend.writer.UpdateRawUnit(unitID, contents)
-}
diff --git a/mdl/enginecompare/bsoncompare.go b/mdl/enginecompare/bsoncompare.go
deleted file mode 100644
index 8de761e1aa..0000000000
--- a/mdl/enginecompare/bsoncompare.go
+++ /dev/null
@@ -1,250 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-package enginecompare
-
-import (
-	"fmt"
-	"sort"
-	"strings"
-
-	"go.mongodb.org/mongo-driver/v2/bson"
-
-	"github.com/mendixlabs/mxcli/modelsdk/codec"
-	genConst "github.com/mendixlabs/mxcli/modelsdk/gen/constants"
-	_ "github.com/mendixlabs/mxcli/modelsdk/gen/datatypes" // register DataTypes$* for constant decode
-	genDm "github.com/mendixlabs/mxcli/modelsdk/gen/domainmodels"
-	genEnum "github.com/mendixlabs/mxcli/modelsdk/gen/enumerations"
-	genMf "github.com/mendixlabs/mxcli/modelsdk/gen/microflows"
-	mmpr "github.com/mendixlabs/mxcli/modelsdk/mpr"
-	"github.com/mendixlabs/mxcli/modelsdk/mprread"
-)
-
-// MicroflowCanonBSON returns the canonicalized raw BSON of a named microflow unit
-// in a module (microflows are top-level documents).
-func MicroflowCanonBSON(projectPath, moduleName, mfName string) (string, error) {
-	r, err := mmpr.OpenWithOptions(projectPath, mmpr.OpenOptions{ReadOnly: true})
-	if err != nil {
-		return "", err
-	}
-	defer r.Close()
-
-	mod, err := r.GetModuleByName(moduleName)
-	if err != nil || mod == nil {
-		return "", fmt.Errorf("module %q not found: %v", moduleName, err)
-	}
-	units, err := mprread.ListUnitsWithContainer[*genMf.Microflow](r)
-	if err != nil {
-		return "", err
-	}
-	for _, u := range units {
-		if string(u.ContainerID) != mod.ID || u.Element.Name() != mfName {
-			continue
-		}
-		raw, err := r.GetRawUnitBytes(string(u.Element.ID()))
-		if err != nil {
-			return "", err
-		}
-		return CanonicalizeRaw(bson.Raw(raw)), nil
-	}
-	return "", fmt.Errorf("microflow %q not found in module %q", mfName, moduleName)
-}
-
-// ConstCanonBSON returns the canonicalized raw BSON of a named constant unit in a
-// module (constants are top-level documents).
-func ConstCanonBSON(projectPath, moduleName, constName string) (string, error) {
-	r, err := mmpr.OpenWithOptions(projectPath, mmpr.OpenOptions{ReadOnly: true})
-	if err != nil {
-		return "", err
-	}
-	defer r.Close()
-
-	mod, err := r.GetModuleByName(moduleName)
-	if err != nil || mod == nil {
-		return "", fmt.Errorf("module %q not found: %v", moduleName, err)
-	}
-	units, err := mprread.ListUnitsWithContainer[*genConst.Constant](r)
-	if err != nil {
-		return "", err
-	}
-	for _, u := range units {
-		if string(u.ContainerID) != mod.ID || u.Element.Name() != constName {
-			continue
-		}
-		raw, err := r.GetRawUnitBytes(string(u.Element.ID()))
-		if err != nil {
-			return "", err
-		}
-		return CanonicalizeRaw(bson.Raw(raw)), nil
-	}
-	return "", fmt.Errorf("constant %q not found in module %q", constName, moduleName)
-}
-
-// EnumCanonBSON returns the canonicalized raw BSON of a named enumeration unit in
-// a module (enumerations are top-level documents, not domain-model children).
-func EnumCanonBSON(projectPath, moduleName, enumName string) (string, error) {
-	r, err := mmpr.OpenWithOptions(projectPath, mmpr.OpenOptions{ReadOnly: true})
-	if err != nil {
-		return "", err
-	}
-	defer r.Close()
-
-	mod, err := r.GetModuleByName(moduleName)
-	if err != nil || mod == nil {
-		return "", fmt.Errorf("module %q not found: %v", moduleName, err)
-	}
-	units, err := mprread.ListUnitsWithContainer[*genEnum.Enumeration](r)
-	if err != nil {
-		return "", err
-	}
-	for _, u := range units {
-		if string(u.ContainerID) != mod.ID || u.Element.Name() != enumName {
-			continue
-		}
-		raw, err := r.GetRawUnitBytes(string(u.Element.ID()))
-		if err != nil {
-			return "", err
-		}
-		return CanonicalizeRaw(bson.Raw(raw)), nil
-	}
-	return "", fmt.Errorf("enumeration %q not found in module %q", enumName, moduleName)
-}
-
-// volatileKeys hold per-write-random values (IDs, GUIDs); masked before compare
-// so two engines' BSON can be diffed on structure + stable values.
-var volatileKeys = map[string]bool{
-	"$ID":             true,
-	"GUID":            true,
-	"DataStorageGuid": true,
-}
-
-// CanonicalizeRaw renders a BSON document into an order-independent, ID-masked
-// string: keys sort, embedded docs/arrays recurse, binaries and volatile keys
-// collapse to placeholders. A residual difference is a real structural/value
-// divergence. Walks bson.Raw directly — unmarshalling Mendix unit BSON into
-// bson.M mis-decodes typed arrays.
-func CanonicalizeRaw(raw bson.Raw) string {
-	elems, err := raw.Elements()
-	if err != nil {
-		return "<malformed:" + err.Error() + ">"
-	}
-	parts := make([]string, 0, len(elems))
-	for _, e := range elems {
-		k := e.Key()
-		if volatileKeys[k] {
-			parts = append(parts, k+"=<masked>")
-			continue
-		}
-		parts = append(parts, k+"="+canonValue(e.Value()))
-	}
-	sort.Strings(parts)
-	return "{" + strings.Join(parts, ",") + "}"
-}
-
-func canonValue(v bson.RawValue) string {
-	switch v.Type {
-	case bson.TypeEmbeddedDocument:
-		return CanonicalizeRaw(v.Document())
-	case bson.TypeArray:
-		vals, _ := v.Array().Values()
-		parts := make([]string, len(vals))
-		for i, rv := range vals {
-			parts[i] = canonValue(rv)
-		}
-		return "[" + strings.Join(parts, ",") + "]"
-	case bson.TypeBinary:
-		return "<binary>"
-	default:
-		return v.String()
-	}
-}
-
-// EntityCanonBSON opens a written project, decodes the named module's domain
-// model via the codec, finds the named entity, and returns the canonicalized
-// raw BSON of that entity sub-document — the unit of write-parity comparison.
-func EntityCanonBSON(projectPath, moduleName, entityName string) (string, error) {
-	r, err := mmpr.OpenWithOptions(projectPath, mmpr.OpenOptions{ReadOnly: true})
-	if err != nil {
-		return "", err
-	}
-	defer r.Close()
-
-	mod, err := r.GetModuleByName(moduleName)
-	if err != nil || mod == nil {
-		return "", fmt.Errorf("module %q not found: %v", moduleName, err)
-	}
-	units, err := mprread.ListUnitsWithContainer[*genDm.DomainModel](r)
-	if err != nil {
-		return "", err
-	}
-	dec := codec.NewDecoder(codec.DefaultRegistry)
-	for _, u := range units {
-		if string(u.ContainerID) != mod.ID {
-			continue
-		}
-		raw, err := r.GetRawUnitBytes(string(u.Element.ID()))
-		if err != nil {
-			return "", err
-		}
-		el, err := dec.Decode(raw)
-		if err != nil {
-			return "", err
-		}
-		dm, ok := el.(*genDm.DomainModel)
-		if !ok {
-			continue
-		}
-		for _, ee := range dm.EntitiesItems() {
-			ent, ok := ee.(*genDm.Entity)
-			if !ok || ent.Name() != entityName {
-				continue
-			}
-			return CanonicalizeRaw(bson.Raw(ee.Raw())), nil
-		}
-	}
-	return "", fmt.Errorf("entity %q not found in module %q", entityName, moduleName)
-}
-
-// AssociationCanonBSON returns the canonicalized raw BSON of a named association
-// in a module's domain model (associations are DM children, not entity children).
-func AssociationCanonBSON(projectPath, moduleName, assocName string) (string, error) {
-	r, err := mmpr.OpenWithOptions(projectPath, mmpr.OpenOptions{ReadOnly: true})
-	if err != nil {
-		return "", err
-	}
-	defer r.Close()
-
-	mod, err := r.GetModuleByName(moduleName)
-	if err != nil || mod == nil {
-		return "", fmt.Errorf("module %q not found: %v", moduleName, err)
-	}
-	units, err := mprread.ListUnitsWithContainer[*genDm.DomainModel](r)
-	if err != nil {
-		return "", err
-	}
-	dec := codec.NewDecoder(codec.DefaultRegistry)
-	for _, u := range units {
-		if string(u.ContainerID) != mod.ID {
-			continue
-		}
-		raw, err := r.GetRawUnitBytes(string(u.Element.ID()))
-		if err != nil {
-			return "", err
-		}
-		el, err := dec.Decode(raw)
-		if err != nil {
-			return "", err
-		}
-		dm, ok := el.(*genDm.DomainModel)
-		if !ok {
-			continue
-		}
-		for _, ae := range dm.AssociationsItems() {
-			as, ok := ae.(*genDm.Association)
-			if !ok || as.Name() != assocName {
-				continue
-			}
-			return CanonicalizeRaw(bson.Raw(ae.Raw())), nil
-		}
-	}
-	return "", fmt.Errorf("association %q not found in module %q", assocName, moduleName)
-}
diff --git a/mdl/enginecompare/compare.go b/mdl/enginecompare/compare.go
deleted file mode 100644
index 84c75e4953..0000000000
--- a/mdl/enginecompare/compare.go
+++ /dev/null
@@ -1,105 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-// Package enginecompare runs the same MDL read query through both the legacy
-// (sdk/mpr) and the modelsdk engines in-process and compares their rendered
-// output. It is the read-side of the dual-engine comparison harness described in
-// docs/plans/2026-06-05-adopt-modelsdk-engine.md — automating the manual
-// `--engine legacy` vs `--engine modelsdk` diffs into a repeatable parity gate.
-//
-// (Write/BSON comparison with an ID-canonicalizer comes in Phase 2, once the
-// modelsdk backend can write.)
-package enginecompare
-
-import (
-	"bytes"
-	"fmt"
-	"sort"
-	"strings"
-
-	"github.com/mendixlabs/mxcli/mdl/backend"
-	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
-	mprbackend "github.com/mendixlabs/mxcli/mdl/backend/mpr"
-	"github.com/mendixlabs/mxcli/mdl/executor"
-	"github.com/mendixlabs/mxcli/mdl/visitor"
-)
-
-// Engine selects which backend implementation to run a query against.
-type Engine string
-
-const (
-	Legacy   Engine = "legacy"
-	ModelSDK Engine = "modelsdk"
-)
-
-func factory(e Engine) func() backend.FullBackend {
-	if e == ModelSDK {
-		return func() backend.FullBackend { return modelsdkbackend.New() }
-	}
-	return func() backend.FullBackend { return mprbackend.New() }
-}
-
-// Run connects to projectPath with the chosen engine, executes a single read
-// query, and returns the rendered output.
-func Run(eng Engine, projectPath, query string) (string, error) {
-	var buf bytes.Buffer
-	exec := executor.New(&buf)
-	exec.SetBackendFactory(factory(eng))
-	defer exec.Close()
-
-	prog, errs := visitor.Build(fmt.Sprintf("CONNECT LOCAL '%s'; %s", projectPath, query))
-	if len(errs) > 0 {
-		return "", fmt.Errorf("parse %q: %v", query, errs[0])
-	}
-	if err := exec.ExecuteProgram(prog); err != nil {
-		return "", fmt.Errorf("execute %q on %s: %w", query, eng, err)
-	}
-	return buf.String(), nil
-}
-
-// NormalizeTable reduces a rendered markdown-ish table to comparable rows:
-// it keeps table rows, trims per-cell padding (so column widths don't matter),
-// drops separator rows, applies an optional row filter, and sorts (so row order
-// doesn't matter). The result is what two engines must agree on.
-func NormalizeTable(out string, keep func(string) bool) []string {
-	var rows []string
-	for line := range strings.SplitSeq(out, "\n") {
-		if !strings.HasPrefix(line, "|") || strings.HasPrefix(line, "|--") || strings.HasPrefix(line, "| --") {
-			continue
-		}
-		cells := strings.Split(line, "|")
-		for i := range cells {
-			cells[i] = strings.TrimSpace(cells[i])
-		}
-		norm := strings.Join(cells, "|")
-		if keep != nil && !keep(norm) {
-			continue
-		}
-		rows = append(rows, norm)
-	}
-	sort.Strings(rows)
-	return rows
-}
-
-// DiffRows returns a human-readable summary of rows present in only one side.
-func DiffRows(legacy, modelsdk []string) string {
-	ls := map[string]bool{}
-	for _, r := range legacy {
-		ls[r] = true
-	}
-	ms := map[string]bool{}
-	for _, r := range modelsdk {
-		ms[r] = true
-	}
-	var b strings.Builder
-	for _, r := range legacy {
-		if !ms[r] {
-			fmt.Fprintf(&b, "  - legacy-only:   %s\n", r)
-		}
-	}
-	for _, r := range modelsdk {
-		if !ls[r] {
-			fmt.Fprintf(&b, "  + modelsdk-only: %s\n", r)
-		}
-	}
-	return b.String()
-}
diff --git a/mdl/enginecompare/compare_test.go b/mdl/enginecompare/compare_test.go
deleted file mode 100644
index bbae87b46a..0000000000
--- a/mdl/enginecompare/compare_test.go
+++ /dev/null
@@ -1,76 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-package enginecompare
-
-import (
-	"slices"
-	"strings"
-	"testing"
-)
-
-const fixture = "../../testdata/expr-checker/minimal.mpr"
-
-// dropSystem filters out rows whose qualified name is in the System module —
-// legacy injects the whole System module from hardcoded sdk/mpr/system_module.go,
-// while the modelsdk engine reads only real project units. This is a known,
-// tracked architectural difference, not a conversion error.
-func dropSystem(row string) bool { return !strings.HasPrefix(row, "|System.") }
-
-// dropSystemModule drops the System module's row from a SHOW MODULES table
-// (module name in the first cell), same rationale as dropSystem.
-func dropSystemModule(row string) bool { return !strings.HasPrefix(row, "|System|") }
-
-// TestReadParity runs each read query through both engines and asserts their
-// normalized output matches. Cases with a knownGap are reported, not failed —
-// they document where the engines legitimately differ today (and flag if they
-// unexpectedly start matching, a cue to promote them to strict).
-func TestReadParity(t *testing.T) {
-	cases := []struct {
-		name     string
-		query    string
-		keep     func(string) bool
-		knownGap string
-	}{
-		{name: "microflows", query: "SHOW MICROFLOWS"},
-		{name: "nanoflows", query: "SHOW NANOFLOWS"},
-		{name: "pages", query: "SHOW PAGES"},
-		{name: "enumerations", query: "SHOW ENUMERATIONS"},
-		{name: "constants", query: "SHOW CONSTANTS"},
-		{name: "entities", query: "SHOW ENTITIES", keep: dropSystem},
-		// Non-System modules match across every column (Source, and all per-doc
-		// counts: entities, enums, pages, snippets, microflows, nanoflows, java
-		// actions). The System row differs only because legacy injects a
-		// hardcoded System module while modelsdk reads the real (sparser) unit —
-		// same principled difference as entities — so it is filtered out.
-		{name: "modules", query: "SHOW MODULES", keep: dropSystemModule},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			legacy, err := Run(Legacy, fixture, tc.query)
-			if err != nil {
-				t.Fatalf("legacy: %v", err)
-			}
-			modelsdk, err := Run(ModelSDK, fixture, tc.query)
-			if err != nil {
-				t.Fatalf("modelsdk: %v", err)
-			}
-			lr := NormalizeTable(legacy, tc.keep)
-			mr := NormalizeTable(modelsdk, tc.keep)
-			equal := slices.Equal(lr, mr)
-
-			if tc.knownGap != "" {
-				if equal {
-					t.Logf("known-gap case now MATCHES — consider promoting %q to strict", tc.name)
-				} else {
-					t.Logf("known gap (expected divergence): %s", tc.knownGap)
-				}
-				return
-			}
-			if !equal {
-				t.Errorf("read-parity divergence in %q (%d legacy rows, %d modelsdk rows):\n%s",
-					tc.name, len(lr), len(mr), DiffRows(lr, mr))
-			}
-		})
-	}
-}
diff --git a/mdl/enginecompare/write_alter_test.go b/mdl/enginecompare/write_alter_test.go
deleted file mode 100644
index d172b062de..0000000000
--- a/mdl/enginecompare/write_alter_test.go
+++ /dev/null
@@ -1,187 +0,0 @@
-package enginecompare
-
-import "testing"
-
-// dropOneAttr runs CREATE then ALTER…DROP ATTRIBUTE as two separate sessions so
-// the drop loads the entity back from persisted disk — exercising the codec's
-// passthrough dirty-path (kept attributes re-emitted from their original raw
-// bytes, only the Attributes list rebuilt).
-func dropAttrSeq(t *testing.T, eng Engine) string {
-	t.Helper()
-	p := copyProject(t)
-	const create = "CREATE PERSISTENT ENTITY MyFirstModule.DropAttrTest " +
-		"( Keep1: string(50), Gone: integer, Keep2: boolean )"
-	const drop = "ALTER ENTITY MyFirstModule.DropAttrTest DROP ATTRIBUTE Gone"
-	if _, e := Run(eng, p, create); e != nil {
-		t.Fatalf("%s create: %v", eng, e)
-	}
-	if _, e := Run(eng, p, drop); e != nil {
-		t.Fatalf("%s drop: %v", eng, e)
-	}
-	s, e := EntityCanonBSON(p, "MyFirstModule", "DropAttrTest")
-	if e != nil {
-		t.Fatalf("%s canon: %v", eng, e)
-	}
-	return s
-}
-
-func TestWriteParity_DropAttribute(t *testing.T) {
-	leg := dropAttrSeq(t, Legacy)
-	msd := dropAttrSeq(t, ModelSDK)
-	if leg != msd {
-		t.Errorf("DROP ATTRIBUTE divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
-
-// TestWriteParity_AlterKeepsAccessRule verifies that ALTERing an entity which
-// already has an access rule preserves that rule (and its member accesses) on the
-// codec round-trip. The role/entity/grant are set up via the legacy engine on
-// both copies so the starting state is identical; only the final ALTER differs by
-// engine. This is the path the UpdateEntity guard used to refuse.
-func TestWriteParity_AlterKeepsAccessRule(t *testing.T) {
-	const ent = "MyFirstModule.AREnt"
-	setup := []string{
-		"CREATE MODULE ROLE MyFirstModule.ARRole",
-		"CREATE PERSISTENT ENTITY " + ent + " ( Code: string(20), Rank: integer )",
-		"GRANT MyFirstModule.ARRole ON " + ent + " (read *, write *)",
-	}
-	alter := "ALTER ENTITY " + ent + " ADD ATTRIBUTE Extra: boolean"
-
-	run := func(alterEng Engine) string {
-		p := copyProject(t)
-		for _, s := range setup {
-			if _, e := Run(Legacy, p, s); e != nil {
-				t.Fatalf("setup %q: %v", s, e)
-			}
-		}
-		if _, e := Run(alterEng, p, alter); e != nil {
-			t.Fatalf("%s alter: %v", alterEng, e)
-		}
-		s, e := EntityCanonBSON(p, "MyFirstModule", "AREnt")
-		if e != nil {
-			t.Fatalf("%s canon: %v", alterEng, e)
-		}
-		return s
-	}
-	if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-		t.Errorf("ALTER-keeps-access-rule divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
-
-// TestWriteParity_AlterKeepsEventHandler verifies that ALTERing an entity which
-// has an event handler preserves it on the codec round-trip — the path the
-// UpdateEntity guard used to refuse, now closed after the MCP capture confirmed
-// the BSON keys (Type / SendInputParameter) and fixed the gen storage names.
-func TestWriteParity_AlterKeepsEventHandler(t *testing.T) {
-	const ent = "MyFirstModule.EvtEnt"
-	setup := []string{
-		"CREATE MICROFLOW MyFirstModule.OnEvt () RETURNS BOOLEAN BEGIN RETURN true; END",
-		"CREATE PERSISTENT ENTITY " + ent + " ( Code: string(20), Rank: integer )",
-		"ALTER ENTITY " + ent + " ADD EVENT HANDLER ON BEFORE COMMIT CALL MyFirstModule.OnEvt RAISE ERROR",
-	}
-	alter := "ALTER ENTITY " + ent + " ADD ATTRIBUTE Extra: boolean"
-
-	run := func(alterEng Engine) string {
-		p := copyProject(t)
-		for _, s := range setup {
-			if _, e := Run(Legacy, p, s); e != nil {
-				t.Fatalf("setup %q: %v", s, e)
-			}
-		}
-		if _, e := Run(alterEng, p, alter); e != nil {
-			t.Fatalf("%s alter: %v", alterEng, e)
-		}
-		s, e := EntityCanonBSON(p, "MyFirstModule", "EvtEnt")
-		if e != nil {
-			t.Fatalf("%s canon: %v", alterEng, e)
-		}
-		return s
-	}
-	if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-		t.Errorf("ALTER-keeps-event-handler divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
-
-// alterSeq runs a CREATE then an ALTER as two sessions (so the ALTER loads the
-// entity from disk: read-modify-write), returning the entity's canonical BSON.
-func alterSeq(t *testing.T, eng Engine, create, alter, module, entity string) string {
-	t.Helper()
-	p := copyProject(t)
-	if _, e := Run(eng, p, create); e != nil {
-		t.Fatalf("%s create: %v", eng, e)
-	}
-	if _, e := Run(eng, p, alter); e != nil {
-		t.Fatalf("%s alter %q: %v", eng, alter, e)
-	}
-	s, e := EntityCanonBSON(p, module, entity)
-	if e != nil {
-		t.Fatalf("%s canon: %v", eng, e)
-	}
-	return s
-}
-
-// TestWriteParity_AlterEntity exercises ALTER ENTITY read-modify-write across
-// the codec engine vs legacy. Each case creates an entity then applies one ALTER
-// op; both engines must produce identical canonical BSON. Cases touching indexes
-// stress the lossless read adapter beyond attributes.
-func TestWriteParity_AlterEntity(t *testing.T) {
-	const ent = "MyFirstModule.AlterT"
-	base := "CREATE PERSISTENT ENTITY " + ent + " ( Code: string(20), Rank: integer )"
-	idxBase := base + " index (Code)"
-	cases := []struct{ name, create, alter string }{
-		{"AddAttribute", base, "ALTER ENTITY " + ent + " ADD ATTRIBUTE Extra: decimal"},
-		{"RenameAttribute", base, "ALTER ENTITY " + ent + " RENAME ATTRIBUTE Rank TO Position"},
-		{"ModifyAttribute", base, "ALTER ENTITY " + ent + " MODIFY ATTRIBUTE Code string(200)"},
-		{"SetDocumentation", base, "ALTER ENTITY " + ent + " SET DOCUMENTATION 'an altered entity'"},
-		{"AddIndex", base, "ALTER ENTITY " + ent + " ADD INDEX (Rank)"},
-		{"DropIndexKeepsAttrs", idxBase, "ALTER ENTITY " + ent + " ADD ATTRIBUTE Extra: boolean"},
-		{"AlterKeepsValidation",
-			"CREATE PERSISTENT ENTITY " + ent + " ( Code: string(20) unique error 'must be unique', Rank: integer )",
-			"ALTER ENTITY " + ent + " ADD ATTRIBUTE Extra: boolean"},
-	}
-	for _, c := range cases {
-		t.Run(c.name, func(t *testing.T) {
-			leg := alterSeq(t, Legacy, c.create, c.alter, "MyFirstModule", "AlterT")
-			msd := alterSeq(t, ModelSDK, c.create, c.alter, "MyFirstModule", "AlterT")
-			if leg != msd {
-				t.Errorf("%s divergence:\nlegacy:   %s\nmodelsdk: %s", c.name, leg, msd)
-			}
-		})
-	}
-}
-
-// dropEntitySeq creates two entities + an association between them, then drops
-// the FROM entity. The kept entity's canonical BSON is returned; the cascade
-// (entity + association removed) is asserted separately by the caller.
-func dropEntitySeq(t *testing.T, eng Engine) string {
-	t.Helper()
-	p := copyProject(t)
-	stmts := []string{
-		"CREATE PERSISTENT ENTITY MyFirstModule.DropParent ( Code: string(20) )",
-		"CREATE PERSISTENT ENTITY MyFirstModule.DropChild ( Label: string(20) )",
-		"CREATE ASSOCIATION MyFirstModule.DropChild_DropParent FROM MyFirstModule.DropChild TO MyFirstModule.DropParent",
-		"DROP ENTITY MyFirstModule.DropChild",
-	}
-	for _, s := range stmts {
-		if _, e := Run(eng, p, s); e != nil {
-			t.Fatalf("%s %q: %v", eng, s, e)
-		}
-	}
-	// The dropped entity must be gone.
-	if _, e := EntityCanonBSON(p, "MyFirstModule", "DropChild"); e == nil {
-		t.Fatalf("%s: DropChild still present after DROP ENTITY", eng)
-	}
-	kept, e := EntityCanonBSON(p, "MyFirstModule", "DropParent")
-	if e != nil {
-		t.Fatalf("%s: kept entity canon: %v", eng, e)
-	}
-	return kept
-}
-
-func TestWriteParity_DropEntity(t *testing.T) {
-	leg := dropEntitySeq(t, Legacy)
-	msd := dropEntitySeq(t, ModelSDK)
-	if leg != msd {
-		t.Errorf("DROP ENTITY (kept entity) divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
diff --git a/mdl/enginecompare/write_assoc_drop_test.go b/mdl/enginecompare/write_assoc_drop_test.go
deleted file mode 100644
index 721f8698c4..0000000000
--- a/mdl/enginecompare/write_assoc_drop_test.go
+++ /dev/null
@@ -1,30 +0,0 @@
-package enginecompare
-
-import "testing"
-
-// TestWriteParity_DropAssociation verifies DROP ASSOCIATION removes the association
-// in both engines (the kept entities/associations must still match).
-func TestWriteParity_DropAssociation(t *testing.T) {
-	setup := []string{
-		"CREATE PERSISTENT ENTITY MyFirstModule.DA_A ( Code: string(20) )",
-		"CREATE PERSISTENT ENTITY MyFirstModule.DA_B ( Label: string(20) )",
-		"CREATE ASSOCIATION MyFirstModule.DA_A_B FROM MyFirstModule.DA_A TO MyFirstModule.DA_B TYPE reference OWNER default",
-		"DROP ASSOCIATION MyFirstModule.DA_A_B",
-	}
-	run := func(eng Engine) string {
-		p := copyProject(t)
-		for _, s := range setup {
-			if _, e := Run(eng, p, s); e != nil {
-				t.Fatalf("%s %q: %v", eng, s, e)
-			}
-		}
-		s, e := EntityCanonBSON(p, "MyFirstModule", "DA_A")
-		if e != nil {
-			t.Fatalf("%s canon: %v", eng, e)
-		}
-		return s
-	}
-	if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-		t.Errorf("drop-association divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
diff --git a/mdl/enginecompare/write_assoc_test.go b/mdl/enginecompare/write_assoc_test.go
deleted file mode 100644
index 015b58e64f..0000000000
--- a/mdl/enginecompare/write_assoc_test.go
+++ /dev/null
@@ -1,36 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-package enginecompare
-
-import "testing"
-
-// TestWriteParity_CreateAssociation creates two entities and an association
-// between them via each engine and compares the canonicalized association BSON
-// (entity-id pointers are masked, so structure + enum strings + delete behavior
-// are what must match).
-func TestWriteParity_CreateAssociation(t *testing.T) {
-	const script = "CREATE PERSISTENT ENTITY MyFirstModule.AsA;" +
-		"CREATE PERSISTENT ENTITY MyFirstModule.AsB;" +
-		"CREATE ASSOCIATION MyFirstModule.AsA_AsB FROM MyFirstModule.AsA TO MyFirstModule.AsB;"
-
-	legProj := copyProject(t)
-	if _, err := Run(Legacy, legProj, script); err != nil {
-		t.Fatalf("legacy write: %v", err)
-	}
-	msdkProj := copyProject(t)
-	if _, err := Run(ModelSDK, msdkProj, script); err != nil {
-		t.Fatalf("modelsdk write: %v", err)
-	}
-
-	leg, err := AssociationCanonBSON(legProj, "MyFirstModule", "AsA_AsB")
-	if err != nil {
-		t.Fatalf("legacy assoc bson: %v", err)
-	}
-	msd, err := AssociationCanonBSON(msdkProj, "MyFirstModule", "AsA_AsB")
-	if err != nil {
-		t.Fatalf("modelsdk assoc bson: %v", err)
-	}
-	if leg != msd {
-		t.Errorf("CreateAssociation BSON divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
diff --git a/mdl/enginecompare/write_attr_test.go b/mdl/enginecompare/write_attr_test.go
deleted file mode 100644
index 061a963c2a..0000000000
--- a/mdl/enginecompare/write_attr_test.go
+++ /dev/null
@@ -1,35 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-package enginecompare
-
-import "testing"
-
-// TestWriteParity_CreateEntityWithAttributes extends the write gate to an entity
-// carrying typed attributes (string+length, integer, boolean, decimal, and a
-// default), verifying the gen attribute/type/StoredValue conversion matches
-// legacy (byte-faithful to Studio Pro) canonically.
-func TestWriteParity_CreateEntityWithAttributes(t *testing.T) {
-	const stmt = "CREATE PERSISTENT ENTITY MyFirstModule.AttrTest " +
-		"( FullName: string(100), Count: integer, Active: boolean, Score: decimal, SortOrder: integer default 5 )"
-
-	legProj := copyProject(t)
-	if _, err := Run(Legacy, legProj, stmt); err != nil {
-		t.Fatalf("legacy write: %v", err)
-	}
-	msdkProj := copyProject(t)
-	if _, err := Run(ModelSDK, msdkProj, stmt); err != nil {
-		t.Fatalf("modelsdk write: %v", err)
-	}
-
-	leg, err := EntityCanonBSON(legProj, "MyFirstModule", "AttrTest")
-	if err != nil {
-		t.Fatalf("legacy entity bson: %v", err)
-	}
-	msd, err := EntityCanonBSON(msdkProj, "MyFirstModule", "AttrTest")
-	if err != nil {
-		t.Fatalf("modelsdk entity bson: %v", err)
-	}
-	if leg != msd {
-		t.Errorf("CreateEntity-with-attributes BSON divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
diff --git a/mdl/enginecompare/write_const_test.go b/mdl/enginecompare/write_const_test.go
deleted file mode 100644
index 39a5a45228..0000000000
--- a/mdl/enginecompare/write_const_test.go
+++ /dev/null
@@ -1,60 +0,0 @@
-package enginecompare
-
-import "testing"
-
-// TestWriteParity_Constant exercises constant writes (top-level documents) through
-// the codec engine vs legacy: CREATE across types and CREATE OR MODIFY (which
-// routes through UpdateConstant). Both engines must produce identical canonical BSON.
-func TestWriteParity_Constant(t *testing.T) {
-	cases := []struct{ name, create, modify, cname string }{
-		{"String", "CREATE CONSTANT MyFirstModule.Endpoint TYPE string DEFAULT 'https://api.example.com'", "", "Endpoint"},
-		{"Integer", "CREATE CONSTANT MyFirstModule.MaxRetries TYPE integer DEFAULT 5", "", "MaxRetries"},
-		{"Decimal", "CREATE CONSTANT MyFirstModule.TaxRate TYPE decimal DEFAULT 0.21", "", "TaxRate"},
-		{"Boolean", "CREATE CONSTANT MyFirstModule.Flag TYPE boolean DEFAULT true", "", "Flag"},
-		{"Modify",
-			"CREATE CONSTANT MyFirstModule.Endpoint2 TYPE string DEFAULT 'https://old'",
-			"CREATE OR MODIFY CONSTANT MyFirstModule.Endpoint2 TYPE string DEFAULT 'https://new'",
-			"Endpoint2"},
-	}
-	for _, c := range cases {
-		t.Run(c.name, func(t *testing.T) {
-			run := func(eng Engine) string {
-				p := copyProject(t)
-				if _, e := Run(eng, p, c.create); e != nil {
-					t.Fatalf("%s create: %v", eng, e)
-				}
-				if c.modify != "" {
-					if _, e := Run(eng, p, c.modify); e != nil {
-						t.Fatalf("%s modify: %v", eng, e)
-					}
-				}
-				s, e := ConstCanonBSON(p, "MyFirstModule", c.cname)
-				if e != nil {
-					t.Fatalf("%s canon: %v", eng, e)
-				}
-				return s
-			}
-			if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-				t.Errorf("constant divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-			}
-		})
-	}
-}
-
-// TestWriteParity_DropConstant verifies DROP CONSTANT removes the unit in both engines.
-func TestWriteParity_DropConstant(t *testing.T) {
-	const create = "CREATE CONSTANT MyFirstModule.GoneC TYPE string DEFAULT 'x'"
-	const drop = "DROP CONSTANT MyFirstModule.GoneC"
-	for _, eng := range []Engine{Legacy, ModelSDK} {
-		p := copyProject(t)
-		if _, e := Run(eng, p, create); e != nil {
-			t.Fatalf("%s create: %v", eng, e)
-		}
-		if _, e := Run(eng, p, drop); e != nil {
-			t.Fatalf("%s drop: %v", eng, e)
-		}
-		if _, e := ConstCanonBSON(p, "MyFirstModule", "GoneC"); e == nil {
-			t.Errorf("%s: constant still present after DROP", eng)
-		}
-	}
-}
diff --git a/mdl/enginecompare/write_enum_test.go b/mdl/enginecompare/write_enum_test.go
deleted file mode 100644
index 66599c179e..0000000000
--- a/mdl/enginecompare/write_enum_test.go
+++ /dev/null
@@ -1,66 +0,0 @@
-package enginecompare
-
-import "testing"
-
-// TestWriteParity_Enumeration exercises enumeration writes (top-level documents,
-// inserted as units) through the codec engine vs legacy: CREATE with plain and
-// captioned values, and ALTER (read-modify-write) adding a value. Both engines
-// must produce identical canonical BSON.
-func TestWriteParity_Enumeration(t *testing.T) {
-	t.Run("CreatePlain", func(t *testing.T) {
-		const s = "CREATE ENUMERATION MyFirstModule.Status ( Open, Pending, Closed )"
-		assertEnumParity(t, s, "", "Status")
-	})
-	t.Run("CreateCaptioned", func(t *testing.T) {
-		const s = "CREATE ENUMERATION MyFirstModule.Prio ( Low 'Low prio', High 'High prio' )"
-		assertEnumParity(t, s, "", "Prio")
-	})
-	t.Run("AlterAddValue", func(t *testing.T) {
-		const create = "CREATE ENUMERATION MyFirstModule.Color ( Red, Green )"
-		assertEnumParity(t, create, "ALTER ENUMERATION MyFirstModule.Color ADD VALUE Blue CAPTION 'Bluey'", "Color")
-	})
-}
-
-// assertEnumParity runs create (and optional alter, as a separate session) on a
-// copy per engine and compares the enumeration's canonical BSON.
-func assertEnumParity(t *testing.T, create, alter, enumName string) {
-	t.Helper()
-	run := func(eng Engine) string {
-		p := copyProject(t)
-		if _, e := Run(eng, p, create); e != nil {
-			t.Fatalf("%s create: %v", eng, e)
-		}
-		if alter != "" {
-			if _, e := Run(eng, p, alter); e != nil {
-				t.Fatalf("%s alter: %v", eng, e)
-			}
-		}
-		s, e := EnumCanonBSON(p, "MyFirstModule", enumName)
-		if e != nil {
-			t.Fatalf("%s canon: %v", eng, e)
-		}
-		return s
-	}
-	if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-		t.Errorf("enumeration divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
-
-// TestWriteParity_DropEnumeration verifies DROP ENUMERATION removes the unit in
-// both engines.
-func TestWriteParity_DropEnumeration(t *testing.T) {
-	const create = "CREATE ENUMERATION MyFirstModule.Gone ( A, B )"
-	const drop = "DROP ENUMERATION MyFirstModule.Gone"
-	for _, eng := range []Engine{Legacy, ModelSDK} {
-		p := copyProject(t)
-		if _, e := Run(eng, p, create); e != nil {
-			t.Fatalf("%s create: %v", eng, e)
-		}
-		if _, e := Run(eng, p, drop); e != nil {
-			t.Fatalf("%s drop: %v", eng, e)
-		}
-		if _, e := EnumCanonBSON(p, "MyFirstModule", "Gone"); e == nil {
-			t.Errorf("%s: enumeration still present after DROP", eng)
-		}
-	}
-}
diff --git a/mdl/enginecompare/write_gen_test.go b/mdl/enginecompare/write_gen_test.go
deleted file mode 100644
index 8c5ae8344b..0000000000
--- a/mdl/enginecompare/write_gen_test.go
+++ /dev/null
@@ -1,26 +0,0 @@
-package enginecompare
-
-import "testing"
-
-func TestWriteParity_Generalization(t *testing.T) {
-	const s = "CREATE PERSISTENT ENTITY MyFirstModule.GenParent;CREATE PERSISTENT ENTITY MyFirstModule.GenChild EXTENDS MyFirstModule.GenParent;"
-	lp := copyProject(t)
-	if _, err := Run(Legacy, lp, s); err != nil {
-		t.Fatalf("legacy: %v", err)
-	}
-	mp := copyProject(t)
-	if _, err := Run(ModelSDK, mp, s); err != nil {
-		t.Fatalf("modelsdk: %v", err)
-	}
-	leg, err := EntityCanonBSON(lp, "MyFirstModule", "GenChild")
-	if err != nil {
-		t.Fatalf("leg: %v", err)
-	}
-	msd, err := EntityCanonBSON(mp, "MyFirstModule", "GenChild")
-	if err != nil {
-		t.Fatalf("msd: %v", err)
-	}
-	if leg != msd {
-		t.Errorf("Generalization divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
diff --git a/mdl/enginecompare/write_index_test.go b/mdl/enginecompare/write_index_test.go
deleted file mode 100644
index 5723f343a0..0000000000
--- a/mdl/enginecompare/write_index_test.go
+++ /dev/null
@@ -1,58 +0,0 @@
-package enginecompare
-
-import (
-	"strings"
-	"testing"
-)
-
-// TestWriteParity_Index validates index serialization against the AUTHORITATIVE
-// Studio-Pro 11.x structure captured via the MCP backend (mx-test-projects/
-// test7-app: MxcliDiskProbe.IdxProbe). Both engines must match it: the modelsdk
-// engine builds it natively, and legacy's stale-writer bug (SortOrder string,
-// marker 3, missing GUID/IncludeInOffline/AssociationPointer/Type) was fixed in
-// lockstep. See docs/plans/2026-06-05-adopt-modelsdk-engine.md "Index spec".
-func TestWriteParity_Index(t *testing.T) {
-	const s = "CREATE PERSISTENT ENTITY MyFirstModule.IdxTest " +
-		"( Code: string(20), Rank: integer ) index (Code, Rank desc)"
-
-	mp := copyProject(t)
-	if _, e := Run(ModelSDK, mp, s); e != nil {
-		t.Fatalf("modelsdk: %v", e)
-	}
-	msd, e := EntityCanonBSON(mp, "MyFirstModule", "IdxTest")
-	if e != nil {
-		t.Fatalf("msd: %v", e)
-	}
-
-	// The authoritative EntityIndex block: marker 2 on the IndexedAttribute list,
-	// Ascending(bool)+Type("Normal")+AttributePointer+AssociationPointer per
-	// segment, GUID + IncludeInOffline=false on the index. Keys are canonical
-	// (alphabetical) and IDs/binaries masked.
-	const wantIndex = `Indexes=[{"$numberInt":"3"},` +
-		`{$ID=<masked>,$Type="DomainModels$EntityIndex",` +
-		`Attributes=[{"$numberInt":"2"},` +
-		`{$ID=<masked>,$Type="DomainModels$IndexedAttribute",Ascending=true,AssociationPointer=<binary>,AttributePointer=<binary>,Type="Normal"},` +
-		`{$ID=<masked>,$Type="DomainModels$IndexedAttribute",Ascending=false,AssociationPointer=<binary>,AttributePointer=<binary>,Type="Normal"}],` +
-		`GUID=<masked>,IncludeInOffline=false}]`
-
-	if !strings.Contains(msd, wantIndex) {
-		t.Errorf("index serialization does not match Studio-Pro 11.x truth.\nwant substring: %s\ngot:            %s", wantIndex, msd)
-	}
-
-	// Legacy's stale index writer was fixed in lockstep, so it must now match the
-	// same Studio-Pro truth (and no longer emit the old SortOrder string).
-	lp := copyProject(t)
-	if _, e := Run(Legacy, lp, s); e != nil {
-		t.Fatalf("legacy: %v", e)
-	}
-	leg, e := EntityCanonBSON(lp, "MyFirstModule", "IdxTest")
-	if e != nil {
-		t.Fatalf("leg: %v", e)
-	}
-	if !strings.Contains(leg, wantIndex) {
-		t.Errorf("legacy index serialization does not match Studio-Pro 11.x truth.\nwant substring: %s\ngot:            %s", wantIndex, leg)
-	}
-	if strings.Contains(leg, "SortOrder") {
-		t.Errorf("legacy still emits stale SortOrder string:\n%s", leg)
-	}
-}
diff --git a/mdl/enginecompare/write_microflow_test.go b/mdl/enginecompare/write_microflow_test.go
deleted file mode 100644
index ea0e1531b7..0000000000
--- a/mdl/enginecompare/write_microflow_test.go
+++ /dev/null
@@ -1,213 +0,0 @@
-package enginecompare
-
-import "testing"
-
-// TestWriteParity_Microflow_ObjectOps validates the object-operations group
-// (create/change/commit/delete/rollback) against legacy. The entity is set up via
-// legacy on both copies; only the microflow CREATE differs by engine.
-func TestWriteParity_Microflow_ObjectOps(t *testing.T) {
-	const setup = "CREATE PERSISTENT ENTITY MyFirstModule.Thing ( Name: string(100), Count: integer )"
-	cases := []struct{ name, stmt, mf string }{
-		{"CreateChangeCommit",
-			"CREATE MICROFLOW MyFirstModule.MfCCC () BEGIN\n" +
-				"$New = create MyFirstModule.Thing (Name = 'x', Count = 5);\n" +
-				"change $New (Count = 6);\n" +
-				"commit $New;\n" +
-				"END", "MfCCC"},
-		{"CommitWithEvents",
-			"CREATE MICROFLOW MyFirstModule.MfCE (Item: MyFirstModule.Thing) BEGIN commit $Item with events; END", "MfCE"},
-		{"Delete",
-			"CREATE MICROFLOW MyFirstModule.MfDel (Item: MyFirstModule.Thing) BEGIN delete $Item; END", "MfDel"},
-		{"Rollback",
-			"CREATE MICROFLOW MyFirstModule.MfRb (Item: MyFirstModule.Thing) BEGIN rollback $Item; END", "MfRb"},
-	}
-	for _, c := range cases {
-		t.Run(c.name, func(t *testing.T) {
-			run := func(eng Engine) string {
-				p := copyProject(t)
-				if _, e := Run(Legacy, p, setup); e != nil {
-					t.Fatalf("setup: %v", e)
-				}
-				if _, e := Run(eng, p, c.stmt); e != nil {
-					t.Fatalf("%s create: %v", eng, e)
-				}
-				s, e := MicroflowCanonBSON(p, "MyFirstModule", c.mf)
-				if e != nil {
-					t.Fatalf("%s canon: %v", eng, e)
-				}
-				return s
-			}
-			if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-				t.Errorf("%s divergence:\nlegacy:   %s\nmodelsdk: %s", c.name, leg, msd)
-			}
-		})
-	}
-}
-
-// TestWriteParity_Microflow_Calls validates the call group: microflow calls
-// (with/without args + result) and nanoflow calls, each with a nested Call
-// element + parameter mappings (marker-2 list).
-func TestWriteParity_Microflow_Calls(t *testing.T) {
-	setup := []string{
-		"CREATE MICROFLOW MyFirstModule.CTarget () RETURNS BOOLEAN BEGIN RETURN true; END",
-		"CREATE MICROFLOW MyFirstModule.CTargetP (Val: string) RETURNS STRING BEGIN RETURN $Val; END",
-		"CREATE NANOFLOW MyFirstModule.NTarget () RETURNS BOOLEAN BEGIN RETURN true; END",
-	}
-	cases := []struct{ name, stmt, mf string }{
-		{"MicroflowNoArgs", "CREATE MICROFLOW MyFirstModule.MfCall () BEGIN call microflow MyFirstModule.CTarget(); END", "MfCall"},
-		{"MicroflowArgResult", "CREATE MICROFLOW MyFirstModule.MfCallR () BEGIN $R = call microflow MyFirstModule.CTargetP(Val = 'x'); END", "MfCallR"},
-		{"NanoflowCall", "CREATE MICROFLOW MyFirstModule.MfNano () BEGIN call nanoflow MyFirstModule.NTarget(); END", "MfNano"},
-	}
-	for _, c := range cases {
-		t.Run(c.name, func(t *testing.T) {
-			run := func(eng Engine) string {
-				p := copyProject(t)
-				for _, s := range setup {
-					if _, e := Run(Legacy, p, s); e != nil {
-						t.Fatalf("setup %q: %v", s, e)
-					}
-				}
-				if _, e := Run(eng, p, c.stmt); e != nil {
-					t.Fatalf("%s create: %v", eng, e)
-				}
-				s, e := MicroflowCanonBSON(p, "MyFirstModule", c.mf)
-				if e != nil {
-					t.Fatalf("%s canon: %v", eng, e)
-				}
-				return s
-			}
-			if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-				t.Errorf("%s divergence:\nlegacy:   %s\nmodelsdk: %s", c.name, leg, msd)
-			}
-		})
-	}
-}
-
-// TestWriteParity_Microflow_Loops validates the loop group: iterate-over-list
-// (IterableList) and while (WhileLoopCondition), each with a nested body
-// (ObjectCollection objects-only) and supported branch activities.
-func TestWriteParity_Microflow_Loops(t *testing.T) {
-	const setup = "CREATE PERSISTENT ENTITY MyFirstModule.LThing ( Code: string(20) )"
-	cases := []struct{ name, stmt, mf string }{
-		{"IterateList",
-			"CREATE MICROFLOW MyFirstModule.MfLoop (Items: list of MyFirstModule.LThing) BEGIN " +
-				"loop $It in $Items begin commit $It; end loop; END", "MfLoop"},
-		{"While",
-			"CREATE MICROFLOW MyFirstModule.MfWhile (Item: MyFirstModule.LThing) BEGIN " +
-				"while $Item/Code != '' begin commit $Item; end while; END", "MfWhile"},
-	}
-	for _, c := range cases {
-		t.Run(c.name, func(t *testing.T) {
-			run := func(eng Engine) string {
-				p := copyProject(t)
-				if _, e := Run(Legacy, p, setup); e != nil {
-					t.Fatalf("setup: %v", e)
-				}
-				if _, e := Run(eng, p, c.stmt); e != nil {
-					t.Fatalf("%s create: %v", eng, e)
-				}
-				s, e := MicroflowCanonBSON(p, "MyFirstModule", c.mf)
-				if e != nil {
-					t.Fatalf("%s canon: %v", eng, e)
-				}
-				return s
-			}
-			if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-				t.Errorf("%s divergence:\nlegacy:   %s\nmodelsdk: %s", c.name, leg, msd)
-			}
-		})
-	}
-}
-
-// TestWriteParity_Microflow_Splits validates the exclusive-split group: an if/else
-// (ExclusiveSplit + ExpressionSplitCondition + ExclusiveMerge + branch flows whose
-// cases serialize as EnumerationCase true/false), with supported branch activities.
-func TestWriteParity_Microflow_Splits(t *testing.T) {
-	const setup = "CREATE PERSISTENT ENTITY MyFirstModule.SThing ( Count: integer )"
-	const mf = "CREATE MICROFLOW MyFirstModule.MfSplit (Item: MyFirstModule.SThing) BEGIN " +
-		"if $Item/Count > 10 then commit $Item; else rollback $Item; end if; END"
-	run := func(eng Engine) string {
-		p := copyProject(t)
-		if _, e := Run(Legacy, p, setup); e != nil {
-			t.Fatalf("setup: %v", e)
-		}
-		if _, e := Run(eng, p, mf); e != nil {
-			t.Fatalf("%s create: %v", eng, e)
-		}
-		s, e := MicroflowCanonBSON(p, "MyFirstModule", "MfSplit")
-		if e != nil {
-			t.Fatalf("%s canon: %v", eng, e)
-		}
-		return s
-	}
-	if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-		t.Errorf("split divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
-
-// TestWriteParity_Microflow_Retrieve validates the retrieve group: database
-// source (all + XPath) and association source. Real BSON (test7) confirmed a
-// DatabaseRetrieveSource always carries a default Range + an empty NewSortings.
-func TestWriteParity_Microflow_Retrieve(t *testing.T) {
-	setup := []string{
-		"CREATE PERSISTENT ENTITY MyFirstModule.RThing ( Code: string(20), Count: integer )",
-		"CREATE PERSISTENT ENTITY MyFirstModule.ROther ( Label: string(20) )",
-		"CREATE ASSOCIATION MyFirstModule.RThing_ROther FROM MyFirstModule.RThing TO MyFirstModule.ROther",
-	}
-	cases := []struct{ name, stmt, mf string }{
-		{"DatabaseAll", "CREATE MICROFLOW MyFirstModule.MfRetAll () BEGIN retrieve $L from MyFirstModule.RThing; END", "MfRetAll"},
-		{"DatabaseWhere", "CREATE MICROFLOW MyFirstModule.MfRetWhere () BEGIN retrieve $L from MyFirstModule.RThing where Count = 5; END", "MfRetWhere"},
-		{"Association", "CREATE MICROFLOW MyFirstModule.MfRetAssoc (Item: MyFirstModule.RThing) BEGIN retrieve $L from $Item/MyFirstModule.RThing_ROther; END", "MfRetAssoc"},
-	}
-	for _, c := range cases {
-		t.Run(c.name, func(t *testing.T) {
-			run := func(eng Engine) string {
-				p := copyProject(t)
-				for _, s := range setup {
-					if _, e := Run(Legacy, p, s); e != nil {
-						t.Fatalf("setup %q: %v", s, e)
-					}
-				}
-				if _, e := Run(eng, p, c.stmt); e != nil {
-					t.Fatalf("%s create: %v", eng, e)
-				}
-				s, e := MicroflowCanonBSON(p, "MyFirstModule", c.mf)
-				if e != nil {
-					t.Fatalf("%s canon: %v", eng, e)
-				}
-				return s
-			}
-			if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-				t.Errorf("%s divergence:\nlegacy:   %s\nmodelsdk: %s", c.name, leg, msd)
-			}
-		})
-	}
-}
-
-// TestWriteParity_Microflow validates the codec-native microflow CREATE path
-// against legacy, group by group. Skeleton = start → end, boolean return.
-func TestWriteParity_Microflow(t *testing.T) {
-	cases := []struct{ name, stmt, mf string }{
-		{"Skeleton", "CREATE MICROFLOW MyFirstModule.MfEmpty () RETURNS BOOLEAN BEGIN RETURN true; END", "MfEmpty"},
-		{"Parameters", "CREATE MICROFLOW MyFirstModule.MfParams (Count: integer, Label: string) RETURNS BOOLEAN BEGIN RETURN true; END", "MfParams"},
-		{"VoidReturn", "CREATE MICROFLOW MyFirstModule.MfVoid () BEGIN END", "MfVoid"},
-	}
-	for _, c := range cases {
-		t.Run(c.name, func(t *testing.T) {
-			run := func(eng Engine) string {
-				p := copyProject(t)
-				if _, e := Run(eng, p, c.stmt); e != nil {
-					t.Fatalf("%s create: %v", eng, e)
-				}
-				s, e := MicroflowCanonBSON(p, "MyFirstModule", c.mf)
-				if e != nil {
-					t.Fatalf("%s canon: %v", eng, e)
-				}
-				return s
-			}
-			if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-				t.Errorf("%s divergence:\nlegacy:   %s\nmodelsdk: %s", c.name, leg, msd)
-			}
-		})
-	}
-}
diff --git a/mdl/enginecompare/write_module_test.go b/mdl/enginecompare/write_module_test.go
deleted file mode 100644
index fe33fa9acd..0000000000
--- a/mdl/enginecompare/write_module_test.go
+++ /dev/null
@@ -1,28 +0,0 @@
-package enginecompare
-
-import "testing"
-
-// TestWriteParity_CreateModule verifies the modelsdk engine can create a module
-// (+ its mandatory contained units) such that subsequent statements land in it.
-// The ModuleImpl unit is NOT byte-compared against legacy: legacy emits
-// NewSortIndex as int64, but real Studio-Pro BSON (and the codec) use a double —
-// legacy is wrong there. Instead, an entity created in the new module must match
-// across engines, proving the module is functional.
-func TestWriteParity_CreateModule(t *testing.T) {
-	const script = "CREATE MODULE NewMod; " +
-		"CREATE PERSISTENT ENTITY NewMod.Thing ( Code: string(20), Rank: integer )"
-	run := func(eng Engine) string {
-		p := copyProject(t)
-		if _, e := Run(eng, p, script); e != nil {
-			t.Fatalf("%s: %v", eng, e)
-		}
-		s, e := EntityCanonBSON(p, "NewMod", "Thing")
-		if e != nil {
-			t.Fatalf("%s canon: %v", eng, e)
-		}
-		return s
-	}
-	if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-		t.Errorf("entity-in-new-module divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
diff --git a/mdl/enginecompare/write_move_test.go b/mdl/enginecompare/write_move_test.go
deleted file mode 100644
index 9145eb9514..0000000000
--- a/mdl/enginecompare/write_move_test.go
+++ /dev/null
@@ -1,64 +0,0 @@
-package enginecompare
-
-import "testing"
-
-// TestWriteParity_MoveEntity moves an entity (whose association to a same-module
-// entity becomes a cross-module association) and checks the moved entity matches
-// legacy in the target module. Cross-association correctness is covered by mx check.
-func TestWriteParity_MoveEntity(t *testing.T) {
-	setup := []string{
-		"CREATE MODULE SrcM",
-		"CREATE MODULE DstM",
-		"CREATE PERSISTENT ENTITY SrcM.Parent ( Code: string(20) )",
-		"CREATE PERSISTENT ENTITY SrcM.Child ( Label: string(20) )",
-		"CREATE ASSOCIATION SrcM.Parent_Child FROM SrcM.Parent TO SrcM.Child TYPE reference OWNER default",
-		"MOVE ENTITY SrcM.Child TO DstM",
-	}
-	run := func(eng Engine) string {
-		p := copyProject(t)
-		for _, s := range setup {
-			if _, e := Run(eng, p, s); e != nil {
-				t.Fatalf("%s %q: %v", eng, s, e)
-			}
-		}
-		s, e := EntityCanonBSON(p, "DstM", "Child")
-		if e != nil {
-			t.Fatalf("%s canon: %v", eng, e)
-		}
-		return s
-	}
-	if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-		t.Errorf("moved-entity divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
-
-// TestWriteParity_MoveViewEntity moves a view entity to another module. This
-// exercises the reference-cleanup helpers that keep the moved view consistent:
-// MoveViewEntitySourceDocument (reparent the OQL source doc, else CE6786) and the
-// OqlViewValue round-trip in attributeFromGen (else the rebuilt view goes out of
-// sync, CE6770). The moved entity's BSON must match legacy in the target module.
-func TestWriteParity_MoveViewEntity(t *testing.T) {
-	setup := []string{
-		"CREATE MODULE SrcV",
-		"CREATE MODULE DstV",
-		"CREATE PERSISTENT ENTITY SrcV.Base ( Name: string(50), Amount: integer )",
-		"CREATE OR MODIFY VIEW ENTITY SrcV.BaseView ( Name: string(50) ) AS select b.Name as Name from SrcV.Base as b",
-		"MOVE ENTITY SrcV.BaseView TO DstV",
-	}
-	run := func(eng Engine) string {
-		p := copyProject(t)
-		for _, s := range setup {
-			if _, e := Run(eng, p, s); e != nil {
-				t.Fatalf("%s %q: %v", eng, s, e)
-			}
-		}
-		s, e := EntityCanonBSON(p, "DstV", "BaseView")
-		if e != nil {
-			t.Fatalf("%s canon: %v", eng, e)
-		}
-		return s
-	}
-	if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-		t.Errorf("moved-view-entity divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
diff --git a/mdl/enginecompare/write_test.go b/mdl/enginecompare/write_test.go
deleted file mode 100644
index 65158984a2..0000000000
--- a/mdl/enginecompare/write_test.go
+++ /dev/null
@@ -1,50 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-
-package enginecompare
-
-import (
-	"os"
-	"path/filepath"
-	"testing"
-)
-
-func copyProject(t *testing.T) string {
-	t.Helper()
-	dst := t.TempDir()
-	if err := os.CopyFS(dst, os.DirFS("../../testdata/expr-checker")); err != nil {
-		t.Fatalf("copy project: %v", err)
-	}
-	return filepath.Join(dst, "minimal.mpr")
-}
-
-// TestWriteParity_CreateEntity writes the same entity through both engines and
-// compares the canonicalized BSON of the created entity — the Phase-2 write gate.
-func TestWriteParity_CreateEntity(t *testing.T) {
-	const stmt = "CREATE PERSISTENT ENTITY MyFirstModule.SliceTest"
-
-	legProj := copyProject(t)
-	if _, err := Run(Legacy, legProj, stmt); err != nil {
-		t.Fatalf("legacy write: %v", err)
-	}
-	msdkProj := copyProject(t)
-	if _, err := Run(ModelSDK, msdkProj, stmt); err != nil {
-		t.Fatalf("modelsdk write: %v", err)
-	}
-
-	leg, err := EntityCanonBSON(legProj, "MyFirstModule", "SliceTest")
-	if err != nil {
-		t.Fatalf("legacy entity bson: %v", err)
-	}
-	msd, err := EntityCanonBSON(msdkProj, "MyFirstModule", "SliceTest")
-	if err != nil {
-		t.Fatalf("modelsdk entity bson: %v", err)
-	}
-	// Strict: with applyDefaults wired (codec.RegisterTypeDefaults for
-	// DomainModels$EntityImpl emits GUID + the empty member arrays Studio Pro
-	// produces), the modelsdk-written entity is canonically identical to legacy's
-	// — which is itself byte-faithful to Studio Pro (verified vs real BSON in
-	// mx-test-projects/test7-app).
-	if leg != msd {
-		t.Errorf("CreateEntity BSON divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
diff --git a/mdl/enginecompare/write_valid_test.go b/mdl/enginecompare/write_valid_test.go
deleted file mode 100644
index 9a77b51ff2..0000000000
--- a/mdl/enginecompare/write_valid_test.go
+++ /dev/null
@@ -1,27 +0,0 @@
-package enginecompare
-
-import "testing"
-
-func TestWriteParity_ValidationRules(t *testing.T) {
-	const s = "CREATE PERSISTENT ENTITY MyFirstModule.ValTest " +
-		"( Name: string(100) not null error 'Name is required', Code: string(20) unique error 'Code must be unique' )"
-	lp := copyProject(t)
-	if _, e := Run(Legacy, lp, s); e != nil {
-		t.Fatalf("legacy: %v", e)
-	}
-	mp := copyProject(t)
-	if _, e := Run(ModelSDK, mp, s); e != nil {
-		t.Fatalf("modelsdk: %v", e)
-	}
-	leg, e := EntityCanonBSON(lp, "MyFirstModule", "ValTest")
-	if e != nil {
-		t.Fatalf("leg: %v", e)
-	}
-	msd, e := EntityCanonBSON(mp, "MyFirstModule", "ValTest")
-	if e != nil {
-		t.Fatalf("msd: %v", e)
-	}
-	if leg != msd {
-		t.Errorf("ValidationRules divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
diff --git a/mdl/enginecompare/write_view_test.go b/mdl/enginecompare/write_view_test.go
deleted file mode 100644
index b842effe5d..0000000000
--- a/mdl/enginecompare/write_view_test.go
+++ /dev/null
@@ -1,26 +0,0 @@
-package enginecompare
-
-import "testing"
-
-// TestWriteParity_ViewEntity verifies a view entity (OQL source document + the
-// entity's OqlViewEntitySource + OqlViewValue attributes) matches legacy.
-func TestWriteParity_ViewEntity(t *testing.T) {
-	const script = "CREATE MODULE VM; " +
-		"CREATE PERSISTENT ENTITY VM.Product ( Name: string(100), Price: decimal, IsActive: boolean default true ); " +
-		"CREATE VIEW ENTITY VM.ActiveProducts ( Name: string(100), Price: decimal ) AS " +
-		"select p.Name as Name, p.Price as Price from VM.Product as p where p.IsActive = true"
-	run := func(eng Engine) string {
-		p := copyProject(t)
-		if _, e := Run(eng, p, script); e != nil {
-			t.Fatalf("%s: %v", eng, e)
-		}
-		s, e := EntityCanonBSON(p, "VM", "ActiveProducts")
-		if e != nil {
-			t.Fatalf("%s canon: %v", eng, e)
-		}
-		return s
-	}
-	if leg, msd := run(Legacy), run(ModelSDK); leg != msd {
-		t.Errorf("view-entity divergence:\nlegacy:   %s\nmodelsdk: %s", leg, msd)
-	}
-}
diff --git a/mdl/executor/mapping_customhandler_test.go b/mdl/executor/mapping_customhandler_test.go
index aa8eb9b2f0..78902a1b61 100644
--- a/mdl/executor/mapping_customhandler_test.go
+++ b/mdl/executor/mapping_customhandler_test.go
@@ -52,8 +52,12 @@ end;
 
 func newCustomHandlerEnv(t *testing.T) *testEnv {
 	t.Helper()
-	// modelsdk: the legacy serializers write CustomHandlerCall as nil, and the
-	// legacy backend refuses rather than dropping it (see TestCustomHandlerLegacyRefuses).
+	// Named explicitly rather than via setupTestEnv, because this construct is
+	// the reason the engine mattered: the legacy serializers wrote
+	// CustomHandlerCall as nil, so that backend refused the statement instead of
+	// dropping the microflow silently. That engine is gone
+	// (docs/plans/2026-09-14-retire-legacy-engine.md) and the refusal test with
+	// it; the naming stays because it says which writer these assertions pin.
 	env := setupTestEnvWithBackend(t, func() backend.FullBackend { return modelsdkbackend.New() })
 	if err := env.executeMDL(customHandlerSetup); err != nil {
 		t.Fatalf("setup failed: %v", err)
@@ -182,26 +186,3 @@ func TestCustomHandlerRefusals(t *testing.T) {
 		t.Errorf("error %q does not say the microflow was not found", err)
 	}
 }
-
-// TestCustomHandlerLegacyRefuses: the legacy serializers hardcode
-// CustomHandlerCall to nil, so writing there would drop the microflow silently —
-// the exact failure this issue is about. The backend refuses instead.
-func TestCustomHandlerLegacyRefuses(t *testing.T) {
-	env := setupTestEnv(t) // legacy backend
-	defer env.teardown()
-
-	if err := env.executeMDL(customHandlerSetup); err != nil {
-		t.Fatalf("setup failed: %v", err)
-	}
-	err := env.executeMDL(`create import mapping ` + testModule + `.IM_CHLegacy
-  with json structure ` + testModule + `.JSON_CH
-{
-  find ` + testModule + `.CHRoot by ` + testModule + `.CH_Resolve ( Obj: parent ) { Name = name }
-};`)
-	if err == nil {
-		t.Fatal("legacy engine accepted a custom handler it cannot serialize")
-	}
-	if !strings.Contains(err.Error(), "modelsdk") {
-		t.Errorf("error %q does not point at the modelsdk engine", err)
-	}
-}
diff --git a/mdl/executor/odata_engine_parity_test.go b/mdl/executor/odata_role_grants_test.go
similarity index 54%
rename from mdl/executor/odata_engine_parity_test.go
rename to mdl/executor/odata_role_grants_test.go
index e9644125c9..f6026b1d12 100644
--- a/mdl/executor/odata_engine_parity_test.go
+++ b/mdl/executor/odata_role_grants_test.go
@@ -5,12 +5,10 @@
 package executor
 
 import (
-	"sort"
 	"testing"
 
 	"github.com/mendixlabs/mxcli/mdl/backend"
 	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
-	mprbackend "github.com/mendixlabs/mxcli/mdl/backend/mpr"
 	"github.com/mendixlabs/mxcli/mdl/visitor"
 	"github.com/mendixlabs/mxcli/model"
 	"go.mongodb.org/mongo-driver/bson"
@@ -104,65 +102,50 @@ func storedODataService(t *testing.T, factory func() backend.FullBackend) map[st
 	return raw
 }
 
-// The two OData writers must serialize the same key set.
+// A published OData service must keep its role grants when it is written.
 //
-// mxcli-formula1 §41: the §26 role-grant fix went into sdk/mpr/writer_odata.go,
-// and the modelsdk writer had no reference to AllowedModuleRoles at all — so a
-// `create or modify odata service` on that engine kept revoking the grants for a
-// whole release. Nothing noticed, because every existing test exercised one
-// writer or the other, never the two against each other.
+// This was a cross-ENGINE parity test: mxcli-formula1 §41, where the §26
+// role-grant fix went into sdk/mpr/writer_odata.go and the modelsdk writer had
+// no reference to AllowedModuleRoles at all, so `create or modify odata service`
+// on that engine revoked the grants for a whole release. Nothing noticed,
+// because every test exercised one writer or the other and never the two
+// against each other.
 //
-// The doctype gate cannot stand in for this. A published service with no allowed
-// roles is 0 errors under `mx check` on Mendix 11.12 (measured, not assumed), so
-// the build is blind to the symptom; the loss is only visible in the stored
-// document. That is why this asserts on BSON rather than on a check result.
+// The legacy engine is gone (docs/plans/2026-09-14-retire-legacy-engine.md), so
+// the comparison has nothing to compare and the differential half is dropped
+// rather than faked against itself. What is kept is the property the comparison
+// was a means to: the grant is in the stored document after a write. That still
+// needs its own test, because the doctype gate cannot see it — a published
+// service with no allowed roles is 0 errors under `mx check` on Mendix 11.12
+// (measured, not assumed), so the build is blind to the symptom and the loss is
+// only visible in the BSON.
 //
-// Asserted as the general property, not the one field: whatever legacy writes,
-// modelsdk writes too.
-func TestODataService_EngineWriteParity(t *testing.T) {
-	legacy := storedODataService(t, func() backend.FullBackend { return mprbackend.New() })
-	msdk := storedODataService(t, func() backend.FullBackend { return modelsdkbackend.New() })
-
-	var missing []string
-	for k := range legacy {
-		if _, ok := msdk[k]; !ok {
-			missing = append(missing, k)
-		}
+// Asserted by VALUE, not presence: an empty marker array satisfies a key-set
+// check while still having revoked the grant, which is exactly how a key-set
+// comparison would have passed over the original bug.
+func TestODataService_KeepsRoleGrants(t *testing.T) {
+	doc := storedODataService(t, func() backend.FullBackend { return modelsdkbackend.New() })
+
+	roles, ok := doc["AllowedModuleRoles"]
+	if !ok {
+		t.Fatal("AllowedModuleRoles absent — the grant was dropped by the writer")
 	}
-	sort.Strings(missing)
-	if len(missing) > 0 {
-		t.Errorf("modelsdk drops %d key(s) the mpr engine writes: %v\n"+
-			"The document is serialized wholesale, so a key the serializer omits is "+
-			"not left alone — it is deleted on the next modify.", len(missing), missing)
+	// The readers hand this back under different static types (bson.A on one
+	// path, a plain []any on the other), so accept both rather than pinning an
+	// incidental difference.
+	var arr []any
+	switch v := roles.(type) {
+	case bson.A:
+		arr = v
+	case []any:
+		arr = v
+	default:
+		t.Fatalf("AllowedModuleRoles is %T, want an array", roles)
 	}
-
-	// The reported field, by value rather than presence: an empty marker array
-	// satisfies a key-set check while still having revoked the grant.
-	for name, doc := range map[string]map[string]any{"legacy": legacy, "modelsdk": msdk} {
-		roles, ok := doc["AllowedModuleRoles"]
-		if !ok {
-			t.Errorf("%s: AllowedModuleRoles absent", name)
-			continue
-		}
-		// The two readers hand back the same array under different static
-		// types (bson.A on one path, a plain []any on the other), so accept both
-		// rather than pinning an incidental difference.
-		var arr []any
-		switch v := roles.(type) {
-		case bson.A:
-			arr = v
-		case []any:
-			arr = v
-		default:
-			t.Errorf("%s: AllowedModuleRoles is %T, want an array", name, roles)
-			continue
-		}
-		if len(arr) != 2 {
-			t.Errorf("%s: AllowedModuleRoles = %v, want marker + the granted role", name, arr)
-			continue
-		}
-		if arr[1] != "PTest.Admin" {
-			t.Errorf("%s: granted role = %v, want PTest.Admin", name, arr[1])
-		}
+	if len(arr) != 2 {
+		t.Fatalf("AllowedModuleRoles = %v, want marker + the granted role", arr)
+	}
+	if arr[1] != "PTest.Admin" {
+		t.Errorf("granted role = %v, want PTest.Admin", arr[1])
 	}
 }
diff --git a/mdl/executor/roundtrip_doctype_test.go b/mdl/executor/roundtrip_doctype_test.go
index 4ec306adea..95eb8b60c7 100644
--- a/mdl/executor/roundtrip_doctype_test.go
+++ b/mdl/executor/roundtrip_doctype_test.go
@@ -18,16 +18,19 @@ import (
 	"github.com/mendixlabs/mxcli/mdl/ast"
 	"github.com/mendixlabs/mxcli/mdl/backend"
 	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
-	mprbackend "github.com/mendixlabs/mxcli/mdl/backend/mpr"
 	"github.com/mendixlabs/mxcli/mdl/types"
 	"github.com/mendixlabs/mxcli/mdl/visitor"
 )
 
 // gateEngine pairs an engine name with its backend factory. The gate runs every
-// doctype script through exec + mx check on BOTH engines: modelsdk (the default)
-// and legacy. Previously it only ran legacy, so modelsdk-only serialization
-// regressions (dangling pointers, lossy round-trips, missing serializers) went
-// uncaught — see issue #691.
+// doctype script through exec + mx check on every engine in the matrix.
+//
+// The matrix has ONE entry since the legacy sdk/mpr engine was deleted
+// (docs/plans/2026-09-14-retire-legacy-engine.md). It is kept as a matrix rather
+// than collapsed into a single call for two reasons, neither of them symmetry:
+// it is the seam a future backend plugs into, and — the load-bearing one — the
+// selection below still turns a stale `MXCLI_TEST_ENGINES=legacy` into a loud
+// failure instead of a gate that runs nothing and reports success.
 type gateEngine struct {
 	name    string
 	factory func() backend.FullBackend
@@ -35,36 +38,27 @@ type gateEngine struct {
 
 var allGateEngines = []gateEngine{
 	{"modelsdk", func() backend.FullBackend { return modelsdkbackend.New() }},
-	{"legacy", func() backend.FullBackend { return mprbackend.New() }},
 }
 
 // gateEnginesEnv narrows the matrix above to a subset, as a comma- or
-// space-separated list of engine names ("modelsdk", "legacy"); empty or "all"
-// means every engine.
+// space-separated list of engine names; empty or "all" means every engine.
 //
-// It exists because the matrix is most of what the gate costs: each script is
-// executed and then handed to mxbuild once PER ENGINE, and mxbuild dominates.
-// On CI the per-push job runs `modelsdk` alone (see .github/workflows/
-// push-test.yml) and the nightly runs both — but on ONE Mendix version rather
-// than all five (nightly.yml), since nothing routes to legacy any more and it
-// was five sixths of that fleet's cost. Legacy stays verified daily, at a fifth
-// of what it used to cost, and its unit tests still run on every push.
+// With a one-engine matrix it narrows nothing, and what remains is the guard:
+// a name that is not in the matrix is REPORTED, so a workflow or a shell still
+// exporting MXCLI_TEST_ENGINES=legacy fails in TestMain rather than selecting
+// zero engines and reporting the gate green. That is why the deletion of legacy
+// left this in place instead of taking it along.
 //
-// The DEFAULT is every engine, deliberately. Nightly could have relied on a
-// default of "modelsdk" and set "all" itself, but then a mistake in EITHER
-// workflow file loses legacy coverage silently, and a lost gate is the failure
-// this repo has already shipped once (#808, an integration test that had only
-// ever skipped). With this default a mistake in the per-push file costs
-// minutes, not coverage — the failure mode is biased the right way. For the
-// same reason a narrowed matrix is announced in TestMain rather than applied
-// quietly: a run that covered less than it looks like it did should say so.
+// The DEFAULT is every engine, deliberately: a workflow file that forgets to set
+// this loses minutes, never coverage. A lost gate is the failure this repo has
+// already shipped once (#808, an integration test that had only ever skipped),
+// so the failure mode is biased the other way on purpose.
 //
-// One limit on that announcement, measured rather than assumed: `go test`
-// without -v DISCARDS a passing package's output, so TestMain's notice does not
-// reach a green CI log — only a -v run or a FAILING package shows it. The fatal
-// path is unaffected (an unknown name exits non-zero, and a failing package's
-// output is shown), but the visibility half is carried by the CI step NAME,
-// which states the engine set outright.
+// One limit on TestMain's announcement of a narrowed matrix, measured rather
+// than assumed: `go test` without -v DISCARDS a passing package's output, so the
+// notice does not reach a green CI log — only a -v run or a FAILING package
+// shows it. The fatal path is unaffected (an unknown name exits non-zero, and a
+// failing package's output is shown).
 const gateEnginesEnv = "MXCLI_TEST_ENGINES"
 
 // gateEngines is the matrix every gate test loops over.
diff --git a/mdl/executor/roundtrip_helpers_test.go b/mdl/executor/roundtrip_helpers_test.go
index 627a09d681..2779c05066 100644
--- a/mdl/executor/roundtrip_helpers_test.go
+++ b/mdl/executor/roundtrip_helpers_test.go
@@ -26,7 +26,7 @@ import (
 	"github.com/mendixlabs/mxcli/cmd/mxcli/docker"
 	"github.com/mendixlabs/mxcli/mdl/ast"
 	"github.com/mendixlabs/mxcli/mdl/backend"
-	mprbackend "github.com/mendixlabs/mxcli/mdl/backend/mpr"
+	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
 	"github.com/mendixlabs/mxcli/mdl/visitor"
 	"github.com/pmezard/go-difflib/difflib"
 )
@@ -295,14 +295,18 @@ func copyDir(src, dst string) error {
 }
 
 // setupTestEnv creates a new test environment with a fresh copy of the source project.
+//
+// This defaulted to the LEGACY engine, so most of this package's integration
+// tests ran on the engine that has since been deleted rather than on the one
+// users get. Deleting it (docs/plans/2026-09-14-retire-legacy-engine.md) moved
+// them all onto the codec engine, which is the coverage that was intended.
 func setupTestEnv(t *testing.T) *testEnv {
-	return setupTestEnvWithBackend(t, func() backend.FullBackend { return mprbackend.New() })
+	return setupTestEnvWithBackend(t, func() backend.FullBackend { return modelsdkbackend.New() })
 }
 
-// setupTestEnvWithBackend is setupTestEnv parametrized by the engine's backend
-// factory, so a test can exercise the same script on both the modelsdk (default)
-// and legacy engines (see TestMxCheck_DoctypeScripts). setupTestEnv keeps the
-// legacy default for the many tests that don't care which engine they run on.
+// setupTestEnvWithBackend is setupTestEnv parametrized by the backend factory,
+// so a test can name the engine it wants (see TestMxCheck_DoctypeScripts, which
+// loops over the matrix).
 func setupTestEnvWithBackend(t *testing.T, factory func() backend.FullBackend) *testEnv {
 	t.Helper()
 
diff --git a/mdl/executor/typecheck_test.go b/mdl/executor/typecheck_test.go
index e9edffc9d0..eb989d6a0c 100644
--- a/mdl/executor/typecheck_test.go
+++ b/mdl/executor/typecheck_test.go
@@ -10,7 +10,7 @@ import (
 	"testing"
 
 	"github.com/mendixlabs/mxcli/mdl/backend"
-	mprbackend "github.com/mendixlabs/mxcli/mdl/backend/mpr"
+	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
 	"github.com/mendixlabs/mxcli/mdl/linter"
 	"github.com/mendixlabs/mxcli/mdl/visitor"
 )
@@ -34,7 +34,7 @@ func typeCheckFixture(t *testing.T) *Executor {
 
 	exec := New(&bytes.Buffer{})
 	exec.SetQuiet(true)
-	exec.SetBackendFactory(func() backend.FullBackend { return mprbackend.New() })
+	exec.SetBackendFactory(func() backend.FullBackend { return modelsdkbackend.New() })
 	t.Cleanup(func() { exec.Close() })
 
 	run(t, exec, "CONNECT LOCAL '"+visitor.QuoteString(proj)+"'")
diff --git a/mdl/repl/repl.go b/mdl/repl/repl.go
index cc5d6fe054..e241ef8988 100644
--- a/mdl/repl/repl.go
+++ b/mdl/repl/repl.go
@@ -18,7 +18,7 @@ import (
 	"github.com/chzyer/readline"
 	"github.com/mendixlabs/mxcli/mdl/ast"
 	"github.com/mendixlabs/mxcli/mdl/backend"
-	mprbackend "github.com/mendixlabs/mxcli/mdl/backend/mpr"
+	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
 	"github.com/mendixlabs/mxcli/mdl/diaglog"
 	"github.com/mendixlabs/mxcli/mdl/executor"
 	"github.com/mendixlabs/mxcli/mdl/visitor"
@@ -42,10 +42,10 @@ func (r *REPL) SetLogger(l *diaglog.Logger) {
 }
 
 // SetBackendFactory overrides the backend factory used when the REPL connects to
-// a project. The default is the legacy local .mpr backend (see New); the CLI
-// passes the engine- and MCP-aware factory here so the interactive REPL honors
-// MXCLI_ENGINE/--engine and --mcp (it ignored both before). Call before the first
-// CONNECT (e.g. before auto-connect), since CONNECT consumes the factory.
+// a project. The default is a local codec backend (see New); the CLI passes its
+// MCP-aware factory here so the interactive REPL honors --mcp (it ignored it
+// before). Call before the first CONNECT (e.g. before auto-connect), since
+// CONNECT consumes the factory.
 func (r *REPL) SetBackendFactory(f executor.BackendFactory) {
 	r.executor.SetBackendFactory(f)
 }
@@ -59,7 +59,7 @@ func (r *REPL) SetTracer(t *backend.Tracer) {
 // New creates a new REPL with the given input and output.
 func New(input io.Reader, output io.Writer) *REPL {
 	exec := executor.New(output)
-	exec.SetBackendFactory(func() backend.FullBackend { return mprbackend.New() })
+	exec.SetBackendFactory(func() backend.FullBackend { return modelsdkbackend.New() })
 	c := newColorPalette()
 	return &REPL{
 		executor: exec,

From de4b09edf80ae3840afd2467625fc2f9d7751f7f Mon Sep 17 00:00:00 2001
From: Ako <andrej@koelewijn.net>
Date: Tue, 15 Sep 2026 07:45:07 +0000
Subject: [PATCH 14/24] docs(proposal): phase 2 engines paragraph after the
 legacy engine's removal

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../PROPOSAL_workflow_studio_pro_constructs.md           | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md b/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
index f1811189d6..c013dccd7f 100644
--- a/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
+++ b/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
@@ -202,10 +202,11 @@ from 11.10; the writer already records that Mendix 11.9 split
 (restate with `call agent microflow`, which describe emits); it was refused
 outright before, since describe printed an agent task only as a comment.
 
-**Engines.** Written and read by the modelsdk engine. The retiring legacy engine
-carries the flag through (same shape, agent `$Type`) rather than silently turning
-an agent task into a call microflow; the MCP backend refuses one, since PED's
-agent element has not been measured.
+**Engines.** Written and read by the codec engine, the only one since #468 retired
+the legacy backend. The `sdk/mpr` serializer, which remains for the tools that still
+hold it, carries the flag through (same shape, agent `$Type`) rather than silently
+turning an agent task into a call microflow. The MCP backend sends it as
+`Workflows$AIAgentTaskActivity`, verified against Studio Pro 11.14.
 
 ## Phase 3 — completion rules
 

From f06a85575dbe12db99044757a249fc2652712872 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 15 Sep 2026 07:59:15 +0000
Subject: [PATCH 15/24] Delete the dead FullBackend surface the census had
 mislabelled
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 3 step 4 of docs/plans/2026-09-14-retire-legacy-engine.md: re-run the
reachability probe over what was left. Six of the eleven remaining entries were
not bypasses awaiting a port — nothing anywhere wanted them.

scripts/backend-reachability.sh reports DEAD for "nothing calls this through a
backend value", and that one verdict covers three situations wanting opposite
fixes: a BYPASS (a caller wants it but holds a concrete reader/writer — port the
caller), an ORPHAN (no caller anywhere — delete), and a DUPLICATE (callers
exist, but through a narrower package-local interface with a different
signature — also delete). The probe cannot separate them; a grep for callers
under any type can.

Deleted, all measured DEAD: the whole WidgetSerializationBackend interface
(SerializeWidget, SerializeClientAction, SerializeDataSource,
SerializeWorkflowActivity), GetUnitTypes and UpdateLayout.

- SerializeWidget/DataSource are superseded by WidgetBuilderBackend's *ToOpaque
  pair, whose own comment says "This replaces the direct mpr.SerializeWidget
  call" — the supersession was known and the old pair never removed.
- SerializeClientAction and SerializeWorkflowActivity are reached through
  pagemutator's and wfmutator's own deps interfaces, which declare them
  returning bson.D rather than (any, error). The vestigial *Backend copy of
  SerializeWorkflowActivity carried a comment claiming ALTER WORKFLOW used it;
  ALTER WORKFLOW uses codecWorkflowDeps.
- GetUnitTypes exists only on modelsdk/mpr.Reader; UpdateLayout was superseded
  by the page mutator when ALTER LAYOUT landed.

Both generated stub files regenerated (276 -> 270 methods), mock stubs dropped.
Census 11 -> 6, and all six that remain are genuine bypasses.

This corrects a claim shipped in the previous PR: the census header and the plan
both said the list "shrinks by closing a bypass, never by deleting methods",
which holds for a bypass and is wrong for the other two. Both are rewritten to
name the three causes, as is the probe script's own header, which still told the
reader to fall back to the deleted engine.

Gates: build, vet (incl. -tags integration), go test ./..., check-mdl,
check-findings. The census pin (TestNoReachableUnimplementedBackendMethods)
passes at six entries with its control intact.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hifgRSawfaRWXS44YKtSJ
---
 .../fix-issue/findings/mdl-backend.jsonl      |  1 +
 docs/plans/2026-09-14-retire-legacy-engine.md | 47 ++++++++++-
 mdl/backend/backend.go                        |  1 -
 mdl/backend/infrastructure.go                 |  1 -
 mdl/backend/mcp/unsupported_gen.go            | 30 --------
 mdl/backend/mock/backend.go                   |  6 --
 mdl/backend/mock/mock_infrastructure.go       |  7 --
 mdl/backend/mock/mock_mutation.go             | 29 -------
 mdl/backend/mock/mock_page.go                 |  7 --
 mdl/backend/modelsdk/unimplemented_gen.go     | 29 -------
 .../unimplemented_reachability_test.go        | 77 +++++++++++--------
 .../modelsdk/workflow_mutator_write.go        | 10 ---
 mdl/backend/mutation.go                       | 19 -----
 mdl/backend/page.go                           |  1 -
 scripts/backend-reachability.sh               | 21 +++--
 15 files changed, 106 insertions(+), 180 deletions(-)

diff --git a/.claude/skills/fix-issue/findings/mdl-backend.jsonl b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
index dd899e50fe..a926b9adca 100644
--- a/.claude/skills/fix-issue/findings/mdl-backend.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
@@ -98,3 +98,4 @@
 {"area":"mdl/backend","date":"2026-09-15","symptom":"AddAttribute and UpdateAttribute were unimplemented on the default engine, so api/ could only work on the retired legacy one — and api/'s whole integration suite reported green while verifying nothing","cause":"api/ imported mdl/backend zero times: it held a concrete *mpr.Writer and bypassed the backend abstraction, so the two methods had no caller through a backend value and were never ported.","file":"api/api.go","fix":"api.New takes a backend.FullBackend (plus an api.Open convenience that owns its connection); the two methods are implemented on the codec backend and struck off unreachableUnimplemented.","insight":"unreachableUnimplemented is a CENSUS OF WHO BYPASSES THE ABSTRACTION, not dead interface surface. Read its reason column as a map and it names api/, the MCP backend, and the cmd/mxcli commands holding a concrete reader; a method is on it BECAUSE such a caller exists and unreachable BECAUSE that caller does not use a backend value. So the list shrinks by closing a bypass, never by deleting methods — and the pin fails loudly when you do, which is how it should be used. Two traps in the port itself. (1) The generated gen list offers only Append and Remove, so replacing an element in place means rebuilding the list; the naive remove-then-add moves the edited attribute to the bottom of the entity, which is a diff on every edit — control: break the rebuild and the order test catches it. (2) THE SUITE THAT WOULD HAVE VERIFIED THE PORT HAD ONLY EVER SKIPPED. api/'s integration tests pointed at ../mx-test-projects/test-source-app, which is not in the repository, so all ten skipped on every machine and in CI since they were written (the #808 shape). `go test ./api/` passing said nothing. Repointed at the committed testdata/expr-checker fixture the codec backend's own tests use, and made a missing fixture FATAL rather than a skip, since a committed fixture's absence is a broken checkout. Before trusting a suite to verify a refactor, check it is not skipping."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"The MCP backend held a concrete *mpr.Reader for its local reads, keeping three methods (GetDomainModelByID, GetWorkflow, ListNavigationDocuments) on FullBackend with no caller through a backend value — and 190 tests in the package, not one of which called Connect, so swapping the reader underneath it would have landed unverified with the suite green.","cause":"Those three reads had no codec-backend implementation, so MCP could not compose a backend and kept a legacy reader instead. Each was a re-keying or widening of a read the package already did, not new decoding.","file":"mdl/backend/mcp/backend.go","fix":"Implemented the three on the codec backend (mdl/backend/modelsdk/mcp_bypass_reads.go), sharing domainModelFromGen / workflowFromGen / navProfileFromGen with their siblings; added Backend.ConnectReadOnly and pointed MCP's reader field at backend.FullBackend. Wrote mdl/backend/mcp/connect_reads_test.go — the first test to call Connect at all.","insight":"A test can be vacuous in two different ways in one file, and the second is the one you miss. The read-only assertion SKIPPED (MyFirstModule has no entities), which the runner prints — so it was obvious. The GetWorkflow assertion looped over the listing and the fixture has ZERO workflows, so the loop body never ran and the test reported PASS having called nothing. Same failure class as #808, but silent. The fixes differ by shape: for the skip, pick a probe needing nothing pre-existing (CreateEntity, not AddAttribute); for the empty loop, SEED the thing through a read-write backend, then reconnect read-only and assert a specific named item is in the listing BEFORE fetching it — that guard is what converts a future vacuous pass into a failure. Cheapest way to find both: print the counts a test loops over before trusting it. MCP's read-only constraint also has a real control: revert ConnectReadOnly to Connect and the write-refusal test fails with the reported symptom, and the companion TestConnect_TheSameWriteSucceedsReadWrite proves the probe write is not failing for an unrelated reason."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"Deleting the legacy sdk/mpr backend (mdl/backend/mpr) turned up three things the removal plan had not sized: a runtime error telling users to rerun on the engine that had just been deleted, an integration suite that had been exercising the retired engine rather than the default one, and a cross-engine parity test whose comparison became vacuous.","cause":"Each is a reference to the second engine that was invisible while two engines existed. errUnimplemented's message named MXCLI_ENGINE=legacy as the fallback; setupTestEnv in mdl/executor/roundtrip_helpers_test.go hardcoded mprbackend.New() as its default, so most of the package's integration tests ran on legacy; TestODataService_EngineWriteParity compared writer A's key set against writer B's.","file":"mdl/backend/modelsdk/backend.go","fix":"errUnimplemented now asks for a bug report instead of naming a fallback. setupTestEnv defaults to the codec backend. The parity test keeps its value assertion (a published OData service retains AllowedModuleRoles) and drops the comparison, renamed to match. --engine/MXCLI_ENGINE kept as a warning-only no-op; `bson compare` and mdl/enginecompare deleted.","insight":"Deleting one of two implementations is not finished when the code compiles — grep for the deleted thing in three places the compiler cannot reach. (1) RUNTIME STRINGS: an error message naming a removed fallback is strictly worse than no fallback, because the user follows it and gets a second failure; this one had been shipping the instruction 'rerun with MXCLI_ENGINE=legacy' from 19 generated stubs. (2) TEST DEFAULTS: a shared setup helper's hardcoded choice of implementation decides what a whole package actually covers, and here it silently pointed most of mdl/executor's integration tests at the engine being retired — deleting the other one moved them onto the default engine for the first time, which is coverage gained, not lost. (3) DIFFERENTIAL TESTS: a test that compares A to B has no meaning with one implementation, but the PROPERTY it was a means to usually does — for the OData one, that a service keeps its role grants, which mx check reports as 0 errors either way. Drop the comparison, keep the property, rename the file so the next reader is not misled. One counter-case worth noting: the doctype gate's engine MATRIX was kept at one entry rather than collapsed, because its selection function still converts a stale MXCLI_TEST_ENGINES=legacy into a loud failure instead of a gate that selects zero engines and reports success."}
+{"area":"mdl/backend","date":"2026-09-15","symptom":"Six FullBackend methods sat on the unreachable census being treated as abstraction bypasses awaiting a port, when nothing anywhere wanted them: the whole WidgetSerializationBackend interface (SerializeWidget/ClientAction/DataSource/WorkflowActivity), GetUnitTypes and UpdateLayout. They had been superseded and simply never removed.","cause":"scripts/backend-reachability.sh reports DEAD for 'nothing calls this through a backend value', and that one verdict covers three different situations. The census header read all of them as bypasses, so the standing instruction was to port them — which for these would have meant implementing methods with no caller.","file":"mdl/backend/mutation.go","fix":"Deleted WidgetSerializationBackend, GetUnitTypes and UpdateLayout from the interface; regenerated unimplemented_gen.go and mcp/unsupported_gen.go (276 -> 270 methods); dropped the mock stubs and a duplicate *Backend impl. Census 11 -> 6, and the remaining six are genuine bypasses. Rewrote the census header and the probe script's own header to name the three causes.","insight":"A reachability probe that removes a method and rebuilds answers ONE question — is anything calling this through the interface — and DEAD has three causes wanting opposite fixes: BYPASS (a caller wants it but holds a concrete type; port the caller), ORPHAN (no caller anywhere; delete), DUPLICATE (callers exist but through a narrower package-local interface with a DIFFERENT SIGNATURE; delete). The probe cannot separate them; a grep for callers under any type can. DUPLICATE is the one that misleads, and it is worth knowing its two tells. First, a raw call-site count looks healthy — SerializeWidget had 6 and SerializeClientAction 4 — so the name reads as live; only comparing signatures shows the interface copy is unused (bson.D on the real path vs (any, error) on FullBackend). Second, the supersession is usually DOCUMENTED at the replacement, not at the corpse: WidgetBuilderBackend.SerializeWidgetToOpaque says 'This replaces the direct mpr.SerializeWidget call' — so grepping the NEW method's doc comment finds the old one faster than auditing the old one does. A stale comment on the dead method actively lies (the vestigial *Backend SerializeWorkflowActivity claimed the ALTER WORKFLOW paths used it; they use codecWorkflowDeps). Generalisable: when a helper has both an (any, error) and a concrete-typed variant, suspect the general-typed one is the abandoned interface obligation."}
diff --git a/docs/plans/2026-09-14-retire-legacy-engine.md b/docs/plans/2026-09-14-retire-legacy-engine.md
index fd25172b53..a889625f83 100644
--- a/docs/plans/2026-09-14-retire-legacy-engine.md
+++ b/docs/plans/2026-09-14-retire-legacy-engine.md
@@ -267,7 +267,12 @@ correction is the plan's main lesson:
 `mdl/backend/modelsdk/unimplemented_reachability_test.go` is a **census of who bypasses the
 abstraction**, not dead interface surface. A method is on it *because* some caller reaches it while
 holding a concrete reader or writer, and unreachable *because* that caller does not use a backend
-value. So the list shrinks by closing a bypass, never by deleting methods. It went 11 entries
+value. So the list shrinks by closing a bypass, never by deleting methods.
+
+> **Corrected 2026-09-15 — see [§7.3](#phase-3-step-4-the-census-has-three-causes-not-one).** That
+> last sentence is true of a bypass and false of the other two things on the list. Five of the
+> eleven remaining entries had no caller anywhere, or callers using a different signature, and were
+> deleted rather than ported. It went 11 entries
 lighter over these two steps (5 struck off), and what remains names exactly the work left in
 Phase 3: the `cmd/mxcli` bson/diag/extract-templates commands.
 
@@ -297,3 +302,43 @@ Went as written, at the sizes given. Three things the plan did not anticipate:
   kept as a single-engine test. The doctype gate's engine matrix was *not* deleted: with one entry
   it still turns a stale `MXCLI_TEST_ENGINES=legacy` into a loud failure instead of a gate that
   runs nothing and reports success.
+
+### Phase 3 step 4 — the census has three causes, not one (2026-09-15)
+
+Re-running the probe over what was left produced a correction to the paragraph above, which is the
+part of this plan most likely to be reused and was wrong.
+
+`scripts/backend-reachability.sh` reports **DEAD** for "nothing calls this through a backend
+value". That single verdict covers three situations that want opposite fixes:
+
+| cause | what it means | fix |
+|---|---|---|
+| **bypass** | a caller wants it but holds a concrete reader/writer | port the caller |
+| **orphan** | nothing anywhere calls it, under any type | delete the method |
+| **duplicate** | callers exist, but through a narrower package-local interface with a *different signature* | delete the method |
+
+The probe cannot separate them — that is what a grep for callers under **any** type is for. The
+duplicate case is the one that misleads: the name has plenty of call sites, so it reads as a
+bypass until you compare signatures.
+
+Measured, all six DEAD: the whole **`WidgetSerializationBackend`** interface (`SerializeWidget`,
+`SerializeClientAction`, `SerializeDataSource`, `SerializeWorkflowActivity`), plus `GetUnitTypes`
+and `UpdateLayout`.
+
+- `SerializeWidget` / `SerializeDataSource` are superseded by `WidgetBuilderBackend`'s
+  `SerializeWidgetToOpaque` / `SerializeDataSourceToOpaque` — whose own doc comment says *"This
+  replaces the direct mpr.SerializeWidget call"*, so the supersession was known and the old pair
+  simply never removed.
+- `SerializeClientAction` and `SerializeWorkflowActivity` are reached through `pagemutator` and
+  `wfmutator`'s own `deps` interfaces, which declare them returning `bson.D` rather than
+  `(any, error)`. The `*Backend` copy of `SerializeWorkflowActivity` even carried a comment claiming
+  the ALTER WORKFLOW paths used it; they use `codecWorkflowDeps`.
+- `GetUnitTypes` exists only on `modelsdk/mpr.Reader`; `UpdateLayout` was superseded by the page
+  mutator when ALTER LAYOUT landed.
+
+Deleted from the interface, both generated stub files regenerated (276 → 270 methods), mock stubs
+dropped. **Census 11 → 6**, and all six that remain are genuine bypasses — the `cmd/mxcli`
+bson/diag/extract-templates commands and `examples/read_project`, which hold a concrete reader
+deliberately. Whether those should be ported at all is the open question for the rest of Phase 3;
+they are debugging tools whose whole job is raw access, so "leave them" is a defensible answer that
+the earlier framing did not allow for.
diff --git a/mdl/backend/backend.go b/mdl/backend/backend.go
index 1eb4a33954..a57e80e3a1 100644
--- a/mdl/backend/backend.go
+++ b/mdl/backend/backend.go
@@ -37,6 +37,5 @@ type FullBackend interface {
 	AgentEditorBackend
 	PageMutationBackend
 	WorkflowMutationBackend
-	WidgetSerializationBackend
 	WidgetBuilderBackend
 }
diff --git a/mdl/backend/infrastructure.go b/mdl/backend/infrastructure.go
index 607a073605..64646d0405 100644
--- a/mdl/backend/infrastructure.go
+++ b/mdl/backend/infrastructure.go
@@ -42,7 +42,6 @@ type RawUnitBackend interface {
 type MetadataBackend interface {
 	ListAllUnitIDs() ([]string, error)
 	ListUnits() ([]*types.UnitInfo, error)
-	GetUnitTypes() (map[string]int, error)
 	GetProjectRootID() (string, error)
 	ContentsDir() string
 	ExportJSON() ([]byte, error)
diff --git a/mdl/backend/mcp/unsupported_gen.go b/mdl/backend/mcp/unsupported_gen.go
index 9f940925c7..06258da69b 100644
--- a/mdl/backend/mcp/unsupported_gen.go
+++ b/mdl/backend/mcp/unsupported_gen.go
@@ -644,11 +644,6 @@ func (unsupportedBackend) GetScheduledEvent(_ model.ID) (r0 *model.ScheduledEven
 	return
 }
 
-func (unsupportedBackend) GetUnitTypes() (r0 map[string]int, err1 error) {
-	err1 = errUnsupported("GetUnitTypes")
-	return
-}
-
 func (unsupportedBackend) GetWorkflow(_ model.ID) (r0 *workflows.Workflow, err1 error) {
 	err1 = errUnsupported("GetWorkflow")
 	return
@@ -1104,34 +1099,14 @@ func (unsupportedBackend) RevokeEntityMemberAccess(_ model.ID, _ string, _ []str
 	return
 }
 
-func (unsupportedBackend) SerializeClientAction(_ pages.ClientAction) (r0 any, err1 error) {
-	err1 = errUnsupported("SerializeClientAction")
-	return
-}
-
-func (unsupportedBackend) SerializeDataSource(_ pages.DataSource) (r0 any, err1 error) {
-	err1 = errUnsupported("SerializeDataSource")
-	return
-}
-
 func (unsupportedBackend) SerializeDataSourceToOpaque(_ pages.DataSource) (r0 any) {
 	return
 }
 
-func (unsupportedBackend) SerializeWidget(_ pages.Widget) (r0 any, err1 error) {
-	err1 = errUnsupported("SerializeWidget")
-	return
-}
-
 func (unsupportedBackend) SerializeWidgetToOpaque(_ pages.Widget) (r0 any) {
 	return
 }
 
-func (unsupportedBackend) SerializeWorkflowActivity(_ workflows.WorkflowActivity) (r0 any, err1 error) {
-	err1 = errUnsupported("SerializeWorkflowActivity")
-	return
-}
-
 func (unsupportedBackend) SetDomainModelAnnotations(_ model.ID, _ []*domainmodel.Annotation) (err0 error) {
 	err0 = errUnsupported("SetDomainModelAnnotations")
 	return
@@ -1262,11 +1237,6 @@ func (unsupportedBackend) UpdateJsonStructure(_ *types.JsonStructure) (err0 erro
 	return
 }
 
-func (unsupportedBackend) UpdateLayout(_ *pages.Layout) (err0 error) {
-	err0 = errUnsupported("UpdateLayout")
-	return
-}
-
 func (unsupportedBackend) UpdateMenuDocument(_ *types.MenuDocument) (err0 error) {
 	err0 = errUnsupported("UpdateMenuDocument")
 	return
diff --git a/mdl/backend/mock/backend.go b/mdl/backend/mock/backend.go
index 99fdf10e36..63efdeefaf 100644
--- a/mdl/backend/mock/backend.go
+++ b/mdl/backend/mock/backend.go
@@ -120,7 +120,6 @@ type MockBackend struct {
 	PageLayoutNameFunc     func(id model.ID) (string, error)
 	GetLayoutFunc          func(id model.ID) (*pages.Layout, error)
 	CreateLayoutFunc       func(layout *pages.Layout) error
-	UpdateLayoutFunc       func(layout *pages.Layout) error
 	DeleteLayoutFunc       func(id model.ID) error
 	ListSnippetsFunc       func() ([]*pages.Snippet, error)
 	CreateSnippetFunc      func(snippet *pages.Snippet) error
@@ -317,7 +316,6 @@ type MockBackend struct {
 	// MetadataBackend
 	ListAllUnitIDsFunc   func() ([]string, error)
 	ListUnitsFunc        func() ([]*types.UnitInfo, error)
-	GetUnitTypesFunc     func() (map[string]int, error)
 	GetProjectRootIDFunc func() (string, error)
 	ContentsDirFunc      func() string
 	ExportJSONFunc       func() ([]byte, error)
@@ -334,10 +332,6 @@ type MockBackend struct {
 	OpenWorkflowForMutationFunc func(unitID model.ID) (backend.WorkflowMutator, error)
 
 	// WidgetSerializationBackend
-	SerializeWidgetFunc           func(w pages.Widget) (any, error)
-	SerializeClientActionFunc     func(a pages.ClientAction) (any, error)
-	SerializeDataSourceFunc       func(ds pages.DataSource) (any, error)
-	SerializeWorkflowActivityFunc func(a workflows.WorkflowActivity) (any, error)
 
 	// WidgetBuilderBackend
 	LoadWidgetTemplateFunc          func(widgetID string, projectPath string) (backend.WidgetObjectBuilder, error)
diff --git a/mdl/backend/mock/mock_infrastructure.go b/mdl/backend/mock/mock_infrastructure.go
index 43a6a69469..98b409d7a0 100644
--- a/mdl/backend/mock/mock_infrastructure.go
+++ b/mdl/backend/mock/mock_infrastructure.go
@@ -116,13 +116,6 @@ func (m *MockBackend) ListUnits() ([]*types.UnitInfo, error) {
 	return nil, nil
 }
 
-func (m *MockBackend) GetUnitTypes() (map[string]int, error) {
-	if m.GetUnitTypesFunc != nil {
-		return m.GetUnitTypesFunc()
-	}
-	return nil, nil
-}
-
 func (m *MockBackend) GetProjectRootID() (string, error) {
 	if m.GetProjectRootIDFunc != nil {
 		return m.GetProjectRootIDFunc()
diff --git a/mdl/backend/mock/mock_mutation.go b/mdl/backend/mock/mock_mutation.go
index 1f53c1865c..f9d9f53c61 100644
--- a/mdl/backend/mock/mock_mutation.go
+++ b/mdl/backend/mock/mock_mutation.go
@@ -8,7 +8,6 @@ import (
 	"github.com/mendixlabs/mxcli/mdl/backend"
 	"github.com/mendixlabs/mxcli/model"
 	"github.com/mendixlabs/mxcli/sdk/pages"
-	"github.com/mendixlabs/mxcli/sdk/workflows"
 )
 
 // ---------------------------------------------------------------------------
@@ -37,34 +36,6 @@ func (m *MockBackend) OpenWorkflowForMutation(unitID model.ID) (backend.Workflow
 // WidgetSerializationBackend
 // ---------------------------------------------------------------------------
 
-func (m *MockBackend) SerializeWidget(w pages.Widget) (any, error) {
-	if m.SerializeWidgetFunc != nil {
-		return m.SerializeWidgetFunc(w)
-	}
-	return nil, nil
-}
-
-func (m *MockBackend) SerializeClientAction(a pages.ClientAction) (any, error) {
-	if m.SerializeClientActionFunc != nil {
-		return m.SerializeClientActionFunc(a)
-	}
-	return nil, nil
-}
-
-func (m *MockBackend) SerializeDataSource(ds pages.DataSource) (any, error) {
-	if m.SerializeDataSourceFunc != nil {
-		return m.SerializeDataSourceFunc(ds)
-	}
-	return nil, nil
-}
-
-func (m *MockBackend) SerializeWorkflowActivity(a workflows.WorkflowActivity) (any, error) {
-	if m.SerializeWorkflowActivityFunc != nil {
-		return m.SerializeWorkflowActivityFunc(a)
-	}
-	return nil, nil
-}
-
 // ---------------------------------------------------------------------------
 // WidgetBuilderBackend
 // ---------------------------------------------------------------------------
diff --git a/mdl/backend/mock/mock_page.go b/mdl/backend/mock/mock_page.go
index 29f6428e79..469380ec84 100644
--- a/mdl/backend/mock/mock_page.go
+++ b/mdl/backend/mock/mock_page.go
@@ -72,13 +72,6 @@ func (m *MockBackend) CreateLayout(layout *pages.Layout) error {
 	return nil
 }
 
-func (m *MockBackend) UpdateLayout(layout *pages.Layout) error {
-	if m.UpdateLayoutFunc != nil {
-		return m.UpdateLayoutFunc(layout)
-	}
-	return nil
-}
-
 func (m *MockBackend) DeleteLayout(id model.ID) error {
 	if m.DeleteLayoutFunc != nil {
 		return m.DeleteLayoutFunc(id)
diff --git a/mdl/backend/modelsdk/unimplemented_gen.go b/mdl/backend/modelsdk/unimplemented_gen.go
index 5ee943e182..ce5f628e99 100644
--- a/mdl/backend/modelsdk/unimplemented_gen.go
+++ b/mdl/backend/modelsdk/unimplemented_gen.go
@@ -558,11 +558,6 @@ func (unimplemented) GetScheduledEvent(_ model.ID) (*model.ScheduledEvent, error
 	return r0, errUnimplemented("GetScheduledEvent")
 }
 
-func (unimplemented) GetUnitTypes() (map[string]int, error) {
-	var r0 map[string]int
-	return r0, errUnimplemented("GetUnitTypes")
-}
-
 func (unimplemented) GetWorkflow(_ model.ID) (*workflows.Workflow, error) {
 	var r0 *workflows.Workflow
 	return r0, errUnimplemented("GetWorkflow")
@@ -1001,36 +996,16 @@ func (unimplemented) RevokeEntityMemberAccess(_ model.ID, _ string, _ []string,
 	return r0, errUnimplemented("RevokeEntityMemberAccess")
 }
 
-func (unimplemented) SerializeClientAction(_ pages.ClientAction) (interface{}, error) {
-	var r0 interface{}
-	return r0, errUnimplemented("SerializeClientAction")
-}
-
-func (unimplemented) SerializeDataSource(_ pages.DataSource) (interface{}, error) {
-	var r0 interface{}
-	return r0, errUnimplemented("SerializeDataSource")
-}
-
 func (unimplemented) SerializeDataSourceToOpaque(_ pages.DataSource) interface{} {
 	var r0 interface{}
 	return r0
 }
 
-func (unimplemented) SerializeWidget(_ pages.Widget) (interface{}, error) {
-	var r0 interface{}
-	return r0, errUnimplemented("SerializeWidget")
-}
-
 func (unimplemented) SerializeWidgetToOpaque(_ pages.Widget) interface{} {
 	var r0 interface{}
 	return r0
 }
 
-func (unimplemented) SerializeWorkflowActivity(_ workflows.WorkflowActivity) (interface{}, error) {
-	var r0 interface{}
-	return r0, errUnimplemented("SerializeWorkflowActivity")
-}
-
 func (unimplemented) SetDomainModelAnnotations(_ model.ID, _ []*domainmodel.Annotation) error {
 	return errUnimplemented("SetDomainModelAnnotations")
 }
@@ -1135,10 +1110,6 @@ func (unimplemented) UpdateJsonStructure(_ *types.JsonStructure) error {
 	return errUnimplemented("UpdateJsonStructure")
 }
 
-func (unimplemented) UpdateLayout(_ *pages.Layout) error {
-	return errUnimplemented("UpdateLayout")
-}
-
 func (unimplemented) UpdateMenuDocument(_ *types.MenuDocument) error {
 	return errUnimplemented("UpdateMenuDocument")
 }
diff --git a/mdl/backend/modelsdk/unimplemented_reachability_test.go b/mdl/backend/modelsdk/unimplemented_reachability_test.go
index a23bc7fe1c..d24de51b94 100644
--- a/mdl/backend/modelsdk/unimplemented_reachability_test.go
+++ b/mdl/backend/modelsdk/unimplemented_reachability_test.go
@@ -1,31 +1,47 @@
 // SPDX-License-Identifier: Apache-2.0
 
-// Can a default-engine run still hit errUnimplemented?
+// Can a run still hit errUnimplemented?
 //
-// That is the question standing between the modelsdk engine and dropping
-// `legacy` from nightly, and counting unimplemented methods answers it wrongly:
-// 19 of FullBackend's 276 methods were not declared on *Backend, but 17 of them
-// are interface surface nothing calls through a backend value, so their stub
-// could never fire. Measured with scripts/backend-reachability.sh, which removes
-// one method from its interface at a time and rebuilds — grep cannot tell
-// `b.reader.X()` inside the MPR backend from `ctx.Backend.X()` in the executor.
+// Counting unimplemented methods answers that wrongly: 19 of FullBackend's 276
+// methods were not declared on *Backend, but 17 of them were interface surface
+// nothing calls through a backend value, so their stub could never fire.
+// Measured with scripts/backend-reachability.sh, which removes one method from
+// its interface at a time and rebuilds — grep cannot tell `b.reader.X()` inside
+// a backend from `ctx.Backend.X()` in the executor.
 //
-// Read the reason column as a MAP and it names the places that hold a concrete
-// sdk/mpr reader or writer instead of a backend value — api/, the MCP backend,
-// and the cmd/mxcli commands that do so deliberately. A method is on this list
-// *because* such a caller exists and unreachable *because* that caller does not
-// use a backend. So the list shrinks by closing a bypass, not by deleting
-// interface surface: AddAttribute and UpdateAttribute left it when api/ was
-// routed through the abstraction, which made them reachable and therefore worth
-// implementing. See docs/plans/2026-09-14-retire-legacy-engine.md, Phase 3.
+// WHY A METHOD IS UNREACHABLE — three causes, and they want opposite fixes.
+// The reason column records which, because reading them all as one is how this
+// list gets mismanaged:
 //
-// Struck off so far, each by closing the bypass rather than by deleting surface:
-// AddAttribute and UpdateAttribute (api/ routed through the abstraction), then
-// GetDomainModelByID, GetWorkflow and ListNavigationDocuments (the MCP backend
-// composing this one for its reads).
+//  1. BYPASS — a caller wants the method but holds a concrete sdk/mpr reader or
+//     writer instead of a backend value. The fix is to route that caller through
+//     the abstraction, which makes the method reachable and therefore worth
+//     implementing. AddAttribute and UpdateAttribute left the list this way when
+//     api/ was ported; GetDomainModelByID, GetWorkflow and ListNavigationDocuments
+//     when the MCP backend composed this one for its reads.
+//  2. ORPHAN — nothing anywhere calls it, under any type. There is no bypass to
+//     close, so the fix is to DELETE it from the interface.
+//  3. DUPLICATE — callers exist, but through a narrower package-local interface
+//     with a different signature, so the FullBackend copy is vestigial. Also a
+//     delete, and the easiest of the three to mistake for a bypass: the name has
+//     plenty of call sites.
 //
-// This test does not repeat that measurement (a build per method takes minutes).
-// It pins its OUTPUT: the set of methods *Backend leaves to the stub must be
+// docs/plans/2026-09-14-retire-legacy-engine.md's Phase 3 write-up asserted the
+// list "shrinks by closing a bypass, never by deleting methods". That holds for
+// (1) and is wrong for (2) and (3): the whole WidgetSerializationBackend
+// interface (SerializeWidget, SerializeClientAction, SerializeDataSource,
+// SerializeWorkflowActivity), GetUnitTypes and UpdateLayout were measured DEAD
+// with either no caller at all or callers using a different signature —
+// SerializeWidget/DataSource superseded by WidgetBuilderBackend's *ToOpaque
+// pair, whose own comment says so, and SerializeWorkflowActivity by wfmutator's
+// deps. They were deleted rather than ported, taking the list from 11 to 6.
+//
+// So: establish the cause before acting on an entry. The probe says DEAD for all
+// three, which is exactly why it cannot tell them apart — grep for callers under
+// ANY type is what separates (1) from (2) and (3).
+//
+// This test does not repeat the probe (a build per method takes minutes). It
+// pins its OUTPUT: the set of methods *Backend leaves to the stub must be
 // exactly the set measured unreachable. A new stub, or a rename that drops an
 // implementation, fails here and is a prompt to re-run the script rather than to
 // extend the list on faith.
@@ -49,17 +65,12 @@ import (
 // and cmd/mxcli commands that open a reader directly) — none of which route
 // through this engine.
 var unreachableUnimplemented = map[string]string{
-	"ExportJSON":               "examples/read_project calls it on the sdk reader",
-	"FindCustomWidgetType":     "cmd/mxcli/cmd_extract_templates.go holds a concrete reader",
-	"FindAllCustomWidgetTypes": "reached only via the reader, inside modelsdk/mpr itself",
-	"GetProjectRootID":         "callers hold a reader; this package uses b.reader.GetProjectRootID directly",
-	"GetUnitTypes":             "no caller at all outside the MPR delegation",
-	"ListAllUnitIDs":           "cmd/mxcli/diag.go holds a concrete reader; infrastructure_write.go uses b.reader",
-	"ListRawUnits":             "the bson dump/discover/describe commands hold a concrete reader",
-	"UpdateLayout":             "ALTER LAYOUT goes through the page mutator, not this method",
-	"SerializeWidget":          "the child serializer is a separate type (codecChildSerializer), not Backend",
-	"SerializeClientAction":    "same as SerializeWidget",
-	"SerializeDataSource":      "no caller at all, on any type",
+	"ExportJSON":               "BYPASS: examples/read_project calls it on the sdk reader",
+	"FindCustomWidgetType":     "BYPASS: cmd/mxcli/cmd_extract_templates.go holds a concrete reader",
+	"FindAllCustomWidgetTypes": "BYPASS: reached only via the reader, inside modelsdk/mpr itself",
+	"GetProjectRootID":         "BYPASS: callers hold a reader; this package uses b.reader.GetProjectRootID directly",
+	"ListAllUnitIDs":           "BYPASS: cmd/mxcli/diag.go holds a concrete reader; infrastructure_write.go uses b.reader",
+	"ListRawUnits":             "BYPASS: the bson dump/discover/describe commands hold a concrete reader",
 }
 
 func TestNoReachableUnimplementedBackendMethods(t *testing.T) {
diff --git a/mdl/backend/modelsdk/workflow_mutator_write.go b/mdl/backend/modelsdk/workflow_mutator_write.go
index 94863d3af2..83da435c75 100644
--- a/mdl/backend/modelsdk/workflow_mutator_write.go
+++ b/mdl/backend/modelsdk/workflow_mutator_write.go
@@ -33,16 +33,6 @@ func (b *Backend) OpenWorkflowForMutation(unitID model.ID) (backend.WorkflowMuta
 	return wfmutator.New(d, unitID, codecWorkflowDeps{b: b}), nil
 }
 
-// SerializeWorkflowActivity converts a domain WorkflowActivity to its raw bson.D
-// form via the codec converters (used by the ALTER WORKFLOW insert/replace paths).
-func (b *Backend) SerializeWorkflowActivity(a workflows.WorkflowActivity) (any, error) {
-	d := serializeWorkflowActivityToBSON(a, b.useCallMicroflowActivityName())
-	if d == nil {
-		return nil, fmt.Errorf("SerializeWorkflowActivity: unsupported activity %T", a)
-	}
-	return d, nil
-}
-
 // codecWorkflowDeps implements wfmutator.Deps for the modelsdk (codec) backend.
 type codecWorkflowDeps struct{ b *Backend }
 
diff --git a/mdl/backend/mutation.go b/mdl/backend/mutation.go
index ddc7ae8c33..f04e295cd9 100644
--- a/mdl/backend/mutation.go
+++ b/mdl/backend/mutation.go
@@ -302,25 +302,6 @@ type WorkflowMutationBackend interface {
 	OpenWorkflowForMutation(unitID model.ID) (WorkflowMutator, error)
 }
 
-// WidgetSerializationBackend provides widget and activity serialization
-// for CREATE paths where the executor builds domain objects that need
-// to be converted to the storage format.
-type WidgetSerializationBackend interface {
-	// SerializeWidget converts a domain Widget to its storage representation.
-	// The returned value is opaque to the caller; it is only used as input
-	// to mutation operations or passed to the backend for persistence.
-	SerializeWidget(w pages.Widget) (any, error)
-
-	// SerializeClientAction converts a domain ClientAction to storage format.
-	SerializeClientAction(a pages.ClientAction) (any, error)
-
-	// SerializeDataSource converts a domain DataSource to storage format.
-	SerializeDataSource(ds pages.DataSource) (any, error)
-
-	// SerializeWorkflowActivity converts a domain WorkflowActivity to storage format.
-	SerializeWorkflowActivity(a workflows.WorkflowActivity) (any, error)
-}
-
 // WidgetObjectBuilder provides storage-agnostic operations on a loaded pluggable widget template.
 // The executor calls these methods with domain-typed values; the backend handles
 // all storage-specific manipulation internally.
diff --git a/mdl/backend/page.go b/mdl/backend/page.go
index e3fd76f381..79f0f09661 100644
--- a/mdl/backend/page.go
+++ b/mdl/backend/page.go
@@ -21,7 +21,6 @@ type PageBackend interface {
 	ListLayouts() ([]*pages.Layout, error)
 	GetLayout(id model.ID) (*pages.Layout, error)
 	CreateLayout(layout *pages.Layout) error
-	UpdateLayout(layout *pages.Layout) error
 	DeleteLayout(id model.ID) error
 
 	// PageLayoutName returns the qualified name of the layout a page renders
diff --git a/scripts/backend-reachability.sh b/scripts/backend-reachability.sh
index 64bc1988e7..2d27ee5411 100755
--- a/scripts/backend-reachability.sh
+++ b/scripts/backend-reachability.sh
@@ -2,11 +2,18 @@
 # Which backend.FullBackend methods does anything actually CALL through a
 # backend value?
 #
-# The modelsdk engine answers unported methods with errUnimplemented ("rerun
-# with MXCLI_ENGINE=legacy"), which is a reason the legacy engine has to stay
-# shipped and tested. Counting the unimplemented ones overstates the problem
-# badly: most are interface surface that only the MPR implementation and its own
-# reader ever touch, so no engine can reach them and the stub can never fire.
+# The engine answers unported methods with errUnimplemented. Counting the
+# unimplemented ones overstates the problem badly: most are interface surface
+# that only an implementation and its own reader ever touch, so nothing can
+# reach them and the stub can never fire.
+#
+# WHAT THIS SCRIPT CANNOT TELL YOU. DEAD has three causes that want opposite
+# fixes — a caller that bypasses the abstraction (port it), no caller anywhere
+# (delete the method), or callers using a narrower interface with a different
+# signature (also delete). All three report DEAD, because all three mean
+# "nothing calls it through a backend value". Separate them by grepping for
+# callers under ANY type; see the header of
+# mdl/backend/modelsdk/unimplemented_reachability_test.go.
 #
 # Grep cannot tell the difference — `b.reader.GetRawUnitByName(...)` inside the
 # MPR backend and `ctx.Backend.GetRawUnitByName(...)` in the executor look the
@@ -16,7 +23,9 @@
 #
 # Measured on 2026-09-12 over the 19 methods *Backend did not declare: 17 DEAD,
 # 2 LIVE (GetRawUnitByName, ParseMicroflowBSON — four call sites, all in
-# mdl/executor/cmd_microflows_builder.go). Both are now implemented;
+# mdl/executor/cmd_microflows_builder.go). Both are now implemented.
+# Re-measured 2026-09-15: six more DEAD entries turned out to be orphans or
+# duplicates rather than bypasses and were deleted from the interface.
 # TestNoReachableUnimplementedBackendMethods in mdl/backend/modelsdk holds the
 # list this script produced.
 #

From 694b379fb731dd3d76e865c64b9400ad6404251b Mon Sep 17 00:00:00 2001
From: Ako <andrej@koelewijn.net>
Date: Tue, 15 Sep 2026 08:58:42 +0000
Subject: [PATCH 16/24] test(mcp): dial the fake PED at its listener, not
 through defaultDial
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five TestConnect_* tests from #468 built the backend with an empty dial
address, so defaultDial rewrote 127.0.0.1 to host.docker.internal wherever
that name resolves. In a devcontainer the request went to the Docker host
instead of the httptest listener and Connect failed with "connection
refused"; on CI the name does not resolve, so the suite was green.

Route the three constructor calls through backendFor, which passes the
listener address explicitly the way fakePED.connectClient does.
defaultDial is unchanged — it is correct for a real Studio Pro.

Control: with the dial reverted to "" the same five tests fail in the
devcontainer with the reported message.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../fix-issue/findings/mdl-backend.jsonl       |  1 +
 mdl/backend/mcp/connect_reads_test.go          | 18 +++++++++++++++---
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/.claude/skills/fix-issue/findings/mdl-backend.jsonl b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
index dd899e50fe..27a5c1d28d 100644
--- a/.claude/skills/fix-issue/findings/mdl-backend.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
@@ -98,3 +98,4 @@
 {"area":"mdl/backend","date":"2026-09-15","symptom":"AddAttribute and UpdateAttribute were unimplemented on the default engine, so api/ could only work on the retired legacy one — and api/'s whole integration suite reported green while verifying nothing","cause":"api/ imported mdl/backend zero times: it held a concrete *mpr.Writer and bypassed the backend abstraction, so the two methods had no caller through a backend value and were never ported.","file":"api/api.go","fix":"api.New takes a backend.FullBackend (plus an api.Open convenience that owns its connection); the two methods are implemented on the codec backend and struck off unreachableUnimplemented.","insight":"unreachableUnimplemented is a CENSUS OF WHO BYPASSES THE ABSTRACTION, not dead interface surface. Read its reason column as a map and it names api/, the MCP backend, and the cmd/mxcli commands holding a concrete reader; a method is on it BECAUSE such a caller exists and unreachable BECAUSE that caller does not use a backend value. So the list shrinks by closing a bypass, never by deleting methods — and the pin fails loudly when you do, which is how it should be used. Two traps in the port itself. (1) The generated gen list offers only Append and Remove, so replacing an element in place means rebuilding the list; the naive remove-then-add moves the edited attribute to the bottom of the entity, which is a diff on every edit — control: break the rebuild and the order test catches it. (2) THE SUITE THAT WOULD HAVE VERIFIED THE PORT HAD ONLY EVER SKIPPED. api/'s integration tests pointed at ../mx-test-projects/test-source-app, which is not in the repository, so all ten skipped on every machine and in CI since they were written (the #808 shape). `go test ./api/` passing said nothing. Repointed at the committed testdata/expr-checker fixture the codec backend's own tests use, and made a missing fixture FATAL rather than a skip, since a committed fixture's absence is a broken checkout. Before trusting a suite to verify a refactor, check it is not skipping."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"The MCP backend held a concrete *mpr.Reader for its local reads, keeping three methods (GetDomainModelByID, GetWorkflow, ListNavigationDocuments) on FullBackend with no caller through a backend value — and 190 tests in the package, not one of which called Connect, so swapping the reader underneath it would have landed unverified with the suite green.","cause":"Those three reads had no codec-backend implementation, so MCP could not compose a backend and kept a legacy reader instead. Each was a re-keying or widening of a read the package already did, not new decoding.","file":"mdl/backend/mcp/backend.go","fix":"Implemented the three on the codec backend (mdl/backend/modelsdk/mcp_bypass_reads.go), sharing domainModelFromGen / workflowFromGen / navProfileFromGen with their siblings; added Backend.ConnectReadOnly and pointed MCP's reader field at backend.FullBackend. Wrote mdl/backend/mcp/connect_reads_test.go — the first test to call Connect at all.","insight":"A test can be vacuous in two different ways in one file, and the second is the one you miss. The read-only assertion SKIPPED (MyFirstModule has no entities), which the runner prints — so it was obvious. The GetWorkflow assertion looped over the listing and the fixture has ZERO workflows, so the loop body never ran and the test reported PASS having called nothing. Same failure class as #808, but silent. The fixes differ by shape: for the skip, pick a probe needing nothing pre-existing (CreateEntity, not AddAttribute); for the empty loop, SEED the thing through a read-write backend, then reconnect read-only and assert a specific named item is in the listing BEFORE fetching it — that guard is what converts a future vacuous pass into a failure. Cheapest way to find both: print the counts a test loops over before trusting it. MCP's read-only constraint also has a real control: revert ConnectReadOnly to Connect and the write-refusal test fails with the reported symptom, and the companion TestConnect_TheSameWriteSucceedsReadWrite proves the probe write is not failing for an unrelated reason."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"Deleting the legacy sdk/mpr backend (mdl/backend/mpr) turned up three things the removal plan had not sized: a runtime error telling users to rerun on the engine that had just been deleted, an integration suite that had been exercising the retired engine rather than the default one, and a cross-engine parity test whose comparison became vacuous.","cause":"Each is a reference to the second engine that was invisible while two engines existed. errUnimplemented's message named MXCLI_ENGINE=legacy as the fallback; setupTestEnv in mdl/executor/roundtrip_helpers_test.go hardcoded mprbackend.New() as its default, so most of the package's integration tests ran on legacy; TestODataService_EngineWriteParity compared writer A's key set against writer B's.","file":"mdl/backend/modelsdk/backend.go","fix":"errUnimplemented now asks for a bug report instead of naming a fallback. setupTestEnv defaults to the codec backend. The parity test keeps its value assertion (a published OData service retains AllowedModuleRoles) and drops the comparison, renamed to match. --engine/MXCLI_ENGINE kept as a warning-only no-op; `bson compare` and mdl/enginecompare deleted.","insight":"Deleting one of two implementations is not finished when the code compiles — grep for the deleted thing in three places the compiler cannot reach. (1) RUNTIME STRINGS: an error message naming a removed fallback is strictly worse than no fallback, because the user follows it and gets a second failure; this one had been shipping the instruction 'rerun with MXCLI_ENGINE=legacy' from 19 generated stubs. (2) TEST DEFAULTS: a shared setup helper's hardcoded choice of implementation decides what a whole package actually covers, and here it silently pointed most of mdl/executor's integration tests at the engine being retired — deleting the other one moved them onto the default engine for the first time, which is coverage gained, not lost. (3) DIFFERENTIAL TESTS: a test that compares A to B has no meaning with one implementation, but the PROPERTY it was a means to usually does — for the OData one, that a service keeps its role grants, which mx check reports as 0 errors either way. Drop the comparison, keep the property, rename the file so the next reader is not misled. One counter-case worth noting: the doctype gate's engine MATRIX was kept at one entry rather than collapsed, because its selection function still converts a stale MXCLI_TEST_ENGINES=legacy into a loud failure instead of a gate that selects zero engines and reports success."}
+{"area": "mdl/backend", "date": "2026-09-15", "symptom": "Five `TestConnect_*` tests in `mdl/backend/mcp/connect_reads_test.go` (added by ako/mxcli#468) fail in a devcontainer — on pristine origin/main — with `Connect: connect to MCP server \"http://127.0.0.1:NNNNN/mcp\": ... dial tcp 192.168.65.254:NNNNN: connect: connection refused`, while CI is green", "cause": "The tests built the backend with `New(ped.srv.URL+\"/mcp\", \"\")`. An empty dial address falls through to `defaultDial` → `dialFor` in `mdl/backend/mcp/client.go`, which rewrites a localhost endpoint to `host.docker.internal:<port>` whenever that name resolves — the intended convenience for reaching a Studio Pro on the Docker host. Inside a devcontainer it resolves, so the request goes to the host gateway and never reaches the httptest listener on the container's own 127.0.0.1. On a CI runner the name does not resolve and the rewrite is a no-op, which is why the suite was green there", "file": "`mdl/backend/mcp/connect_reads_test.go` (`backendFor`, used by `connected`, `TestConnect_GetWorkflowReadsASeededWorkflow`, `TestConnect_DisconnectIsIdempotent`); precedent `fakePED.connectClient` in `client_test.go`", "insight": "**A fake server must be dialled at the address it is listening on, never through production address resolution.** Any helper that takes an optional dial/host override and defaults to environment-sensitive logic (DNS lookups, proxy env, gateway rewrites) makes a test pass or fail by where it runs, not by what it tests — and CI is precisely the environment where such a rewrite is inert, so it cannot catch it. Pass the listener address explicitly (as `connectClient` already did) rather than changing `defaultDial`, which is correct for real connections. The tell in the error is the dialled IP differing from the URL's host. Control: revert the dial to `\"\"` in the devcontainer and the same five fail with the reported message; `TestConnect_TheSameWriteSucceedsReadWrite` passes either way because it never builds an MCP backend, which is what localises the defect to the constructor call", "refs": ["ako/mxcli#468"]}
diff --git a/mdl/backend/mcp/connect_reads_test.go b/mdl/backend/mcp/connect_reads_test.go
index 95641aec34..1434dcb004 100644
--- a/mdl/backend/mcp/connect_reads_test.go
+++ b/mdl/backend/mcp/connect_reads_test.go
@@ -14,6 +14,7 @@ package mcp
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
@@ -33,11 +34,22 @@ func localProject(t *testing.T) string {
 	return filepath.Join(dst, "minimal.mpr")
 }
 
+// backendFor returns an unconnected Backend pointed at the fake Studio Pro.
+//
+// The dial address is passed explicitly, as connectClient does. An empty one
+// lets defaultDial rewrite 127.0.0.1 to host.docker.internal wherever that name
+// resolves — correct for a real Studio Pro on the host, but inside a devcontainer
+// it sends the request to the Docker host instead of the httptest listener in
+// this container, and Connect fails with "connection refused".
+func backendFor(ped *fakePED) *Backend {
+	return New(ped.srv.URL+"/mcp", strings.TrimPrefix(ped.srv.URL, "http://"))
+}
+
 // connected returns a Backend wired to a fake Studio Pro and the local fixture.
 func connected(t *testing.T) *Backend {
 	t.Helper()
 	ped := newFakePED(t, func(string, map[string]any) (string, bool) { return "{}", false })
-	b := New(ped.srv.URL+"/mcp", "")
+	b := backendFor(ped)
 	if err := b.Connect(localProject(t)); err != nil {
 		t.Fatalf("Connect: %v", err)
 	}
@@ -138,7 +150,7 @@ func TestConnect_GetWorkflowReadsASeededWorkflow(t *testing.T) {
 	}
 
 	ped := newFakePED(t, func(string, map[string]any) (string, bool) { return "{}", false })
-	b := New(ped.srv.URL+"/mcp", "")
+	b := backendFor(ped)
 	if err := b.Connect(path); err != nil {
 		t.Fatalf("Connect: %v", err)
 	}
@@ -235,7 +247,7 @@ func TestConnect_TheSameWriteSucceedsReadWrite(t *testing.T) {
 // lifecycle and a double teardown is cheap to get wrong.
 func TestConnect_DisconnectIsIdempotent(t *testing.T) {
 	ped := newFakePED(t, func(string, map[string]any) (string, bool) { return "{}", false })
-	b := New(ped.srv.URL+"/mcp", "")
+	b := backendFor(ped)
 	if err := b.Connect(localProject(t)); err != nil {
 		t.Fatalf("Connect: %v", err)
 	}

From 898e78eb86dd645cfdd95861371c936309b5eada Mon Sep 17 00:00:00 2001
From: Ako <andrej@koelewijn.net>
Date: Tue, 15 Sep 2026 09:24:06 +0000
Subject: [PATCH 17/24] =?UTF-8?q?feat(workflow):=20multi-user=20task=20com?=
 =?UTF-8?q?pletion=20rules=20=E2=80=94=20participants,=20decide=20by,=20aw?=
 =?UTF-8?q?ait=20all=20users?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 3 of PROPOSAL_workflow_studio_pro_constructs.md.

  multi user task Vote 'Vote on the request'
    page HR.VotePage
    participants 80 percent
    decide by threshold 60 percent fallback 'Reject'
    await all users
    outcomes 'Approve' { } 'Reject' { };

Rules: consensus / majority more than half / majority most chosen /
threshold <n> percent|votes, each with fallback '<outcome>'; veto
'<outcome>'; microflow M. Omitted clauses are what a rebuild has always
written, so existing describe output is unchanged.

The shapes come from Studio Pro, not gen: the examples were built in Studio
Pro 11.14 over MCP, saved to ako/TestApp, and the saved document is the
reader's fixture — "more than half" is an Absolute majority, a percentage
threshold Relative, and both outcome pointers hold the outcome's $ID.

Measured on mxbuild 11.13.0: fallback required for consensus/majority/
threshold (CE1866), veto outcome required (CE1867) — MDL-WF13 at check time,
also for a name that is none of the task's outcomes; a decision microflow
returns String (CE5012), parameters free; thresholds and participant counts
are not range-checked by the build, so not by mxcli.

Fixed on the way:
- a workflow rewrite silently reset every multi-user task's participant
  count and "await all users" (never guarded); a rewrite not restating them,
  or a stored completion rule, is now refused.
- MCP: multi-user tasks could not be created on Studio Pro 11.14 (the
  constructor takes a taskPage element); PED's default consensus has no
  fallback (CE1866) and its constructor drops a more-than-half majority's
  fallback, which is now set by the outcome's $ID afterwards. Verified live:
  created, read back, no errors.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../fix-issue/findings/mdl-backend.jsonl      |   1 +
 .../fix-issue/findings/mdl-executor.jsonl     |   1 +
 .../skills/mendix/write-workflows/SKILL.md    |  23 +-
 CHANGELOG.md                                  |   6 +
 cmd/mxcli/lsp_completions_gen.go              |  15 ++
 cmd/mxcli/syntax/features_workflow.go         |  22 +-
 docs-site/src/language/workflow-activities.md |  40 +++
 docs/01-project/MDL_QUICK_REFERENCE.md        |   3 +-
 ...PROPOSAL_workflow_studio_pro_constructs.md |  80 +++++-
 .../doctype-tests/24-workflow-examples.mdl    |  62 +++++
 mdl/ast/ast_workflow.go                       |  23 ++
 mdl/backend/mcp/backend.go                    |   5 +
 mdl/backend/mcp/workflow.go                   | 206 ++++++++++++++++
 mdl/backend/mcp/workflow_completion_test.go   | 123 ++++++++++
 .../mcp/workflow_multitask_page_test.go       |  61 +++++
 .../TestApp.ZzMxcliExample_Completion2.bson   | Bin 0 -> 11868 bytes
 .../modelsdk/workflow_completion_test.go      | 168 +++++++++++++
 mdl/backend/modelsdk/workflow_read.go         |  45 ++++
 mdl/backend/modelsdk/workflow_write.go        |  88 ++++++-
 mdl/executor/cmd_alter_workflow.go            |   3 +
 mdl/executor/cmd_workflows.go                 |  59 +++++
 mdl/executor/cmd_workflows_write.go           |  53 ++++
 mdl/executor/validate_workflow.go             |   1 +
 mdl/executor/validate_workflow_completion.go  |  96 ++++++++
 mdl/executor/validate_workflow_refs.go        |   5 +
 mdl/executor/validate_workflow_rewrite.go     | 140 +++++++++--
 .../validate_workflow_task_signature.go       |   3 +
 mdl/executor/workflow_completion_test.go      | 229 ++++++++++++++++++
 mdl/grammar/MDLLexer.g4                       |  18 ++
 mdl/grammar/domains/MDLSettings.g4            |   4 +
 mdl/grammar/domains/MDLWorkflow.g4            |  32 +++
 mdl/visitor/visitor_workflow.go               |  66 ++++-
 .../visitor_workflow_completion_test.go       |  72 ++++++
 sdk/workflows/workflow.go                     |  23 ++
 34 files changed, 1727 insertions(+), 49 deletions(-)
 create mode 100644 mdl/backend/mcp/workflow_completion_test.go
 create mode 100644 mdl/backend/mcp/workflow_multitask_page_test.go
 create mode 100644 mdl/backend/modelsdk/testdata/TestApp.ZzMxcliExample_Completion2.bson
 create mode 100644 mdl/backend/modelsdk/workflow_completion_test.go
 create mode 100644 mdl/executor/validate_workflow_completion.go
 create mode 100644 mdl/executor/workflow_completion_test.go
 create mode 100644 mdl/visitor/visitor_workflow_completion_test.go

diff --git a/.claude/skills/fix-issue/findings/mdl-backend.jsonl b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
index fb6181b5e5..3a3633c226 100644
--- a/.claude/skills/fix-issue/findings/mdl-backend.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
@@ -99,3 +99,4 @@
 {"area":"mdl/backend","date":"2026-09-15","symptom":"AddAttribute and UpdateAttribute were unimplemented on the default engine, so api/ could only work on the retired legacy one — and api/'s whole integration suite reported green while verifying nothing","cause":"api/ imported mdl/backend zero times: it held a concrete *mpr.Writer and bypassed the backend abstraction, so the two methods had no caller through a backend value and were never ported.","file":"api/api.go","fix":"api.New takes a backend.FullBackend (plus an api.Open convenience that owns its connection); the two methods are implemented on the codec backend and struck off unreachableUnimplemented.","insight":"unreachableUnimplemented is a CENSUS OF WHO BYPASSES THE ABSTRACTION, not dead interface surface. Read its reason column as a map and it names api/, the MCP backend, and the cmd/mxcli commands holding a concrete reader; a method is on it BECAUSE such a caller exists and unreachable BECAUSE that caller does not use a backend value. So the list shrinks by closing a bypass, never by deleting methods — and the pin fails loudly when you do, which is how it should be used. Two traps in the port itself. (1) The generated gen list offers only Append and Remove, so replacing an element in place means rebuilding the list; the naive remove-then-add moves the edited attribute to the bottom of the entity, which is a diff on every edit — control: break the rebuild and the order test catches it. (2) THE SUITE THAT WOULD HAVE VERIFIED THE PORT HAD ONLY EVER SKIPPED. api/'s integration tests pointed at ../mx-test-projects/test-source-app, which is not in the repository, so all ten skipped on every machine and in CI since they were written (the #808 shape). `go test ./api/` passing said nothing. Repointed at the committed testdata/expr-checker fixture the codec backend's own tests use, and made a missing fixture FATAL rather than a skip, since a committed fixture's absence is a broken checkout. Before trusting a suite to verify a refactor, check it is not skipping."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"The MCP backend held a concrete *mpr.Reader for its local reads, keeping three methods (GetDomainModelByID, GetWorkflow, ListNavigationDocuments) on FullBackend with no caller through a backend value — and 190 tests in the package, not one of which called Connect, so swapping the reader underneath it would have landed unverified with the suite green.","cause":"Those three reads had no codec-backend implementation, so MCP could not compose a backend and kept a legacy reader instead. Each was a re-keying or widening of a read the package already did, not new decoding.","file":"mdl/backend/mcp/backend.go","fix":"Implemented the three on the codec backend (mdl/backend/modelsdk/mcp_bypass_reads.go), sharing domainModelFromGen / workflowFromGen / navProfileFromGen with their siblings; added Backend.ConnectReadOnly and pointed MCP's reader field at backend.FullBackend. Wrote mdl/backend/mcp/connect_reads_test.go — the first test to call Connect at all.","insight":"A test can be vacuous in two different ways in one file, and the second is the one you miss. The read-only assertion SKIPPED (MyFirstModule has no entities), which the runner prints — so it was obvious. The GetWorkflow assertion looped over the listing and the fixture has ZERO workflows, so the loop body never ran and the test reported PASS having called nothing. Same failure class as #808, but silent. The fixes differ by shape: for the skip, pick a probe needing nothing pre-existing (CreateEntity, not AddAttribute); for the empty loop, SEED the thing through a read-write backend, then reconnect read-only and assert a specific named item is in the listing BEFORE fetching it — that guard is what converts a future vacuous pass into a failure. Cheapest way to find both: print the counts a test loops over before trusting it. MCP's read-only constraint also has a real control: revert ConnectReadOnly to Connect and the write-refusal test fails with the reported symptom, and the companion TestConnect_TheSameWriteSucceedsReadWrite proves the probe write is not failing for an unrelated reason."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"Deleting the legacy sdk/mpr backend (mdl/backend/mpr) turned up three things the removal plan had not sized: a runtime error telling users to rerun on the engine that had just been deleted, an integration suite that had been exercising the retired engine rather than the default one, and a cross-engine parity test whose comparison became vacuous.","cause":"Each is a reference to the second engine that was invisible while two engines existed. errUnimplemented's message named MXCLI_ENGINE=legacy as the fallback; setupTestEnv in mdl/executor/roundtrip_helpers_test.go hardcoded mprbackend.New() as its default, so most of the package's integration tests ran on legacy; TestODataService_EngineWriteParity compared writer A's key set against writer B's.","file":"mdl/backend/modelsdk/backend.go","fix":"errUnimplemented now asks for a bug report instead of naming a fallback. setupTestEnv defaults to the codec backend. The parity test keeps its value assertion (a published OData service retains AllowedModuleRoles) and drops the comparison, renamed to match. --engine/MXCLI_ENGINE kept as a warning-only no-op; `bson compare` and mdl/enginecompare deleted.","insight":"Deleting one of two implementations is not finished when the code compiles — grep for the deleted thing in three places the compiler cannot reach. (1) RUNTIME STRINGS: an error message naming a removed fallback is strictly worse than no fallback, because the user follows it and gets a second failure; this one had been shipping the instruction 'rerun with MXCLI_ENGINE=legacy' from 19 generated stubs. (2) TEST DEFAULTS: a shared setup helper's hardcoded choice of implementation decides what a whole package actually covers, and here it silently pointed most of mdl/executor's integration tests at the engine being retired — deleting the other one moved them onto the default engine for the first time, which is coverage gained, not lost. (3) DIFFERENTIAL TESTS: a test that compares A to B has no meaning with one implementation, but the PROPERTY it was a means to usually does — for the OData one, that a service keeps its role grants, which mx check reports as 0 errors either way. Drop the comparison, keep the property, rename the file so the next reader is not misled. One counter-case worth noting: the doctype gate's engine MATRIX was kept at one entry rather than collapsed, because its selection function still converts a stale MXCLI_TEST_ENGINES=legacy into a loud failure instead of a gate that selects zero engines and reports success."}
+{"area": "mdl/backend/mcp", "date": "2026-09-15", "symptom": "Over MCP against Studio Pro 11.14, `create workflow` with any `multi user task` fails: `ped_create_document …: {\"/flow/activities/1/taskPage\":\"Expected an object, but the value is missing.\"}`", "cause": "The 11.14 Workflows$MultiUserTaskActivity CONSTRUCTOR takes `taskPage: Element<'Workflows$PageReference'>`; mapWorkflowActivity sent the older bare `pageReference` string. Same class as the workflow constructor's `context` change in the same release", "file": "`mdl/backend/mcp/workflow.go` (`multiUserTaskConstructorTakesTaskPage`, `adaptMultiUserTaskPages`)", "insight": "PED constructor shapes drift per Studio Pro release independently of the element (update) shapes, and serverInfo.version is frozen at 1.0.0, so probe the constructor schema text rather than gating on a version. When one constructor of a document family changed shape in a release, check the others in that family before trusting the mapper — this one surfaced only because a phase-3 live probe used a multi-user task"}
diff --git a/.claude/skills/fix-issue/findings/mdl-executor.jsonl b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
index 8b182d1a74..b33980d1d7 100644
--- a/.claude/skills/fix-issue/findings/mdl-executor.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
@@ -619,3 +619,4 @@
 {"area": "mdl/executor", "date": "2026-09-14", "symptom": "An `exec` / `check --references` error on a CREATE WORKFLOW statement ends with 'hint: M.W is defined later in this script — move its create statement before this one', naming the failing workflow itself (or a workflow already created earlier in the script).", "cause": "annotateForwardRef draws candidate names from scriptContext.allNames (which includes workflows) and excludes the statement's own name and already-created names via scriptContext.has — which checked modules, entities, enumerations, microflows, nanoflows, pages, snippets and code actions but NOT workflows. A parallel list that drifted from the one it filters.", "fix": "scriptContext.has also answers for sc.workflows.", "file": "mdl/executor/validate.go", "insight": "Two lists over the same kinds (allNames and has) with nothing tying them together — the same drift shape as collectDefinitions/collectSingle. The misfire only became visible once an error routinely named its own workflow, i.e. a new rule surfaced a latent bug in how every rule's message is decorated. When adding a document kind to scriptContext, check every method that enumerates kinds, not just the collector."}
 {"area": "mdl/executor", "date": "2026-09-14", "symptom": "On the **legacy** engine (MXCLI_ENGINE=legacy), `create or modify workflow` that does not restate stored event handlers / boundary events / nested Ends / AI agent tasks / completion rules is written (\"Created workflow\") and deletes them, while the default modelsdk engine refuses the same statement with the guard-don't-drop list", "cause": "The workflow rewrite guards walk `ctx.Backend.GetRawUnit` with type switches on `map[string]any` / `[]any`. The legacy backend decodes with mongo-driver v1 `bson.Unmarshal` into map[string]any, which yields nested documents as map[string]any but ARRAYS AS `primitive.A` — a named type a `case []any` does not match. So every guard saw no list at all (measured with a probe: `OnWorkflowEvent primitive.A`, `Flow map[string]interface {}`). The modelsdk reader normalizes to plain slices (`modelsdk/mpr/reader_raw.go normalizeBSONValue`), which is why only legacy was blind", "file": "`mdl/executor/validate_workflow_rewrite.go` (`plainRawUnit`, applied in `checkNoDroppedWorkflowConstructs` and `validateAlterReplaceKeepsStudioProState`)", "insight": "A guard tested only with hand-built `[]any` fixtures proves nothing about the legacy engine: build the fixture, then `bson.Marshal` + `bson.Unmarshal` into map[string]any to get the shape legacy's GetRawUnit really returns (`legacyShaped` in validate_workflow_rewrite_legacy_test.go). Normalized in the guard, not in MprBackend.GetRawUnit, because catalog (`builder_regularexpressions.go`) asserts `bson.A` on raw units. Found only by running the e2e rewrite on BOTH engines — the modelsdk run was green. Other `[]any`-only raw walkers (REST body guard, queued-call guard) are suspects of the same class. Control: normalizer returning its input fails the legacy-shape tests"}
 {"area": "mdl/executor", "date": "2026-09-15", "symptom": "`describe workflow` → `create or modify` → `describe` differs: a call microflow authored with `comment 'Summarise'` comes back captioned with the microflow's name (`-- ACT_Summarise`)", "cause": "`formatCallMicroflowTask` printed the caption only as a trailing `-- caption` MDL comment, which the parser discards; re-execution then fell back to the builder's default caption (the microflow's short name)", "file": "`mdl/executor/cmd_workflows.go` (`formatCallMicroflowTask`)", "insight": "A trailing `--` comment in describe output is documentation, not data — anything round-trippable must be a grammar clause. Emit `comment '…'` only when the caption differs from the derived default, matching jump/wait (issuetracker #16), so an unauthored caption does not start appearing as authored. Only an end-to-end describe → exec → describe with an AUTHORED caption catches it; fixtures without captions pass either way"}
+{"area": "mdl/executor", "date": "2026-09-15", "symptom": "`create or modify workflow` over a workflow whose multi-user task needs 3 participants / 80 percent, or waits for all users, succeeds and the task afterwards needs all participants and does not wait — no refusal, `mx check` clean", "cause": "The rebuild writes `TargetUserInput: AllUserInput` and `AwaitAllUsers: false` for every multi-user task, and the guard-don't-drop check (`checkNoDroppedWorkflowConstructs`) only inspected `CompletionCriteria`; TargetUserInput and AwaitAllUsers were neither expressible nor guarded", "file": "`mdl/executor/validate_workflow_rewrite.go` (`rawMultiUserTaskSettings`, `rawReplaceLosses`)", "insight": "When auditing a guard, list every property the rebuild writes as a constant, not just the ones that look like 'configuration' — a constant default in the writer is exactly the set a rewrite silently resets. Found by diffing Studio Pro's saved multi-user task (ako/TestApp) key by key against mxcli's writer while adding completion rules. Once a property becomes authorable, the guard changes from 'cannot express' to 'restated?' (count stored non-defaults vs authored clauses)"}
diff --git a/.claude/skills/mendix/write-workflows/SKILL.md b/.claude/skills/mendix/write-workflows/SKILL.md
index 36eb23a359..2b9f655122 100644
--- a/.claude/skills/mendix/write-workflows/SKILL.md
+++ b/.claude/skills/mendix/write-workflows/SKILL.md
@@ -329,9 +329,8 @@ documented in `system-module`.
 ## Platform rules
 
 - **Some workflow state has no MDL spelling, and a rewrite refuses rather than
-  reset it.** An event sub-process, a workflow event handler subscribed to no
-  event types, and a multi-user task's completion rule other than consensus
-  falling back to its first outcome are set in Studio Pro.
+  reset it.** An event sub-process and a workflow event handler subscribed to no
+  event types are set in Studio Pro.
   `create or modify` on a workflow that holds any of them is refused with the
   list, and so is `alter workflow … replace activity` on an activity that holds
   one. Change such a workflow with `alter workflow … set activity …` (it edits
@@ -356,6 +355,24 @@ documented in `system-module`.
   An outcome left **empty** does not stop anything — it rejoins the main flow.
   `comment '…'` sets the End's caption, as on every workflow activity.
 
+- **A multi-user task says who must respond and how their outcomes decide**,
+  in this clause order before `outcomes`:
+  `participants all | <n> | <n> percent`, then `decide by …`, then
+  `await all users`. The rules (`decide by`):
+  `consensus fallback '<outcome>'`, `majority more than half fallback '…'`,
+  `majority most chosen fallback '…'`, `threshold <n> percent|votes fallback '…'`,
+  `veto '<outcome>'`, `microflow Module.Decide`. Omitted means all participants,
+  consensus falling back to the first outcome, and not waiting. Measured on
+  mxbuild 11.13:
+  - consensus, majority and threshold **need a fallback** (`CE1866`) and a veto
+    needs its outcome (`CE1867`); `check` refuses a missing one, and a name
+    that is not one of the task's outcomes (`MDL-WF13`);
+  - the decision microflow must **return String** (`CE5012`); its parameters
+    are free;
+  - thresholds and participant counts are **not range-checked** by the build
+    (0, 101 percent, more votes than users all build), so check them yourself.
+  A rewrite that does not restate a stored rule, participant count or `await all
+  users` is refused — each omitted clause would reset it.
 - **An AI agent task is `call agent microflow`** (Mendix 11.9+) — the call
   microflow statement stored as `Workflows$AIAgentTaskActivity`, with the same
   `as`, `comment`, `with (…)`, `outcomes` and boundary events. The microflow is
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 686b5cf215..4648f0badb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,12 +8,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- **Multi-user task completion rules: `participants`, `decide by`, `await all users`** (docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md, phase 3) — how many participants must respond (`all`, a number, a percentage), how their outcomes decide the task (`consensus`, `majority more than half`, `majority most chosen`, `threshold <n> percent|votes`, each with `fallback '<outcome>'`; `veto '<outcome>'`; `microflow M`), and whether it waits for everyone. The shapes were captured from Studio Pro rather than read off gen: the examples were built in Studio Pro 11.14 over MCP, saved to ako/TestApp, and the saved document is now the reader's fixture — which is how "more than half" is known to be an Absolute majority and a percentage threshold a Relative one, and that both outcome pointers hold the outcome's `$ID`. Measured on mxbuild 11.13.0: a fallback is required for consensus, majority and threshold (CE1866) and a veto needs its outcome (CE1867), both refused by `check` as MDL-WF13 along with a name that is none of the task's outcomes; a decision microflow must return String (CE5012), its parameters are free; and the build does **not** range-check thresholds or participant counts, so neither does mxcli. Over MCP the backend works around two constructor quirks it measured: PED's default consensus has no fallback, and a more-than-half majority's fallback is dropped and has to be set by `$ID` afterwards.
+
 - **AI agent tasks in workflows: `call agent microflow`** (docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md, phase 2) — the workflow step that runs an AI agent, which `describe workflow` could only print as a `-- [Workflows$AIAgentTaskActivity]` comment and a rewrite therefore refused. It is the call-microflow statement with `agent` added — same `as`, `comment`, `with (…)`, `outcomes` and boundary events — because Mendix stores exactly the call-microflow shape under a different `$Type` (ako/TestApp, 11.14.0). The rules were measured on mxbuild 11.13.0 by writing each shape as a call microflow and switching only the `$Type`: every shape builds the same except an agent microflow with **no parameters**, which fails **CE1590**, so that is the one new check. Needs Mendix 11.9 (`workflows.ai_agent_task`); describe emits it, and a rewrite that restates it proceeds.
 
   Verified in Studio Pro 11.14 over MCP as well as mxbuild: the shapes are accepted, and Studio Pro reports the same on-created and handler signature errors, flags an agent task without parameter mappings, and refuses an invented event type at create.
 
 ### Fixed
 
+- **Multi-user tasks could not be created over MCP on Studio Pro 11.14.** Its multi-user task constructor takes the page as a `taskPage` element and refused the bare `pageReference` string mxcli sent (`"/flow/activities/1/taskPage":"Expected an object, but the value is missing."`). The backend reads the constructor schema and sends the shape the server declares, as it already did for the workflow's own constructor.
+
+- **A workflow rewrite reset every multi-user task's participant count and "wait for all users" without a word.** The rewrite guard refused a non-default completion rule, but a task needing 3 participants or 80 percent, or one waiting for all users, was rebuilt as "all participants, not waiting" and exec reported success. Both are expressible now, and a rewrite that does not restate them is refused.
+
 - **Workflows written over MCP lost their on-created microflows and event handlers, and could not be created at all on Studio Pro 11.14.** The MCP mapper hard-coded `onCreatedEvent: NoEvent` and sent no `onWorkflowEvent`, so both constructs from the previous release were dropped without a word; it now sends `MicroflowBasedEvent` and the handlers, and replaces stored handlers on a rewrite. Separately, Studio Pro 11.14's workflow constructor takes the context entity as `context` and `workflowName` as a string and rejects the older payload (`"/context":"Expected reference (string), got undefined"`), so every workflow create over MCP failed; the backend now reads the constructor schema and sends whichever shape the server declares. AI agent tasks are sent as `Workflows$AIAgentTaskActivity`.
 - **`describe workflow` turned a call microflow's caption into the microflow's name on re-execute.** The caption was printed only as a trailing `-- caption` comment, which the parser discards, so describe → exec replaced `comment 'Summarise the order'` with `ACT_Summarise`. An authored caption is now described as `comment '…'`; the derived default is not. Found by the AI agent task's end-to-end round trip.
 
diff --git a/cmd/mxcli/lsp_completions_gen.go b/cmd/mxcli/lsp_completions_gen.go
index 79a59f3ba8..a657860778 100644
--- a/cmd/mxcli/lsp_completions_gen.go
+++ b/cmd/mxcli/lsp_completions_gen.go
@@ -618,6 +618,21 @@ var mdlGeneratedKeywords = []protocol.CompletionItem{
 	{Label: "OFF", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "USERS", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "GROUPS", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "DECIDE", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "CONSENSUS", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "MAJORITY", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "MORE", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "THAN", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "HALF", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "MOST", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "CHOSEN", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "THRESHOLD", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "PERCENT", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "VOTES", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "VETO", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "FALLBACK", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "PARTICIPANTS", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "AWAIT", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "DATA", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "TRANSFORM", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "TRANSFORMER", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
diff --git a/cmd/mxcli/syntax/features_workflow.go b/cmd/mxcli/syntax/features_workflow.go
index 7ab63cd036..ece59882e3 100644
--- a/cmd/mxcli/syntax/features_workflow.go
+++ b/cmd/mxcli/syntax/features_workflow.go
@@ -157,6 +157,8 @@ func init() {
 		Keywords: []string{
 			"multi user task", "multi-user task", "several users", "multiple assignees",
 			"assessors", "voting", "parallel approval", "group approval",
+			"decide by", "consensus", "majority", "threshold", "veto", "fallback",
+			"participants", "await all users", "completion criteria",
 		},
 		// The grammar has accepted MULTI USER TASK since issue #8, and a team
 		// shipped one fanning out to eight assessors — but there was no topic for
@@ -170,11 +172,23 @@ func init() {
 			"  [ENTITY Module.Entity]\n" +
 			"  [DUE DATE '<expression>']\n" +
 			"  [DESCRIPTION '<text>']\n" +
+			"  [PARTICIPANTS ALL | <n> | <n> PERCENT]\n" +
+			"  [DECIDE BY <rule>]\n" +
+			"  [AWAIT ALL USERS]\n" +
 			"  OUTCOMES '<outcome1>' { <activities> } '<outcome2>' { <activities> };\n\n" +
-			"-- Same clauses, task-page rule and targeting rule as USER TASK.\n" +
-			"-- MDL has no clause for a multi-user task's completion settings (how the\n" +
-			"-- individual answers decide the outcome); set those in Studio Pro.",
-		Example: "MULTI USER TASK ExpertAssessment 'Expert assessment'\n  PAGE MOC.AssessmentPage\n  TARGETING MICROFLOW MOC.GetAssessors\n  OUTCOMES 'Approve' { } 'Reject' { };",
+			"-- Rules:\n" +
+			"--   DECIDE BY CONSENSUS FALLBACK '<outcome>'\n" +
+			"--   DECIDE BY MAJORITY MORE THAN HALF FALLBACK '<outcome>'\n" +
+			"--   DECIDE BY MAJORITY MOST CHOSEN FALLBACK '<outcome>'\n" +
+			"--   DECIDE BY THRESHOLD <n> PERCENT | <n> VOTES FALLBACK '<outcome>'\n" +
+			"--   DECIDE BY VETO '<outcome>'\n" +
+			"--   DECIDE BY MICROFLOW Module.Decide      -- returns String (else CE5012)\n" +
+			"-- The fallback is required for consensus, majority and threshold (CE1866); a\n" +
+			"-- veto needs its outcome (CE1867); both must name one of the task's outcomes\n" +
+			"-- (MDL-WF13). Omitted: all participants, consensus on the first outcome, not\n" +
+			"-- waiting. The build does not range-check thresholds or participant counts.\n" +
+			"-- Same page and targeting rules as USER TASK.",
+		Example: "MULTI USER TASK ExpertAssessment 'Expert assessment'\n  PAGE MOC.AssessmentPage\n  TARGETING MICROFLOW MOC.GetAssessors\n  PARTICIPANTS 80 PERCENT\n  DECIDE BY THRESHOLD 60 PERCENT FALLBACK 'Reject'\n  AWAIT ALL USERS\n  OUTCOMES 'Approve' { } 'Reject' { };",
 		SeeAlso: []string{"workflow.user-task", "workflow.user-task.targeting"},
 	})
 
diff --git a/docs-site/src/language/workflow-activities.md b/docs-site/src/language/workflow-activities.md
index d57006dbf1..29556f2b1c 100644
--- a/docs-site/src/language/workflow-activities.md
+++ b/docs-site/src/language/workflow-activities.md
@@ -38,6 +38,46 @@ USER TASK ReviewTask 'Review the request'
   };
 ```
 
+## Multi-User Task
+
+A multi-user task gives the same task to several users and combines their
+outcomes into one. Three clauses, before `OUTCOMES`, say how:
+
+```sql
+MULTI USER TASK <name> '<caption>'
+  PAGE <Module>.<Page>
+  [PARTICIPANTS ALL | <n> | <n> PERCENT]
+  [DECIDE BY <rule>]
+  [AWAIT ALL USERS]
+  OUTCOMES '<outcome>' { <activities> } ...;
+```
+
+| Rule | Completes when | Needs |
+|------|----------------|-------|
+| `CONSENSUS` | everyone chose the same outcome | `FALLBACK '<outcome>'` |
+| `MAJORITY MORE THAN HALF` | more than half chose one outcome | `FALLBACK '<outcome>'` |
+| `MAJORITY MOST CHOSEN` | one outcome was chosen most | `FALLBACK '<outcome>'` |
+| `THRESHOLD <n> PERCENT` / `<n> VOTES` | an outcome reaches the threshold | `FALLBACK '<outcome>'` |
+| `VETO '<outcome>'` | anyone chooses the veto outcome | — |
+| `MICROFLOW <Module>.<Name>` | the microflow returns the outcome (String) | — |
+
+Example:
+
+```sql
+MULTI USER TASK Vote 'Vote on the request'
+  PAGE HR.VotePage
+  PARTICIPANTS 80 PERCENT
+  DECIDE BY THRESHOLD 60 PERCENT FALLBACK 'Reject'
+  AWAIT ALL USERS
+  OUTCOMES 'Approve' { } 'Reject' { };
+```
+
+Omitted, the task needs all participants, decides by consensus falling back to
+its first outcome, and does not wait for everyone. The fallback is required for
+consensus, majority and threshold, and the build does not check threshold or
+participant numbers against each other — `THRESHOLD 5 VOTES` with three users
+builds and never completes.
+
 ## Call Microflow
 
 Execute a microflow as part of the workflow. Optionally specify a comment and outcomes:
diff --git a/docs/01-project/MDL_QUICK_REFERENCE.md b/docs/01-project/MDL_QUICK_REFERENCE.md
index 1cd8fc2b2c..577f0457b9 100644
--- a/docs/01-project/MDL_QUICK_REFERENCE.md
+++ b/docs/01-project/MDL_QUICK_REFERENCE.md
@@ -663,7 +663,8 @@ Nested folders use `/` separator: `'Parent/Child/Grandchild'`. Missing folders a
 | Drop workflow | `drop workflow Module.Name;` | |
 
 **Workflow Activity Types:**
-- `[multi] user task <name> '<caption>' [page Mod.Page] [targeting [users|groups] microflow Mod.MF] [targeting [users|groups] xpath '<expr>'] [on created microflow Mod.MF] [outcomes '<out>' { } ...];`
+- `[multi] user task <name> '<caption>' [page Mod.Page] [targeting [users|groups] microflow Mod.MF] [targeting [users|groups] xpath '<expr>'] [on created microflow Mod.MF] [participants all|<n>|<n> percent] [decide by <rule>] [await all users] [outcomes '<out>' { } ...];`
+  - **Multi-user only:** `decide by consensus|majority more than half|majority most chosen|threshold <n> percent|votes fallback '<outcome>'`, `decide by veto '<outcome>'`, `decide by microflow Mod.MF`. A fallback is required for consensus, majority and threshold (CE1866), a veto needs its outcome (CE1867), and a decision microflow returns String (CE5012) — all `MDL-WF13` / check. Omitted: all participants, consensus on the first outcome, not waiting.
   - The **task page** must take a `System.WorkflowUserTask` parameter — none at all is CE7410, none of that type is CE7412; extra parameters are allowed.
   - A **targeting microflow** takes exactly `System.Workflow` + the context entity (or a generalization of it), in either order — anything else is CE6677. Users targeting returns a list of `System.User`, groups a list of `System.WorkflowGroup`.
   - An **on-created microflow** takes exactly `System.WorkflowUserTask` + the context entity, in either order (CE6683), and returns nothing (CE5012).
diff --git a/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md b/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
index c013dccd7f..308253cbd3 100644
--- a/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
+++ b/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
@@ -1,6 +1,6 @@
 # Proposal: Workflow constructs only Studio Pro could author
 
-**Status:** Phases 1 and 2 implemented; phases 3–4 designed, awaiting reference documents
+**Status:** Phases 1–3 implemented; phase 4 designed, reference documents captured
 **Date:** 2026-09-14
 
 ## Problem Statement
@@ -208,15 +208,77 @@ hold it, carries the flag through (same shape, agent `$Type`) rather than silent
 turning an agent task into a call microflow. The MCP backend sends it as
 `Workflows$AIAgentTaskActivity`, verified against Studio Pro 11.14.
 
-## Phase 3 — completion rules
+## Phase 3 — completion rules (implemented)
 
-gen carries `ConsensusCompletionCriteria` (FallbackOutcomePointer),
-`MajorityCompletionCriteria` (CompletionType Absolute|Relative,
-FallbackOutcomePointer), `ThresholdCompletionCriteria` (+ Threshold),
-`VetoCompletionCriteria` (VetoOutcomePointer) and `MicroflowCompletionCriteria`
-(Microflow). **Needed before syntax is designed:** a Studio Pro workflow with one
-multi-user task per rule, including both completion types for majority and
-threshold — pointer semantics and defaults cannot be read off gen.
+```sql
+multi user task Vote 'Vote on the request'
+  page HR.VotePage
+  participants 80 percent
+  decide by threshold 60 percent fallback 'Reject'
+  await all users
+  outcomes 'Approve' { } 'Reject' { };
+```
+
+`decide by consensus|majority more than half|majority most chosen|threshold <n>
+percent|votes [fallback '<outcome>']`, `decide by veto '<outcome>'`, `decide by
+microflow M`; `participants all|<n>|<n> percent`; `await all users`. Each clause
+omitted is what a rebuild has always written — all participants, consensus falling
+back to the first outcome, not waiting — so existing describe output is unchanged.
+
+### Reference documents
+
+The examples were built in Studio Pro 11.14 over MCP, checked clean, saved and
+committed to ako/TestApp (`workflow.ZzMxcliExample_Completion2`, now the reader
+fixture `mdl/backend/modelsdk/testdata/TestApp.ZzMxcliExample_Completion2.bson`).
+Stored:
+
+| MDL | CompletionCriteria | TargetUserInput |
+|-----|--------------------|-----------------|
+| `consensus fallback 'Fast'` | `ConsensusCompletionCriteria{FallbackOutcomePointer}` | |
+| `majority more than half fallback 'Fast'` | `MajorityCompletionCriteria{CompletionType: Absolute, FallbackOutcomePointer}` | |
+| `majority most chosen fallback 'Fast'` | `…{CompletionType: Relative, …}` | |
+| `threshold 60 percent fallback 'Fiurious'` | `ThresholdCompletionCriteria{CompletionType: Relative, FallbackOutcomePointer, Threshold: 60}` | |
+| `threshold 2 votes …` | `…{CompletionType: Absolute, …, Threshold: 2}` | |
+| `veto 'Fiurious'` | `VetoCompletionCriteria{VetoOutcomePointer}` | |
+| `microflow M` | `MicroflowCompletionCriteria{Microflow: "M"}` | |
+| `participants 80 percent` / `participants 3` / omitted | | `PercentageAmountUserInput{Percentage}` / `AbsoluteAmountUserInput{Amount}` / `AllUserInput` |
+
+Both pointers hold the **`$ID` of one of the task's own outcomes** (not its
+`PersistentId`); `AwaitAllUsers` is a bool on the task.
+
+### Measured (mxbuild 11.13.0, one task per shape)
+
+| Shape | Verdict |
+|-------|---------|
+| consensus / majority (both) / threshold without fallback | CE1866 |
+| veto without veto outcome | CE1867 |
+| microflow rule without microflow | CE0113 |
+| decision microflow returning Boolean | CE5012 |
+| decision microflow with no, context or WorkflowUserTask parameters | 0 errors |
+| threshold 0 or 101 percent, 0 or 5 votes; participants 0 or 150 percent, 0 | 0 errors |
+
+`check` refuses the first two rows and an outcome name that matches none
+(MDL-WF13, no project), and CE5012 when the script declares the microflow's return
+type. The numbers are not range-checked: the build accepts them, so a refusal
+would be a guess.
+
+### Guard
+
+A rewrite writes what the statement says, so each omitted clause resets a stored
+value. Refused when the statement declares fewer non-default rules, non-`all`
+participant counts or `await all users` than are stored — the last two were not
+guarded before this and a rewrite reset them silently. `replace activity` is
+refused when the replacement does not restate them.
+
+### MCP
+
+The multi-user task constructor takes `completionCriteria`, `majorityType`
+(MoreThanHalf|MostChosen), `thresholdType` (Percentage|AbsoluteNumber),
+`thresholdValue`, `fallbackOutcome` / `vetoOutcome` (outcome names),
+`participiantInput` (sic) / `participiantValue` and `awaitAllUsers`. Two quirks,
+both measured: PED's default is consensus with **no** fallback (CE1866), so mxcli
+always sends one; and the constructor **drops the fallback of a more-than-half
+majority**, so the backend reads the outcome's `$ID` afterwards and sets it.
 
 ## Phase 4 — event sub-processes and notify targets
 
diff --git a/mdl-examples/doctype-tests/24-workflow-examples.mdl b/mdl-examples/doctype-tests/24-workflow-examples.mdl
index 00ce6ab1b3..8a54c53a50 100644
--- a/mdl-examples/doctype-tests/24-workflow-examples.mdl
+++ b/mdl-examples/doctype-tests/24-workflow-examples.mdl
@@ -662,3 +662,65 @@ begin
       false -> { };
 end workflow;
 /
+
+-- @version: any
+-- ############################################################################
+-- PART H: MULTI-USER TASK COMPLETION — participants, decide by, await all users
+-- ############################################################################
+--
+-- A fallback is required for consensus, majority and threshold (CE1866), a veto
+-- needs its outcome (CE1867), and a decision microflow returns String (CE5012).
+-- Omitted clauses mean all participants, consensus on the first outcome, and not
+-- waiting for everyone.
+
+create microflow WFTest.ACT_DecideOrder (
+  $OrderContext: WFTest.OrderContext
+)
+returns string as $Outcome
+begin
+  return 'Approve';
+end;
+/
+
+create workflow WFTest.CompletionRules
+  parameter $OrderContext: WFTest.OrderContext
+begin
+  multi user task ConsensusVote 'Consensus'
+    page WFTest.TaskPage
+    decide by consensus fallback 'Reject'
+    outcomes 'Approve' { } 'Reject' { };
+
+  multi user task MajorityVote 'Majority'
+    page WFTest.TaskPage
+    decide by majority more than half fallback 'Approve'
+    outcomes 'Approve' { } 'Reject' { };
+
+  multi user task MostChosenVote 'Most chosen'
+    page WFTest.TaskPage
+    decide by majority most chosen fallback 'Reject'
+    outcomes 'Approve' { } 'Reject' { };
+
+  multi user task ThresholdVote 'Threshold'
+    page WFTest.TaskPage
+    participants 80 percent
+    decide by threshold 60 percent fallback 'Reject'
+    outcomes 'Approve' { } 'Reject' { };
+
+  multi user task VotesVote 'Votes'
+    page WFTest.TaskPage
+    participants 3
+    decide by threshold 2 votes fallback 'Reject'
+    await all users
+    outcomes 'Approve' { } 'Reject' { };
+
+  multi user task VetoVote 'Veto'
+    page WFTest.TaskPage
+    decide by veto 'Reject'
+    outcomes 'Approve' { } 'Reject' { };
+
+  multi user task MicroflowVote 'Microflow'
+    page WFTest.TaskPage
+    decide by microflow WFTest.ACT_DecideOrder
+    outcomes 'Approve' { } 'Reject' { };
+end workflow;
+/
diff --git a/mdl/ast/ast_workflow.go b/mdl/ast/ast_workflow.go
index 320d8bfed7..8508fe1c86 100644
--- a/mdl/ast/ast_workflow.go
+++ b/mdl/ast/ast_workflow.go
@@ -66,6 +66,29 @@ type WorkflowUserTaskNode struct {
 	IsMultiUser     bool                        // Issue #8: true if MULTI USER TASK
 	BoundaryEvents  []WorkflowBoundaryEventNode // Issue #7
 	TaskDescription string                      // from DESCRIPTION 'text'
+
+	// Multi-user task only.
+	Participants  *WorkflowParticipantsNode   // `participants …`; nil = all
+	Completion    *WorkflowCompletionRuleNode // `decide by …`; nil = consensus on the first outcome
+	AwaitAllUsers bool                        // `await all users`
+}
+
+// WorkflowParticipantsNode is `participants all | N | N percent`.
+type WorkflowParticipantsNode struct {
+	Kind  string // "all", "number" or "percent"
+	Value int
+}
+
+// WorkflowCompletionRuleNode is `decide by …` on a multi-user task.
+type WorkflowCompletionRuleNode struct {
+	Rule          string // "consensus", "majority", "threshold", "veto" or "microflow"
+	Majority      string // "more than half" or "most chosen"
+	Threshold     int
+	ThresholdUnit string // "percent" or "votes"
+	Fallback      string // outcome named by `fallback '…'`; "" when absent
+	HasFallback   bool
+	Veto          string // outcome named by `veto '…'`
+	Microflow     QualifiedName
 }
 
 func (n *WorkflowUserTaskNode) workflowActivityNode() {}
diff --git a/mdl/backend/mcp/backend.go b/mdl/backend/mcp/backend.go
index 5d1f024e9d..f100613947 100644
--- a/mdl/backend/mcp/backend.go
+++ b/mdl/backend/mcp/backend.go
@@ -70,6 +70,11 @@ type Backend struct {
 	// workflowConstructorTakesContext.
 	workflowCtorContext *bool
 
+	// multiTaskPageCtor caches whether the server's MultiUserTaskActivity
+	// constructor takes the page as a `taskPage` element (Studio Pro 11.14)
+	// rather than a bare `pageReference`; nil until probed.
+	multiTaskPageCtor *bool
+
 	// capsCache memoizes the session's resolved capability set. Every authoring
 	// gate consults it and resolution costs a tools/list round-trip, so it is
 	// computed once per connection.
diff --git a/mdl/backend/mcp/workflow.go b/mdl/backend/mcp/workflow.go
index fdeb2c623c..fc24913e65 100644
--- a/mdl/backend/mcp/workflow.go
+++ b/mdl/backend/mcp/workflow.go
@@ -29,12 +29,18 @@ func (b *Backend) CreateWorkflow(wf *workflows.Workflow) error {
 	if err != nil {
 		return err
 	}
+	if b.multiUserTaskConstructorTakesTaskPage() {
+		adaptMultiUserTaskPages(content)
+	}
 	if err := b.ensureSchema(workflowDocType); err != nil {
 		return err
 	}
 	if err := b.pedCreateDocument(moduleName, workflowDocType, wf.Name, content, folderPath); err != nil {
 		return err
 	}
+	if err := b.applyMoreThanHalfFallbacks(moduleName+"."+wf.Name, wf); err != nil {
+		return err
+	}
 	if contextShape {
 		// The context-shaped constructor has no documentation or description;
 		// both are leaves of the created element.
@@ -81,6 +87,9 @@ func (b *Backend) UpdateWorkflow(wf *workflows.Workflow) error {
 	// Start/End (it refuses to remove them) and auto-positions an index-less add by
 	// activity type, so we strip the executor's leading Start / trailing End and
 	// let PED place the new middles between the existing ones.
+	if b.multiUserTaskConstructorTakesTaskPage() {
+		adaptMultiUserTaskPages(flowVal)
+	}
 	middles := stripStartEnd(flowVal["activities"].([]any))
 
 	n, err := b.workflowActivityCount(qn)
@@ -136,6 +145,9 @@ func (b *Backend) UpdateWorkflow(wf *workflows.Workflow) error {
 	if err := b.pedUpdateDoc(workflowDocType, qn, ops...); err != nil {
 		return err
 	}
+	if err := b.applyMoreThanHalfFallbacks(qn, wf); err != nil {
+		return err
+	}
 	b.markDirty(mod.Name)
 	b.upsertSessionWorkflow(wf)
 	return b.pedCheckDocument(workflowDocType, qn)
@@ -275,6 +287,55 @@ func (b *Backend) workflowConstructorTakesContext() bool {
 	return takes
 }
 
+// multiUserTaskConstructorTakesTaskPage reports whether the connected server's
+// Workflows$MultiUserTaskActivity constructor takes the page as a `taskPage`
+// element. Studio Pro 11.14 does, and rejects the bare `pageReference` string the
+// mapper sends for older servers — measured live:
+// `"/flow/activities/1/taskPage":"Expected an object, but the value is missing."`,
+// so no multi-user task could be created over MCP. Read off the live constructor
+// schema, like workflowConstructorTakesContext; the probe doubles as the schema
+// fetch PED asks for before a create.
+func (b *Backend) multiUserTaskConstructorTakesTaskPage() bool {
+	if b.multiTaskPageCtor != nil {
+		return *b.multiTaskPageCtor
+	}
+	const multiTaskType = "Workflows$MultiUserTaskActivity"
+	takes := false
+	if b.client != nil {
+		res, err := b.client.CallTool("ped_get_schema", map[string]any{"elementTypes": []string{multiTaskType}})
+		if err == nil && res != nil && !res.IsError {
+			takes = strings.Contains(res.Text, "taskPage: Element<'Workflows$PageReference'>")
+			if b.schemaFetched == nil {
+				b.schemaFetched = map[string]bool{}
+			}
+			b.schemaFetched[multiTaskType] = true
+		}
+	}
+	b.multiTaskPageCtor = &takes
+	return takes
+}
+
+// adaptMultiUserTaskPages rewrites, at any depth, each mapped multi-user task's
+// bare `pageReference` into the `taskPage` element the 11.14 constructor takes.
+func adaptMultiUserTaskPages(v any) {
+	switch t := v.(type) {
+	case map[string]any:
+		if t["$Type"] == "Workflows$MultiUserTaskActivity" {
+			if page, ok := t["pageReference"].(string); ok {
+				delete(t, "pageReference")
+				t["taskPage"] = map[string]any{"$Type": "Workflows$PageReference", "page": page}
+			}
+		}
+		for _, c := range t {
+			adaptMultiUserTaskPages(c)
+		}
+	case []any:
+		for _, c := range t {
+			adaptMultiUserTaskPages(c)
+		}
+	}
+}
+
 // mapWorkflow maps the executor's Workflow onto the PED Workflows$Workflow content
 // in the parameter-element shape.
 func (b *Backend) mapWorkflow(wf *workflows.Workflow) (map[string]any, error) {
@@ -517,6 +578,7 @@ func mapWorkflowActivity(a workflows.WorkflowActivity) (map[string]any, error) {
 				"onCreatedEvent":    mapOnCreatedEvent(act.OnCreated),
 				"outcomes":          vals,
 			}
+			mapMultiUserTaskCompletion(m, act, vals)
 		} else {
 			outcomes, err := mapUserTaskOutcomes(act.Outcomes)
 			if err != nil {
@@ -545,6 +607,150 @@ func mapWorkflowActivity(a workflows.WorkflowActivity) (map[string]any, error) {
 	}
 }
 
+// mapMultiUserTaskCompletion sets a multi-user task constructor's participant and
+// completion fields (ped_get_schema, Studio Pro 11.14). The constructor names
+// outcomes by value. With no rule it sends consensus falling back to the first
+// outcome — what the file engine writes — because PED's own default is consensus
+// with no fallback, which is CE1866.
+func mapMultiUserTaskCompletion(m map[string]any, act *workflows.UserTask, outcomes []any) {
+	if t := act.TargetUserInput; t != nil {
+		switch t.Kind {
+		case "Absolute":
+			m["participiantInput"] = "AbsoluteNumber"
+			m["participiantValue"] = t.Amount
+		case "Percentage":
+			m["participiantInput"] = "Percentage"
+			m["participiantValue"] = t.Percentage
+		}
+	}
+	if act.AwaitAllUsers {
+		m["awaitAllUsers"] = true
+	}
+	cc := act.CompletionCriteria
+	if cc == nil {
+		m["completionCriteria"] = "Consensus"
+		if len(outcomes) > 0 {
+			m["fallbackOutcome"] = outcomes[0]
+		}
+		return
+	}
+	setFallback := func() {
+		if cc.FallbackOutcome != "" {
+			m["fallbackOutcome"] = cc.FallbackOutcome
+		}
+	}
+	switch cc.Kind {
+	case "Majority":
+		m["completionCriteria"] = "Majority"
+		m["majorityType"] = "MostChosen"
+		if cc.CompletionType == "Absolute" {
+			m["majorityType"] = "MoreThanHalf"
+		}
+		setFallback()
+	case "Threshold":
+		m["completionCriteria"] = "Threshold"
+		m["thresholdType"] = "AbsoluteNumber"
+		if cc.CompletionType == "Relative" {
+			m["thresholdType"] = "Percentage"
+		}
+		m["thresholdValue"] = cc.Threshold
+		setFallback()
+	case "Veto":
+		m["completionCriteria"] = "Veto"
+		m["vetoOutcome"] = cc.VetoOutcome
+	case "Microflow":
+		m["completionCriteria"] = "Microflow"
+		m["microflow"] = cc.Microflow
+	default:
+		m["completionCriteria"] = "Consensus"
+		setFallback()
+	}
+}
+
+// moreThanHalfFallbacks lists, by JSON path, every multi-user task in a flow that
+// decides by majority-more-than-half with a fallback, and that fallback's outcome
+// index. PED's constructor drops `fallbackOutcome` for MoreThanHalf (measured,
+// Studio Pro 11.14: stored null, then "Fallback outcome cannot be empty"), so it
+// is set afterwards by the outcome's $ID.
+func moreThanHalfFallbacks(flow *workflows.Flow, base string) map[string]int {
+	out := map[string]int{}
+	if flow == nil {
+		return out
+	}
+	for i, a := range flow.Activities {
+		path := fmt.Sprintf("%s/%d", base, i)
+		sub := func(f *workflows.Flow, p string) {
+			for k, v := range moreThanHalfFallbacks(f, p) {
+				out[k] = v
+			}
+		}
+		switch t := a.(type) {
+		case *workflows.UserTask:
+			if cc := t.CompletionCriteria; t.IsMulti && cc != nil && cc.Kind == "Majority" && cc.CompletionType == "Absolute" && cc.FallbackOutcome != "" {
+				for j, o := range t.Outcomes {
+					if o.Value == cc.FallbackOutcome || (o.Value == "" && o.Caption == cc.FallbackOutcome) {
+						out[path] = j
+					}
+				}
+			}
+			for j, o := range t.Outcomes {
+				sub(o.Flow, fmt.Sprintf("%s/outcomes/%d/flow/activities", path, j))
+			}
+			for j, be := range t.BoundaryEvents {
+				sub(be.Flow, fmt.Sprintf("%s/boundaryEvents/%d/flow/activities", path, j))
+			}
+		case *workflows.CallMicroflowTask:
+			for j, o := range t.Outcomes {
+				sub(o.GetFlow(), fmt.Sprintf("%s/outcomes/%d/flow/activities", path, j))
+			}
+			for j, be := range t.BoundaryEvents {
+				sub(be.Flow, fmt.Sprintf("%s/boundaryEvents/%d/flow/activities", path, j))
+			}
+		case *workflows.ExclusiveSplitActivity:
+			for j, o := range t.Outcomes {
+				sub(o.GetFlow(), fmt.Sprintf("%s/outcomes/%d/flow/activities", path, j))
+			}
+		case *workflows.ParallelSplitActivity:
+			for j, o := range t.Outcomes {
+				if o != nil {
+					sub(o.Flow, fmt.Sprintf("%s/outcomes/%d/flow/activities", path, j))
+				}
+			}
+		}
+	}
+	return out
+}
+
+// applyMoreThanHalfFallbacks sets each majority-more-than-half fallback the
+// constructor dropped, reading the outcome's $ID and pointing at it.
+func (b *Backend) applyMoreThanHalfFallbacks(qn string, wf *workflows.Workflow) error {
+	for path, idx := range moreThanHalfFallbacks(wf.Flow, "/flow/activities") {
+		idPath := fmt.Sprintf("%s/outcomes/%d/$ID", path, idx)
+		res, err := b.client.CallTool("ped_read_document", map[string]any{
+			"documentType": workflowDocType,
+			"documentName": qn,
+			"paths":        []string{idPath},
+		})
+		if err != nil {
+			return err
+		}
+		text := pedStripReminder(res.Text)
+		var doc struct {
+			Results []struct {
+				Result string `json:"result"`
+			} `json:"results"`
+		}
+		if res.IsError || json.Unmarshal([]byte(text), &doc) != nil || len(doc.Results) == 0 || doc.Results[0].Result == "" {
+			return fmt.Errorf("read outcome id at %s of %s: %s", idPath, qn, text)
+		}
+		op := pedOpEntry{Path: path + "/completionCriteria/fallbackOutcome", Operation: pedOperation{Type: "set", Value: doc.Results[0].Result}}
+		if err := b.pedUpdateDoc(workflowDocType, qn, op); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
 // mapOnCreatedEvent maps a user task's on-created microflow onto its PED element:
 // Workflows$MicroflowBasedEvent when one is set, Workflows$NoEvent otherwise. This
 // was hard-coded to NoEvent, so an on-created microflow written over MCP was
diff --git a/mdl/backend/mcp/workflow_completion_test.go b/mdl/backend/mcp/workflow_completion_test.go
new file mode 100644
index 0000000000..d1d3f3288f
--- /dev/null
+++ b/mdl/backend/mcp/workflow_completion_test.go
@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package mcp
+
+import (
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// The constructor fields are Studio Pro 11.14's (ped_get_schema) and the
+// mapping is what it stored for ako/TestApp's ZzMxcliExample_Completion2.
+func TestMapMultiUserTaskCompletion(t *testing.T) {
+	outcomes := []any{"Approve", "Reject"}
+	cases := []struct {
+		name string
+		task workflows.UserTask
+		want map[string]any
+	}{
+		{"no rule sends consensus on the first outcome", workflows.UserTask{},
+			map[string]any{"completionCriteria": "Consensus", "fallbackOutcome": "Approve"}},
+		{"majority more than half", workflows.UserTask{CompletionCriteria: &workflows.CompletionCriteria{Kind: "Majority", CompletionType: "Absolute", FallbackOutcome: "Reject"}},
+			map[string]any{"completionCriteria": "Majority", "majorityType": "MoreThanHalf", "fallbackOutcome": "Reject"}},
+		{"majority most chosen", workflows.UserTask{CompletionCriteria: &workflows.CompletionCriteria{Kind: "Majority", CompletionType: "Relative", FallbackOutcome: "Approve"}},
+			map[string]any{"completionCriteria": "Majority", "majorityType": "MostChosen", "fallbackOutcome": "Approve"}},
+		{"threshold percent with percentage participants", workflows.UserTask{
+			CompletionCriteria: &workflows.CompletionCriteria{Kind: "Threshold", CompletionType: "Relative", Threshold: 60, FallbackOutcome: "Reject"},
+			TargetUserInput:    &workflows.TargetUserInput{Kind: "Percentage", Percentage: 80}},
+			map[string]any{"completionCriteria": "Threshold", "thresholdType": "Percentage", "thresholdValue": 60, "fallbackOutcome": "Reject", "participiantInput": "Percentage", "participiantValue": 80}},
+		{"threshold votes with a participant count", workflows.UserTask{
+			CompletionCriteria: &workflows.CompletionCriteria{Kind: "Threshold", CompletionType: "Absolute", Threshold: 2, FallbackOutcome: "Reject"},
+			TargetUserInput:    &workflows.TargetUserInput{Kind: "Absolute", Amount: 3}},
+			map[string]any{"completionCriteria": "Threshold", "thresholdType": "AbsoluteNumber", "thresholdValue": 2, "fallbackOutcome": "Reject", "participiantInput": "AbsoluteNumber", "participiantValue": 3}},
+		{"veto waiting for all users", workflows.UserTask{CompletionCriteria: &workflows.CompletionCriteria{Kind: "Veto", VetoOutcome: "Reject"}, AwaitAllUsers: true},
+			map[string]any{"completionCriteria": "Veto", "vetoOutcome": "Reject", "awaitAllUsers": true}},
+		{"microflow", workflows.UserTask{CompletionCriteria: &workflows.CompletionCriteria{Kind: "Microflow", Microflow: "M.Decide"}},
+			map[string]any{"completionCriteria": "Microflow", "microflow": "M.Decide"}},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			m := map[string]any{"participiantInput": "AllTargetUsers"}
+			task := c.task
+			mapMultiUserTaskCompletion(m, &task, outcomes)
+			if _, ok := c.want["participiantInput"]; !ok {
+				c.want["participiantInput"] = "AllTargetUsers"
+			}
+			if !reflect.DeepEqual(m, c.want) {
+				t.Errorf("mapped %v\nwant   %v", m, c.want)
+			}
+		})
+	}
+}
+
+func majorityHalfTask(name, fallback string) *workflows.UserTask {
+	task := &workflows.UserTask{
+		IsMulti:            true,
+		Outcomes:           []*workflows.UserTaskOutcome{{Value: "Approve"}, {Value: "Reject"}},
+		CompletionCriteria: &workflows.CompletionCriteria{Kind: "Majority", CompletionType: "Absolute", FallbackOutcome: fallback},
+	}
+	task.Name = name
+	return task
+}
+
+// PED's constructor drops the fallback of a more-than-half majority (measured,
+// Studio Pro 11.14), so every such task — at any depth — is located by JSON path
+// with the index of its fallback outcome.
+func TestMoreThanHalfFallbackPaths(t *testing.T) {
+	nested := majorityHalfTask("inner", "Approve")
+	call := &workflows.CallMicroflowTask{Microflow: "M.Do", Outcomes: []workflows.ConditionOutcome{
+		&workflows.BooleanConditionOutcome{Value: true, Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{nested}}},
+		&workflows.BooleanConditionOutcome{Value: false, Flow: &workflows.Flow{}},
+	}}
+	mostChosen := majorityHalfTask("most", "Reject")
+	mostChosen.CompletionCriteria.CompletionType = "Relative"
+	flow := &workflows.Flow{Activities: []workflows.WorkflowActivity{
+		&workflows.StartWorkflowActivity{},
+		majorityHalfTask("top", "Reject"),
+		call,
+		mostChosen,
+	}}
+	got := moreThanHalfFallbacks(flow, "/flow/activities")
+	want := map[string]int{
+		"/flow/activities/1":                              1,
+		"/flow/activities/2/outcomes/0/flow/activities/0": 0,
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("paths = %v, want %v", got, want)
+	}
+}
+
+// After a create, the fallback is read back as the outcome's $ID and set.
+func TestApplyMoreThanHalfFallbacks(t *testing.T) {
+	f := newFakePED(t, func(name string, args map[string]any) (string, bool) {
+		if name == "ped_read_document" {
+			paths, _ := args["paths"].([]any)
+			if len(paths) == 1 && paths[0] == "/flow/activities/1/outcomes/1/$ID" {
+				return `{"results":[{"path":"/flow/activities/1/outcomes/1/$ID","result":"4d2c6f1e-0000-4000-8000-000000000001"}]}`, false
+			}
+			return `{"results":[{"path":"?","result":""}]}`, false
+		}
+		return "SUCCESS", false
+	})
+	b := &Backend{client: f.connectClient(t)}
+	wf := &workflows.Workflow{Name: "W", Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+		&workflows.StartWorkflowActivity{}, majorityHalfTask("top", "Reject"),
+	}}}
+	if err := b.applyMoreThanHalfFallbacks("M.W", wf); err != nil {
+		t.Fatalf("applyMoreThanHalfFallbacks: %v", err)
+	}
+	call, ok := f.callByName("ped_update_document")
+	if !ok {
+		t.Fatal("no ped_update_document sent")
+	}
+	raw, _ := json.Marshal(call.Args["operations"])
+	for _, want := range []string{`"path":"/flow/activities/1/completionCriteria/fallbackOutcome"`, `"value":"4d2c6f1e-0000-4000-8000-000000000001"`} {
+		if !strings.Contains(string(raw), want) {
+			t.Errorf("update lacks %s: %s", want, raw)
+		}
+	}
+}
diff --git a/mdl/backend/mcp/workflow_multitask_page_test.go b/mdl/backend/mcp/workflow_multitask_page_test.go
new file mode 100644
index 0000000000..d11f31e9ac
--- /dev/null
+++ b/mdl/backend/mcp/workflow_multitask_page_test.go
@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package mcp
+
+import (
+	"reflect"
+	"testing"
+)
+
+// Studio Pro 11.14's multi-user task constructor takes the page as a `taskPage`
+// element and rejects a bare `pageReference` (measured live). The shape is read
+// off the live constructor schema, once.
+func TestMultiUserTaskConstructorPageProbe(t *testing.T) {
+	calls := 0
+	f := newFakePED(t, func(name string, _ map[string]any) (string, bool) {
+		if name == "ped_get_schema" {
+			calls++
+			return `{"kind":"constructor","schema":"constructor type 'Workflows$MultiUserTaskActivity' = {\n name: string;\n outcomes: string[];\n taskPage: Element<'Workflows$PageReference'>;\n}"}`, false
+		}
+		return "SUCCESS", false
+	})
+	b := &Backend{client: f.connectClient(t)}
+	if !b.multiUserTaskConstructorTakesTaskPage() || !b.multiUserTaskConstructorTakesTaskPage() {
+		t.Fatal("an 11.14 constructor schema must select the taskPage shape")
+	}
+	if calls != 1 {
+		t.Errorf("ped_get_schema called %d times, want 1 (cached)", calls)
+	}
+	old := newFakePED(t, func(name string, _ map[string]any) (string, bool) {
+		return `{"schemas":[{"elementType":"Workflows$MultiUserTaskActivity","schema":{"properties":{"pageReference":{}}}}]}`, false
+	})
+	if (&Backend{client: old.connectClient(t)}).multiUserTaskConstructorTakesTaskPage() {
+		t.Error("a constructor without taskPage must keep pageReference")
+	}
+}
+
+func TestAdaptMultiUserTaskPages(t *testing.T) {
+	nested := map[string]any{"$Type": "Workflows$MultiUserTaskActivity", "name": "inner", "pageReference": "M.Inner"}
+	content := map[string]any{
+		"flow": map[string]any{"$Type": "Workflows$Flow", "activities": []any{
+			map[string]any{"$Type": "Workflows$MultiUserTaskActivity", "name": "top", "pageReference": "M.Top"},
+			map[string]any{"$Type": "Workflows$SingleUserTaskActivity", "name": "single", "taskPage": map[string]any{"$Type": "Workflows$PageReference", "page": "M.Single"}},
+			map[string]any{"$Type": "Workflows$CallMicroflowActivity", "outcomes": []any{
+				map[string]any{"$Type": "Workflows$BooleanConditionOutcome", "flow": map[string]any{"activities": []any{nested}}},
+			}},
+		}},
+	}
+	adaptMultiUserTaskPages(content)
+	top := content["flow"].(map[string]any)["activities"].([]any)[0].(map[string]any)
+	for name, m := range map[string]map[string]any{"top": top, "inner": nested} {
+		if _, ok := m["pageReference"]; ok {
+			t.Errorf("%s still sends pageReference", name)
+		}
+	}
+	if !reflect.DeepEqual(top["taskPage"], map[string]any{"$Type": "Workflows$PageReference", "page": "M.Top"}) {
+		t.Errorf("top taskPage = %v", top["taskPage"])
+	}
+	if !reflect.DeepEqual(nested["taskPage"], map[string]any{"$Type": "Workflows$PageReference", "page": "M.Inner"}) {
+		t.Errorf("nested taskPage = %v", nested["taskPage"])
+	}
+}
diff --git a/mdl/backend/modelsdk/testdata/TestApp.ZzMxcliExample_Completion2.bson b/mdl/backend/modelsdk/testdata/TestApp.ZzMxcliExample_Completion2.bson
new file mode 100644
index 0000000000000000000000000000000000000000..c02d36cd16605e51160cb8e995d4795d7a16c470
GIT binary patch
literal 11868
zcmd5?c|a5A5?@YHsaU`ktko!ZyowYM4+<&?Nk|9@r&LAMkSq`hSx7b<R#a5fDxf08
z3Mg_2DuoIPD2RwwD^{zBs8ziBiYF@8+G6p^`w}+C(k(<2ULXIEWcQny-^@3^`F3^|
z+Cz|$Et3ijhrr*y@gb{D8Ml!u(;Pbe-3LF{w+&2)h9L`Z>2pLJ874&HB({oA&=4{|
zN+9y(hQr{aNQ9tVRDg&eeJa9}M!_QNtDa1-K2-`+xhM?DzZueE!Q}vHsIM5|!4e59
zflR?o!yO=f+07=jc%D$ohxuR~Ej}6%quy{VEQAJuYYYLO4~rlJIxq#|PF6R*{&>xU
ztREfRldfEQQDO1LDa?2?uu5UF#8$q}kjz5`u>w>86psQjfMNr1mw_X63H(#J!`-qa
zD%I&Wr>1;l-ujyt5;2J+oWuZ>D@GLxFu@6Uhj?(K<(}zr1&132LmvPc#4C+_VX;IY
zL4k*u{GPCMd$p`zzJ|jp$*r5%1ywK6_lJeR*Re1gctZ&LA_5T#83Kt8uE2!>f@QGs
z8)V=FH5jRb5_S1yH!PaunQ^VkaM-UM4TPZBQXwjsD}lv<TuCG$C=;?2MaU9~AY2q6
z5QPijK(06(MrCV21j%t+0ZJAMWnU!_WJp1zB0g7~AP+n~+WHFb3;_T<5Rn8HNu(0U
zzypbj7Q!;Wd58rlEEaH~L~w^HI)`3d8M4gyDf!EBHBZBv-fYK!OaM12!XdF$3M3F`
zMCS^Hp<G_1j}+x0Q9XVH=F3xIL5}G7<TqRC8xvmF#<GGx@3n>X<xzYO=!%k}N+pni
z53m*n8=Wsl3c2Adjwn7_v-{I6-t~v_BQG1|Ibs%@<1FSNJxd`&%q$610XB|mkN$|0
z+1pM`=181OMI<qaSo-+k1U=q;#b4@9p;W%O-eJ{#pb`_*Px@eaD@z{`o4;<|IqfZ!
ziv^PzsfSaK$NXBqK|hEql)@0$kr16LK|#_v^-4Nw_UwsQw|z;gTf{7Tl~J(iodJa+
z%g<UqI!)c~HPbR~S;aBk0Giac!2kBMP4rFQ8Je6AHgLxP4VD2CNW}sK>|H`n)K1VJ
ze|w`IHP5<j*7*^3Rd12R2CCd*ilU_`M3$*gvi64Q<@TobXUIi*tr6z4C{Y;D55Y~U
zM8J}<XFUWYN+PMSgeMmCP*XTgBIIqA|5%ty-m~=9ozD273)N!47VyMKPaz0E#US$o
zVUVXXYB%)diUGBORPB}Efp9$9L;O8@<*9>LxFdMPpv;pDk8G-^kHs~Ud%9I9FHv}f
zgIj!`J3L{tk`0b7fBEX}C`_Rh&S$c9{%{y9hDAIW(wB?*2;32e)k1q5P0BAr20ghZ
z<3ivZh>G*;Cym{ET^w$?ufFz-aocHph#E{)q&Ns(1jv!8&{G_T7ql*M&CDL-v*Wn6
z<C_)L*D*OHob@>4{zn`x^B<eL6akE#K#D@dFbR#|ibxS$VHhE!@4&g|qdN_Es^ced
zwuC4B)_8eRHwJ4w9u_8^fY9|-zsb)nvZN%3N)VwGY|lQ~ep(9r?CQy*tUY6v?nak)
zuOei7SzQ2ZufWHUgX)v;bIWa#ex7lUdGu2L(N?`T`WPUs2*0<fn9R2)e8(?N{Ze#l
zHEUm^>D5_7YAi58S`z*ZR(wb@{KosMM~G1<%j)<33IBT==C^H!k8_e@Y+c<lnzp_(
zp!h#p#&5Mw<7^AM9`-6^xL7xUrUW%P&j0--JIy7DQnzb(u*QV{0Vl*EE-`?)WixHe
z+Pspfx+DA<v5d{q?p(&6j`LM9&MnaxP%Q|b^vRs8)-hD~Vhb<vo=ZrYS_}q;@K=9=
zniz+aGizY}v1IoMJKZWIAbh0rod2m2R~g?x3}o(<A0A^02bl0_<P%3sMx6D|@^JgS
zlH9#f4Q8K&?+iW05&k)+U~2QMdCa;WUKMmCet#B|L&7uTKX7Ot0W44uA|QMTO5#Nz
z;0Uh)+b191682zJgx5a74!eID&MU+)X~p)62cy2(es#M+!K1JY`q7fMwf+X@rf9<U
zY=Etw<NZ3MJ$b5knrE@uaf^wZp_4H{TCsg^QwcYaCdd0D?=5rr&DYFhjr9W~cmMKy
zOpumrf9`{Wjqy=di~~`6wyjGqX7$hZu3<J)rr7P_BwMy`rkba|erG^Vvx`G)GM#Dl
zQxjP=W+ELO?=3AKj$UXV>s_1PXxasjY1EkQXLlAg#d)r!Bn`VfsG@m)y6)J%wWYi{
zLVSu@WAk{4&~MBH%wt-x{kFuwOD^9yvC22lT(g$X^i_+&z_9(@l(v{m?@-Tm9(EbG
zOg$rYtB`>01w$6h4gA#5YyFvXDgV~@P&{c5Fx&GS>sC1@9Aa%-#(w<skM6_NVD`!O
z(;$+u`U726x66qm)t0mhpDkyjr58IeIsYGQ9~dEqB@u{_Pl|@cJXxC$^#6#uHKm|5
zs2);(Vw}DiJaVwtetP;{`tzgq7$$tTMk!l$kXJT;hz|Ff(f$6^Ob@dsRrD(M!^jmB
zqiyC&HS+!pFtc}qvZuR)o%fY@`||p$0N;Ha)jpJe$*Uk?!(7o}+jtD5Ruv%f?*8Ys
zQph9Cz0++n+2t<brqZMWY%LA7%bqiqTC^aou&Hg8jw-;U8}qxY8idROix|7`ore|2
zV{m%;y9Q71aJ)01#otVDHeC=z&!JR23uL)z*zoPIV^yDbz%kGDeR5H)Z~P+m&038s
zfFywL_iBy}XTy`G1uF!*oVBR{p}>8r+<7i)E_`7986z`2%ei6HVGiaoTX2(#S3vI#
z%SLh(=(fr`u|3@$bJZot7p#&0_0s{O1wEJ4A7j%Cvt|u*`>^SZT95{&M3m-TnGq>$
z;H1^ADa}gdQgo}3phRqL$!eb*@uhbSb<P|op9`j#!T~N39S=K#3-=#p<StK*8TGts
zsv1mHC<!`1(;+KdiLhVkj(Ww@In`52OtTheF2dxHKx|cV{)rBd>|K$PF-crS_oe>=
zu`J*fX-U#U>MECURS%)&CJd2w1wym#&!Wwy#$4NCkMv<n;G~<IzE>*{@)uIFgu%bT
zA}$a>TR)EoWy5x*?I_Lg&NPpzcXRd>U?8<B5Kp!pd^yCpf|5C{J~y%QGVzwuq(B73
z2D&&Ok&>$t{@izVR$Vz}oR*IW)9S;G7hmXf-*_o4_}7mPC{EOU6o}s8!0dSY4p+%u
zi;1&bohe19f0^f)Gk>LS0J-r`<o<E`ws)b6;E7GwuyTzHL_~Q|vEPb&w5?CS@*U@N
zzgn9Du@G!YRe>-m3D4hReTGr-VB-%?mQ=;Ta~!xy#RiI8_)B@{`9b~)RJPOmdpYn&
z=iVIC=zO0wk6w?twS8ltT6hMgG;k~{`8%hNXBK<?+}M0DAy~Hx2}%RY%WUHA*FQ0K
zz0Br3IFqv;Q#in-A=z?80sqiYM(yj7JIr10DT0XK_5`J222_UY6>)C04LNy;?^*n9
zbIUJvQ_f@7lR#uun?bjwK~JL>yt0%Jf>DI<X#u<nRNK(@ySj@8*;_DEbF9DiES%Yn
zVHk_UAd^M#pkO5Xo#>TrmUMPTeRVLqvM~Mjj~l<uCFFDypaL}cd+hA9xgX!L-Sm8I
z6sxMWaJu=M!LgW)T5<V~iG`HKWz#6D?|Y4Ath-r&$;9sgO}M<(qwdd>e)DOW&-bTY
zOrL3u3DT0wmo$zpdUi93Q+Mr3v~kO%sr|Qmdi(sH0oARm&reJ_!7LN=tadKEwnaC9
zNP&f~{R|n*oRx_2`~T^v)|ksTrL?YHdztK+Wp<nvn3{%a!{zw5xfi;kx;l@vkq_x@
zf0>`Emx%$@qTR#4kzQf$^@?70X!Ls@#xeEOVlXg-eJ!JSoYD7|9_twQEovquy6RRT
z0by5O2;yX{iD2!dWXHwij6R1c9ALsO@7iuUy1ay0++3E!o+SQU4W^1{2?%>8)Py5!
zKbQ6w_vxp-R*yPi`fBO9T1*ZJM|Qd;Y|SQeWK^cyAtXM`6Y#;r6wy&W8QiHlj@;U?
zc&gd(Y|rgu9yH%tJ~kBtgg?qF1rt!XzVad@TNI~w-@afO8;phtXz^UxY|vt=+#<zL
z3n86j6FMq+eNX5lJ2lKNT<PGG;<!y*KK6aZ8)&UK-J;GM^{S5Jl(P1^oV;0BN4QNi
z;q+?HIy;A4o_kpt<?;)9{cuc>mYn`_)X3itzWkK2tHk8v@Y}(q{d0Q#?6Kkp=f7dD
zl1zSat?c#fcLr445K|z&k>gcW^{l!j+{<4#fHMA5Gh?T5hR4327wo=oIatw=>VHDV
zTj)2U%EptO8kZE7xSn=hcbtCl&xJEiSXX$K-YXhv6TLPC1F8k5XL>fY)mqJUueynZ
zEM>KzYB5mmb&0JGCv+md-gO`07P3}#I$W$@cU65XO9u)GIK6Jk%d2@^ugN*AJ1g(&
z%{z)A9AHj&Xf_-X^x0Wj@k%|n;@^*zs`<4~PIu`w#nu(v@TV0VMo)LxyYr1(wqm$q
zG>+40BECW>;e3vAG!o4JfewUxZc2uq%@v4<))LI$T{5%^_@dQ?T5)2+nzT^+z_-}b
zN|myar(Vpf;%p}{rzldO=$TwppXD`B4u$oa-fSre`Pi=Nig#L^c{FK6cLwHYOQ1_3
zO=7EBtWOi6V5SJN2G`>h<v{)ciF4#3B2+eGrs~QlM1aXm`4ytk#H?<T5#qC(mh5!3
zCa=Yqs~;#pg)r0)S_6gXzn`8<sbq7veb>s_^VqC$Mna2%)?|lx?NVikLN^;mxnP`{
w3n{IU?~Np&K~;t6A-{APtvE!<k3CzvJ7)A%wXOWFX7uA5$V6dakP|TFzmfgQrvLx|

literal 0
HcmV?d00001

diff --git a/mdl/backend/modelsdk/workflow_completion_test.go b/mdl/backend/modelsdk/workflow_completion_test.go
new file mode 100644
index 0000000000..58e2669de6
--- /dev/null
+++ b/mdl/backend/modelsdk/workflow_completion_test.go
@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+import (
+	"fmt"
+	"os"
+	"reflect"
+	"testing"
+
+	genWf "github.com/mendixlabs/mxcli/modelsdk/gen/workflows"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// The workflow Studio Pro 11.14 saved for ako/TestApp's
+// ZzMxcliExample_Completion2: one multi-user task per completion rule, built over
+// MCP and checked clean before it was saved.
+const completionFixture = "testdata/TestApp.ZzMxcliExample_Completion2.bson"
+
+// The reader decodes every rule off the Studio Pro document, turning each outcome
+// pointer ($ID) back into the outcome's value.
+func TestReadCompletionCriteriaFromStudioProFixture(t *testing.T) {
+	raw, err := os.ReadFile(completionFixture)
+	if err != nil {
+		t.Fatal(err)
+	}
+	g := genWf.NewWorkflow()
+	g.InitFromRaw(bson.Raw(raw))
+	wf := workflowFromGen(g, "")
+
+	got := map[string]*workflows.UserTask{}
+	for _, a := range wf.Flow.Activities {
+		if ut, ok := a.(*workflows.UserTask); ok {
+			got[ut.Name] = ut
+		}
+	}
+	want := map[string]struct {
+		cc    workflows.CompletionCriteria
+		input workflows.TargetUserInput
+		await bool
+	}{
+		"mutConsensus":    {workflows.CompletionCriteria{Kind: "Consensus", FallbackOutcome: "Fast"}, workflows.TargetUserInput{Kind: "All"}, false},
+		"mutMajorityHalf": {workflows.CompletionCriteria{Kind: "Majority", CompletionType: "Absolute", FallbackOutcome: "Fast"}, workflows.TargetUserInput{Kind: "All"}, false},
+		"mutMajorityMost": {workflows.CompletionCriteria{Kind: "Majority", CompletionType: "Relative", FallbackOutcome: "Fast"}, workflows.TargetUserInput{Kind: "All"}, false},
+		"mutThresholdPct": {workflows.CompletionCriteria{Kind: "Threshold", CompletionType: "Relative", Threshold: 60, FallbackOutcome: "Fiurious"}, workflows.TargetUserInput{Kind: "Percentage", Percentage: 80}, false},
+		"mutThresholdAbs": {workflows.CompletionCriteria{Kind: "Threshold", CompletionType: "Absolute", Threshold: 2, FallbackOutcome: "Fiurious"}, workflows.TargetUserInput{Kind: "Absolute", Amount: 3}, false},
+		"mutVeto":         {workflows.CompletionCriteria{Kind: "Veto", VetoOutcome: "Fiurious"}, workflows.TargetUserInput{Kind: "All"}, true},
+		"mutMicroflow":    {workflows.CompletionCriteria{Kind: "Microflow", Microflow: "workflow.ZzMxcliExample_DecideOutcome"}, workflows.TargetUserInput{Kind: "All"}, false},
+	}
+	for name, w := range want {
+		ut := got[name]
+		if ut == nil {
+			t.Errorf("%s not read", name)
+			continue
+		}
+		if ut.CompletionCriteria == nil || *ut.CompletionCriteria != w.cc {
+			t.Errorf("%s criteria = %+v, want %+v", name, ut.CompletionCriteria, w.cc)
+		}
+		if ut.TargetUserInput == nil || *ut.TargetUserInput != w.input {
+			t.Errorf("%s participants = %+v, want %+v", name, ut.TargetUserInput, w.input)
+		}
+		if ut.AwaitAllUsers != w.await {
+			t.Errorf("%s await = %v, want %v", name, ut.AwaitAllUsers, w.await)
+		}
+	}
+}
+
+// Every rule survives a write and a fresh read, and the stored pointer is the
+// $ID of the named outcome — Studio Pro's shape, not the first outcome by default.
+func TestCreateWorkflow_CompletionCriteriaRoundTrip(t *testing.T) {
+	proj := copyFixture(t)
+	b := New()
+	if err := b.Connect(proj); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+	mod, err := b.GetModuleByName("MyFirstModule")
+	if err != nil || mod == nil {
+		t.Fatalf("GetModuleByName: %v", err)
+	}
+
+	type setting struct {
+		cc    *workflows.CompletionCriteria
+		input *workflows.TargetUserInput
+		await bool
+	}
+	settings := map[string]setting{
+		"consensus":      {&workflows.CompletionCriteria{Kind: "Consensus", FallbackOutcome: "Reject"}, nil, false},
+		"majorityHalf":   {&workflows.CompletionCriteria{Kind: "Majority", CompletionType: "Absolute", FallbackOutcome: "Reject"}, nil, false},
+		"thresholdPct":   {&workflows.CompletionCriteria{Kind: "Threshold", CompletionType: "Relative", Threshold: 60, FallbackOutcome: "Reject"}, &workflows.TargetUserInput{Kind: "Percentage", Percentage: 80}, false},
+		"thresholdVotes": {&workflows.CompletionCriteria{Kind: "Threshold", CompletionType: "Absolute", Threshold: 2, FallbackOutcome: "Approve"}, &workflows.TargetUserInput{Kind: "Absolute", Amount: 3}, true},
+		"veto":           {&workflows.CompletionCriteria{Kind: "Veto", VetoOutcome: "Reject"}, nil, true},
+		"microflow":      {&workflows.CompletionCriteria{Kind: "Microflow", Microflow: "MyFirstModule.Decide"}, nil, false},
+		"default":        {nil, nil, false},
+	}
+	acts := []workflows.WorkflowActivity{&workflows.StartWorkflowActivity{BaseWorkflowActivity: workflows.BaseWorkflowActivity{Name: "Start"}}}
+	for name, s := range settings {
+		task := &workflows.UserTask{
+			BaseWorkflowActivity: workflows.BaseWorkflowActivity{Name: name, Caption: name},
+			IsMulti:              true,
+			Outcomes:             []*workflows.UserTaskOutcome{{Value: "Approve"}, {Value: "Reject"}},
+			CompletionCriteria:   s.cc,
+			TargetUserInput:      s.input,
+			AwaitAllUsers:        s.await,
+		}
+		acts = append(acts, task)
+	}
+	acts = append(acts, &workflows.EndWorkflowActivity{BaseWorkflowActivity: workflows.BaseWorkflowActivity{Name: "End"}})
+	wf := &workflows.Workflow{ContainerID: mod.ID, Name: "ZzCompletion", Parameter: &workflows.WorkflowParameter{EntityRef: "MyFirstModule.Ctx"}, Flow: &workflows.Flow{Activities: acts}}
+	if err := b.CreateWorkflow(wf); err != nil {
+		t.Fatalf("CreateWorkflow: %v", err)
+	}
+
+	b2 := New()
+	if err := b2.Connect(proj); err != nil {
+		t.Fatalf("reconnect: %v", err)
+	}
+	t.Cleanup(func() { _ = b2.Disconnect() })
+	all, err := b2.ListWorkflows()
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got *workflows.Workflow
+	for _, w := range all {
+		if w.Name == "ZzCompletion" {
+			got = w
+		}
+	}
+	if got == nil {
+		t.Fatal("workflow not found after reconnect")
+	}
+	for _, a := range got.Flow.Activities {
+		ut, ok := a.(*workflows.UserTask)
+		if !ok {
+			continue
+		}
+		s := settings[ut.Name]
+		wantCC := s.cc
+		if wantCC == nil {
+			wantCC = &workflows.CompletionCriteria{Kind: "Consensus", FallbackOutcome: "Approve"}
+		}
+		wantInput := s.input
+		if wantInput == nil {
+			wantInput = &workflows.TargetUserInput{Kind: "All"}
+		}
+		if !reflect.DeepEqual(ut.CompletionCriteria, wantCC) || !reflect.DeepEqual(ut.TargetUserInput, wantInput) || ut.AwaitAllUsers != s.await {
+			t.Errorf("%s read back as %+v %+v %v, want %+v %+v %v", ut.Name, ut.CompletionCriteria, ut.TargetUserInput, ut.AwaitAllUsers, wantCC, wantInput, s.await)
+		}
+	}
+
+	raw, err := b2.GetRawUnit(got.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, a := range raw["Flow"].(map[string]any)["Activities"].([]any) {
+		m, ok := a.(map[string]any)
+		if !ok || m["Name"] != "majorityHalf" {
+			continue
+		}
+		outs := m["Outcomes"].([]any)
+		reject := outs[2].(map[string]any)["$ID"]
+		cc := m["CompletionCriteria"].(map[string]any)
+		if fmt.Sprint(cc["FallbackOutcomePointer"]) != fmt.Sprint(reject) || cc["CompletionType"] != "Absolute" {
+			t.Errorf("majorityHalf CompletionCriteria = %v, want an Absolute majority pointing at Reject's $ID %v", cc, reject)
+		}
+	}
+}
diff --git a/mdl/backend/modelsdk/workflow_read.go b/mdl/backend/modelsdk/workflow_read.go
index 47cc603973..2dcd338413 100644
--- a/mdl/backend/modelsdk/workflow_read.go
+++ b/mdl/backend/modelsdk/workflow_read.go
@@ -91,6 +91,48 @@ func workflowEventHandlersFromGen(items []element.Element) []*workflows.Workflow
 	return out
 }
 
+// completionCriteriaFromGen reads a multi-user task's CompletionCriteria, turning
+// its outcome pointers ($IDs) back into outcome values.
+func completionCriteriaFromGen(el element.Element, outcomes []*workflows.UserTaskOutcome) *workflows.CompletionCriteria {
+	value := func(id element.ID) string {
+		for _, o := range outcomes {
+			if string(o.ID) == string(id) {
+				if o.Value != "" {
+					return o.Value
+				}
+				return o.Caption
+			}
+		}
+		return ""
+	}
+	switch c := el.(type) {
+	case *genWf.ConsensusCompletionCriteria:
+		return &workflows.CompletionCriteria{Kind: "Consensus", FallbackOutcome: value(c.FallbackOutcomeRefID())}
+	case *genWf.MajorityCompletionCriteria:
+		return &workflows.CompletionCriteria{Kind: "Majority", CompletionType: c.CompletionType(), FallbackOutcome: value(c.FallbackOutcomeRefID())}
+	case *genWf.ThresholdCompletionCriteria:
+		return &workflows.CompletionCriteria{Kind: "Threshold", CompletionType: c.CompletionType(), Threshold: int(c.Threshold()), FallbackOutcome: value(c.FallbackOutcomeRefID())}
+	case *genWf.VetoCompletionCriteria:
+		return &workflows.CompletionCriteria{Kind: "Veto", VetoOutcome: value(c.VetoOutcomeRefID())}
+	case *genWf.MicroflowCompletionCriteria:
+		return &workflows.CompletionCriteria{Kind: "Microflow", Microflow: c.MicroflowQualifiedName()}
+	}
+	return nil
+}
+
+// targetUserInputFromGen reads a multi-user task's TargetUserInput.
+func targetUserInputFromGen(el element.Element) *workflows.TargetUserInput {
+	switch t := el.(type) {
+	case *genWf.AbsoluteAmountUserInput:
+		return &workflows.TargetUserInput{Kind: "Absolute", Amount: int(t.Amount())}
+	case *genWf.PercentageAmountUserInput:
+		return &workflows.TargetUserInput{Kind: "Percentage", Percentage: int(t.Percentage())}
+	case *genWf.AllUserInput:
+		return &workflows.TargetUserInput{Kind: "All"}
+	}
+	return nil
+}
+
 // workflowFlowFromGen converts a gen Flow to the semantic Flow.
 func workflowFlowFromGen(g *genWf.Flow) *workflows.Flow {
 	f := &workflows.Flow{}
@@ -148,6 +190,9 @@ func workflowActivityFromGen(el element.Element) workflows.WorkflowActivity {
 		setWfBase(&t.BaseWorkflowActivity, a.ID(), a.Name(), a.Caption(), a.Annotation(), "Workflows$MultiUserTaskActivity")
 		t.BoundaryEvents = boundaryEventsFromGen(a.BoundaryEventsItems())
 		t.Outcomes = userTaskOutcomesFromGen(a.OutcomesItems())
+		t.AwaitAllUsers = a.AwaitAllUsers()
+		t.CompletionCriteria = completionCriteriaFromGen(a.CompletionCriteria(), t.Outcomes)
+		t.TargetUserInput = targetUserInputFromGen(a.TargetUserInput())
 		return t
 	case *genWf.CallMicroflowTask:
 		t := &workflows.CallMicroflowTask{Microflow: a.MicroflowQualifiedName()}
diff --git a/mdl/backend/modelsdk/workflow_write.go b/mdl/backend/modelsdk/workflow_write.go
index 5a493bca03..f6e8be60bd 100644
--- a/mdl/backend/modelsdk/workflow_write.go
+++ b/mdl/backend/modelsdk/workflow_write.go
@@ -308,7 +308,7 @@ func userTaskToGen(a *workflows.UserTask) element.Element {
 	}
 	addBool(g, "AutoAssignSingleTargetUser", false)
 	if a.IsMulti {
-		addBool(g, "AwaitAllUsers", false)
+		addBool(g, "AwaitAllUsers", a.AwaitAllUsers)
 	}
 	if len(a.BoundaryEvents) > 0 {
 		addPartList(g, "BoundaryEvents", boundaryEventsToGen(a.BoundaryEvents))
@@ -322,13 +322,7 @@ func userTaskToGen(a *workflows.UserTask) element.Element {
 		}
 	}
 	if a.IsMulti {
-		fallbackID := mmpr.GenerateID()
-		if len(a.Outcomes) > 0 {
-			fallbackID = string(a.Outcomes[0].ID)
-		}
-		cc := newElem("Workflows$ConsensusCompletionCriteria", "")
-		addIDRef(cc, "FallbackOutcomePointer", model.ID(fallbackID))
-		addPart(g, "CompletionCriteria", cc)
+		addPart(g, "CompletionCriteria", completionCriteriaToGen(a))
 	}
 	addStr(g, "DueDate", a.DueDate)
 	addStr(g, "Name", a.Name)
@@ -352,12 +346,88 @@ func userTaskToGen(a *workflows.UserTask) element.Element {
 	addPart(g, "TaskName", workflowStringTemplate(taskName))
 	addPart(g, "TaskPage", pageReferenceElem(a.Page))
 	if a.IsMulti {
-		addPart(g, "TargetUserInput", newElem("Workflows$AllUserInput", ""))
+		addPart(g, "TargetUserInput", targetUserInputToGen(a.TargetUserInput))
 	}
 	addPart(g, "UserTargeting", userTargetingToGen(a.UserSource))
 	return g
 }
 
+// completionCriteriaToGen builds a multi-user task's CompletionCriteria in the
+// shape ako/TestApp (Studio Pro 11.14.0) stores: FallbackOutcomePointer and
+// VetoOutcomePointer hold the $ID of one of the task's own outcomes. With no rule
+// it is consensus falling back to the first outcome, as every rebuild has written.
+// An outcome name that matches none is left unset rather than pointed at a guess;
+// check reports it (CE1866 / CE1867).
+func completionCriteriaToGen(a *workflows.UserTask) element.Element {
+	outcomeID := func(value string) (model.ID, bool) {
+		for _, o := range a.Outcomes {
+			if o.Value == value || (o.Value == "" && o.Caption == value) {
+				return o.ID, true
+			}
+		}
+		return "", false
+	}
+	cc := a.CompletionCriteria
+	if cc == nil {
+		g := newElem("Workflows$ConsensusCompletionCriteria", "")
+		if len(a.Outcomes) > 0 {
+			addIDRef(g, "FallbackOutcomePointer", a.Outcomes[0].ID)
+		}
+		return g
+	}
+	setFallback := func(g *element.Base) {
+		if id, ok := outcomeID(cc.FallbackOutcome); ok && cc.FallbackOutcome != "" {
+			addIDRef(g, "FallbackOutcomePointer", id)
+		}
+	}
+	switch cc.Kind {
+	case "Majority":
+		g := newElem("Workflows$MajorityCompletionCriteria", "")
+		addStr(g, "CompletionType", cc.CompletionType)
+		setFallback(g)
+		return g
+	case "Threshold":
+		g := newElem("Workflows$ThresholdCompletionCriteria", "")
+		addStr(g, "CompletionType", cc.CompletionType)
+		setFallback(g)
+		addInt32(g, "Threshold", int32(cc.Threshold))
+		return g
+	case "Veto":
+		g := newElem("Workflows$VetoCompletionCriteria", "")
+		if id, ok := outcomeID(cc.VetoOutcome); ok {
+			addIDRef(g, "VetoOutcomePointer", id)
+		}
+		return g
+	case "Microflow":
+		g := newElem("Workflows$MicroflowCompletionCriteria", "")
+		addStr(g, "Microflow", cc.Microflow)
+		return g
+	default:
+		g := newElem("Workflows$ConsensusCompletionCriteria", "")
+		setFallback(g)
+		return g
+	}
+}
+
+// targetUserInputToGen builds a multi-user task's TargetUserInput.
+func targetUserInputToGen(t *workflows.TargetUserInput) element.Element {
+	if t == nil {
+		return newElem("Workflows$AllUserInput", "")
+	}
+	switch t.Kind {
+	case "Absolute":
+		g := newElem("Workflows$AbsoluteAmountUserInput", "")
+		addInt32(g, "Amount", int32(t.Amount))
+		return g
+	case "Percentage":
+		g := newElem("Workflows$PercentageAmountUserInput", "")
+		addInt32(g, "Percentage", int32(t.Percentage))
+		return g
+	default:
+		return newElem("Workflows$AllUserInput", "")
+	}
+}
+
 func callMicroflowTaskToGen(a *workflows.CallMicroflowTask) element.Element {
 	typeName := callMicroflowTaskType
 	if a.IsAgent {
diff --git a/mdl/executor/cmd_alter_workflow.go b/mdl/executor/cmd_alter_workflow.go
index 76404bc160..f8d1c32727 100644
--- a/mdl/executor/cmd_alter_workflow.go
+++ b/mdl/executor/cmd_alter_workflow.go
@@ -28,6 +28,9 @@ func execAlterWorkflow(ctx *ExecContext, s *ast.AlterWorkflowStmt) error {
 		return err
 	}
 
+	if vs := completionRuleViolations(alterWorkflowAddedActivities(s), workflowLocation(s.Name)); len(vs) > 0 {
+		return mdlerrors.NewValidationf("%s\n  → %s", vs[0].Message, vs[0].Suggestion)
+	}
 	if workflowUsesAgentTask(alterWorkflowAddedActivities(s)) {
 		if err := checkFeature(ctx, "workflows", "ai_agent_task", "call agent microflow",
 			"AI agent tasks need Mendix 11.9 or later — use `call microflow` on older projects"); err != nil {
diff --git a/mdl/executor/cmd_workflows.go b/mdl/executor/cmd_workflows.go
index 242be1f180..572507d12c 100644
--- a/mdl/executor/cmd_workflows.go
+++ b/mdl/executor/cmd_workflows.go
@@ -528,6 +528,10 @@ func formatUserTask(a *workflows.UserTask, indent string) []string {
 		lines = append(lines, fmt.Sprintf("%s  description %s", indent, mdlQuoted(a.TaskDescription)))
 	}
 
+	if a.IsMulti {
+		lines = append(lines, formatMultiUserTaskCompletion(a, indent)...)
+	}
+
 	// Outcomes
 	if len(a.Outcomes) > 0 {
 		lines = append(lines, fmt.Sprintf("%s  outcomes", indent))
@@ -615,6 +619,61 @@ func sameStringSet(a, b []string) bool {
 	return len(set) == len(b)
 }
 
+// formatMultiUserTaskCompletion emits a multi-user task's `participants`,
+// `decide by` and `await all users` clauses, in grammar order. What a rebuild
+// writes anyway — all participants, consensus falling back to the first outcome,
+// not waiting — is omitted, so a task that never had them describes as before.
+func formatMultiUserTaskCompletion(a *workflows.UserTask, indent string) []string {
+	var lines []string
+	if t := a.TargetUserInput; t != nil {
+		switch t.Kind {
+		case "Absolute":
+			lines = append(lines, fmt.Sprintf("%s  participants %d", indent, t.Amount))
+		case "Percentage":
+			lines = append(lines, fmt.Sprintf("%s  participants %d percent", indent, t.Percentage))
+		}
+	}
+	if cc := a.CompletionCriteria; cc != nil {
+		fallback := ""
+		if cc.FallbackOutcome != "" {
+			fallback = " fallback " + mdlQuoted(cc.FallbackOutcome)
+		}
+		firstOutcome := ""
+		if len(a.Outcomes) > 0 {
+			firstOutcome = a.Outcomes[0].Value
+			if firstOutcome == "" {
+				firstOutcome = a.Outcomes[0].Caption
+			}
+		}
+		switch cc.Kind {
+		case "Consensus":
+			if cc.FallbackOutcome != firstOutcome || firstOutcome == "" {
+				lines = append(lines, fmt.Sprintf("%s  decide by consensus%s", indent, fallback))
+			}
+		case "Majority":
+			rule := "most chosen"
+			if cc.CompletionType == "Absolute" {
+				rule = "more than half"
+			}
+			lines = append(lines, fmt.Sprintf("%s  decide by majority %s%s", indent, rule, fallback))
+		case "Threshold":
+			unit := "votes"
+			if cc.CompletionType == "Relative" {
+				unit = "percent"
+			}
+			lines = append(lines, fmt.Sprintf("%s  decide by threshold %d %s%s", indent, cc.Threshold, unit, fallback))
+		case "Veto":
+			lines = append(lines, fmt.Sprintf("%s  decide by veto %s", indent, mdlQuoted(cc.VetoOutcome)))
+		case "Microflow":
+			lines = append(lines, fmt.Sprintf("%s  decide by microflow %s", indent, cc.Microflow))
+		}
+	}
+	if a.AwaitAllUsers {
+		lines = append(lines, indent+"  await all users")
+	}
+	return lines
+}
+
 // formatCallMicroflowTask formats a call microflow task for describe output.
 func formatCallMicroflowTask(a *workflows.CallMicroflowTask, indent string) []string {
 	var lines []string
diff --git a/mdl/executor/cmd_workflows_write.go b/mdl/executor/cmd_workflows_write.go
index 7d88a2e764..a949872dfb 100644
--- a/mdl/executor/cmd_workflows_write.go
+++ b/mdl/executor/cmd_workflows_write.go
@@ -65,6 +65,9 @@ func execCreateWorkflow(ctx *ExecContext, s *ast.CreateWorkflowStmt) error {
 	// Note this runs BEFORE findOrCreateModule, which auto-creates a module on
 	// demand: without it a typo'd module name silently produced a new module
 	// rather than an error.
+	if vs := ValidateWorkflowCompletionRules(s); len(vs) > 0 {
+		return mdlerrors.NewValidationf("%s\n  → %s", vs[0].Message, vs[0].Suggestion)
+	}
 	if vs := ValidateWorkflowEventTypes(s); len(vs) > 0 {
 		return mdlerrors.NewValidationf("%s\n  → %s", vs[0].Message, vs[0].Suggestion)
 	}
@@ -382,6 +385,51 @@ func buildWorkflowEventHandlers(ctx *ExecContext, nodes []ast.WorkflowEventHandl
 	return out, nil
 }
 
+// buildTargetUserInput maps `participants …`; nil (omitted) stays nil — all users.
+func buildTargetUserInput(p *ast.WorkflowParticipantsNode) *workflows.TargetUserInput {
+	if p == nil {
+		return nil
+	}
+	switch p.Kind {
+	case "number":
+		return &workflows.TargetUserInput{Kind: "Absolute", Amount: p.Value}
+	case "percent":
+		return &workflows.TargetUserInput{Kind: "Percentage", Percentage: p.Value}
+	default:
+		return &workflows.TargetUserInput{Kind: "All"}
+	}
+}
+
+// buildCompletionCriteria maps `decide by …`; nil (omitted) stays nil — consensus
+// falling back to the first outcome, which is what a rebuild has always written.
+// `more than half` / `percent` are Studio Pro's Absolute majority and Relative
+// threshold (measured on ako/TestApp, 11.14.0).
+func buildCompletionCriteria(r *ast.WorkflowCompletionRuleNode) *workflows.CompletionCriteria {
+	if r == nil {
+		return nil
+	}
+	switch r.Rule {
+	case "majority":
+		ct := "Relative"
+		if r.Majority == "more than half" {
+			ct = "Absolute"
+		}
+		return &workflows.CompletionCriteria{Kind: "Majority", CompletionType: ct, FallbackOutcome: r.Fallback}
+	case "threshold":
+		ct := "Absolute"
+		if r.ThresholdUnit == "percent" {
+			ct = "Relative"
+		}
+		return &workflows.CompletionCriteria{Kind: "Threshold", CompletionType: ct, Threshold: r.Threshold, FallbackOutcome: r.Fallback}
+	case "veto":
+		return &workflows.CompletionCriteria{Kind: "Veto", VetoOutcome: r.Veto}
+	case "microflow":
+		return &workflows.CompletionCriteria{Kind: "Microflow", Microflow: r.Microflow.String()}
+	default:
+		return &workflows.CompletionCriteria{Kind: "Consensus", FallbackOutcome: r.Fallback}
+	}
+}
+
 func buildUserTask(n *ast.WorkflowUserTaskNode) *workflows.UserTask {
 	task := &workflows.UserTask{}
 	task.ID = model.ID(generateWorkflowUUID())
@@ -390,6 +438,11 @@ func buildUserTask(n *ast.WorkflowUserTaskNode) *workflows.UserTask {
 	task.DueDate = n.DueDate
 	task.TaskDescription = n.TaskDescription
 	task.IsMulti = n.IsMultiUser
+	if n.IsMultiUser {
+		task.AwaitAllUsers = n.AwaitAllUsers
+		task.TargetUserInput = buildTargetUserInput(n.Participants)
+		task.CompletionCriteria = buildCompletionCriteria(n.Completion)
+	}
 
 	if n.Page.Module != "" {
 		task.Page = n.Page.Module + "." + n.Page.Name
diff --git a/mdl/executor/validate_workflow.go b/mdl/executor/validate_workflow.go
index 3ac765a5a5..fa1e465bd7 100644
--- a/mdl/executor/validate_workflow.go
+++ b/mdl/executor/validate_workflow.go
@@ -123,6 +123,7 @@ func ValidateWorkflow(stmt *ast.CreateWorkflowStmt) []linter.Violation {
 	out = append(out, ValidateWorkflowJumpTargets(stmt)...)
 	out = append(out, ValidateWorkflowEnds(stmt)...)
 	out = append(out, ValidateWorkflowEventTypes(stmt)...)
+	out = append(out, ValidateWorkflowCompletionRules(stmt)...)
 	return out
 }
 
diff --git a/mdl/executor/validate_workflow_completion.go b/mdl/executor/validate_workflow_completion.go
new file mode 100644
index 0000000000..ac3ede7338
--- /dev/null
+++ b/mdl/executor/validate_workflow_completion.go
@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// Checks for a multi-user task's completion rule (`decide by …`).
+//
+// Measured on mxbuild 11.13.0, one multi-user task per shape with only its
+// CompletionCriteria / TargetUserInput patched:
+//
+//	consensus, majority (either kind), threshold without a fallback   CE1866
+//	veto without a veto outcome                                       CE1867
+//	microflow rule with no microflow                                  CE0113
+//	microflow returning Boolean                                       CE5012
+//	microflow with no / context / WorkflowUserTask parameters         0 errors
+//	threshold 0 or 101 percent, 0 or 5 votes                          0 errors
+//	participants 0 or 150 percent, 0 users                            0 errors
+//
+// So check refuses a missing or unknown fallback / veto outcome and a decision
+// microflow that provably does not return String. Out-of-range numbers build, and
+// refusing them would be a guess.
+package executor
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/mdl/linter"
+)
+
+// ValidateWorkflowCompletionRules applies MDL-WF13 to a CREATE WORKFLOW body.
+func ValidateWorkflowCompletionRules(stmt *ast.CreateWorkflowStmt) []linter.Violation {
+	return completionRuleViolations(stmt.Activities, workflowLocation(stmt.Name))
+}
+
+// completionRuleViolations reports MDL-WF13 for every multi-user task, at any
+// depth, whose `decide by` names no usable outcome.
+func completionRuleViolations(activities []ast.WorkflowActivityNode, loc linter.Location) []linter.Violation {
+	var out []linter.Violation
+	walkWorkflowActivities(activities, func(a ast.WorkflowActivityNode) {
+		n, ok := a.(*ast.WorkflowUserTaskNode)
+		if !ok || !n.IsMultiUser || n.Completion == nil {
+			return
+		}
+		label := workflowUserTaskLabel(n)
+		var outcomes []string
+		for _, o := range n.Outcomes {
+			outcomes = append(outcomes, o.Caption)
+		}
+		isOutcome := func(v string) bool {
+			for _, o := range outcomes {
+				if o == v {
+					return true
+				}
+			}
+			return false
+		}
+		add := func(msg, suggestion string) {
+			out = append(out, linter.Violation{
+				RuleID: "MDL-WF13", Severity: linter.SeverityError, Location: loc, Message: msg, Suggestion: suggestion,
+			})
+		}
+		known := "'" + strings.Join(outcomes, "', '") + "'"
+		r := n.Completion
+		switch r.Rule {
+		case "consensus", "majority", "threshold":
+			if !r.HasFallback {
+				add(fmt.Sprintf("multi user task %s decides by %s without a fallback outcome — Mendix requires one for this rule; the build fails CE1866", label, r.Rule),
+					fmt.Sprintf("Add `fallback '<outcome>'`, naming one of %s.", known))
+			} else if !isOutcome(r.Fallback) {
+				add(fmt.Sprintf("multi user task %s falls back to '%s', which is not one of its outcomes (%s); the build fails CE1866", label, r.Fallback, known),
+					"Name one of the task's own outcomes in `fallback '…'`.")
+			}
+		case "veto":
+			if !isOutcome(r.Veto) {
+				add(fmt.Sprintf("multi user task %s vetoes with '%s', which is not one of its outcomes (%s); the build fails CE1867", label, r.Veto, known),
+					"Name one of the task's own outcomes in `decide by veto '…'`.")
+			}
+		}
+	})
+	return out
+}
+
+// checkDecisionMicroflow reports a `decide by microflow` whose microflow provably
+// does not return String (CE5012). Only a return type the script declares is
+// known; a stored flow's is not read, and unknown is not wrong.
+func (c *workflowTaskSignatureChecker) checkDecisionMicroflow(label, mfQN string) string {
+	if mfQN == "" || mfQN == "." {
+		return ""
+	}
+	sig, ok := c.flowSignature(mfQN)
+	if !ok || sig == nil || sig.ReturnKind == ast.TypeUnknown || sig.ReturnKind == ast.TypeString {
+		return ""
+	}
+	return fmt.Sprintf(
+		"%s: decision microflow %s returns %s — a multi-user task's decision microflow must return String (the chosen outcome); the build fails CE5012",
+		label, mfQN, sig.ReturnKind.String())
+}
diff --git a/mdl/executor/validate_workflow_refs.go b/mdl/executor/validate_workflow_refs.go
index 0ae345c4be..ad943d066b 100644
--- a/mdl/executor/validate_workflow_refs.go
+++ b/mdl/executor/validate_workflow_refs.go
@@ -145,6 +145,11 @@ func validateWorkflowReferences(ctx *ExecContext, activities []ast.WorkflowActiv
 			if qn := n.OnCreated.String(); qn != "." && qn != "" && !knownMicroflow(qn) {
 				report("microflow", qn, "user task on created")
 			}
+			if n.Completion != nil && n.Completion.Rule == "microflow" {
+				if qn := n.Completion.Microflow.String(); qn != "." && qn != "" && !knownMicroflow(qn) {
+					report("microflow", qn, "multi user task decide by microflow")
+				}
+			}
 		}
 	})
 	return errs
diff --git a/mdl/executor/validate_workflow_rewrite.go b/mdl/executor/validate_workflow_rewrite.go
index 4efe741f4f..9b54185504 100644
--- a/mdl/executor/validate_workflow_rewrite.go
+++ b/mdl/executor/validate_workflow_rewrite.go
@@ -46,10 +46,8 @@ func checkNoDroppedWorkflowConstructs(ctx *ExecContext, workflowID model.ID, qua
 	}
 	raw = plainRawUnit(raw)
 
-	// Constructs MDL cannot express at all. A rebuild writes the default for
-	// each — measured on ako/TestApp (11.14.0): a completion rule becomes
-	// Consensus on the first outcome — so a rewrite loses them without a word. Refused outright, like
-	// an event sub-process, and every reason is listed at once.
+	// Constructs MDL cannot express at all — a rewrite would lose them without a
+	// word. Refused outright, and every reason is listed at once.
 	var cannotExpress []string
 	if n := countEventSubProcesses(raw); n > 0 {
 		cannotExpress = append(cannotExpress, fmt.Sprintf("%d event sub-process(es), which it would delete", n))
@@ -94,6 +92,32 @@ func checkNoDroppedWorkflowConstructs(ctx *ExecContext, workflowID model.ID, qua
 			qualifiedName, len(stored), authored, strings.Join(stored, "\n  - "), qualifiedName))
 	}
 
+	// A multi-user task's completion rule, participant count and "wait for all
+	// users" are expressible now (`decide by`, `participants`, `await all users`).
+	// A rewrite writes what the statement says, and each omitted clause means the
+	// default — consensus on the first outcome, all participants, not waiting — so
+	// a statement that does not restate stored values resets them. Participants
+	// and await were not guarded at all before; a rewrite reset both silently.
+	storedRules, storedParticipants, storedAwait := rawMultiUserTaskSettings(raw)
+	authoredRules, authoredParticipants, authoredAwait := countAuthoredMultiUserSettings(stmt.Activities)
+	for _, g := range []struct {
+		stored   []string
+		authored int
+		what     string
+		restate  string
+	}{
+		{storedRules, authoredRules, "multi-user task(s) with a completion rule other than consensus on the first outcome", "`decide by …`"},
+		{storedParticipants, authoredParticipants, "multi-user task(s) that need only some participants to respond", "`participants …`"},
+		{storedAwait, authoredAwait, "multi-user task(s) that wait for all users", "`await all users`"},
+	} {
+		if len(g.stored) > g.authored {
+			return mdlerrors.NewUnsupported(fmt.Sprintf(
+				"workflow %s has %d %s but this statement declares %d — rewriting it would reset the difference to the default:\n  - %s\n"+
+					"  Restate them (%s), which `describe workflow %s` now emits, or use ALTER WORKFLOW to change one activity at a time.",
+				qualifiedName, len(g.stored), g.what, g.authored, strings.Join(g.stored, "\n  - "), g.restate, qualifiedName))
+		}
+	}
+
 	// Ends inside branches. MDL could not state one until `end workflow`, and
 	// describe dropped them, so a rewrite from an older describe output would
 	// delete every one — and a branch that ended the workflow would silently
@@ -208,9 +232,8 @@ func countAuthoredBoundaryEvents(activities []ast.WorkflowActivityNode) int {
 }
 
 // studioProOnlyWorkflowState lists what a stored workflow holds that a rebuild
-// from MDL would reset: a workflow event handler subscribed to no
-// event types (the grammar has no empty list), and per activity a completion rule
-// other than the one mxcli writes.
+// from MDL would reset: a workflow event handler subscribed to no event types
+// (the grammar has no empty list).
 func studioProOnlyWorkflowState(raw map[string]any) []string {
 	var out []string
 	for _, h := range rawList(raw["OnWorkflowEvent"]) {
@@ -228,20 +251,17 @@ func studioProOnlyWorkflowState(raw map[string]any) []string {
 			out = append(out, fmt.Sprintf("workflow event handler %s subscribes to no event types, which MDL cannot state", rawHandlerLabel(hm)))
 		}
 	}
-	walkRawDocs(raw, func(d map[string]any) {
-		out = append(out, rawActivityState(d)...)
-	})
 	return out
 }
 
-// rawActivityState lists what one stored activity holds that rebuilding it would
-// reset. Both the workflow rewrite and REPLACE ACTIVITY ask.
-func rawActivityState(d map[string]any) []string {
-	var out []string
+// rawCompletionRule describes a stored multi-user task's completion rule when it
+// is not what an omitted `decide by` writes (consensus falling back to the first
+// outcome); "" otherwise.
+func rawCompletionRule(d map[string]any) string {
 	name, _ := d["Name"].(string)
 	cc, ok := d["CompletionCriteria"].(map[string]any)
 	if !ok {
-		return out
+		return ""
 	}
 	kind, _ := cc["$Type"].(string)
 	var outcomes []map[string]any
@@ -252,20 +272,98 @@ func rawActivityState(d map[string]any) []string {
 	}
 	switch kind {
 	case "Workflows$ConsensusCompletionCriteria":
-		// What mxcli writes: Consensus falling back to the first outcome.
 		if len(outcomes) > 0 && reflect.DeepEqual(cc["FallbackOutcomePointer"], outcomes[0]["$ID"]) {
-			return out
+			return ""
 		}
-		fallback := "another outcome"
+		fallback := "no outcome"
 		for _, o := range outcomes {
 			if reflect.DeepEqual(cc["FallbackOutcomePointer"], o["$ID"]) {
 				fallback = "outcome '" + rawOutcomeLabel(o) + "'"
 			}
 		}
-		out = append(out, fmt.Sprintf("multi user task '%s' falls back to %s when consensus fails, which it would move to the first outcome", name, fallback))
+		return fmt.Sprintf("multi user task '%s' falls back to %s when consensus fails", name, fallback)
 	default:
 		rule := strings.ToLower(strings.TrimSuffix(strings.TrimPrefix(kind, "Workflows$"), "CompletionCriteria"))
-		out = append(out, fmt.Sprintf("multi user task '%s' decides by %s, which it would reset to consensus", name, rule))
+		return fmt.Sprintf("multi user task '%s' decides by %s", name, rule)
+	}
+}
+
+// rawParticipants describes a stored multi-user task that needs only some of its
+// targeted users to respond; "" when it needs all of them.
+func rawParticipants(d map[string]any) string {
+	t, ok := d["TargetUserInput"].(map[string]any)
+	if !ok {
+		return ""
+	}
+	name, _ := d["Name"].(string)
+	switch t["$Type"] {
+	case "Workflows$AbsoluteAmountUserInput":
+		return fmt.Sprintf("multi user task '%s' needs %v participants", name, t["Amount"])
+	case "Workflows$PercentageAmountUserInput":
+		return fmt.Sprintf("multi user task '%s' needs %v percent of participants", name, t["Percentage"])
+	}
+	return ""
+}
+
+func rawAwaitsAllUsers(d map[string]any) bool {
+	await, _ := d["AwaitAllUsers"].(bool)
+	return await
+}
+
+// rawMultiUserTaskSettings labels every stored multi-user task setting a rewrite
+// resets when the statement omits it.
+func rawMultiUserTaskSettings(raw map[string]any) (rules, participants, await []string) {
+	walkRawDocs(raw, func(d map[string]any) {
+		if t, _ := d["$Type"].(string); t != "Workflows$MultiUserTaskActivity" {
+			return
+		}
+		if r := rawCompletionRule(d); r != "" {
+			rules = append(rules, r)
+		}
+		if p := rawParticipants(d); p != "" {
+			participants = append(participants, p)
+		}
+		if rawAwaitsAllUsers(d) {
+			name, _ := d["Name"].(string)
+			await = append(await, fmt.Sprintf("multi user task '%s' waits for all users", name))
+		}
+	})
+	return rules, participants, await
+}
+
+func countAuthoredMultiUserSettings(activities []ast.WorkflowActivityNode) (rules, participants, await int) {
+	walkWorkflowActivities(activities, func(a ast.WorkflowActivityNode) {
+		n, ok := a.(*ast.WorkflowUserTaskNode)
+		if !ok || !n.IsMultiUser {
+			return
+		}
+		if n.Completion != nil {
+			rules++
+		}
+		if n.Participants != nil && n.Participants.Kind != "all" {
+			participants++
+		}
+		if n.AwaitAllUsers {
+			await++
+		}
+	})
+	return rules, participants, await
+}
+
+// rawReplaceLosses lists what a stored activity holds that its replacement does
+// not restate, so REPLACE ACTIVITY would reset it.
+func rawReplaceLosses(d map[string]any, replacement ast.WorkflowActivityNode) []string {
+	var out []string
+	mut, _ := replacement.(*ast.WorkflowUserTaskNode)
+	isMulti := mut != nil && mut.IsMultiUser
+	if r := rawCompletionRule(d); r != "" && (!isMulti || mut.Completion == nil) {
+		out = append(out, r+", which the replacement does not restate (add `decide by …`)")
+	}
+	if p := rawParticipants(d); p != "" && (!isMulti || mut.Participants == nil || mut.Participants.Kind == "all") {
+		out = append(out, p+", which the replacement does not restate (add `participants …`)")
+	}
+	if rawAwaitsAllUsers(d) && (!isMulti || !mut.AwaitAllUsers) {
+		out = append(out, "it waits for all users, which the replacement does not restate (add `await all users`)")
 	}
 	return out
 }
@@ -303,7 +401,7 @@ func validateAlterReplaceKeepsStudioProState(ctx *ExecContext, s *ast.AlterWorkf
 		var reasons []string
 		walkRawDocs(raw, func(d map[string]any) {
 			if n, _ := d["Name"].(string); n != "" && n == act.GetName() {
-				reasons = append(reasons, rawActivityState(d)...)
+				reasons = append(reasons, rawReplaceLosses(d, o.NewActivity)...)
 				if mf := rawOnCreatedMicroflow(d); mf != "" && !restatesOnCreated(o.NewActivity) {
 					reasons = append(reasons, fmt.Sprintf(
 						"it runs on-created microflow %s, which the replacement does not restate (add `on created microflow %s`)", mf, mf))
diff --git a/mdl/executor/validate_workflow_task_signature.go b/mdl/executor/validate_workflow_task_signature.go
index f1064ca562..64a545c254 100644
--- a/mdl/executor/validate_workflow_task_signature.go
+++ b/mdl/executor/validate_workflow_task_signature.go
@@ -126,6 +126,9 @@ func (c *workflowTaskSignatureChecker) checkActivities(activities []ast.Workflow
 			errs = appendIfSet(errs, c.checkTargeting(label, n.Targeting.Microflow.String(), contextEntity))
 		}
 		errs = appendIfSet(errs, c.checkOnCreated(label, n.OnCreated.String(), contextEntity))
+		if n.Completion != nil && n.Completion.Rule == "microflow" {
+			errs = appendIfSet(errs, c.checkDecisionMicroflow(label, n.Completion.Microflow.String()))
+		}
 	})
 	return errs
 }
diff --git a/mdl/executor/workflow_completion_test.go b/mdl/executor/workflow_completion_test.go
new file mode 100644
index 0000000000..6caa34b0ea
--- /dev/null
+++ b/mdl/executor/workflow_completion_test.go
@@ -0,0 +1,229 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/mdl/visitor"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+const completionVariants = `create workflow M.W parameter $C: M.Ctx begin
+  multi user task consensusTask 'c' page M.P decide by consensus fallback 'Reject' outcomes 'Approve' { } 'Reject' { };
+  multi user task majorityHalf 'c' page M.P decide by majority more than half fallback 'Approve' outcomes 'Approve' { } 'Reject' { };
+  multi user task majorityMost 'c' page M.P decide by majority most chosen fallback 'Reject' outcomes 'Approve' { } 'Reject' { };
+  multi user task thresholdPct 'c' page M.P participants 80 percent decide by threshold 60 percent fallback 'Reject' outcomes 'Approve' { } 'Reject' { };
+  multi user task thresholdVotes 'c' page M.P participants 3 decide by threshold 2 votes fallback 'Reject' await all users outcomes 'Approve' { } 'Reject' { };
+  multi user task vetoTask 'c' page M.P decide by veto 'Reject' await all users outcomes 'Approve' { } 'Reject' { };
+  multi user task microflowTask 'c' page M.P decide by microflow M.Decide outcomes 'Approve' { } 'Reject' { };
+end workflow;`
+
+func buildCompletionVariants(t *testing.T) map[string]*workflows.UserTask {
+	t.Helper()
+	out := map[string]*workflows.UserTask{}
+	for _, a := range parseWorkflowStmt(t, completionVariants).Activities {
+		task := buildUserTask(a.(*ast.WorkflowUserTaskNode))
+		out[task.Name] = task
+	}
+	return out
+}
+
+// The MDL words map onto Studio Pro's stored kinds — measured on ako/TestApp
+// (11.14.0): "more than half" is an Absolute majority, "most chosen" Relative;
+// a percentage threshold is Relative, a vote count Absolute.
+func TestWorkflowCompletion_BuildsStudioProShapes(t *testing.T) {
+	tasks := buildCompletionVariants(t)
+	want := map[string]*workflows.CompletionCriteria{
+		"consensusTask":  {Kind: "Consensus", FallbackOutcome: "Reject"},
+		"majorityHalf":   {Kind: "Majority", CompletionType: "Absolute", FallbackOutcome: "Approve"},
+		"majorityMost":   {Kind: "Majority", CompletionType: "Relative", FallbackOutcome: "Reject"},
+		"thresholdPct":   {Kind: "Threshold", CompletionType: "Relative", Threshold: 60, FallbackOutcome: "Reject"},
+		"thresholdVotes": {Kind: "Threshold", CompletionType: "Absolute", Threshold: 2, FallbackOutcome: "Reject"},
+		"vetoTask":       {Kind: "Veto", VetoOutcome: "Reject"},
+		"microflowTask":  {Kind: "Microflow", Microflow: "M.Decide"},
+	}
+	for name, w := range want {
+		if got := tasks[name].CompletionCriteria; !reflect.DeepEqual(got, w) {
+			t.Errorf("%s criteria = %+v, want %+v", name, got, w)
+		}
+	}
+	if got := tasks["thresholdPct"].TargetUserInput; !reflect.DeepEqual(got, &workflows.TargetUserInput{Kind: "Percentage", Percentage: 80}) {
+		t.Errorf("thresholdPct participants = %+v", got)
+	}
+	if got := tasks["thresholdVotes"].TargetUserInput; !reflect.DeepEqual(got, &workflows.TargetUserInput{Kind: "Absolute", Amount: 3}) {
+		t.Errorf("thresholdVotes participants = %+v", got)
+	}
+	if !tasks["vetoTask"].AwaitAllUsers || tasks["consensusTask"].AwaitAllUsers {
+		t.Error("await all users not carried")
+	}
+}
+
+// Describe → re-parse → rebuild reproduces every rule, participant count and
+// await flag.
+func TestWorkflowCompletion_DescribeRoundTrips(t *testing.T) {
+	for name, task := range buildCompletionVariants(t) {
+		out := strings.Join(formatSingleActivity(task, "  "), "\n")
+		stmt := parseWorkflowStmt(t, "create workflow M.W begin\n"+out+"\nend workflow;")
+		again := buildUserTask(stmt.Activities[0].(*ast.WorkflowUserTaskNode))
+		if !reflect.DeepEqual(again.CompletionCriteria, task.CompletionCriteria) ||
+			!reflect.DeepEqual(again.TargetUserInput, task.TargetUserInput) || again.AwaitAllUsers != task.AwaitAllUsers {
+			t.Errorf("%s did not round-trip:\n%s\nrebuilt %+v %+v %v", name, out, again.CompletionCriteria, again.TargetUserInput, again.AwaitAllUsers)
+		}
+	}
+}
+
+// What a rebuild writes anyway is not described, so a multi-user task that never
+// had these settings describes exactly as it did before they existed.
+func TestWorkflowCompletion_DefaultsAreNotDescribed(t *testing.T) {
+	task := &workflows.UserTask{
+		IsMulti:            true,
+		Outcomes:           []*workflows.UserTaskOutcome{{Value: "Approve"}, {Value: "Reject"}},
+		CompletionCriteria: &workflows.CompletionCriteria{Kind: "Consensus", FallbackOutcome: "Approve"},
+		TargetUserInput:    &workflows.TargetUserInput{Kind: "All"},
+	}
+	if lines := formatMultiUserTaskCompletion(task, "  "); len(lines) != 0 {
+		t.Errorf("defaults described as %v", lines)
+	}
+	task.CompletionCriteria.FallbackOutcome = "Reject"
+	if lines := formatMultiUserTaskCompletion(task, "  "); len(lines) != 1 || !strings.Contains(lines[0], "decide by consensus fallback 'Reject'") {
+		t.Errorf("a consensus falling back to another outcome must be described, got %v", lines)
+	}
+}
+
+// MDL-WF13, measured on mxbuild 11.13.0: no fallback for consensus, majority or
+// threshold is CE1866; a veto without a veto outcome is CE1867. A name that is
+// not one of the task's outcomes leaves the pointer empty, so it is the same error.
+func TestWorkflowCompletion_MDLWF13(t *testing.T) {
+	task := func(clause string) string {
+		return `create workflow M.W begin multi user task T 'c' page M.P ` + clause + ` outcomes 'Approve' { } 'Reject' { }; end workflow;`
+	}
+	cases := []struct{ name, src, want string }{
+		{"majority without fallback", task(`decide by majority more than half`), "CE1866"},
+		{"consensus without fallback", task(`decide by consensus`), "CE1866"},
+		{"threshold without fallback", task(`decide by threshold 60 percent`), "CE1866"},
+		{"fallback names no outcome", task(`decide by majority most chosen fallback 'Maybe'`), "CE1866"},
+		{"veto names no outcome", task(`decide by veto 'Maybe'`), "CE1867"},
+		{"microflow needs no fallback", task(`decide by microflow M.Decide`), ""},
+		{"valid veto", task(`decide by veto 'Reject'`), ""},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			var msgs []string
+			for _, v := range ValidateWorkflow(parseWorkflowStmt(t, c.src)) {
+				if v.RuleID == "MDL-WF13" {
+					msgs = append(msgs, v.Message)
+				}
+			}
+			got := strings.Join(msgs, "\n")
+			if c.want == "" && got != "" {
+				t.Errorf("expected no MDL-WF13, got %s", got)
+			}
+			if c.want != "" && !strings.Contains(got, c.want) {
+				t.Errorf("expected MDL-WF13 with %s, got %q", c.want, got)
+			}
+		})
+	}
+	var all []string
+	for _, v := range ValidateWorkflow(parseWorkflowStmt(t, completionVariants)) {
+		if v.RuleID == "MDL-WF13" {
+			all = append(all, v.Message)
+		}
+	}
+	if len(all) != 0 {
+		t.Errorf("every valid variant must pass MDL-WF13, got %v", all)
+	}
+}
+
+// A decision microflow must return String (CE5012); its parameters are free
+// (measured: none, the context entity and System.WorkflowUserTask all build).
+func TestWorkflowCompletion_DecisionMicroflow(t *testing.T) {
+	wf := func(mf string) string {
+		return `create workflow M.W parameter $C: M.Ctx begin multi user task T 'c' decide by microflow ` + mf + ` outcomes 'Approve' { } 'Reject' { }; end workflow;`
+	}
+	cases := []struct{ name, src, want, notWant string }{
+		{"returns Boolean", "create microflow M.DecideBool () returns boolean as $b begin return true; end;\n" + wf("M.DecideBool"), "CE5012", ""},
+		{"returns String", "create microflow M.DecideString ( $C: M.Ctx ) returns string as $s begin return 'Approve'; end;\n" + wf("M.DecideString"), "", "CE5012"},
+		{"unknown microflow", wf("M.Nope"), "microflow not found: M.Nope", ""},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			got := checkScript(t, wfHandlerCtx(t, 11, 13, 0), c.src)
+			if c.want != "" && !strings.Contains(got, c.want) {
+				t.Errorf("expected %q, got:\n%s", c.want, got)
+			}
+			if c.notWant != "" && strings.Contains(got, c.notWant) {
+				t.Errorf("did not expect %q, got:\n%s", c.notWant, got)
+			}
+		})
+	}
+}
+
+// storedMultiUserSettings is the Studio Pro workflow fixture with userTask2
+// deciding by an Absolute majority, needing 80 percent and waiting for all users.
+func storedMultiUserSettings() map[string]any {
+	raw := studioProWorkflow(false, false, false, "MajorityCompletionCriteria", true)
+	for _, a := range raw["Flow"].(map[string]any)["Activities"].([]any) {
+		if m, ok := a.(map[string]any); ok && m["Name"] == "userTask2" {
+			m["TargetUserInput"] = map[string]any{"$Type": "Workflows$PercentageAmountUserInput", "Percentage": 80}
+			m["AwaitAllUsers"] = true
+		}
+	}
+	return raw
+}
+
+// A rewrite writes what the statement says; each omitted clause means its default.
+// Participants and await were not guarded at all before this: a rewrite reset
+// both without a word.
+func TestWorkflowRewrite_MultiUserSettingsMustBeRestated(t *testing.T) {
+	stmt := func(clauses string) *ast.CreateWorkflowStmt {
+		return parseWorkflowStmt(t, `create or modify workflow M.W parameter $C: M.Ctx
+begin
+  user task userTask1 'User Task' page M.P outcomes 'Good' { } 'Bad' { };
+  multi user task userTask2 'Multi' page M.P `+clauses+` outcomes 'Fast' { } 'Furious' { };
+end workflow;`)
+	}
+	cases := []struct{ name, clauses, want string }{
+		{"nothing restated", ``, "decides by majority"},
+		{"rule only", `decide by majority more than half fallback 'Fast'`, "80 percent"},
+		{"rule and participants", `participants 80 percent decide by majority more than half fallback 'Fast'`, "waits for all users"},
+		{"everything restated", `participants 80 percent decide by majority more than half fallback 'Fast' await all users`, ""},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			err := checkNoDroppedWorkflowConstructs(rawWorkflowCtx(t, storedMultiUserSettings()), "wf1", "M.W", stmt(c.clauses))
+			switch {
+			case c.want == "" && err != nil:
+				t.Errorf("a rewrite restating everything must be allowed, got %v", err)
+			case c.want != "" && (err == nil || !strings.Contains(err.Error(), c.want)):
+				t.Errorf("must be refused naming %q, got %v", c.want, err)
+			}
+		})
+	}
+}
+
+func TestAlterWorkflow_ReplaceRestatesMultiUserSettings(t *testing.T) {
+	replace := func(clauses string) *ast.AlterWorkflowStmt {
+		prog, errs := visitor.Build(`alter workflow M.W replace activity userTask2 with multi user task userTask2 'Multi' page M.P ` + clauses + ` outcomes 'Fast' { } 'Furious' { };`)
+		if len(errs) > 0 {
+			t.Fatalf("parse errors: %v", errs)
+		}
+		return prog.Statements[0].(*ast.AlterWorkflowStmt)
+	}
+	ctx := storedReplaceCtx(t, storedMultiUserSettings())
+	if got := validateAlterReplaceKeepsStudioProState(ctx, replace(`participants 80 percent decide by majority more than half fallback 'Fast' await all users`)); len(got) != 0 {
+		t.Errorf("a replacement restating everything must be allowed, got %v", got)
+	}
+	got := validateAlterReplaceKeepsStudioProState(ctx, replace(``))
+	if len(got) != 1 {
+		t.Fatalf("want one refusal, got %v", got)
+	}
+	for _, want := range []string{"majority", "80 percent", "waits for all users"} {
+		if !strings.Contains(got[0], want) {
+			t.Errorf("refusal lacks %q: %s", want, got[0])
+		}
+	}
+}
diff --git a/mdl/grammar/MDLLexer.g4 b/mdl/grammar/MDLLexer.g4
index 350612db9b..6e06f2e0fd 100644
--- a/mdl/grammar/MDLLexer.g4
+++ b/mdl/grammar/MDLLexer.g4
@@ -783,6 +783,24 @@ CONDITION: C O N D I T I O N;
 OFF: O F F;
 USERS: U S E R S;
 GROUPS: G R O U P S;
+// Multi-user task completion: `participants …`, `decide by …`, `await all users`.
+DECIDE: D E C I D E;
+CONSENSUS: C O N S E N S U S;
+MAJORITY: M A J O R I T Y;
+// MORE_KW: `more` is a reserved lexer command name in ANTLR.
+MORE_KW: M O R E;
+THAN: T H A N;
+HALF: H A L F;
+MOST: M O S T;
+CHOSEN: C H O S E N;
+THRESHOLD: T H R E S H O L D;
+// PERCENT_KW is the WORD "percent"; PERCENT is the '%' operator.
+PERCENT_KW: P E R C E N T;
+VOTES: V O T E S;
+VETO: V E T O;
+FALLBACK: F A L L B A C K;
+PARTICIPANTS: P A R T I C I P A N T S;
+AWAIT: A W A I T;
 
 // Data transformer tokens
 DATA: D A T A;
diff --git a/mdl/grammar/domains/MDLSettings.g4 b/mdl/grammar/domains/MDLSettings.g4
index 6dd6b973cf..e75a4fa60d 100644
--- a/mdl/grammar/domains/MDLSettings.g4
+++ b/mdl/grammar/domains/MDLSettings.g4
@@ -576,6 +576,10 @@ keyword
     // Agent editor
     | AGENT | AGENTS | KNOWLEDGE | BASES | CONSUMED | MCP | TOOL
 
+    // Workflow multi-user task completion — words, so still usable as names
+    | DECIDE | CONSENSUS | MAJORITY | MORE_KW | THAN | HALF | MOST | CHOSEN | THRESHOLD
+    | PERCENT_KW | VOTES | VETO | FALLBACK | PARTICIPANTS | AWAIT
+
     // Microflow / Nanoflow
     | MICROFLOW | MICROFLOWS | NANOFLOW | NANOFLOWS
     | BEGIN | END | IF | ELSE | ELSIF | ELSEIF | THEN | WHILE | LOOP
diff --git a/mdl/grammar/domains/MDLWorkflow.g4 b/mdl/grammar/domains/MDLWorkflow.g4
index 43a3a4e620..63f6cfac0c 100644
--- a/mdl/grammar/domains/MDLWorkflow.g4
+++ b/mdl/grammar/domains/MDLWorkflow.g4
@@ -115,10 +115,42 @@ workflowUserTaskStmt
       (ENTITY qualifiedName)?
       (DUE DATE_TYPE STRING_LITERAL)?
       (DESCRIPTION STRING_LITERAL)?
+      workflowParticipantsClause?
+      workflowCompletionClause?
+      (AWAIT ALL USERS)?
       (OUTCOMES workflowUserTaskOutcome+)?
       (BOUNDARY EVENT workflowBoundaryEventClause ((BOUNDARY EVENT)? workflowBoundaryEventClause)*)?
     ;
 
+/**
+ * How many of a multi-user task's targeted users must respond (TargetUserInput).
+ * Omitted means all of them. A sub-rule, so its number stays out of the task's
+ * positional reads.
+ */
+workflowParticipantsClause
+    : PARTICIPANTS ALL
+    | PARTICIPANTS NUMBER_LITERAL PERCENT_KW?
+    ;
+
+/**
+ * How a multi-user task turns its participants' outcomes into one outcome
+ * (CompletionCriteria). Omitted means consensus falling back to the first
+ * outcome. The fallback is optional here and required by check (CE1866): a
+ * platform rule reported as a parse error reads as "not implemented".
+ */
+workflowCompletionClause
+    : DECIDE BY CONSENSUS workflowFallbackClause?
+    | DECIDE BY MAJORITY MORE_KW THAN HALF workflowFallbackClause?
+    | DECIDE BY MAJORITY MOST CHOSEN workflowFallbackClause?
+    | DECIDE BY THRESHOLD NUMBER_LITERAL (PERCENT_KW | VOTES) workflowFallbackClause?
+    | DECIDE BY VETO STRING_LITERAL
+    | DECIDE BY MICROFLOW qualifiedName
+    ;
+
+workflowFallbackClause
+    : FALLBACK STRING_LITERAL
+    ;
+
 /**
  * One boundary event. An activity's clauses may each repeat `boundary event`
  * (the form describe emits and the syntax topic documents) or share one
diff --git a/mdl/visitor/visitor_workflow.go b/mdl/visitor/visitor_workflow.go
index 60b5959238..6a5b947efe 100644
--- a/mdl/visitor/visitor_workflow.go
+++ b/mdl/visitor/visitor_workflow.go
@@ -3,6 +3,7 @@
 package visitor
 
 import (
+	"strconv"
 	"strings"
 
 	"github.com/antlr4-go/antlr/v4"
@@ -510,8 +511,15 @@ func buildWorkflowUserTask(ctx parser.IWorkflowUserTaskStmtContext) *ast.Workflo
 	}
 
 	node := &ast.WorkflowUserTaskNode{
-		Name:        taskName,
-		IsMultiUser: utCtx.MULTI() != nil,
+		Name:          taskName,
+		IsMultiUser:   utCtx.MULTI() != nil,
+		AwaitAllUsers: utCtx.AWAIT() != nil,
+	}
+	if pc, ok := utCtx.WorkflowParticipantsClause().(*parser.WorkflowParticipantsClauseContext); ok && pc != nil {
+		node.Participants = buildWorkflowParticipants(pc)
+	}
+	if cc, ok := utCtx.WorkflowCompletionClause().(*parser.WorkflowCompletionClauseContext); ok && cc != nil {
+		node.Completion = buildWorkflowCompletionRule(cc)
 	}
 
 	// Caption is the first STRING_LITERAL
@@ -908,3 +916,57 @@ func parseInt(s string) int {
 	}
 	return n
 }
+
+// buildWorkflowParticipants reads `participants all | N | N percent`.
+func buildWorkflowParticipants(ctx *parser.WorkflowParticipantsClauseContext) *ast.WorkflowParticipantsNode {
+	if ctx.ALL() != nil {
+		return &ast.WorkflowParticipantsNode{Kind: "all"}
+	}
+	n := &ast.WorkflowParticipantsNode{Kind: "number"}
+	if ctx.PERCENT_KW() != nil {
+		n.Kind = "percent"
+	}
+	if num := ctx.NUMBER_LITERAL(); num != nil {
+		n.Value, _ = strconv.Atoi(num.GetText())
+	}
+	return n
+}
+
+// buildWorkflowCompletionRule reads `decide by …`.
+func buildWorkflowCompletionRule(ctx *parser.WorkflowCompletionClauseContext) *ast.WorkflowCompletionRuleNode {
+	r := &ast.WorkflowCompletionRuleNode{}
+	switch {
+	case ctx.CONSENSUS() != nil:
+		r.Rule = "consensus"
+	case ctx.MAJORITY() != nil:
+		r.Rule = "majority"
+		r.Majority = "most chosen"
+		if ctx.MORE_KW() != nil {
+			r.Majority = "more than half"
+		}
+	case ctx.THRESHOLD() != nil:
+		r.Rule = "threshold"
+		r.ThresholdUnit = "votes"
+		if ctx.PERCENT_KW() != nil {
+			r.ThresholdUnit = "percent"
+		}
+		if num := ctx.NUMBER_LITERAL(); num != nil {
+			r.Threshold, _ = strconv.Atoi(num.GetText())
+		}
+	case ctx.VETO() != nil:
+		r.Rule = "veto"
+		if s := ctx.STRING_LITERAL(); s != nil {
+			r.Veto = unquoteString(s.GetText())
+		}
+	case ctx.MICROFLOW() != nil:
+		r.Rule = "microflow"
+		if qn := ctx.QualifiedName(); qn != nil {
+			r.Microflow = buildQualifiedName(qn)
+		}
+	}
+	if fb, ok := ctx.WorkflowFallbackClause().(*parser.WorkflowFallbackClauseContext); ok && fb != nil && fb.STRING_LITERAL() != nil {
+		r.Fallback = unquoteString(fb.STRING_LITERAL().GetText())
+		r.HasFallback = true
+	}
+	return r
+}
diff --git a/mdl/visitor/visitor_workflow_completion_test.go b/mdl/visitor/visitor_workflow_completion_test.go
new file mode 100644
index 0000000000..767f75f187
--- /dev/null
+++ b/mdl/visitor/visitor_workflow_completion_test.go
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package visitor
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+)
+
+// Every `participants`, `decide by` and `await all users` form lands on its
+// fields, and the sub-rules keep their numbers and names out of the task's own
+// positional reads (page, targeting, outcomes stay where they were).
+func TestWorkflowVisitor_MultiUserTaskCompletion(t *testing.T) {
+	stmt := buildWorkflowStmt(t, `create workflow M.W
+begin
+  multi user task consensusTask 'c' page M.P decide by consensus fallback 'Approve' outcomes 'Approve' { } 'Reject' { };
+  multi user task majorityHalf 'c' page M.P participants all decide by majority more than half fallback 'Approve' outcomes 'Approve' { } 'Reject' { };
+  multi user task majorityMost 'c' page M.P decide by majority most chosen outcomes 'Approve' { } 'Reject' { };
+  multi user task thresholdPct 'c' page M.P targeting microflow M.Targets participants 80 percent decide by threshold 60 percent fallback 'Reject' outcomes 'Approve' { } 'Reject' { };
+  multi user task thresholdVotes 'c' page M.P participants 3 decide by threshold 2 votes fallback 'Reject' await all users outcomes 'Approve' { } 'Reject' { };
+  multi user task vetoTask 'c' page M.P decide by veto 'Reject' await all users outcomes 'Approve' { } 'Reject' { };
+  multi user task microflowTask 'c' page M.P decide by microflow M.Decide outcomes 'Approve' { } 'Reject' { };
+  multi user task plain 'c' page M.P outcomes 'Approve' { } 'Reject' { };
+end workflow;`)
+	tasks := map[string]*ast.WorkflowUserTaskNode{}
+	for _, a := range stmt.Activities {
+		n := a.(*ast.WorkflowUserTaskNode)
+		tasks[n.Name] = n
+		if n.Page.String() != "M.P" || len(n.Outcomes) != 2 {
+			t.Errorf("%s: page %s, %d outcomes — the new clauses disturbed the positional reads", n.Name, n.Page, len(n.Outcomes))
+		}
+	}
+
+	check := func(name string, want ast.WorkflowCompletionRuleNode) {
+		t.Helper()
+		got := tasks[name].Completion
+		if got == nil || *got != want {
+			t.Errorf("%s completion = %+v, want %+v", name, got, want)
+		}
+	}
+	check("consensusTask", ast.WorkflowCompletionRuleNode{Rule: "consensus", Fallback: "Approve", HasFallback: true})
+	check("majorityHalf", ast.WorkflowCompletionRuleNode{Rule: "majority", Majority: "more than half", Fallback: "Approve", HasFallback: true})
+	check("majorityMost", ast.WorkflowCompletionRuleNode{Rule: "majority", Majority: "most chosen"})
+	check("thresholdPct", ast.WorkflowCompletionRuleNode{Rule: "threshold", Threshold: 60, ThresholdUnit: "percent", Fallback: "Reject", HasFallback: true})
+	check("thresholdVotes", ast.WorkflowCompletionRuleNode{Rule: "threshold", Threshold: 2, ThresholdUnit: "votes", Fallback: "Reject", HasFallback: true})
+	check("vetoTask", ast.WorkflowCompletionRuleNode{Rule: "veto", Veto: "Reject"})
+	check("microflowTask", ast.WorkflowCompletionRuleNode{Rule: "microflow", Microflow: ast.QualifiedName{Module: "M", Name: "Decide"}})
+
+	participants := map[string]*ast.WorkflowParticipantsNode{
+		"majorityHalf":   {Kind: "all"},
+		"thresholdPct":   {Kind: "percent", Value: 80},
+		"thresholdVotes": {Kind: "number", Value: 3},
+	}
+	for name, n := range tasks {
+		want := participants[name]
+		got := n.Participants
+		if (want == nil) != (got == nil) || (want != nil && *want != *got) {
+			t.Errorf("%s participants = %+v, want %+v", name, got, want)
+		}
+		wantAwait := name == "thresholdVotes" || name == "vetoTask"
+		if n.AwaitAllUsers != wantAwait {
+			t.Errorf("%s await = %v, want %v", name, n.AwaitAllUsers, wantAwait)
+		}
+	}
+	if tasks["plain"].Completion != nil {
+		t.Error("a task without `decide by` must have no completion rule")
+	}
+	if tasks["thresholdPct"].Targeting.Microflow.String() != "M.Targets" {
+		t.Errorf("targeting microflow = %s", tasks["thresholdPct"].Targeting.Microflow)
+	}
+}
diff --git a/sdk/workflows/workflow.go b/sdk/workflows/workflow.go
index 07738658f7..5546327682 100644
--- a/sdk/workflows/workflow.go
+++ b/sdk/workflows/workflow.go
@@ -134,6 +134,29 @@ type UserTask struct {
 	UserTaskEntity  string             `json:"userTaskEntity,omitempty"`  // Qualified name of user task entity
 	OnCreated       string             `json:"onCreated,omitempty"`       // Microflow called on task creation
 	BoundaryEvents  []*BoundaryEvent   `json:"boundaryEvents,omitempty"`  // Boundary events (e.g., timers)
+
+	// Multi-user task only.
+	CompletionCriteria *CompletionCriteria `json:"completionCriteria,omitempty"` // nil = consensus on the first outcome
+	TargetUserInput    *TargetUserInput    `json:"targetUserInput,omitempty"`    // nil = all targeted users
+	AwaitAllUsers      bool                `json:"awaitAllUsers,omitempty"`
+}
+
+// CompletionCriteria is how a multi-user task turns its participants' outcomes
+// into one outcome. Outcomes are named by value; storage points at their $ID.
+type CompletionCriteria struct {
+	Kind            string `json:"kind"`                     // Consensus, Majority, Threshold, Veto or Microflow
+	CompletionType  string `json:"completionType,omitempty"` // Absolute or Relative (Majority, Threshold)
+	Threshold       int    `json:"threshold,omitempty"`      // percent (Relative) or votes (Absolute)
+	FallbackOutcome string `json:"fallbackOutcome,omitempty"`
+	VetoOutcome     string `json:"vetoOutcome,omitempty"`
+	Microflow       string `json:"microflow,omitempty"` // must return String (CE5012)
+}
+
+// TargetUserInput is how many of a multi-user task's targeted users must respond.
+type TargetUserInput struct {
+	Kind       string `json:"kind"` // All, Absolute or Percentage
+	Amount     int    `json:"amount,omitempty"`
+	Percentage int    `json:"percentage,omitempty"`
 }
 
 // ActivityType returns the type name.

From 76fa13851f3e3f85537d0fe2be3a97f08b7a18a1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 15 Sep 2026 10:07:23 +0000
Subject: [PATCH 18/24] Close Phase 3: accept the last six bypasses as
 deliberate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

After the orphans and duplicates were deleted, the six remaining census entries
were all the same kind of caller: cmd/mxcli's bson dump/discover, diag,
extract-templates and examples/read_project — raw-unit debugging and export
commands holding a concrete sdk/mpr reader because raw access is the thing they
exist to provide.

Porting them was considered and declined. The backend interface speaks the
semantic model (ADR-0005); routing a BSON dumper through it would either widen
that interface with raw accessors, undoing the decision, or make the tools worse
at their only job. The framing this plan shipped ("the list shrinks by closing a
bypass") did not offer that option — a second way it was too narrow, alongside
the orphan/duplicate correction: some bypasses are correct.

unreachableUnimplemented becomes a standing record rather than a to-do list, and
its header now says so. It keeps its value as a tripwire: a NEW entry still
means either a new bypass appeared or a method was added that nothing calls, and
the two want opposite fixes, so the cause has to be established rather than a
row added to silence the failure.

sdk/mpr does not go away with this — those six commands still import it, as does
the workflow serializer #469 extended. What Phase 3 delivered is that no engine
path reaches it: the executor, the backends and api/ are clean. Removing the
serializer is downstream of Phase 4.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hifgRSawfaRWXS44YKtSJ
---
 docs/plans/2026-09-14-retire-legacy-engine.md | 33 ++++++++++++++++---
 .../unimplemented_reachability_test.go        | 24 ++++++++++----
 2 files changed, 46 insertions(+), 11 deletions(-)

diff --git a/docs/plans/2026-09-14-retire-legacy-engine.md b/docs/plans/2026-09-14-retire-legacy-engine.md
index a889625f83..3eb97e2900 100644
--- a/docs/plans/2026-09-14-retire-legacy-engine.md
+++ b/docs/plans/2026-09-14-retire-legacy-engine.md
@@ -1,11 +1,11 @@
 # Implementation Plan — Retire the legacy engine
 
 **Date:** 2026-09-14
-**Status:** In progress — Phases 1, 2 and the api/ + MCP steps of Phase 3 have landed
-(2026-09-15). What remains is the rest of Phase 3 (the `cmd/mxcli` commands that hold a concrete
-`sdk/mpr` reader on purpose) and Phase 4 (the mongo-driver migration, which those gate).
-See [§7 What landed](#7-what-landed) for the record of what each phase actually did, including the
-two places the plan was wrong.
+**Status:** Phases 1–3 complete (2026-09-15). Phase 3 closed by *deciding* rather than by porting:
+the six remaining abstraction bypasses are raw-unit debugging commands and are **accepted as
+deliberate** — see [§7.4](#phase-3-closed-the-last-six-bypasses-are-accepted). Phase 4 (the
+mongo-driver migration) is the only phase outstanding, and it is what gates deleting `sdk/mpr`.
+See [§7 What landed](#7-what-landed) for the record, including the two places the plan was wrong.
 **Continues:** [`2026-06-05-adopt-modelsdk-engine.md`](2026-06-05-adopt-modelsdk-engine.md), which
 stops at the cutover. That plan still reads as though `legacy` were the default; it is not, and has
 not been since the codec engine took over. This plan covers what the earlier one deferred to
@@ -342,3 +342,26 @@ bson/diag/extract-templates commands and `examples/read_project`, which hold a c
 deliberately. Whether those should be ported at all is the open question for the rest of Phase 3;
 they are debugging tools whose whole job is raw access, so "leave them" is a defensible answer that
 the earlier framing did not allow for.
+
+### Phase 3 closed — the last six bypasses are accepted (2026-09-15)
+
+After the orphans and duplicates were deleted, the census held six entries and they were all the
+same kind of caller: `cmd/mxcli`'s `bson dump` / `bson discover` / `diag` / `extract-templates` and
+`examples/read_project`. Every one is a **raw-unit debugging or export command**, holding a concrete
+`sdk/mpr` reader because raw access is the thing it exists to provide.
+
+Porting them was considered and **declined**. The backend interface speaks the semantic model by
+[ADR-0005](../13-decisions/0005-semantic-model-interface-currency.md); routing a BSON dumper through
+it would either widen that interface with raw accessors — undoing the decision — or make the tools
+worse at their only job. The earlier framing ("the list shrinks by closing a bypass") did not offer
+this option, which is a second way that framing was too narrow: some bypasses are correct.
+
+`unreachableUnimplemented` therefore becomes a **standing record rather than a to-do list**, and its
+header says so. It keeps its value as a tripwire: a *new* entry still means either a new bypass
+appeared or a method was added that nothing calls, and the fix depends on which — establish the
+cause rather than adding a row to silence the failure.
+
+**`sdk/mpr` does not go away with this.** Those six commands still import it, as does the workflow
+serializer that #469 extended. What Phase 3 delivered is that no *engine* path reaches it — the
+executor, the backends and `api/` are all clean. Removing the serializer is a separate question,
+downstream of Phase 4.
diff --git a/mdl/backend/modelsdk/unimplemented_reachability_test.go b/mdl/backend/modelsdk/unimplemented_reachability_test.go
index d24de51b94..2f63650cd7 100644
--- a/mdl/backend/modelsdk/unimplemented_reachability_test.go
+++ b/mdl/backend/modelsdk/unimplemented_reachability_test.go
@@ -64,13 +64,25 @@ import (
 // that hold a concrete *mpr.Reader / *mpr.Writer (the api/ package, examples/,
 // and cmd/mxcli commands that open a reader directly) — none of which route
 // through this engine.
+// Every remaining entry is a BYPASS, and all six are the same kind of caller:
+// a raw-unit debugging or export command that holds a concrete reader on
+// purpose. ACCEPTED as deliberate rather than queued for porting (2026-09-15,
+// closing Phase 3 of docs/plans/2026-09-14-retire-legacy-engine.md) — routing a
+// raw-BSON dumper through an interface that speaks the semantic model would
+// either widen that interface with raw accessors or make the tools worse at the
+// one thing they exist for.
+//
+// So this map is now a STANDING RECORD, not a to-do list. A new entry is still
+// a finding: it means a NEW bypass appeared, or a method was added to
+// FullBackend that nothing calls — establish which (see the three causes above)
+// rather than adding a row to match the failure.
 var unreachableUnimplemented = map[string]string{
-	"ExportJSON":               "BYPASS: examples/read_project calls it on the sdk reader",
-	"FindCustomWidgetType":     "BYPASS: cmd/mxcli/cmd_extract_templates.go holds a concrete reader",
-	"FindAllCustomWidgetTypes": "BYPASS: reached only via the reader, inside modelsdk/mpr itself",
-	"GetProjectRootID":         "BYPASS: callers hold a reader; this package uses b.reader.GetProjectRootID directly",
-	"ListAllUnitIDs":           "BYPASS: cmd/mxcli/diag.go holds a concrete reader; infrastructure_write.go uses b.reader",
-	"ListRawUnits":             "BYPASS: the bson dump/discover/describe commands hold a concrete reader",
+	"ExportJSON":               "BYPASS, accepted: examples/read_project calls it on the sdk reader",
+	"FindCustomWidgetType":     "BYPASS, accepted: cmd/mxcli/cmd_extract_templates.go holds a concrete reader",
+	"FindAllCustomWidgetTypes": "BYPASS, accepted: reached only via the reader, inside modelsdk/mpr itself",
+	"GetProjectRootID":         "BYPASS, accepted: callers hold a reader; this package uses b.reader.GetProjectRootID directly",
+	"ListAllUnitIDs":           "BYPASS, accepted: cmd/mxcli/diag.go holds a concrete reader; infrastructure_write.go uses b.reader",
+	"ListRawUnits":             "BYPASS, accepted: the bson dump/discover/describe commands hold a concrete reader",
 }
 
 func TestNoReachableUnimplementedBackendMethods(t *testing.T) {

From 49beadaf5c8fc0f5498f5d14b26d08fb26f71c4a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 15 Sep 2026 10:10:14 +0000
Subject: [PATCH 19/24] Re-measure Phase 4: it is two independent migrations,
 not one
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The plan's Phase 4 opens "with [sdk/mpr] gone" — and Phase 3 closed by keeping
it, so its premise did not survive. Measuring it properly shows two migrations
that do not gate each other, and the one worth doing first is not the driver
migration.

Also corrects §7.4, which said "those six commands still import sdk/mpr". That
was wrong by a factor of four and pointed at the wrong files: the census tracks
FullBackend METHODS with no caller through a backend value, not importers. 28
non-test files import sdk/mpr, including 7 in cmd/mxcli/docker, two mdl/executor
validators, and modelsdk.go — whose Reader and Writer are type ALIASES to
sdk/mpr's, so the published library's root API is the legacy serializer.

4a (port the 28 callers) is the half that pays: 23 of 28 use only mpr.Open, so
the dependency is one read-only constructor rather than the serializer's bulk,
and the port is the MCP move repeated — modelsdkbackend.New() + ConnectReadOnly.
The 140-vs-47 reader method comparison that makes it look impossible is the same
wrong comparison the MCP port already disproved: the semantic methods live on
the codec backend, a layer up from modelsdk/mpr's raw reader. Its real gate is
modelsdk.go's public API, which should be decided before 4a starts rather than
during.

4b (convert mdl/'s mutator layer to v2) is independent: those 19 non-test v1
files are v1 because pagemutator/wfmutator/widgetobj declare their deps
interfaces in v1 bson.D, not because they bridge to sdk/mpr, so they do not
shrink when it goes — which is what §4 assumed.

Measured: 249 v1 files, 174 v2, and only 6 importing both — all in
mdl/backend/modelsdk, where the crossing is safe because the interchange is
bytes and BSON bytes carry no driver version.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hifgRSawfaRWXS44YKtSJ
---
 docs/plans/2026-09-14-retire-legacy-engine.md | 79 +++++++++++++++++--
 1 file changed, 74 insertions(+), 5 deletions(-)

diff --git a/docs/plans/2026-09-14-retire-legacy-engine.md b/docs/plans/2026-09-14-retire-legacy-engine.md
index 3eb97e2900..7a37fc8d0e 100644
--- a/docs/plans/2026-09-14-retire-legacy-engine.md
+++ b/docs/plans/2026-09-14-retire-legacy-engine.md
@@ -183,7 +183,12 @@ are almost entirely the MCP protocol surface and are untouched by this.
 
 **Only after step 4 is `sdk/mpr`'s fate a question at all**, and by then it is a small one.
 
-### Phase 4 — mongo-driver v1 → v2 *(Effort: L, Risk: Med — gated on Phase 3)*
+### Phase 4 — mongo-driver v1 → v2 *(superseded by §7.5)*
+
+> **This section's premise did not survive Phase 3.** It opens "with [`sdk/mpr`] gone", and Phase 3
+> closed by *keeping* it. Its sizing is also wrong on its own terms: the v1 files in `mdl/` do not
+> "exist to bridge the two worlds", and do not shrink when `sdk/mpr` goes. See **§7.5**, which
+> re-measures and splits this into two independent migrations. Kept unedited for the record.
 
 Reachable once Phase 3's step 4 settles whether anything still needs `sdk/mpr`. With it gone the
 remaining v1 files are the `mdl/backend/modelsdk` adapter's 44 and `mdl/executor`'s 18 — both exist
@@ -361,7 +366,71 @@ header says so. It keeps its value as a tripwire: a *new* entry still means eith
 appeared or a method was added that nothing calls, and the fix depends on which — establish the
 cause rather than adding a row to silence the failure.
 
-**`sdk/mpr` does not go away with this.** Those six commands still import it, as does the workflow
-serializer that #469 extended. What Phase 3 delivered is that no *engine* path reaches it — the
-executor, the backends and `api/` are all clean. Removing the serializer is a separate question,
-downstream of Phase 4.
+**`sdk/mpr` does not go away with this — and it is imported far more widely than the census
+suggests.** The census tracks `FullBackend` *methods* with no caller through a backend value; it
+says nothing about who imports the package. Measured: **28 non-test files** import `sdk/mpr`,
+including `cmd/mxcli/docker/` (7 files in the run/build pipeline), two `mdl/executor` validators,
+and — most consequentially — **`modelsdk.go`, the published library's root API**, whose `Reader` and
+`Writer` are type *aliases* to `sdk/mpr`'s. An earlier draft of this section said "those six
+commands still import it", which was wrong by a factor of four and pointed at the wrong files.
+
+What Phase 3 delivered is narrower and still worth having: no *engine* path reaches `sdk/mpr`. The
+executor's write paths, the backends and `api/` are clean. Removing the serializer is Phase 4's
+job, and §7.5 measures what that actually takes.
+
+### Phase 4 re-measured — it is two independent migrations, not one (2026-09-15)
+
+§4's Phase 4 assumed one job, gated on `sdk/mpr` being gone. Measuring it after Phase 3 closed
+shows **two migrations that do not gate each other**, and the one worth doing first is not the
+driver migration at all.
+
+**Where v1 actually lives** (249 files import v1, 174 import v2; only **6** import both, all of them
+in `mdl/backend/modelsdk`, and the crossing is safe because the interchange is *bytes* — v1
+`Marshal` → `v2.Raw`, and BSON bytes carry no driver version):
+
+| tree | v1 | v2 | what it is |
+|---|---|---|---|
+| `modelsdk/` | 0 | 116 | the codec — already pure v2 |
+| `sdk/` | 117 | 0 | the legacy serializer |
+| `mdl/` | 107 | 58 | mixed; the mutator layer is v1 |
+| `cmd/`, `examples/`, `scripts/`, `model/` | 25 | 0 | callers |
+
+#### 4a — port the 28 `sdk/mpr` callers (the one that pays)
+
+**23 of the 28 use only `mpr.Open`.** The dependency is overwhelmingly on one read-only
+constructor, not on the serializer's 41k lines. The rest use `mpr.NewWriter` (6) or a small helper
+(`GenerateID`, `BlobToUUID`, `MPRVersionV`, `ParseMicroflowBSON`).
+
+The naive objection is that `sdk/mpr.Reader` has **140 methods** and `modelsdk/mpr.Reader` has
+**47**, so the port looks impossible. That is the same wrong comparison the MCP port already
+disproved: `modelsdk/mpr` is a *raw/unit* reader and the semantic decoding is a layer up, on the
+**codec backend**. Every method these callers invoke — `ListModules`, `GetDomainModel`,
+`ListMicroflows`, `GetProjectSecurity` … — is a `FullBackend` method.
+
+So 4a is **the MCP port repeated**: swap `mpr.Open(path)` for `modelsdkbackend.New()` +
+`ConnectReadOnly(path)`. That move is already written, already tested, and already has a read-only
+guard with a revert control.
+
+**Its one real gate is `modelsdk.go`.** The published library's `Reader` and `Writer` are type
+aliases to `sdk/mpr`'s, so the root API *is* the legacy serializer. Changing it is a breaking change
+of a different order from `api.New`'s — that one had zero in-repo callers and a fluent surface that
+did not move; this one is the documented entry point in README and CLAUDE.md. **Decide this before
+starting 4a**, not during.
+
+#### 4b — convert `mdl/`'s mutator layer to v2
+
+`mdl/backend/modelsdk` has **19 non-test v1 files**, using `bson.D` (70), `bson.A` (25),
+`bson.M` (14), `Marshal`/`Unmarshal` (29). These are not a bridge to `sdk/mpr` and **do not shrink
+when it goes** — §4's sizing claim is wrong here. They are v1 because the *mutator layer's*
+currency is v1 `bson.D`: `pagemutator`, `wfmutator` and `widgetobj` all declare their `deps`
+interfaces in those terms, and the codec backend implements them.
+
+That makes 4b independent of 4a and of the serializer entirely. It is also the half with **no
+user-visible benefit until both are done**, since v1 leaves `go.mod` only when the last importer
+does.
+
+#### Recommended order
+
+**4a, then the `modelsdk.go` decision, then 4c (delete `sdk/mpr`), then 4b.** 4a is a proven move
+that deletes 41k lines; 4b is internal churn whose payoff is gated on 4a finishing anyway. Doing 4b
+first would convert a mutator layer that 4c might reshape.

From 74406310cb5e85d93adaee5e31867e3c0c1d9421 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 15 Sep 2026 11:02:07 +0000
Subject: [PATCH 20/24] Cut the root package off sdk/mpr (Phase 4a gate)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

modelsdk.go — the published library's root API — had Reader and Writer as type
ALIASES to sdk/mpr, so the documented entry point was the legacy serializer.
That was the single biggest gate on deleting it.

Open and OpenForWriting now return a backend.FullBackend from the codec engine.
Repointed all 14 root-package importers: cmd/mxcli/marketplace (7 files),
cmd/mxcli (4), and both examples. Close becomes Disconnect; the two places
typing *modelsdk.Reader/Writer take backend.FullBackend.

Two methods were needed to do it without a bypass:

- ExportJSON on the codec backend. Pure fan-out over the backend's own List*
  methods, so it cannot drift from what every other reader reports. Its only
  caller was examples/read_project holding a concrete sdk/mpr reader, which is
  why it sat on the census — the probe now says LIVE, so it is struck off by
  closing the bypass rather than by deleting the method. Census 6 -> 5.
- AddRawUnit on RawUnitBackend. The marketplace transplant copies a module's
  units between projects verbatim, and copying verbatim is the point: decoding
  and re-encoding would mint fresh identities, and an entity's GUID is what the
  runtime keys the database on.

A behaviour difference found by RUNNING the example, not by any test:
CreateEntity and CreateAssociation left the caller's element holding an EMPTY
id, so the next call failed with "entity not found: " — note the blank after
the colon. The legacy writer populated these. assignID only fills an empty id,
so api/ was unaffected (its builders pre-assign one), which is exactly why the
green suite never saw it. copyAssignedIDs writes the minted ids back, matching
attributes BY NAME rather than by index: entityToGen can add, skip or reorder
(an audit pseudo-type becomes a generalization, not an attribute), so an
index-based copy would hand the caller another attribute's identity — which
looks like it worked and is worse than the empty id.

Both examples run end to end against a fixture and their writes verified in the
model: 6, 3 and 2 attributes land where every one of them used to error.

Gates: build, vet (incl. -tags integration), go test ./..., check-mdl (543),
check-findings. The ID fix has a revert control that fails with the reported
symptom, and a companion test that a caller-assigned id survives — without it
the test would pass against an implementation that overwrites every id and
breaks api/.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hifgRSawfaRWXS44YKtSJ
---
 .../fix-issue/findings/mdl-backend.jsonl      |   1 +
 cmd/mxcli/cmd_describe.go                     |   2 +-
 cmd/mxcli/cmd_fix.go                          |   2 +-
 cmd/mxcli/cmd_marketplace_install.go          |   5 +-
 cmd/mxcli/marketplace/grants.go               |   4 +-
 cmd/mxcli/marketplace/identity.go             |  15 +--
 cmd/mxcli/marketplace/scratch.go              |   6 +-
 cmd/mxcli/marketplace/scratch_test.go         |   5 +-
 cmd/mxcli/marketplace/security_test.go        |  10 +-
 cmd/mxcli/marketplace/theme.go                |   8 +-
 cmd/mxcli/marketplace/transplant.go           |  11 +-
 cmd/mxcli/marketplace/update.go               |   8 +-
 cmd/mxcli/marketplace_compat.go               |   2 +-
 examples/modify_project/main.go               |  17 ++-
 examples/read_project/main.go                 |   2 +-
 mdl/backend/infrastructure.go                 |  12 ++
 mdl/backend/mcp/unsupported_gen.go            |   5 +
 mdl/backend/mock/backend.go                   |   1 +
 mdl/backend/mock/mock_infrastructure.go       |   7 ++
 .../domainmodel_attribute_alter_test.go       | 114 ++++++++++++++++++
 mdl/backend/modelsdk/domainmodel_write.go     |  45 +++++++
 mdl/backend/modelsdk/export_json.go           |  75 ++++++++++++
 mdl/backend/modelsdk/export_json_test.go      |  73 +++++++++++
 mdl/backend/modelsdk/unimplemented_gen.go     |   4 +
 .../unimplemented_reachability_test.go        |   7 +-
 mdl/backend/modelsdk/units.go                 |  16 +++
 modelsdk.go                                   |  48 +++++---
 27 files changed, 436 insertions(+), 69 deletions(-)
 create mode 100644 mdl/backend/modelsdk/export_json.go
 create mode 100644 mdl/backend/modelsdk/export_json_test.go

diff --git a/.claude/skills/fix-issue/findings/mdl-backend.jsonl b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
index 6471c04b24..485cef6ddf 100644
--- a/.claude/skills/fix-issue/findings/mdl-backend.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
@@ -100,3 +100,4 @@
 {"area":"mdl/backend","date":"2026-09-15","symptom":"The MCP backend held a concrete *mpr.Reader for its local reads, keeping three methods (GetDomainModelByID, GetWorkflow, ListNavigationDocuments) on FullBackend with no caller through a backend value — and 190 tests in the package, not one of which called Connect, so swapping the reader underneath it would have landed unverified with the suite green.","cause":"Those three reads had no codec-backend implementation, so MCP could not compose a backend and kept a legacy reader instead. Each was a re-keying or widening of a read the package already did, not new decoding.","file":"mdl/backend/mcp/backend.go","fix":"Implemented the three on the codec backend (mdl/backend/modelsdk/mcp_bypass_reads.go), sharing domainModelFromGen / workflowFromGen / navProfileFromGen with their siblings; added Backend.ConnectReadOnly and pointed MCP's reader field at backend.FullBackend. Wrote mdl/backend/mcp/connect_reads_test.go — the first test to call Connect at all.","insight":"A test can be vacuous in two different ways in one file, and the second is the one you miss. The read-only assertion SKIPPED (MyFirstModule has no entities), which the runner prints — so it was obvious. The GetWorkflow assertion looped over the listing and the fixture has ZERO workflows, so the loop body never ran and the test reported PASS having called nothing. Same failure class as #808, but silent. The fixes differ by shape: for the skip, pick a probe needing nothing pre-existing (CreateEntity, not AddAttribute); for the empty loop, SEED the thing through a read-write backend, then reconnect read-only and assert a specific named item is in the listing BEFORE fetching it — that guard is what converts a future vacuous pass into a failure. Cheapest way to find both: print the counts a test loops over before trusting it. MCP's read-only constraint also has a real control: revert ConnectReadOnly to Connect and the write-refusal test fails with the reported symptom, and the companion TestConnect_TheSameWriteSucceedsReadWrite proves the probe write is not failing for an unrelated reason."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"Deleting the legacy sdk/mpr backend (mdl/backend/mpr) turned up three things the removal plan had not sized: a runtime error telling users to rerun on the engine that had just been deleted, an integration suite that had been exercising the retired engine rather than the default one, and a cross-engine parity test whose comparison became vacuous.","cause":"Each is a reference to the second engine that was invisible while two engines existed. errUnimplemented's message named MXCLI_ENGINE=legacy as the fallback; setupTestEnv in mdl/executor/roundtrip_helpers_test.go hardcoded mprbackend.New() as its default, so most of the package's integration tests ran on legacy; TestODataService_EngineWriteParity compared writer A's key set against writer B's.","file":"mdl/backend/modelsdk/backend.go","fix":"errUnimplemented now asks for a bug report instead of naming a fallback. setupTestEnv defaults to the codec backend. The parity test keeps its value assertion (a published OData service retains AllowedModuleRoles) and drops the comparison, renamed to match. --engine/MXCLI_ENGINE kept as a warning-only no-op; `bson compare` and mdl/enginecompare deleted.","insight":"Deleting one of two implementations is not finished when the code compiles — grep for the deleted thing in three places the compiler cannot reach. (1) RUNTIME STRINGS: an error message naming a removed fallback is strictly worse than no fallback, because the user follows it and gets a second failure; this one had been shipping the instruction 'rerun with MXCLI_ENGINE=legacy' from 19 generated stubs. (2) TEST DEFAULTS: a shared setup helper's hardcoded choice of implementation decides what a whole package actually covers, and here it silently pointed most of mdl/executor's integration tests at the engine being retired — deleting the other one moved them onto the default engine for the first time, which is coverage gained, not lost. (3) DIFFERENTIAL TESTS: a test that compares A to B has no meaning with one implementation, but the PROPERTY it was a means to usually does — for the OData one, that a service keeps its role grants, which mx check reports as 0 errors either way. Drop the comparison, keep the property, rename the file so the next reader is not misled. One counter-case worth noting: the doctype gate's engine MATRIX was kept at one entry rather than collapsed, because its selection function still converts a stale MXCLI_TEST_ENGINES=legacy into a loud failure instead of a gate that selects zero engines and reports success."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"Six FullBackend methods sat on the unreachable census being treated as abstraction bypasses awaiting a port, when nothing anywhere wanted them: the whole WidgetSerializationBackend interface (SerializeWidget/ClientAction/DataSource/WorkflowActivity), GetUnitTypes and UpdateLayout. They had been superseded and simply never removed.","cause":"scripts/backend-reachability.sh reports DEAD for 'nothing calls this through a backend value', and that one verdict covers three different situations. The census header read all of them as bypasses, so the standing instruction was to port them — which for these would have meant implementing methods with no caller.","file":"mdl/backend/mutation.go","fix":"Deleted WidgetSerializationBackend, GetUnitTypes and UpdateLayout from the interface; regenerated unimplemented_gen.go and mcp/unsupported_gen.go (276 -> 270 methods); dropped the mock stubs and a duplicate *Backend impl. Census 11 -> 6, and the remaining six are genuine bypasses. Rewrote the census header and the probe script's own header to name the three causes.","insight":"A reachability probe that removes a method and rebuilds answers ONE question — is anything calling this through the interface — and DEAD has three causes wanting opposite fixes: BYPASS (a caller wants it but holds a concrete type; port the caller), ORPHAN (no caller anywhere; delete), DUPLICATE (callers exist but through a narrower package-local interface with a DIFFERENT SIGNATURE; delete). The probe cannot separate them; a grep for callers under any type can. DUPLICATE is the one that misleads, and it is worth knowing its two tells. First, a raw call-site count looks healthy — SerializeWidget had 6 and SerializeClientAction 4 — so the name reads as live; only comparing signatures shows the interface copy is unused (bson.D on the real path vs (any, error) on FullBackend). Second, the supersession is usually DOCUMENTED at the replacement, not at the corpse: WidgetBuilderBackend.SerializeWidgetToOpaque says 'This replaces the direct mpr.SerializeWidget call' — so grepping the NEW method's doc comment finds the old one faster than auditing the old one does. A stale comment on the dead method actively lies (the vestigial *Backend SerializeWorkflowActivity claimed the ALTER WORKFLOW paths used it; they use codecWorkflowDeps). Generalisable: when a helper has both an (any, error) and a concrete-typed variant, suspect the general-typed one is the abandoned interface obligation."}
+{"area":"mdl/backend","date":"2026-09-15","symptom":"Backend.CreateEntity and CreateAssociation left the caller's semantic element holding an EMPTY ID, so the very next call failed with \"entity not found: \" (note the blank). The legacy writer had populated them, so this was a silent behaviour difference across the engine swap that no test caught.","cause":"assignEntityIDs/assignAssociationIDs mint identities on the gen element built by entityToGen/assocToGen, and nothing copied them back to the *domainmodel.Entity the caller passed in. assignID only fills an EMPTY id, so api/ was unaffected (its builders pre-assign one) — which is exactly why no existing test saw it.","file":"mdl/backend/modelsdk/domainmodel_write.go","fix":"copyAssignedIDs writes the minted entity and attribute ids back onto the caller's element, matching attributes BY NAME rather than by position; CreateAssociation does the same for its own id. Both only fill an empty id, so a caller-assigned one is preserved.","insight":"Found by RUNNING examples/modify_project after repointing it, not by any test — the unit suite, check-mdl and the whole integration gate were green. That is the argument for keeping example programs runnable and actually running them: an example is the only caller that uses the API the way an outside user would, with no pre-assigned ids and no knowledge of internals. Two specifics worth carrying. (1) The empty-string ID makes the error message read \"entity not found: \" with nothing after the colon — a trailing-blank in an error is a strong tell that an identity was never populated rather than looked up and missed. (2) When copying minted ids back, match sub-elements BY NAME, never by index: entityToGen can add, skip or reorder (an audit pseudo-type becomes a System-module generalization, not an attribute), so an index-based copy hands the caller ANOTHER attribute's identity — which looks like it worked and is worse than the empty id it replaced. The control matters here too: a test that only asserts 'id is non-empty' passes against an implementation that overwrites a caller-assigned id, which would break api/; assert the reported id equals the STORED one, and add a companion test that a pre-assigned id survives."}
diff --git a/cmd/mxcli/cmd_describe.go b/cmd/mxcli/cmd_describe.go
index 2a6b1747af..7b4b63da0a 100644
--- a/cmd/mxcli/cmd_describe.go
+++ b/cmd/mxcli/cmd_describe.go
@@ -468,7 +468,7 @@ func resolveViaReader(projectPath, name string) ([]string, error) {
 	if err != nil {
 		return nil, err
 	}
-	defer reader.Close()
+	defer reader.Disconnect()
 
 	var out []string
 	// Top-level documents (microflow, page, snippet, enumeration, ...).
diff --git a/cmd/mxcli/cmd_fix.go b/cmd/mxcli/cmd_fix.go
index e018c04e46..79d1efbcfd 100644
--- a/cmd/mxcli/cmd_fix.go
+++ b/cmd/mxcli/cmd_fix.go
@@ -108,7 +108,7 @@ func runFixTool(cmd *cobra.Command, subcommand, what string) error {
 		return fmt.Errorf("open project: %w", err)
 	}
 	mendixVer, _ := reader.GetMendixVersion()
-	_ = reader.Close()
+	_ = reader.Disconnect()
 
 	mxPath, err := docker.ResolveMxForVersion(mxOverride, mendixVer)
 	if err != nil {
diff --git a/cmd/mxcli/cmd_marketplace_install.go b/cmd/mxcli/cmd_marketplace_install.go
index 406d2c2521..83a8838eeb 100644
--- a/cmd/mxcli/cmd_marketplace_install.go
+++ b/cmd/mxcli/cmd_marketplace_install.go
@@ -17,6 +17,7 @@ import (
 	"github.com/mendixlabs/mxcli/cmd/mxcli/docker"
 	mp "github.com/mendixlabs/mxcli/cmd/mxcli/marketplace"
 	"github.com/mendixlabs/mxcli/internal/marketplace"
+	"github.com/mendixlabs/mxcli/mdl/backend"
 	"github.com/spf13/cobra"
 )
 
@@ -169,7 +170,7 @@ func installModule(ctx context.Context, client *marketplace.Client, v *marketpla
 	}
 	existing, installedVer := findModule(reader, moduleName)
 	mendixVer, _ := reader.GetMendixVersion()
-	_ = reader.Close()
+	_ = reader.Disconnect()
 
 	if existing {
 		// Postponed: do NOT auto-update modules — see the module-update memory.
@@ -297,7 +298,7 @@ func reportFormatChange(mprPath string, out io.Writer) {
 
 // findModule reports whether a marketplace-sourced module of the given name is
 // present, and its installed AppStore version.
-func findModule(reader *modelsdk.Reader, name string) (found bool, appStoreVersion string) {
+func findModule(reader backend.FullBackend, name string) (found bool, appStoreVersion string) {
 	mods, err := reader.ListModules()
 	if err != nil {
 		return false, ""
diff --git a/cmd/mxcli/marketplace/grants.go b/cmd/mxcli/marketplace/grants.go
index 38786784b2..31c2920410 100644
--- a/cmd/mxcli/marketplace/grants.go
+++ b/cmd/mxcli/marketplace/grants.go
@@ -47,7 +47,7 @@ func CaptureRoleGrants(mprPath, moduleName string) (RoleGrants, error) {
 	if err != nil {
 		return nil, fmt.Errorf("open %s: %w", mprPath, err)
 	}
-	defer reader.Close()
+	defer reader.Disconnect()
 
 	sec, err := reader.GetProjectSecurity()
 	if err != nil {
@@ -126,7 +126,7 @@ func moduleRoleNames(mprPath, moduleName string) (map[string]bool, error) {
 	if err != nil {
 		return nil, fmt.Errorf("open %s: %w", mprPath, err)
 	}
-	defer reader.Close()
+	defer reader.Disconnect()
 
 	mods, err := reader.ListModules()
 	if err != nil {
diff --git a/cmd/mxcli/marketplace/identity.go b/cmd/mxcli/marketplace/identity.go
index 25d2970179..5685d21797 100644
--- a/cmd/mxcli/marketplace/identity.go
+++ b/cmd/mxcli/marketplace/identity.go
@@ -8,6 +8,7 @@ import (
 	"strings"
 
 	modelsdk "github.com/mendixlabs/mxcli"
+	"github.com/mendixlabs/mxcli/mdl/backend"
 	"github.com/mendixlabs/mxcli/mdl/types"
 	"github.com/mendixlabs/mxcli/model"
 	"go.mongodb.org/mongo-driver/bson"
@@ -54,7 +55,7 @@ func CaptureIdentities(mprPath, moduleName string) (Identities, error) {
 	if err != nil {
 		return nil, fmt.Errorf("open %s: %w", mprPath, err)
 	}
-	defer reader.Close()
+	defer reader.Disconnect()
 
 	units, err := reader.ListUnits()
 	if err != nil {
@@ -128,7 +129,7 @@ func nameAndGUID(d bson.D) (name string, guid []byte, hasGUID bool) {
 
 // unitsOfModule returns the IDs of every unit contained in the named module,
 // directly or through any depth of folders.
-func unitsOfModule(reader *modelsdk.Reader, units []*types.UnitInfo, moduleName string) ([]string, error) {
+func unitsOfModule(reader backend.FullBackend, units []*types.UnitInfo, moduleName string) ([]string, error) {
 	parent := make(map[string]string, len(units))
 	for _, u := range units {
 		parent[string(u.ID)] = string(u.ContainerID)
@@ -200,12 +201,12 @@ func ApplyIdentities(mprPath, moduleName string, ids Identities) (applied int, m
 	}
 	units, err := reader.ListUnits()
 	if err != nil {
-		reader.Close()
+		reader.Disconnect()
 		return 0, nil, fmt.Errorf("list units: %w", err)
 	}
 	inModule, err := unitsOfModule(reader, units, moduleName)
 	if err != nil {
-		reader.Close()
+		reader.Disconnect()
 		return 0, nil, err
 	}
 
@@ -231,13 +232,13 @@ func ApplyIdentities(mprPath, moduleName string, ids Identities) (applied int, m
 		}
 		encoded, merr := bson.Marshal(doc)
 		if merr != nil {
-			reader.Close()
+			reader.Disconnect()
 			return 0, nil, fmt.Errorf("re-encode unit %s: %w", unitID, merr)
 		}
 		writes = append(writes, pending{unitID, encoded})
 		applied += n
 	}
-	reader.Close()
+	reader.Disconnect()
 
 	for _, p := range ids.Paths() {
 		if !placed[p] {
@@ -252,7 +253,7 @@ func ApplyIdentities(mprPath, moduleName string, ids Identities) (applied int, m
 	if err != nil {
 		return 0, nil, fmt.Errorf("open %s for writing: %w", mprPath, err)
 	}
-	defer writer.Close()
+	defer writer.Disconnect()
 	for _, w := range writes {
 		if err := writer.UpdateRawUnit(w.id, w.contents); err != nil {
 			return 0, nil, fmt.Errorf("write identities into unit %s: %w", w.id, err)
diff --git a/cmd/mxcli/marketplace/scratch.go b/cmd/mxcli/marketplace/scratch.go
index 5772be7c3e..0dda7e7a0c 100644
--- a/cmd/mxcli/marketplace/scratch.go
+++ b/cmd/mxcli/marketplace/scratch.go
@@ -33,7 +33,7 @@ func InstalledModule(mprPath, moduleName string) (appStoreVersion, mendixVersion
 	if err != nil {
 		return "", "", fmt.Errorf("open %s: %w", mprPath, err)
 	}
-	defer reader.Close()
+	defer reader.Disconnect()
 
 	mendixVersion, _ = reader.GetMendixVersion()
 
@@ -88,7 +88,7 @@ func ModuleForVersionIDs(mprPath string, versionIDs []string) (moduleName, versi
 	if err != nil {
 		return "", "", fmt.Errorf("open %s: %w", mprPath, err)
 	}
-	defer reader.Close()
+	defer reader.Disconnect()
 
 	mods, err := reader.ListModules()
 	if err != nil {
@@ -405,7 +405,7 @@ func verifyProjectVersion(mprPath, want string) error {
 		return fmt.Errorf("open reference project: %w", err)
 	}
 	got, _ := reader.GetMendixVersion()
-	_ = reader.Close()
+	_ = reader.Disconnect()
 
 	if got == want {
 		return nil
diff --git a/cmd/mxcli/marketplace/scratch_test.go b/cmd/mxcli/marketplace/scratch_test.go
index 687975a01b..1f1e52d620 100644
--- a/cmd/mxcli/marketplace/scratch_test.go
+++ b/cmd/mxcli/marketplace/scratch_test.go
@@ -7,9 +7,10 @@ import (
 	"testing"
 
 	modelsdk "github.com/mendixlabs/mxcli"
+	"github.com/mendixlabs/mxcli/mdl/backend"
 )
 
-func openFixture(mprPath string) (*modelsdk.Reader, error) { return modelsdk.Open(mprPath) }
+func openFixture(mprPath string) (backend.FullBackend, error) { return modelsdk.Open(mprPath) }
 
 // Version UUIDs read from the live marketplace API, cross-checked against what
 // a blank Mendix 11.12.1 project records for the module each one installs. They
@@ -152,7 +153,7 @@ func listFixtureModules(t *testing.T, mprPath string) []fixtureModule {
 	if err != nil {
 		t.Fatalf("open fixture: %v", err)
 	}
-	defer reader.Close()
+	defer reader.Disconnect()
 
 	mods, err := reader.ListModules()
 	if err != nil {
diff --git a/cmd/mxcli/marketplace/security_test.go b/cmd/mxcli/marketplace/security_test.go
index 1325e0af05..6f585582b7 100644
--- a/cmd/mxcli/marketplace/security_test.go
+++ b/cmd/mxcli/marketplace/security_test.go
@@ -172,7 +172,7 @@ func stripLastMemberAccess(t *testing.T, mprPath, moduleName, entityName string)
 	}
 	units, err := reader.ListRawUnitsByType("DomainModels$DomainModel")
 	if err != nil {
-		reader.Close()
+		reader.Disconnect()
 		t.Fatalf("list domain models: %v", err)
 	}
 
@@ -209,13 +209,13 @@ func stripLastMemberAccess(t *testing.T, mprPath, moduleName, entityName string)
 		}
 		enc, merr := bson.Marshal(doc)
 		if merr != nil {
-			reader.Close()
+			reader.Disconnect()
 			t.Fatalf("re-encode domain model: %v", merr)
 		}
 		unitID, contents = string(u.ID), enc
 		break
 	}
-	reader.Close()
+	reader.Disconnect()
 
 	if unitID == "" || removed == "" {
 		t.Fatalf("no populated access rule found on %s.%s to strip", moduleName, entityName)
@@ -224,7 +224,7 @@ func stripLastMemberAccess(t *testing.T, mprPath, moduleName, entityName string)
 	if err != nil {
 		t.Fatalf("open %s for writing: %v", mprPath, err)
 	}
-	defer writer.Close()
+	defer writer.Disconnect()
 	if err := writer.UpdateRawUnit(unitID, contents); err != nil {
 		t.Fatalf("write domain model: %v", err)
 	}
@@ -240,7 +240,7 @@ func memberRefs(t *testing.T, mprPath, moduleName, entityName string) []string {
 	if err != nil {
 		t.Fatalf("open %s: %v", mprPath, err)
 	}
-	defer reader.Close()
+	defer reader.Disconnect()
 	units, err := reader.ListRawUnitsByType("DomainModels$DomainModel")
 	if err != nil {
 		t.Fatalf("list domain models: %v", err)
diff --git a/cmd/mxcli/marketplace/theme.go b/cmd/mxcli/marketplace/theme.go
index aaca4fc2de..b94f517ddf 100644
--- a/cmd/mxcli/marketplace/theme.go
+++ b/cmd/mxcli/marketplace/theme.go
@@ -86,7 +86,7 @@ func clearThemeModuleFlag(mprPath string) (bool, error) {
 	}
 	units, err := reader.ListRawUnitsByType("Projects$ModuleImpl")
 	if err != nil {
-		_ = reader.Close()
+		_ = reader.Disconnect()
 		return false, fmt.Errorf("read the package's module document: %w", err)
 	}
 
@@ -118,12 +118,12 @@ func clearThemeModuleFlag(mprPath string) (bool, error) {
 		}
 		encoded, err := bson.Marshal(doc)
 		if err != nil {
-			_ = reader.Close()
+			_ = reader.Disconnect()
 			return false, fmt.Errorf("re-encode the module document: %w", err)
 		}
 		edits = append(edits, edit{id: string(u.ID), contents: encoded})
 	}
-	_ = reader.Close()
+	_ = reader.Disconnect()
 
 	if len(edits) == 0 {
 		return false, nil
@@ -133,7 +133,7 @@ func clearThemeModuleFlag(mprPath string) (bool, error) {
 	if err != nil {
 		return false, fmt.Errorf("open the package's project model for writing: %w", err)
 	}
-	defer writer.Close()
+	defer writer.Disconnect()
 	for _, e := range edits {
 		if err := writer.UpdateRawUnit(e.id, e.contents); err != nil {
 			return false, fmt.Errorf("clear the theme-module flag: %w", err)
diff --git a/cmd/mxcli/marketplace/transplant.go b/cmd/mxcli/marketplace/transplant.go
index 017e3bf0ef..7e9436bba7 100644
--- a/cmd/mxcli/marketplace/transplant.go
+++ b/cmd/mxcli/marketplace/transplant.go
@@ -8,6 +8,7 @@ import (
 	"strings"
 
 	modelsdk "github.com/mendixlabs/mxcli"
+	"github.com/mendixlabs/mxcli/mdl/backend"
 	"github.com/mendixlabs/mxcli/model"
 )
 
@@ -38,7 +39,7 @@ func TransplantModule(srcMpr, dstMpr, moduleName string) (copied int, err error)
 	if err != nil {
 		return 0, fmt.Errorf("open source %s: %w", srcMpr, err)
 	}
-	defer src.Close()
+	defer src.Disconnect()
 
 	srcUnits, err := src.ListUnits()
 	if err != nil {
@@ -87,7 +88,7 @@ func TransplantModule(srcMpr, dstMpr, moduleName string) (copied int, err error)
 	if err != nil {
 		return 0, fmt.Errorf("open destination %s for writing: %w", dstMpr, err)
 	}
-	defer writer.Close()
+	defer writer.Disconnect()
 
 	for _, id := range order {
 		u := byID[id]
@@ -122,7 +123,7 @@ func containsStr(haystack []string, needle string) bool {
 	return false
 }
 
-func moduleUnitIDOf(reader *modelsdk.Reader, moduleName string) (string, error) {
+func moduleUnitIDOf(reader backend.FullBackend, moduleName string) (string, error) {
 	mods, err := reader.ListModules()
 	if err != nil {
 		return "", err
@@ -142,7 +143,7 @@ func projectUnitID(mprPath string) (string, error) {
 	if err != nil {
 		return "", fmt.Errorf("open %s: %w", mprPath, err)
 	}
-	defer reader.Close()
+	defer reader.Disconnect()
 
 	units, err := reader.ListUnits()
 	if err != nil {
@@ -164,7 +165,7 @@ func refuseIfPresent(mprPath, moduleName string) error {
 	if err != nil {
 		return fmt.Errorf("open %s: %w", mprPath, err)
 	}
-	defer reader.Close()
+	defer reader.Disconnect()
 
 	mods, err := reader.ListModules()
 	if err != nil {
diff --git a/cmd/mxcli/marketplace/update.go b/cmd/mxcli/marketplace/update.go
index dae0d2fba7..0f09cdcb45 100644
--- a/cmd/mxcli/marketplace/update.go
+++ b/cmd/mxcli/marketplace/update.go
@@ -227,7 +227,7 @@ func StampMarketplaceVersion(mprPath, moduleName, versionNumber, versionID strin
 	}
 	units, err := reader.ListRawUnitsByType("Projects$ModuleImpl")
 	if err != nil {
-		reader.Close()
+		reader.Disconnect()
 		return fmt.Errorf("read module documents: %w", err)
 	}
 
@@ -247,13 +247,13 @@ func StampMarketplaceVersion(mprPath, moduleName, versionNumber, versionID strin
 		setBoolField(doc, "FromAppStore", true)
 		enc, merr := bson.Marshal(doc)
 		if merr != nil {
-			reader.Close()
+			reader.Disconnect()
 			return fmt.Errorf("re-encode module document: %w", merr)
 		}
 		unitID, contents = string(u.ID), enc
 		break
 	}
-	reader.Close()
+	reader.Disconnect()
 
 	if unitID == "" {
 		return fmt.Errorf("module %q not found when stamping its version", moduleName)
@@ -262,7 +262,7 @@ func StampMarketplaceVersion(mprPath, moduleName, versionNumber, versionID strin
 	if err != nil {
 		return fmt.Errorf("open %s for writing: %w", mprPath, err)
 	}
-	defer writer.Close()
+	defer writer.Disconnect()
 	return writer.UpdateRawUnit(unitID, contents)
 }
 
diff --git a/cmd/mxcli/marketplace_compat.go b/cmd/mxcli/marketplace_compat.go
index 8cba679bad..baeb9dc987 100644
--- a/cmd/mxcli/marketplace_compat.go
+++ b/cmd/mxcli/marketplace_compat.go
@@ -17,7 +17,7 @@ func mendixVersionOf(mprPath string) string {
 	if err != nil {
 		return ""
 	}
-	defer reader.Close()
+	defer reader.Disconnect()
 	v, _ := reader.GetMendixVersion()
 	return v
 }
diff --git a/examples/modify_project/main.go b/examples/modify_project/main.go
index 8e08d420c7..8aafa56456 100644
--- a/examples/modify_project/main.go
+++ b/examples/modify_project/main.go
@@ -11,6 +11,7 @@ import (
 	"os"
 
 	"github.com/mendixlabs/mxcli"
+	"github.com/mendixlabs/mxcli/mdl/backend"
 	"github.com/mendixlabs/mxcli/model"
 )
 
@@ -30,14 +31,12 @@ func main() {
 		fmt.Printf("Error opening MPR file: %v\n", err)
 		os.Exit(1)
 	}
-	defer writer.Close()
+	defer writer.Disconnect()
 
-	reader := writer.Reader()
-
-	fmt.Printf("Opened: %s\n", reader.Path())
+	fmt.Printf("Opened: %s\n", writer.Path())
 
 	// Get the first module's domain model
-	modules, err := reader.ListModules()
+	modules, err := writer.ListModules()
 	if err != nil || len(modules) == 0 {
 		fmt.Println("No modules found")
 		os.Exit(1)
@@ -46,7 +45,7 @@ func main() {
 	targetModule := modules[0]
 	fmt.Printf("Working with module: %s\n", targetModule.Name)
 
-	dm, err := reader.GetDomainModel(targetModule.ID)
+	dm, err := writer.GetDomainModel(targetModule.ID)
 	if err != nil {
 		fmt.Printf("Error getting domain model: %v\n", err)
 		os.Exit(1)
@@ -215,7 +214,7 @@ func main() {
 }
 
 // ExampleBuildComplexDomainModel demonstrates building a more complex domain model
-func ExampleBuildComplexDomainModel(writer *modelsdk.Writer, domainModelID modelsdk.ID) {
+func ExampleBuildComplexDomainModel(writer backend.FullBackend, domainModelID modelsdk.ID) {
 	// Create Product entity
 	product := modelsdk.NewEntity("Product")
 	product.Attributes = []*modelsdk.Attribute{
@@ -260,7 +259,7 @@ func ExampleBuildComplexDomainModel(writer *modelsdk.Writer, domainModelID model
 }
 
 // ExampleCreateEnumeration demonstrates creating an enumeration
-func ExampleCreateEnumeration(writer *modelsdk.Writer, moduleID modelsdk.ID) {
+func ExampleCreateEnumeration(writer backend.FullBackend, moduleID modelsdk.ID) {
 	orderStatus := &modelsdk.Enumeration{
 		Name:          "OrderStatus",
 		Documentation: "Possible statuses for an order",
@@ -279,7 +278,7 @@ func ExampleCreateEnumeration(writer *modelsdk.Writer, moduleID modelsdk.ID) {
 }
 
 // ExampleCreateConstant demonstrates creating a constant
-func ExampleCreateConstant(writer *modelsdk.Writer, moduleID modelsdk.ID) {
+func ExampleCreateConstant(writer backend.FullBackend, moduleID modelsdk.ID) {
 	maxOrdersPerDay := &modelsdk.Constant{
 		Name:            "MaxOrdersPerDay",
 		Documentation:   "Maximum number of orders a customer can place per day",
diff --git a/examples/read_project/main.go b/examples/read_project/main.go
index 3fc1c8bf34..08cfeb0f6c 100644
--- a/examples/read_project/main.go
+++ b/examples/read_project/main.go
@@ -53,7 +53,7 @@ func main() {
 		fmt.Printf("Error opening MPR file: %v\n", err)
 		os.Exit(1)
 	}
-	defer reader.Close()
+	defer reader.Disconnect()
 
 	fmt.Printf("Opened: %s\n", reader.Path())
 	fmt.Printf("MPR Version: %d\n", reader.Version())
diff --git a/mdl/backend/infrastructure.go b/mdl/backend/infrastructure.go
index 64646d0405..1e96d116fc 100644
--- a/mdl/backend/infrastructure.go
+++ b/mdl/backend/infrastructure.go
@@ -24,6 +24,18 @@ type RawUnitBackend interface {
 	ListRawUnits(objectType string) ([]*types.RawUnitInfo, error)
 	GetRawUnitByName(objectType, qualifiedName string) (*types.RawUnitInfo, error)
 	GetRawMicroflowByName(qualifiedName string) ([]byte, error)
+	// AddRawUnit inserts a new unit with the given contents.
+	//
+	// The raw counterpart to the typed Create* methods, for a caller copying
+	// units it does not decode — the marketplace module transplant moves a
+	// whole module's units between projects verbatim, which is the point: a
+	// decode and re-encode would rewrite identities the runtime keys on (see
+	// CLAUDE.md on GUIDs).
+	//
+	// Takes strings (not model.ID) to match the writer layer convention, as
+	// UpdateRawUnit does.
+	AddRawUnit(unitID, containerID, containmentName, unitType string, contents []byte) error
+
 	// UpdateRawUnit replaces the contents of a unit by ID.
 	// Takes string (not model.ID) to match the SDK writer layer convention.
 	UpdateRawUnit(unitID string, contents []byte) error
diff --git a/mdl/backend/mcp/unsupported_gen.go b/mdl/backend/mcp/unsupported_gen.go
index 06258da69b..929833b4e2 100644
--- a/mdl/backend/mcp/unsupported_gen.go
+++ b/mdl/backend/mcp/unsupported_gen.go
@@ -45,6 +45,11 @@ func (unsupportedBackend) AddNavigationProfile(_ model.ID, _ string) (err0 error
 	return
 }
 
+func (unsupportedBackend) AddRawUnit(_ string, _ string, _ string, _ string, _ []uint8) (err0 error) {
+	err0 = errUnsupported("AddRawUnit")
+	return
+}
+
 func (unsupportedBackend) AddUserRole(_ model.ID, _ string, _ []string, _ bool) (err0 error) {
 	err0 = errUnsupported("AddUserRole")
 	return
diff --git a/mdl/backend/mock/backend.go b/mdl/backend/mock/backend.go
index 63efdeefaf..30a8874d80 100644
--- a/mdl/backend/mock/backend.go
+++ b/mdl/backend/mock/backend.go
@@ -307,6 +307,7 @@ type MockBackend struct {
 	ListRawUnitsFunc          func(objectType string) ([]*types.RawUnitInfo, error)
 	GetRawUnitByNameFunc      func(objectType, qualifiedName string) (*types.RawUnitInfo, error)
 	GetRawMicroflowByNameFunc func(qualifiedName string) ([]byte, error)
+	AddRawUnitFunc            func(unitID, containerID, containmentName, unitType string, contents []byte) error
 	UpdateRawUnitFunc         func(unitID string, contents []byte) error
 	// UpdateRawUnitOwningTranslationsFunc stubs the write path that is
 	// authoritative about a unit's translations. Falls back to UpdateRawUnitFunc
diff --git a/mdl/backend/mock/mock_infrastructure.go b/mdl/backend/mock/mock_infrastructure.go
index 98b409d7a0..33db30ee4d 100644
--- a/mdl/backend/mock/mock_infrastructure.go
+++ b/mdl/backend/mock/mock_infrastructure.go
@@ -276,3 +276,10 @@ func (m *MockBackend) DeleteAgentEditorAgent(id string) error {
 	}
 	return fmt.Errorf("MockBackend.DeleteAgentEditorAgent not configured")
 }
+
+func (m *MockBackend) AddRawUnit(unitID, containerID, containmentName, unitType string, contents []byte) error {
+	if m.AddRawUnitFunc != nil {
+		return m.AddRawUnitFunc(unitID, containerID, containmentName, unitType, contents)
+	}
+	return fmt.Errorf("MockBackend.AddRawUnit not configured")
+}
diff --git a/mdl/backend/modelsdk/domainmodel_attribute_alter_test.go b/mdl/backend/modelsdk/domainmodel_attribute_alter_test.go
index 195c9ccd71..72ece4f33d 100644
--- a/mdl/backend/modelsdk/domainmodel_attribute_alter_test.go
+++ b/mdl/backend/modelsdk/domainmodel_attribute_alter_test.go
@@ -227,3 +227,117 @@ func sameStrings(a, b []string) bool {
 	}
 	return true
 }
+
+// CreateEntity must report the identities it mints.
+//
+// assignEntityIDs fills them on the gen element; without copying them back, a
+// caller that did not pre-assign an ID holds an entity with an empty one, and
+// its very next call fails with "entity not found: ". The legacy writer
+// populated these, so this was a silent behaviour difference across the engine
+// swap rather than a design choice — found by running examples/modify_project,
+// not by any test, which is why the example is worth keeping runnable.
+func TestCreateEntity_ReportsMintedIDs(t *testing.T) {
+	b := New()
+	if err := b.Connect(copyFixture(t)); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	mod, err := b.GetModuleByName("MyFirstModule")
+	if err != nil || mod == nil {
+		t.Fatalf("GetModuleByName: %v", err)
+	}
+	dm, err := b.GetDomainModel(mod.ID)
+	if err != nil {
+		t.Fatalf("GetDomainModel: %v", err)
+	}
+
+	ent := &domainmodel.Entity{Name: "ZzMintHost", Persistable: true}
+	ent.Attributes = append(ent.Attributes,
+		&domainmodel.Attribute{Name: "Alpha", Type: &domainmodel.StringAttributeType{Length: 200}},
+		&domainmodel.Attribute{Name: "Beta", Type: &domainmodel.IntegerAttributeType{}},
+	)
+	if err := b.CreateEntity(dm.ID, ent); err != nil {
+		t.Fatalf("CreateEntity: %v", err)
+	}
+
+	if ent.ID == "" {
+		t.Fatal("entity ID is still empty after CreateEntity — the caller cannot address what it just made")
+	}
+	for _, a := range ent.Attributes {
+		if a.ID == "" {
+			t.Errorf("attribute %q has no ID after CreateEntity", a.Name)
+		}
+	}
+
+	// The reported IDs must be the STORED ones, not merely non-empty: an ID
+	// that does not match storage is worse than an empty one, because the next
+	// call fails in a way that looks like data loss rather than a missing value.
+	stored, err := b.GetDomainModel(mod.ID)
+	if err != nil {
+		t.Fatalf("GetDomainModel (read-back): %v", err)
+	}
+	var found *domainmodel.Entity
+	for _, e := range stored.Entities {
+		if e.Name == "ZzMintHost" {
+			found = e
+		}
+	}
+	if found == nil {
+		t.Fatal("the created entity is not in storage")
+	}
+	if found.ID != ent.ID {
+		t.Errorf("reported entity ID %s, stored is %s", ent.ID, found.ID)
+	}
+	storedAttr := map[string]string{}
+	for _, a := range found.Attributes {
+		storedAttr[a.Name] = string(a.ID)
+	}
+	for _, a := range ent.Attributes {
+		if got := storedAttr[a.Name]; got != string(a.ID) {
+			t.Errorf("attribute %q: reported %s, stored %s", a.Name, a.ID, got)
+		}
+	}
+
+	// The reported ID is usable, which is the whole point.
+	if err := b.AddAttribute(dm.ID, ent.ID, &domainmodel.Attribute{
+		Name: "Gamma", Type: &domainmodel.BooleanAttributeType{},
+	}); err != nil {
+		t.Errorf("AddAttribute with the reported entity ID failed: %v — "+
+			"this is the exact call examples/modify_project could not make", err)
+	}
+}
+
+// The control: a caller that DOES pre-assign an ID keeps it. Without this, the
+// test above would pass against an implementation that overwrites every ID,
+// which would break api/'s builders (they mint their own before calling).
+func TestCreateEntity_KeepsCallerAssignedID(t *testing.T) {
+	b := New()
+	if err := b.Connect(copyFixture(t)); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	mod, _ := b.GetModuleByName("MyFirstModule")
+	dm, err := b.GetDomainModel(mod.ID)
+	if err != nil {
+		t.Fatalf("GetDomainModel: %v", err)
+	}
+
+	const chosen = "11111111-2222-3333-4444-555555555555"
+	ent := &domainmodel.Entity{Name: "ZzPreAssigned", Persistable: true}
+	ent.ID = model.ID(chosen)
+	if err := b.CreateEntity(dm.ID, ent); err != nil {
+		t.Fatalf("CreateEntity: %v", err)
+	}
+	if string(ent.ID) != chosen {
+		t.Errorf("caller-assigned ID was overwritten: %s", ent.ID)
+	}
+
+	stored, _ := b.GetDomainModel(mod.ID)
+	for _, e := range stored.Entities {
+		if e.Name == "ZzPreAssigned" && string(e.ID) != chosen {
+			t.Errorf("stored ID %s, caller chose %s", e.ID, chosen)
+		}
+	}
+}
diff --git a/mdl/backend/modelsdk/domainmodel_write.go b/mdl/backend/modelsdk/domainmodel_write.go
index 09536b08b7..3b477f2080 100644
--- a/mdl/backend/modelsdk/domainmodel_write.go
+++ b/mdl/backend/modelsdk/domainmodel_write.go
@@ -69,6 +69,11 @@ func (b *Backend) CreateAssociation(domainModelID model.ID, assoc *domainmodel.A
 	}
 	ga := assocToGen(assoc)
 	assignAssociationIDs(ga)
+	// Same contract as CreateEntity: report the minted identity rather than
+	// leaving the caller holding an empty one.
+	if assoc.ID == "" {
+		assoc.ID = model.ID(ga.ID())
+	}
 	dm.AddAssociations(ga)
 
 	contents, err := (&codec.Encoder{}).Encode(dm)
@@ -165,6 +170,13 @@ func (b *Backend) CreateEntity(domainModelID model.ID, entity *domainmodel.Entit
 	}
 	ge := entityToGen(entity, b.moduleNameFor(domainModelID), b.majorVersion())
 	assignEntityIDs(ge)
+	// Report the minted identities back to the caller. assignEntityIDs fills
+	// them on the gen element, so a caller that did not pre-assign an ID is
+	// otherwise left holding an entity with an empty one — and its very next
+	// call (AddAttribute, CreateAssociation) fails with "entity not found: ".
+	// The legacy writer populated these, so not doing it is a silent behaviour
+	// difference rather than a design choice; examples/modify_project caught it.
+	copyAssignedIDs(entity, ge)
 	dm.AddEntities(ge)
 
 	enc := &codec.Encoder{}
@@ -895,3 +907,36 @@ func deleteErrorText(db *domainmodel.DeleteBehavior) *model.Text {
 	}
 	return &model.Text{Translations: map[string]string{"en_US": msg}}
 }
+
+// copyAssignedIDs writes the identities minted on a gen entity back onto the
+// semantic entity the caller passed in.
+//
+// Attributes are matched BY NAME rather than by position: entityToGen may add,
+// skip or reorder elements (an audit pseudo-type becomes a System-module
+// generalization, not an attribute), so an index-based copy would hand the
+// caller another attribute's identity — a worse failure than the empty ID it
+// replaces, because it looks like it worked.
+func copyAssignedIDs(dst *domainmodel.Entity, src *genDm.Entity) {
+	if dst == nil || src == nil {
+		return
+	}
+	if dst.ID == "" {
+		dst.ID = model.ID(src.ID())
+	}
+	byName := map[string]element.ID{}
+	for _, el := range src.AttributesItems() {
+		a, ok := el.(*genDm.Attribute)
+		if !ok {
+			continue
+		}
+		byName[a.Name()] = a.ID()
+	}
+	for _, attr := range dst.Attributes {
+		if attr == nil || attr.ID != "" {
+			continue
+		}
+		if id, ok := byName[attr.Name]; ok {
+			attr.ID = model.ID(id)
+		}
+	}
+}
diff --git a/mdl/backend/modelsdk/export_json.go b/mdl/backend/modelsdk/export_json.go
new file mode 100644
index 0000000000..90bf5ebc40
--- /dev/null
+++ b/mdl/backend/modelsdk/export_json.go
@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+// ExportJSON was the last FullBackend method whose only caller was
+// examples/read_project holding a concrete sdk/mpr reader — the bypass that kept
+// the root package (modelsdk.go) on the legacy serializer. Implementing it here
+// is what lets that example use a backend value, which is the legitimate way an
+// entry leaves unimplemented_reachability_test.go's census: by closing the
+// bypass, not by deleting the method.
+//
+// It is pure fan-out over this backend's own List* methods — no decoding of its
+// own — so it cannot drift from what every other reader reports.
+
+import (
+	"encoding/json"
+)
+
+// ExportJSON renders the project's main document types as one indented JSON
+// object.
+//
+// A section whose listing fails is emitted as null rather than aborting the
+// export, matching the legacy reader's behaviour. That is deliberate for a
+// debugging/inspection dump: a project with one unreadable document type should
+// still tell you about the other seven. It does mean a null section is
+// ambiguous between "failed to read" and "genuinely empty" — callers needing
+// that distinction should use the individual List* methods, which return errors.
+func (b *Backend) ExportJSON() ([]byte, error) {
+	// Each listing is independent; a failure yields a nil section.
+	modules, err := b.ListModules()
+	if err != nil {
+		modules = nil
+	}
+	domainModels, err := b.ListDomainModels()
+	if err != nil {
+		domainModels = nil
+	}
+	microflowsList, err := b.ListMicroflows()
+	if err != nil {
+		microflowsList = nil
+	}
+	nanoflows, err := b.ListNanoflows()
+	if err != nil {
+		nanoflows = nil
+	}
+	pagesList, err := b.ListPages()
+	if err != nil {
+		pagesList = nil
+	}
+	layouts, err := b.ListLayouts()
+	if err != nil {
+		layouts = nil
+	}
+	enumerations, err := b.ListEnumerations()
+	if err != nil {
+		enumerations = nil
+	}
+	constants, err := b.ListConstants()
+	if err != nil {
+		constants = nil
+	}
+
+	// Key names are the legacy reader's, so an existing consumer of this dump
+	// keeps working across the engine swap.
+	return json.MarshalIndent(map[string]any{
+		"modules":      modules,
+		"domainModels": domainModels,
+		"microflows":   microflowsList,
+		"nanoflows":    nanoflows,
+		"pages":        pagesList,
+		"layouts":      layouts,
+		"enumerations": enumerations,
+		"constants":    constants,
+	}, "", "  ")
+}
diff --git a/mdl/backend/modelsdk/export_json_test.go b/mdl/backend/modelsdk/export_json_test.go
new file mode 100644
index 0000000000..7d7f879a27
--- /dev/null
+++ b/mdl/backend/modelsdk/export_json_test.go
@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+// ExportJSON is fan-out, so the interesting failures are not in the assembly —
+// they are a section that is silently empty because a listing returned nothing,
+// which looks identical to a project that genuinely has none of that type.
+// These pin the keys and pin that the sections carry real content on a fixture
+// known to have it.
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func exportSections(t *testing.T) map[string]json.RawMessage {
+	t.Helper()
+	b := New()
+	if err := b.Connect(copyFixture(t)); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	data, err := b.ExportJSON()
+	if err != nil {
+		t.Fatalf("ExportJSON: %v", err)
+	}
+	var out map[string]json.RawMessage
+	if err := json.Unmarshal(data, &out); err != nil {
+		t.Fatalf("ExportJSON produced invalid JSON: %v", err)
+	}
+	return out
+}
+
+// The key set is the legacy reader's, so a consumer of this dump survives the
+// engine swap. A renamed or dropped key is a silent break for anyone parsing it.
+func TestExportJSON_KeySet(t *testing.T) {
+	got := exportSections(t)
+
+	want := []string{"modules", "domainModels", "microflows", "nanoflows",
+		"pages", "layouts", "enumerations", "constants"}
+	for _, k := range want {
+		if _, ok := got[k]; !ok {
+			t.Errorf("section %q is missing", k)
+		}
+	}
+	if len(got) != len(want) {
+		t.Errorf("got %d sections, want %d: %v", len(got), len(want), got)
+	}
+}
+
+// THE test that is not vacuous. Every section is nil-on-error, so an export
+// where each listing failed is still valid JSON with all eight keys — and would
+// pass the key-set test above. The fixture has modules, domain models,
+// microflows, nanoflows and pages, so those five must carry content.
+func TestExportJSON_SectionsAreNotEmpty(t *testing.T) {
+	got := exportSections(t)
+
+	// Layouts, enumerations and constants are deliberately excluded: the
+	// fixture's counts are not guaranteed, and asserting on a section that
+	// happens to be empty would make this test fail for the wrong reason.
+	for _, k := range []string{"modules", "domainModels", "microflows", "nanoflows", "pages"} {
+		var items []json.RawMessage
+		if err := json.Unmarshal(got[k], &items); err != nil {
+			t.Errorf("section %q is not an array (%s) — a failed listing serialises as null", k, got[k])
+			continue
+		}
+		if len(items) == 0 {
+			t.Errorf("section %q is empty; the fixture has %s, so the listing failed "+
+				"and was swallowed by the nil-on-error path", k, k)
+		}
+	}
+}
diff --git a/mdl/backend/modelsdk/unimplemented_gen.go b/mdl/backend/modelsdk/unimplemented_gen.go
index ce5f628e99..43f6f7907a 100644
--- a/mdl/backend/modelsdk/unimplemented_gen.go
+++ b/mdl/backend/modelsdk/unimplemented_gen.go
@@ -41,6 +41,10 @@ func (unimplemented) AddNavigationProfile(_ model.ID, _ string) error {
 	return errUnimplemented("AddNavigationProfile")
 }
 
+func (unimplemented) AddRawUnit(_ string, _ string, _ string, _ string, _ []uint8) error {
+	return errUnimplemented("AddRawUnit")
+}
+
 func (unimplemented) AddUserRole(_ model.ID, _ string, _ []string, _ bool) error {
 	return errUnimplemented("AddUserRole")
 }
diff --git a/mdl/backend/modelsdk/unimplemented_reachability_test.go b/mdl/backend/modelsdk/unimplemented_reachability_test.go
index 2f63650cd7..8a73ffa310 100644
--- a/mdl/backend/modelsdk/unimplemented_reachability_test.go
+++ b/mdl/backend/modelsdk/unimplemented_reachability_test.go
@@ -18,7 +18,9 @@
 //     the abstraction, which makes the method reachable and therefore worth
 //     implementing. AddAttribute and UpdateAttribute left the list this way when
 //     api/ was ported; GetDomainModelByID, GetWorkflow and ListNavigationDocuments
-//     when the MCP backend composed this one for its reads.
+//     when the MCP backend composed this one for its reads; ExportJSON when the
+//     root package (modelsdk.go) stopped aliasing sdk/mpr and examples/
+//     read_project moved onto a backend value (Phase 4a).
 //  2. ORPHAN — nothing anywhere calls it, under any type. There is no bypass to
 //     close, so the fix is to DELETE it from the interface.
 //  3. DUPLICATE — callers exist, but through a narrower package-local interface
@@ -64,7 +66,7 @@ import (
 // that hold a concrete *mpr.Reader / *mpr.Writer (the api/ package, examples/,
 // and cmd/mxcli commands that open a reader directly) — none of which route
 // through this engine.
-// Every remaining entry is a BYPASS, and all six are the same kind of caller:
+// Every remaining entry is a BYPASS, and all five are the same kind of caller:
 // a raw-unit debugging or export command that holds a concrete reader on
 // purpose. ACCEPTED as deliberate rather than queued for porting (2026-09-15,
 // closing Phase 3 of docs/plans/2026-09-14-retire-legacy-engine.md) — routing a
@@ -77,7 +79,6 @@ import (
 // FullBackend that nothing calls — establish which (see the three causes above)
 // rather than adding a row to match the failure.
 var unreachableUnimplemented = map[string]string{
-	"ExportJSON":               "BYPASS, accepted: examples/read_project calls it on the sdk reader",
 	"FindCustomWidgetType":     "BYPASS, accepted: cmd/mxcli/cmd_extract_templates.go holds a concrete reader",
 	"FindAllCustomWidgetTypes": "BYPASS, accepted: reached only via the reader, inside modelsdk/mpr itself",
 	"GetProjectRootID":         "BYPASS, accepted: callers hold a reader; this package uses b.reader.GetProjectRootID directly",
diff --git a/mdl/backend/modelsdk/units.go b/mdl/backend/modelsdk/units.go
index d223f8968d..ca1fddf5a6 100644
--- a/mdl/backend/modelsdk/units.go
+++ b/mdl/backend/modelsdk/units.go
@@ -3,6 +3,8 @@
 package modelsdkbackend
 
 import (
+	"fmt"
+
 	"github.com/mendixlabs/mxcli/mdl/types"
 	"github.com/mendixlabs/mxcli/model"
 )
@@ -83,3 +85,17 @@ func (b *Backend) ListFolders() ([]*types.FolderInfo, error) {
 	}
 	return out, nil
 }
+
+// AddRawUnit inserts a new unit verbatim.
+//
+// Exposed on the backend because the marketplace transplant copies a module's
+// units between projects without decoding them, and had been reaching a
+// concrete sdk/mpr writer to do it. Copying verbatim is deliberate rather than
+// lazy: decoding and re-encoding would mint fresh identities, and an entity's
+// GUID is what the runtime keys the database on (CLAUDE.md).
+func (b *Backend) AddRawUnit(unitID, containerID, containmentName, unitType string, contents []byte) error {
+	if b.writer == nil {
+		return fmt.Errorf("AddRawUnit: not connected for writing")
+	}
+	return b.writer.InsertUnit(unitID, containerID, containmentName, unitType, contents)
+}
diff --git a/modelsdk.go b/modelsdk.go
index a4377486a1..79d32714bd 100644
--- a/modelsdk.go
+++ b/modelsdk.go
@@ -21,20 +21,19 @@
 //
 //	import (
 //	    "fmt"
-//	    "github.com/mendixlabs/mxcli"
-//	    "github.com/mendixlabs/mxcli/sdk/mpr"
+//	    modelsdk "github.com/mendixlabs/mxcli"
 //	)
 //
 //	func main() {
 //	    // Open a Mendix project
-//	    reader, err := mpr.Open("/path/to/MyApp.mpr")
+//	    project, err := modelsdk.Open("/path/to/MyApp.mpr")
 //	    if err != nil {
 //	        panic(err)
 //	    }
-//	    defer reader.Close()
+//	    defer project.Disconnect()
 //
 //	    // List all modules
-//	    modules, err := reader.ListModules()
+//	    modules, err := project.ListModules()
 //	    if err != nil {
 //	        panic(err)
 //	    }
@@ -116,10 +115,12 @@
 package modelsdk
 
 import (
+	"github.com/mendixlabs/mxcli/mdl/backend"
+	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
 	"github.com/mendixlabs/mxcli/model"
+	mmpr "github.com/mendixlabs/mxcli/modelsdk/mpr"
 	"github.com/mendixlabs/mxcli/sdk/domainmodel"
 	"github.com/mendixlabs/mxcli/sdk/microflows"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
 	"github.com/mendixlabs/mxcli/sdk/pages"
 )
 
@@ -175,22 +176,31 @@ type (
 
 	// Snippet represents a page snippet.
 	Snippet = pages.Snippet
-
-	// Reader provides methods to read Mendix project files.
-	Reader = mpr.Reader
-
-	// Writer provides methods to write Mendix project files.
-	Writer = mpr.Writer
 )
 
-// Open opens an MPR file for reading.
-func Open(path string) (*Reader, error) {
-	return mpr.Open(path)
+// Open opens a Mendix project for reading.
+//
+// The returned backend is the one every part of mxcli uses; call Disconnect
+// when done. It replaces a `*mpr.Reader` from the legacy serializer — see the
+// note on connections in this package's doc comment.
+func Open(path string) (backend.FullBackend, error) {
+	b := modelsdkbackend.New()
+	if err := b.ConnectReadOnly(path); err != nil {
+		return nil, err
+	}
+	return b, nil
 }
 
-// OpenForWriting opens an MPR file for reading and writing.
-func OpenForWriting(path string) (*Writer, error) {
-	return mpr.NewWriter(path)
+// OpenForWriting opens a Mendix project for reading and writing.
+//
+// Prefer the fluent builders in the api package for anything beyond a few
+// calls: api.Open(path) wraps this and adds the entity/microflow/page builders.
+func OpenForWriting(path string) (backend.FullBackend, error) {
+	b := modelsdkbackend.New()
+	if err := b.Connect(path); err != nil {
+		return nil, err
+	}
+	return b, nil
 }
 
 // NewStringAttribute creates a new string attribute.
@@ -302,5 +312,5 @@ func NewPage(name string) *Page {
 
 // GenerateID generates a new unique ID for model elements.
 func GenerateID() ID {
-	return ID(mpr.GenerateID())
+	return ID(mmpr.GenerateID())
 }

From ccd92a2f0e0bf91bcc0c8bb696b593b504d9de45 Mon Sep 17 00:00:00 2001
From: Ako <andrej@koelewijn.net>
Date: Tue, 15 Sep 2026 11:47:46 +0000
Subject: [PATCH 21/24] feat(workflow): event sub-processes and notification
 events
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 4a of PROPOSAL_workflow_studio_pro_constructs.md. Three workflow
constructs only Studio Pro could author become MDL:

  event subprocess <name> ['<caption>'] on [non] interrupting notification|timer … { … };
  notification <name> [comment '<caption>'];
  boundary event [non] interrupting notification <name> ['<caption>'] { … }

Describe used to leave sub-processes out, print a notification activity as a
comment and drop notification boundary events. The shapes come from ako/TestApp
(Studio Pro 11.14, built over MCP and saved); that document is the reader's
fixture, since gen has no type for the timer starts, the notification activity
or the notification boundary events, which are read off the raw document.

Measured on mxbuild 11.13.0: a sub-process body with no end is CE0105 (the
builder appends the End), a jump across flows CE6682 (MDL-WF05 now scopes jumps
per flow), a timer start with no expression CE0126 (MDL-WF14), two interrupting
boundary events on one activity CE6697 (MDL-WF15), a start named like an
activity CE0495 (names deduplicated across flows). Version gates were measured
by loading each construct into blank 11.10-11.13 projects: notification starts
11.8 (gen; load from 11.10), notification activity and boundary events 11.11,
timer starts 11.13.

The rewrite guard now requires sub-processes and notification activities to be
restated, walks sub-process bodies, and does not count a sub-process's implicit
End. Fixes a silent loss: a rewrite from describe output deleted every
notification activity (measured 1 -> 0 with the previous build).

MCP: sub-processes go into the constructor and a rewrite replaces the stored
ones. Verified live against Studio Pro 11.14, which also showed that the single
user task constructor drops boundary events (notification events are now
re-added after create and update) and that its interrupting constructors
rewrite a boundary path's ending (such notification paths are refused with the
ending Studio Pro needs). Timer boundary events are affected by the same
constructors and are left for a separate change.

ALTER WORKFLOW's insert boundary event refuses notification kinds, which need a
name the op does not carry; the three boundary-event writers now share one
EventType -> $Type map instead of defaulting unknown kinds to an interrupting
timer.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../fix-issue/findings/mdl-executor.jsonl     |   1 +
 .../skills/mendix/write-workflows/SKILL.md    |  57 +++-
 CHANGELOG.md                                  |   6 +
 cmd/mxcli/lsp_completions_gen.go              |   1 +
 cmd/mxcli/syntax/features_workflow.go         |  54 ++-
 docs-site/src/language/workflow-activities.md |  52 +++
 docs/01-project/MDL_QUICK_REFERENCE.md        |   4 +
 ...PROPOSAL_workflow_studio_pro_constructs.md | 120 ++++++-
 .../doctype-tests/24-workflow-examples.mdl    |  68 ++++
 mdl/ast/ast_workflow.go                       |  32 +-
 mdl/backend/mcp/workflow.go                   | 308 +++++++++++++++++-
 mdl/backend/mcp/workflow_esp_test.go          | 276 ++++++++++++++++
 mdl/backend/mcp/workflow_test.go              |   6 +-
 ...tApp.ZzMxcliExample_EventSubProcesses.bson | Bin 0 -> 7070 bytes
 mdl/backend/modelsdk/workflow_esp_test.go     | 219 +++++++++++++
 mdl/backend/modelsdk/workflow_read.go         |  53 +++
 mdl/backend/modelsdk/workflow_write.go        |  72 +++-
 mdl/backend/wfmutator/mutator.go              |  11 +-
 mdl/executor/cmd_alter_workflow.go            |  12 +
 mdl/executor/cmd_workflows.go                 |  80 ++++-
 mdl/executor/cmd_workflows_write.go           | 119 ++++++-
 mdl/executor/validate_workflow.go             |   3 +-
 mdl/executor/validate_workflow_completion.go  |   2 +-
 mdl/executor/validate_workflow_end.go         |  19 +-
 mdl/executor/validate_workflow_esp.go         | 153 +++++++++
 mdl/executor/validate_workflow_jump.go        |  80 +++--
 mdl/executor/validate_workflow_refs.go        |  10 +-
 mdl/executor/validate_workflow_rewrite.go     | 112 ++++++-
 .../validate_workflow_rewrite_test.go         |   2 +-
 mdl/executor/workflow_esp_test.go             | 256 +++++++++++++++
 mdl/grammar/MDLLexer.g4                       |   1 +
 mdl/grammar/domains/MDLSettings.g4            |   2 +-
 mdl/grammar/domains/MDLWorkflow.g4            |  41 ++-
 mdl/visitor/visitor_workflow.go               |  74 ++++-
 mdl/visitor/visitor_workflow_esp_test.go      |  93 ++++++
 sdk/versions/mendix-11.yaml                   |  12 +
 sdk/workflows/workflow.go                     | 122 ++++++-
 37 files changed, 2430 insertions(+), 103 deletions(-)
 create mode 100644 mdl/backend/mcp/workflow_esp_test.go
 create mode 100644 mdl/backend/modelsdk/testdata/TestApp.ZzMxcliExample_EventSubProcesses.bson
 create mode 100644 mdl/backend/modelsdk/workflow_esp_test.go
 create mode 100644 mdl/executor/validate_workflow_esp.go
 create mode 100644 mdl/executor/workflow_esp_test.go
 create mode 100644 mdl/visitor/visitor_workflow_esp_test.go

diff --git a/.claude/skills/fix-issue/findings/mdl-executor.jsonl b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
index b33980d1d7..54f79dc5c5 100644
--- a/.claude/skills/fix-issue/findings/mdl-executor.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
@@ -620,3 +620,4 @@
 {"area": "mdl/executor", "date": "2026-09-14", "symptom": "On the **legacy** engine (MXCLI_ENGINE=legacy), `create or modify workflow` that does not restate stored event handlers / boundary events / nested Ends / AI agent tasks / completion rules is written (\"Created workflow\") and deletes them, while the default modelsdk engine refuses the same statement with the guard-don't-drop list", "cause": "The workflow rewrite guards walk `ctx.Backend.GetRawUnit` with type switches on `map[string]any` / `[]any`. The legacy backend decodes with mongo-driver v1 `bson.Unmarshal` into map[string]any, which yields nested documents as map[string]any but ARRAYS AS `primitive.A` — a named type a `case []any` does not match. So every guard saw no list at all (measured with a probe: `OnWorkflowEvent primitive.A`, `Flow map[string]interface {}`). The modelsdk reader normalizes to plain slices (`modelsdk/mpr/reader_raw.go normalizeBSONValue`), which is why only legacy was blind", "file": "`mdl/executor/validate_workflow_rewrite.go` (`plainRawUnit`, applied in `checkNoDroppedWorkflowConstructs` and `validateAlterReplaceKeepsStudioProState`)", "insight": "A guard tested only with hand-built `[]any` fixtures proves nothing about the legacy engine: build the fixture, then `bson.Marshal` + `bson.Unmarshal` into map[string]any to get the shape legacy's GetRawUnit really returns (`legacyShaped` in validate_workflow_rewrite_legacy_test.go). Normalized in the guard, not in MprBackend.GetRawUnit, because catalog (`builder_regularexpressions.go`) asserts `bson.A` on raw units. Found only by running the e2e rewrite on BOTH engines — the modelsdk run was green. Other `[]any`-only raw walkers (REST body guard, queued-call guard) are suspects of the same class. Control: normalizer returning its input fails the legacy-shape tests"}
 {"area": "mdl/executor", "date": "2026-09-15", "symptom": "`describe workflow` → `create or modify` → `describe` differs: a call microflow authored with `comment 'Summarise'` comes back captioned with the microflow's name (`-- ACT_Summarise`)", "cause": "`formatCallMicroflowTask` printed the caption only as a trailing `-- caption` MDL comment, which the parser discards; re-execution then fell back to the builder's default caption (the microflow's short name)", "file": "`mdl/executor/cmd_workflows.go` (`formatCallMicroflowTask`)", "insight": "A trailing `--` comment in describe output is documentation, not data — anything round-trippable must be a grammar clause. Emit `comment '…'` only when the caption differs from the derived default, matching jump/wait (issuetracker #16), so an unauthored caption does not start appearing as authored. Only an end-to-end describe → exec → describe with an AUTHORED caption catches it; fixtures without captions pass either way"}
 {"area": "mdl/executor", "date": "2026-09-15", "symptom": "`create or modify workflow` over a workflow whose multi-user task needs 3 participants / 80 percent, or waits for all users, succeeds and the task afterwards needs all participants and does not wait — no refusal, `mx check` clean", "cause": "The rebuild writes `TargetUserInput: AllUserInput` and `AwaitAllUsers: false` for every multi-user task, and the guard-don't-drop check (`checkNoDroppedWorkflowConstructs`) only inspected `CompletionCriteria`; TargetUserInput and AwaitAllUsers were neither expressible nor guarded", "file": "`mdl/executor/validate_workflow_rewrite.go` (`rawMultiUserTaskSettings`, `rawReplaceLosses`)", "insight": "When auditing a guard, list every property the rebuild writes as a constant, not just the ones that look like 'configuration' — a constant default in the writer is exactly the set a rewrite silently resets. Found by diffing Studio Pro's saved multi-user task (ako/TestApp) key by key against mxcli's writer while adding completion rules. Once a property becomes authorable, the guard changes from 'cannot express' to 'restated?' (count stored non-defaults vs authored clauses)"}
+{"area":"mdl/executor","date":"2026-09-15","symptom":"`create or modify workflow` from `describe workflow` output deletes every notification activity (`Workflows$NotificationActivity`) and reports \"Created workflow\" — no refusal, `mx check` clean","cause":"The reader had no case for NotificationActivity, so it became a GenericWorkflowActivity that describe prints as a `-- [Workflows$NotificationActivity]` comment; the rewrite guard (`checkNoDroppedWorkflowConstructs`) counted boundary events, ends and sub-processes but not this activity, so nothing noticed it was missing from the statement","file":"`mdl/executor/validate_workflow_rewrite.go` (`countAuthoredNotificationActivities`), `mdl/backend/modelsdk/workflow_read.go` (`workflowSimpleActivityFromGen`)","insight":"A `-- [Workflows$…]` comment in describe output is a guard gap until proven otherwise: whatever describe cannot state, a rewrite from that output deletes. Grep the describer's generic fallback against the guard's counters when adding either. Measured with the previous build on an 11.13 copy: one stored activity, zero after the rewrite; the ESP guard had masked it in the Studio Pro reference workflow, which also held a sub-process."}
diff --git a/.claude/skills/mendix/write-workflows/SKILL.md b/.claude/skills/mendix/write-workflows/SKILL.md
index 2b9f655122..b42d253ba6 100644
--- a/.claude/skills/mendix/write-workflows/SKILL.md
+++ b/.claude/skills/mendix/write-workflows/SKILL.md
@@ -115,6 +115,10 @@ begin
   -- Wait for an external notification (e.g. an event)
   wait for notification waitForNotification1;
 
+  -- An intermediate notification event (Mendix 11.11+): what `notify workflow`
+  -- targets by name
+  notification DocumentsReceived comment 'Documents received';
+
   -- Loop back, or stop the whole workflow, from inside an outcome. A `jump to`
   -- and an `end workflow` must each END their path, so neither can close the
   -- main flow itself (CE6679 / CE6671).
@@ -166,6 +170,48 @@ end workflow;
   an interrupting path is **CE0105** at build, and a non-interrupting one builds
   cleanly and then stops the runtime from starting ("Expected the flow to end with
   an end event"). Use `jump to <task>` when the path should return to the task.
+- **A notification boundary event** (Mendix 11.11+) fires when `notify workflow`
+  targets it, so it takes a **name** instead of a delay:
+  `boundary event interrupting notification Withdrawn 'Request withdrawn' { end workflow; }`.
+  The name is unique in the workflow. Only one interrupting boundary event per
+  activity, of either kind (CE6697, MDL-WF15). `alter workflow … insert boundary
+  event` cannot add one yet — restate the workflow.
+- **Over MCP (`--mcp`), Studio Pro dictates how a notification path ends**, which
+  mxbuild does not: an interrupting one ends in `end workflow;` (in `jump to` inside
+  a parallel split), a non-interrupting one runs to its end. mxcli refuses the
+  other shapes with that remedy, because Studio Pro's constructor would rewrite or
+  reject them.
+
+**Event sub-processes** are flows outside the main flow, written after the main body.
+A notification (11.8+) or a timer (11.13+) starts one while the workflow runs;
+`interrupting` cancels every active path first, `non interrupting` runs alongside:
+
+```sql
+create or modify workflow HR.Leave
+  parameter $Context: HR.Request
+begin
+  user task Review 'Review' page HR.ReviewPage outcomes 'Approve' { } 'Reject' { };
+
+  event subprocess ESP_Cancel 'Cancel request'
+    on interrupting notification espCancelStart 'Cancel received' {
+    call microflow HR.ACT_LogCancel;
+  };
+  event subprocess ESP_Reminder 'Daily reminder'
+    on non interrupting timer 'addDays([%CurrentDateTime%], 1)' as espReminderStart {
+    call microflow HR.ACT_Remind;
+  };
+end workflow;
+```
+
+- **The End is implicit**, as in the main flow: mxcli appends one unless the body
+  already ends (`end workflow`, a `jump to`, or branches that all end). A body with
+  no end is CE0105.
+- **`jump to` stays inside its sub-process** — a jump to its own activities or its
+  start event builds; into another sub-process, or between one and the main flow,
+  is CE6682 (MDL-WF05).
+- **A timer start needs its expression** (CE0126, MDL-WF14).
+- **Names are shared with the main flow**: a start event named like an activity is
+  CE0495, so mxcli makes it unique.
 
 ## DROP WORKFLOW
 
@@ -223,10 +269,8 @@ describing a Studio-Pro-authored workflow, and `describe → drop → exec`
 reproduces a workflow that builds. (The implicit start/end activities are
 omitted, as they are re-synthesised on create.)
 
-**What DESCRIBE still cannot see: event sub-processes.** mxcli has no model for
-them at all, so they do not appear in the output and cannot be written from MDL.
-A workflow that has one can only be edited in Studio Pro or through
-`ALTER WORKFLOW` (below) — never with `CREATE OR REPLACE`.
+Event sub-processes come back as `event subprocess … on …` blocks after the main
+body, and notification activities and notification boundary events as statements.
 
 ## Activity names, and why `jump to` depends on them
 
@@ -259,8 +303,9 @@ workflow that simply no longer does what it did.
 
 mxcli refuses the two cases where that would lose something:
 
-- a stored **event sub-process** — MDL cannot express one, so the rewrite is
-  refused outright;
+- **more stored event sub-processes or notification activities than the statement
+  declares** — restate them; a sub-process with no start event, which MDL cannot
+  state, is refused outright;
 - **more stored boundary events than the statement declares** — restate them and
   the rewrite proceeds, which is what `describe workflow` now emits for you;
 - **more stored workflow event handlers, or user tasks with an on-created
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4648f0badb..0939896e30 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- **Workflow event sub-processes and notification events** (docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md, phase 4) — `event subprocess <name> on [non] interrupting notification|timer … { … };` after the main body, `notification <name>;`, and `boundary event [non] interrupting notification <name> { … }`. Until now `describe workflow` left event sub-processes out, printed a notification activity as a comment and dropped notification boundary events, so a workflow with any of them could only be edited in Studio Pro. The shapes come from ako/TestApp, built in Studio Pro 11.14 and saved; the saved document is the reader's fixture, which matters because gen has no type for the timer starts, the notification activity or the notification boundary events. Measured on mxbuild 11.13.0: a sub-process body with no end is CE0105, so mxcli appends the End as it does for the main flow; a jump into or out of a sub-process is CE6682 (MDL-WF05, which now checks each flow as its own scope); a timer start without its expression is CE0126 (MDL-WF14); two interrupting boundary events on one activity are CE6697 (MDL-WF15); a start event named like an activity is CE0495, so names are made unique across the flows. The version gates were measured by loading each construct alone into a blank project: notification-started sub-processes load from 11.10 (11.8 per gen), the notification activity and boundary events from 11.11, timer-started sub-processes only from 11.13. A rewrite must restate them; `alter workflow … insert boundary event` refuses the notification kinds for now. Over MCP they go into the constructor, and a rewrite replaces the stored sub-processes.
+
 - **Multi-user task completion rules: `participants`, `decide by`, `await all users`** (docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md, phase 3) — how many participants must respond (`all`, a number, a percentage), how their outcomes decide the task (`consensus`, `majority more than half`, `majority most chosen`, `threshold <n> percent|votes`, each with `fallback '<outcome>'`; `veto '<outcome>'`; `microflow M`), and whether it waits for everyone. The shapes were captured from Studio Pro rather than read off gen: the examples were built in Studio Pro 11.14 over MCP, saved to ako/TestApp, and the saved document is now the reader's fixture — which is how "more than half" is known to be an Absolute majority and a percentage threshold a Relative one, and that both outcome pointers hold the outcome's `$ID`. Measured on mxbuild 11.13.0: a fallback is required for consensus, majority and threshold (CE1866) and a veto needs its outcome (CE1867), both refused by `check` as MDL-WF13 along with a name that is none of the task's outcomes; a decision microflow must return String (CE5012), its parameters are free; and the build does **not** range-check thresholds or participant counts, so neither does mxcli. Over MCP the backend works around two constructor quirks it measured: PED's default consensus has no fallback, and a more-than-half majority's fallback is dropped and has to be set by `$ID` afterwards.
 
 - **AI agent tasks in workflows: `call agent microflow`** (docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md, phase 2) — the workflow step that runs an AI agent, which `describe workflow` could only print as a `-- [Workflows$AIAgentTaskActivity]` comment and a rewrite therefore refused. It is the call-microflow statement with `agent` added — same `as`, `comment`, `with (…)`, `outcomes` and boundary events — because Mendix stores exactly the call-microflow shape under a different `$Type` (ako/TestApp, 11.14.0). The rules were measured on mxbuild 11.13.0 by writing each shape as a call microflow and switching only the `$Type`: every shape builds the same except an agent microflow with **no parameters**, which fails **CE1590**, so that is the one new check. Needs Mendix 11.9 (`workflows.ai_agent_task`); describe emits it, and a rewrite that restates it proceeds.
@@ -16,6 +18,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Fixed
 
+- **A workflow rewrite deleted every notification activity without a word.** `describe workflow` printed a `Workflows$NotificationActivity` as a `-- [Workflows$NotificationActivity]` comment and the rewrite guard did not count them, so `create or modify` from that output removed it and reported "Created workflow". Measured with the previous build: one stored, zero after the rewrite. Notification activities are described as statements now, and a rewrite that does not restate them is refused.
+
+- **Over MCP, a user task's notification boundary events would have been lost without a word.** Studio Pro 11.14's single user task constructor drops `boundaryEvents` — at create and when an update adds the task — and reports "No errors found." Measured live; a multi-user task keeps them, and a notification event added afterwards at the task's `boundaryEvents` is stored, so the backend adds them after each create and update when the stored list is empty. Its interrupting constructors also rewrite a boundary path's ending (a `jump to` outside a parallel split becomes an End), so a notification path Studio Pro would rewrite is refused with the ending it needs. Timer boundary events are affected by the same constructors and are not yet handled.
+
 - **Multi-user tasks could not be created over MCP on Studio Pro 11.14.** Its multi-user task constructor takes the page as a `taskPage` element and refused the bare `pageReference` string mxcli sent (`"/flow/activities/1/taskPage":"Expected an object, but the value is missing."`). The backend reads the constructor schema and sends the shape the server declares, as it already did for the workflow's own constructor.
 
 - **A workflow rewrite reset every multi-user task's participant count and "wait for all users" without a word.** The rewrite guard refused a non-default completion rule, but a task needing 3 participants or 80 percent, or one waiting for all users, was rebuilt as "all participants, not waiting" and exec reported success. Both are expressible now, and a rewrite that does not restate them is refused.
diff --git a/cmd/mxcli/lsp_completions_gen.go b/cmd/mxcli/lsp_completions_gen.go
index a657860778..5740127241 100644
--- a/cmd/mxcli/lsp_completions_gen.go
+++ b/cmd/mxcli/lsp_completions_gen.go
@@ -607,6 +607,7 @@ var mdlGeneratedKeywords = []protocol.CompletionItem{
 	{Label: "BOUNDARY", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "INTERRUPTING", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "NON", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "SUBPROCESS", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "MULTI", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "BY", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "READ", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
diff --git a/cmd/mxcli/syntax/features_workflow.go b/cmd/mxcli/syntax/features_workflow.go
index ece59882e3..a7cd1cd714 100644
--- a/cmd/mxcli/syntax/features_workflow.go
+++ b/cmd/mxcli/syntax/features_workflow.go
@@ -378,10 +378,60 @@ func init() {
 		// 'Workflows$TimerBoundaryEvent' could not be found"). This entry showed
 		// the bare form, with 'P3D' — not a valid timer expression — as its delay.
 		// ako/view-entity-examples FINDINGS §7.
-		Syntax:     "-- inline, as a clause of a USER TASK (after OUTCOMES):\nBOUNDARY EVENT (INTERRUPTING | NON INTERRUPTING) TIMER '<datetime-expression>' { <activities> }\n\n-- or add one to an existing task:\nALTER WORKFLOW <wf> INSERT BOUNDARY EVENT ON <task> (INTERRUPTING | NON INTERRUPTING) TIMER '<datetime-expression>' { <activities> }\n\n-- Name the kind: a bare TIMER is refused on Mendix 11 (MDL-WF07) — it writes a\n-- type the runtime cannot load. The delay is an expression that yields a\n-- DateTime, e.g. 'addDays([%CurrentDateTime%], 3)'. mxcli ends every boundary\n-- path with Mendix's end-of-path marker, so a path may end in a call; use\n-- JUMP TO to return to the task instead.",
+		Syntax:     "-- inline, as a clause of a USER TASK (after OUTCOMES):\nBOUNDARY EVENT (INTERRUPTING | NON INTERRUPTING) TIMER '<datetime-expression>' { <activities> }\nBOUNDARY EVENT (INTERRUPTING | NON INTERRUPTING) NOTIFICATION <name> ['<caption>'] { <activities> }\n\n-- A notification boundary event (Mendix 11.11+) is triggered by `notify workflow`\n-- targeting its name, so the name is unique in the workflow. ALTER cannot insert\n-- one yet; restate the workflow instead.\n\n-- or add a timer to an existing task:\nALTER WORKFLOW <wf> INSERT BOUNDARY EVENT ON <task> (INTERRUPTING | NON INTERRUPTING) TIMER '<datetime-expression>' { <activities> }\n\n-- Name the kind: a bare TIMER is refused on Mendix 11 (MDL-WF07) — it writes a\n-- type the runtime cannot load. The delay is an expression that yields a\n-- DateTime, e.g. 'addDays([%CurrentDateTime%], 3)'. mxcli ends every boundary\n-- path with Mendix's end-of-path marker, so a path may end in a call; use\n-- JUMP TO to return to the task instead.",
 		Example:    "user task ReviewTask 'Review'\n  page Module.WF_Review\n  outcomes 'Done' { }\n  boundary event interrupting timer 'addDays([%CurrentDateTime%], 3)' {\n    call microflow Module.WF_Escalate;\n  };",
 		MinVersion: "10.6.0",
-		SeeAlso:    []string{"workflow.user-task"},
+		SeeAlso:    []string{"workflow.user-task", "workflow.notification", "workflow.event-subprocess"},
+	})
+
+	Register(SyntaxFeature{
+		Path:    "workflow.event-subprocess",
+		Summary: "Event sub-processes — flows a notification or timer starts while the workflow runs",
+		Keywords: []string{
+			"event subprocess", "event sub-process", "esp", "cancel workflow",
+			"interrupting", "non interrupting", "notification start", "timer start",
+		},
+		Syntax: "-- after the main body, before END WORKFLOW:\n" +
+			"EVENT SUBPROCESS <name> ['<caption>']\n" +
+			"  ON (INTERRUPTING | NON INTERRUPTING) NOTIFICATION [<start>] ['<start caption>']\n" +
+			"  { <activities> };\n" +
+			"EVENT SUBPROCESS <name> ['<caption>']\n" +
+			"  ON (INTERRUPTING | NON INTERRUPTING) TIMER '<first-execution-time>' [AS <start>] [COMMENT '<start caption>']\n" +
+			"  { <activities> };\n\n" +
+			"-- Interrupting cancels every active path first; non-interrupting runs alongside.\n" +
+			"-- A notification start is what `notify workflow` targets. The body's End is\n" +
+			"-- implicit, as in the main flow; `jump to` stays inside its own sub-process\n" +
+			"-- (CE6682, MDL-WF05). A timer needs its expression (CE0126, MDL-WF14).\n" +
+			"-- Mendix 11.8+ for notification starts, 11.13+ for timer starts.",
+		Example: "create workflow HR.Leave parameter $Ctx: HR.Request\n" +
+			"begin\n" +
+			"  user task Review 'Review' page HR.ReviewPage outcomes 'Approve' { } 'Reject' { };\n" +
+			"  event subprocess ESP_Cancel 'Cancel request'\n" +
+			"    on interrupting notification espCancelStart 'Cancel received' {\n" +
+			"    call microflow HR.ACT_LogCancel;\n" +
+			"  };\n" +
+			"  event subprocess ESP_Reminder 'Daily reminder'\n" +
+			"    on non interrupting timer 'addDays([%CurrentDateTime%], 1)' as espReminderStart {\n" +
+			"    call microflow HR.ACT_Remind;\n" +
+			"  };\n" +
+			"end workflow;",
+		MinVersion: "11.8.0",
+		SeeAlso:    []string{"workflow.notification", "workflow.boundary-event", "workflow.create"},
+	})
+
+	Register(SyntaxFeature{
+		Path:    "workflow.notification",
+		Summary: "Notification activity — an intermediate notification event on a flow",
+		Keywords: []string{
+			"notification", "notification activity", "intermediate event", "notify",
+		},
+		Syntax: "NOTIFICATION [<name>] [COMMENT '<caption>'];\n\n" +
+			"-- The point a `notify workflow` action reaches (Workflows$NotificationActivity,\n" +
+			"-- Mendix 11.11+). `wait for notification` is the older activity for the same\n" +
+			"-- purpose and works on every version.",
+		Example:    "notification DocumentsReceived comment 'Documents received';",
+		MinVersion: "11.11.0",
+		SeeAlso:    []string{"workflow.event-subprocess", "workflow.boundary-event"},
 	})
 
 	Register(SyntaxFeature{
diff --git a/docs-site/src/language/workflow-activities.md b/docs-site/src/language/workflow-activities.md
index 29556f2b1c..d5fbe76490 100644
--- a/docs-site/src/language/workflow-activities.md
+++ b/docs-site/src/language/workflow-activities.md
@@ -217,6 +217,56 @@ Pause the workflow until an external notification resumes it:
 WAIT FOR NOTIFICATION;
 ```
 
+## Notification
+
+An intermediate notification event (Mendix 11.11+): the point a `NOTIFY WORKFLOW` action targets by name.
+
+```sql
+NOTIFICATION [<name>] [COMMENT '<caption>'];
+```
+
+A **notification boundary event** attaches the same trigger to a user task, call microflow or wait. It takes a name instead of a timer delay:
+
+```sql
+USER TASK Review 'Review'
+  PAGE HR.ReviewPage
+  OUTCOMES 'Approve' { } 'Reject' { }
+  BOUNDARY EVENT INTERRUPTING NOTIFICATION Withdrawn 'Request withdrawn' {
+    END WORKFLOW;
+  };
+```
+
+An activity may carry only one interrupting boundary event (CE6697). `ALTER WORKFLOW … INSERT BOUNDARY EVENT` cannot add a notification boundary event yet.
+
+## Event Sub-Processes
+
+A flow outside the main flow, started by its own start event while the workflow runs. Written after the main body, before `END WORKFLOW`:
+
+```sql
+EVENT SUBPROCESS <name> ['<caption>']
+  ON (INTERRUPTING | NON INTERRUPTING) NOTIFICATION [<start>] ['<start caption>']
+  { <activities> };
+
+EVENT SUBPROCESS <name> ['<caption>']
+  ON (INTERRUPTING | NON INTERRUPTING) TIMER '<first-execution-time>' [AS <start>] [COMMENT '<start caption>']
+  { <activities> };
+```
+
+Example:
+
+```sql
+EVENT SUBPROCESS ESP_Cancel 'Cancel request'
+  ON INTERRUPTING NOTIFICATION espCancelStart 'Cancel received' {
+  CALL MICROFLOW HR.ACT_LogCancel;
+};
+```
+
+- **Interrupting** cancels every active path before the sub-process runs; **non-interrupting** runs alongside the main flow.
+- The body's End is implicit, as in the main flow. A body that already ends (in `END WORKFLOW`, a `JUMP TO`, or branches that all end) gets none.
+- A `JUMP TO` must stay inside its own sub-process (CE6682).
+- A timer start needs its expression (CE0126).
+- Versions: notification starts need Mendix 11.8+, timer starts 11.13+.
+
 ## End
 
 Terminate the current workflow path:
@@ -240,6 +290,8 @@ Typically used inside an outcome block to stop the workflow after a rejection or
 | `JUMP TO` | Go to named activity | No |
 | `WAIT FOR TIMER` | Delay execution | Yes |
 | `WAIT FOR NOTIFICATION` | Wait for external signal | Yes |
+| `NOTIFICATION` | Intermediate notification event (11.11+) | Yes |
+| `EVENT SUBPROCESS` | Flow started by a notification or timer (11.8+) | No (runs beside or replaces the main flow) |
 | `END` | Terminate path | N/A |
 
 ## See Also
diff --git a/docs/01-project/MDL_QUICK_REFERENCE.md b/docs/01-project/MDL_QUICK_REFERENCE.md
index 577f0457b9..38aff290e3 100644
--- a/docs/01-project/MDL_QUICK_REFERENCE.md
+++ b/docs/01-project/MDL_QUICK_REFERENCE.md
@@ -677,7 +677,11 @@ Nested folders use `/` separator: `'Parent/Child/Grandchild'`. Missing folders a
 - `jump to <activity-name>;`
 - `wait for timer [<name>] ['<expr>'];`
 - `wait for notification [<name>];`
+- `notification [<name>] [comment '<caption>'];` — an intermediate notification event (Mendix 11.11+)
 - `end workflow [comment '<caption>'];` — only inside a `{ }` block; ends the whole workflow
+- Boundary events, after `outcomes`: `boundary event [non] interrupting timer '<expr>' { … }` or `boundary event [non] interrupting notification <name> ['<caption>'] { … }` (11.11+). One interrupting event per activity (CE6697, MDL-WF15).
+
+**Event sub-processes**, after the main body: `event subprocess <name> ['<caption>'] on [non] interrupting notification [<start>] ['<caption>'] { … };` (11.8+) or `… on [non] interrupting timer '<first-execution-time>' [as <start>] [comment '<caption>'] { … };` (11.13+). The body's End is implicit; a `jump to` stays in its own sub-process (CE6682, MDL-WF05); a timer needs its expression (CE0126, MDL-WF14).
 
 **Workflow event handlers.** `on workflow events (UserTaskStarted, UserTaskEnded)
 microflow Mod.MF as 'Task audit'` in the header runs the microflow for each listed
diff --git a/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md b/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
index 308253cbd3..17accf878b 100644
--- a/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
+++ b/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
@@ -1,6 +1,6 @@
 # Proposal: Workflow constructs only Studio Pro could author
 
-**Status:** Phases 1–3 implemented; phase 4 designed, reference documents captured
+**Status:** Phases 1–3 and 4a (event sub-processes, notification events) implemented; 4b (`notify workflow … target`) designed
 **Date:** 2026-09-14
 
 ## Problem Statement
@@ -17,7 +17,7 @@ the team's workflows reference them:
 | 1 | workflow event handlers | `Workflow.OnWorkflowEvent` → `Workflows$WorkflowEventHandler` | ako/TestApp `workflow.Workflow1` |
 | 2 | AI agent task | `Workflows$AIAgentTaskActivity` | ako/TestApp `workflow.Workflow1` |
 | 3 | multi-user completion rules (majority, threshold, veto, microflow) | `CompletionCriteria` variants | **needed** |
-| 4 | event sub-processes, and `notify workflow` targeting one | `Workflow.EventSubProcesses`, `NotifyWorkflowAction.NotifyTarget` | partial (TestApp has one interrupting notification sub-process) |
+| 4 | event sub-processes, notification events, and `notify workflow` targeting one | `Workflow.EventSubProcesses`, `Workflows$NotificationActivity`, `Workflows$*NotificationBoundaryEvent`, `NotifyWorkflowAction.NotifyTarget` | ako/TestApp `workflow.ZzMxcliExample_EventSubProcesses`, `workflow.ZzMxcliExample_Notify` |
 
 ## Phase 1 — handlers (implemented)
 
@@ -280,15 +280,115 @@ both measured: PED's default is consensus with **no** fallback (CE1866), so mxcl
 always sends one; and the constructor **drops the fallback of a more-than-half
 majority**, so the backend reads the outcome's `$ID` afterwards and sets it.
 
-## Phase 4 — event sub-processes and notify targets
+## Phase 4a — event sub-processes and notification events (implemented)
 
-`Workflow.EventSubProcesses` (11.8.0) holds `Workflows$EventSubProcess` with a
-`Caption`, `Name` and `Flow` whose first activity is an
-`(Non)InterruptingNotificationEventSubProcessStartActivity`. Timer starts appear in
-11.13's event types but have no gen type yet. `NotifyWorkflowAction.notifyTarget`
-(11.7.0) is how a microflow notifies a sub-process start; the MDL `notify workflow`
-statement has no target today. **Needed:** a Studio Pro example with a
-non-interrupting and a timer sub-process, and a microflow that notifies one.
+### Reference documents (ako/TestApp, Studio Pro 11.14.0, built over MCP and saved)
+
+`workflow.ZzMxcliExample_EventSubProcesses` holds one sub-process per start kind,
+a notification activity, and both notification boundary events on a user task:
+
+| Construct | Stored as |
+|---|---|
+| sub-process | `EventSubProcesses` (marker 2) → `Workflows$EventSubProcess{Annotation, Caption, Flow, Name, PersistentId}` |
+| its start | the flow's first activity: `Workflows$(Non)Interrupting(Notification\|Timer)EventSubProcessStartActivity`; a timer adds `FirstExecutionTime` |
+| its end | a closing `Workflows$EndWorkflowActivity`, as in the main flow |
+| notification activity | `Workflows$NotificationActivity{Annotation, Caption, Name, PersistentId, RelativeMiddlePoint, Size}` |
+| notification boundary event | `Workflows$(Non)InterruptingNotificationBoundaryEvent{Annotation, Caption, Flow, Name, PersistentId}` |
+
+gen has no type for the timer starts, the notification activity or the
+notification boundary events; the reader takes them off the raw document, and the
+saved document is its fixture.
+
+### MDL syntax
+
+```sql
+begin
+  notification DocumentsReceived comment 'Documents received';
+  user task Review 'Review' page HR.ReviewPage outcomes 'Approve' { } 'Reject' { }
+    boundary event interrupting notification Withdrawn 'Withdrawn' { end workflow; };
+
+  event subprocess ESP_Cancel 'Cancel request'
+    on interrupting notification espCancelStart 'Cancel received' { … };
+  event subprocess ESP_Reminder 'Daily reminder'
+    on non interrupting timer 'addDays([%CurrentDateTime%], 1)' as espReminderStart { … };
+end workflow;
+```
+
+Sub-processes follow the main body because they are stored beside the flow, not in
+it. The body's End is implicit, like the main flow's.
+
+### Measured (mxbuild 11.13.0, Studio Pro-saved shapes, one construct per workflow)
+
+| Shape | Verdict |
+|---|---|
+| each of the four starts, body ending in End | 0 errors |
+| body with activities; body ending in a jump within the sub-process (also to its start) | 0 errors |
+| body with no end | **CE0105** — the builder appends the End |
+| jump into another sub-process, or between one and the main flow | **CE6682** — MDL-WF05 |
+| timer start with no first execution time | **CE0126** — MDL-WF14 |
+| start event named like another activity | **CE0495** — names deduplicated across flows |
+| boundary-path end marker inside a sub-process | CE6692 (not authorable) |
+| notification boundary event on a user task, multi-user task, call microflow, wait for notification or wait for timer | 0 errors |
+| interrupting notification path ending in the end-of-path marker | 0 errors |
+| interrupting notification path with no end | **CE0105** — the builder appends the marker |
+| two interrupting boundary events on one activity | **CE6697** — MDL-WF15 |
+
+### Versions (each construct loaded alone into a blank project)
+
+| | 11.10 | 11.11 | 11.12 | 11.13 | Gate |
+|---|---|---|---|---|---|
+| notification-started sub-process | loads | loads | loads | loads | `event_subprocesses` 11.8 (gen) |
+| notification activity / boundary events | unknown type | loads | loads | loads | `notification_events` 11.11 |
+| timer-started sub-process | unknown type | unknown type | unknown type | loads | `timer_event_subprocesses` 11.13 |
+
+### Guard
+
+Event sub-processes and notification activities are restate-or-refuse, like
+boundary events; only a sub-process with no start event is refused outright. Every
+counter walks the sub-process bodies, and a sub-process's closing End is not
+counted as a stored `end workflow`. A rewrite from an older describe used to
+delete notification activities silently — measured, 1 → 0 with the previous build.
+`alter workflow … insert boundary event` refuses the notification kinds: the op
+carries no name.
+
+### MCP
+
+The workflow constructor takes `eventSubProcesses`, each flow sent whole. The
+interrupting notification boundary event's constructor requires
+`isInsideOfParallelSplit`, set from the event's position. A rewrite removes the
+stored sub-processes and adds the statement's.
+
+Measured live against Studio Pro 11.14 (`mxcli exec --mcp`, then `ped_check_errors`
+and `ped_read_document`):
+
+| Shape | Result |
+|---|---|
+| notification and timer sub-processes, a jump inside one, a notification activity, an interrupting notification event on a wait ending in `end workflow` | stored as sent, "No errors found." |
+| boundary events on a **single** user task — timer or notification — at create, and at an `add` of the task in an update | **dropped**, "No errors found." (a multi-user task keeps them) |
+| a notification event added afterwards at `<task>/boundaryEvents` | stored |
+| interrupting notification event inside a parallel split, path ending in `jump to` | stored as sent |
+| the same path ending in the end-of-path marker | refused: the constructor appends a jump with no target after it |
+| interrupting **timer** event, path ending in the marker / `end workflow` / `jump to` | End appended after the marker (refused) / stored / **jump replaced by an End**; every one "Missing value for parameter 'Timer'" |
+
+The interrupting constructors normalize the path's terminator — End outside a
+split, jump inside one, removing the other — and the interrupting timer
+constructor has no `firstExecutionTime` at all. mxbuild 11.13 builds every one of
+these paths, so the rules are Studio Pro's. For notification events the MCP
+backend refuses each shape the constructor would rewrite, naming the ending it
+needs, and re-adds a single user task's notification events after every create
+and update. The timer-event losses predate this phase and are tracked separately.
+
+## Phase 4b — notify targets
+
+`NotifyWorkflowAction.NotifyTarget` (11.7.0) names what a microflow notifies:
+`Workflows$(Non)InterruptingNotificationEventSubProcessStartActivityTarget`,
+`NotifyNotificationActivityTarget`, `NotifyWaitForNotificationActivityTarget`
+(each `Activity: "Module.Workflow.name"`) and `NotifyNotificationBoundaryEventTarget`
+(`BoundaryEvent: …`). Reference: ako/TestApp `workflow.ZzMxcliExample_Notify`.
+Syntax: `$Notified = notify workflow $Workflow target HR.Leave.espCancelStart;`.
+Two bugs to fix with it: the reader takes the output variable from gen's
+`VariableName` key where Studio Pro stores `OutputVariableName`, and a rewrite drops
+the target.
 
 ## Test plan (phase 1)
 
diff --git a/mdl-examples/doctype-tests/24-workflow-examples.mdl b/mdl-examples/doctype-tests/24-workflow-examples.mdl
index 8a54c53a50..9e0223f6c3 100644
--- a/mdl-examples/doctype-tests/24-workflow-examples.mdl
+++ b/mdl-examples/doctype-tests/24-workflow-examples.mdl
@@ -724,3 +724,71 @@ begin
     outcomes 'Approve' { } 'Reject' { };
 end workflow;
 /
+
+-- @version: 11.11+
+-- ############################################################################
+-- PART I: NOTIFICATION EVENTS AND EVENT SUB-PROCESSES (Mendix 11.11+)
+-- ############################################################################
+--
+-- A notification activity and a notification boundary event are what `notify
+-- workflow` targets, by name. An event sub-process runs outside the main flow
+-- when its start event fires: interrupting cancels every active path first,
+-- non-interrupting runs alongside. Its End is implicit, like the main flow's.
+
+create microflow WFTest.ACT_LogCancel (
+  $OrderContext: WFTest.OrderContext
+)
+begin
+end;
+/
+
+create workflow WFTest.WithNotifications
+  parameter $OrderContext: WFTest.OrderContext
+begin
+  notification DocumentsReceived comment 'Documents received';
+
+  user task Review 'Review the order'
+    page WFTest.TaskPage
+    outcomes 'Approve' { } 'Reject' { }
+    boundary event interrupting notification Withdrawn 'Order withdrawn' {
+      end workflow;
+    }
+    boundary event non interrupting notification Nudge 'Reminder requested' {
+      call microflow WFTest.ACT_LogCancel with (OrderContext = '$WorkflowContext');
+    };
+
+  event subprocess ESP_Cancel 'Cancel order'
+    on interrupting notification CancelStart 'Cancel received' {
+    call microflow WFTest.ACT_LogCancel with (OrderContext = '$WorkflowContext');
+  };
+
+  event subprocess ESP_Audit 'Audit'
+    on non interrupting notification AuditStart {
+  };
+end workflow;
+/
+
+-- @version: 11.13+
+-- ############################################################################
+-- PART J: TIMER-STARTED EVENT SUB-PROCESSES (Mendix 11.13+)
+-- ############################################################################
+--
+-- A timer start takes its first execution time, which Mendix requires (CE0126).
+
+create workflow WFTest.WithTimerSubProcesses
+  parameter $OrderContext: WFTest.OrderContext
+begin
+  user task Review 'Review the order'
+    page WFTest.TaskPage
+    outcomes 'Approve' { } 'Reject' { };
+
+  event subprocess ESP_Expire 'Expire'
+    on interrupting timer 'addDays([%CurrentDateTime%], 30)' as ExpireStart comment 'After 30 days' {
+  };
+
+  event subprocess ESP_Remind 'Daily reminder'
+    on non interrupting timer 'addDays([%CurrentDateTime%], 1)' as RemindStart {
+    call microflow WFTest.ACT_LogCancel with (OrderContext = '$WorkflowContext');
+  };
+end workflow;
+/
diff --git a/mdl/ast/ast_workflow.go b/mdl/ast/ast_workflow.go
index 8508fe1c86..62f5716faf 100644
--- a/mdl/ast/ast_workflow.go
+++ b/mdl/ast/ast_workflow.go
@@ -28,6 +28,23 @@ type CreateWorkflowStmt struct {
 
 	// Activities
 	Activities []WorkflowActivityNode
+
+	// Event sub-processes, written after the main body.
+	EventSubProcesses []WorkflowEventSubProcessNode
+}
+
+// WorkflowEventSubProcessNode is `event subprocess <name> ['<caption>'] on
+// [non] interrupting notification|timer … { … };`.
+type WorkflowEventSubProcessNode struct {
+	Name         string
+	Caption      string
+	Interrupting bool
+	Timer        bool   // a timer start; otherwise a notification start
+	StartName    string // the start event's name; "" = derived from Name
+	StartCaption string
+	// FirstExecutionTime is a timer start's expression.
+	FirstExecutionTime string
+	Activities         []WorkflowActivityNode
 }
 
 // WorkflowEventHandlerNode is one `on workflow events (…) microflow M as '…'` or
@@ -187,6 +204,15 @@ type WorkflowWaitForNotificationNode struct {
 
 func (n *WorkflowWaitForNotificationNode) workflowActivityNode() {}
 
+// WorkflowNotificationNode is `notification [<name>] [comment '<caption>']`, an
+// intermediate notification event.
+type WorkflowNotificationNode struct {
+	Name    string
+	Caption string
+}
+
+func (n *WorkflowNotificationNode) workflowActivityNode() {}
+
 // WorkflowEndNode is `end workflow [comment '<caption>']` inside a branch: it
 // ends the whole workflow there. The main flow's End is not a node — the body's
 // closing `end workflow` is it.
@@ -207,8 +233,12 @@ func (n *WorkflowReturnNode) workflowActivityNode() {}
 // WorkflowBoundaryEventNode represents a BOUNDARY EVENT clause on a user task.
 // Issue #7
 type WorkflowBoundaryEventNode struct {
-	EventType  string                 // "InterruptingTimer", "NonInterruptingTimer", "Timer"
+	// EventType is "InterruptingTimer", "NonInterruptingTimer", "Timer",
+	// "InterruptingNotification" or "NonInterruptingNotification".
+	EventType  string
 	Delay      string                 // ISO duration expression e.g. "${PT1H}"
+	Name       string                 // notification events: what `notify workflow … target` names
+	Caption    string                 // notification events
 	Activities []WorkflowActivityNode // Sub-flow activities inside the boundary event
 }
 
diff --git a/mdl/backend/mcp/workflow.go b/mdl/backend/mcp/workflow.go
index fc24913e65..76d22330d7 100644
--- a/mdl/backend/mcp/workflow.go
+++ b/mdl/backend/mcp/workflow.go
@@ -5,6 +5,7 @@ package mcp
 import (
 	"encoding/json"
 	"fmt"
+	"sort"
 	"strings"
 
 	"github.com/mendixlabs/mxcli/mdl/backend"
@@ -41,6 +42,9 @@ func (b *Backend) CreateWorkflow(wf *workflows.Workflow) error {
 	if err := b.applyMoreThanHalfFallbacks(moduleName+"."+wf.Name, wf); err != nil {
 		return err
 	}
+	if err := b.applyUserTaskBoundaryEvents(moduleName+"."+wf.Name, wf); err != nil {
+		return err
+	}
 	if contextShape {
 		// The context-shaped constructor has no documentation or description;
 		// both are leaves of the created element.
@@ -83,6 +87,13 @@ func (b *Backend) UpdateWorkflow(wf *workflows.Workflow) error {
 	if err != nil {
 		return err
 	}
+	if err := markNotificationEventsInSplits(flowVal, false); err != nil {
+		return err
+	}
+	esps, err := mapEventSubProcesses(wf.EventSubProcesses)
+	if err != nil {
+		return err
+	}
 	// Replace only the *middle* activities: PED keeps the workflow's structural
 	// Start/End (it refuses to remove them) and auto-positions an index-less add by
 	// activity type, so we strip the executor's leading Start / trailing End and
@@ -126,6 +137,21 @@ func (b *Backend) UpdateWorkflow(wf *workflows.Workflow) error {
 		ops = append(ops, pedOpEntry{Path: "/onWorkflowEvent", Operation: pedOperation{Type: "add", Value: h}})
 	}
 
+	// Event sub-processes: replaced whole, like the handlers — the rewrite guard
+	// has already refused a statement declaring fewer than are stored. Removing a
+	// container (not its start event) is the one-call form Studio Pro's
+	// workflow-update skill allows.
+	if storedESPs, err := b.workflowListCount(qn, "/eventSubProcesses"); err != nil {
+		return err
+	} else {
+		for i := storedESPs - 1; i >= 0; i-- {
+			ops = append(ops, removeAtOp("/eventSubProcesses", i))
+		}
+	}
+	for _, e := range esps {
+		ops = append(ops, pedOpEntry{Path: "/eventSubProcesses", Operation: pedOperation{Type: "add", Value: e}})
+	}
+
 	title := wf.WorkflowName
 	if title == "" {
 		title = wf.Name
@@ -148,6 +174,9 @@ func (b *Backend) UpdateWorkflow(wf *workflows.Workflow) error {
 	if err := b.applyMoreThanHalfFallbacks(qn, wf); err != nil {
 		return err
 	}
+	if err := b.applyUserTaskBoundaryEvents(qn, wf); err != nil {
+		return err
+	}
 	b.markDirty(mod.Name)
 	b.upsertSessionWorkflow(wf)
 	return b.pedCheckDocument(workflowDocType, qn)
@@ -350,6 +379,231 @@ func (b *Backend) mapWorkflowContent(wf *workflows.Workflow, contextShape bool)
 	if err != nil {
 		return nil, err
 	}
+	if err := markNotificationEventsInSplits(flow, false); err != nil {
+		return nil, err
+	}
+	esps, err := mapEventSubProcesses(wf.EventSubProcesses)
+	if err != nil {
+		return nil, err
+	}
+	content, err := b.mapWorkflowContentShape(wf, flow, contextShape)
+	if err != nil {
+		return nil, err
+	}
+	if esps != nil {
+		content["eventSubProcesses"] = esps
+	}
+	return content, nil
+}
+
+// mapEventSubProcesses maps the workflow's event sub-processes onto the
+// constructor's `eventSubProcesses` (ped_get_schema, Studio Pro 11.14). Each flow
+// is sent whole — its start event first — and nil for none so the key is omitted.
+func mapEventSubProcesses(esps []*workflows.EventSubProcess) ([]any, error) {
+	if len(esps) == 0 {
+		return nil, nil
+	}
+	out := make([]any, 0, len(esps))
+	for _, esp := range esps {
+		fm, err := mapWorkflowFlowValue(esp.Flow)
+		if err != nil {
+			return nil, err
+		}
+		if fm == nil {
+			fm = map[string]any{"$Type": "Workflows$Flow", "activities": []any{}}
+		}
+		if err := markNotificationEventsInSplits(fm, false); err != nil {
+			return nil, err
+		}
+		out = append(out, map[string]any{
+			"$Type":   "Workflows$EventSubProcess",
+			"name":    esp.Name,
+			"caption": esp.Caption,
+			"flow":    fm,
+		})
+	}
+	return out, nil
+}
+
+// markNotificationEventsInSplits sets `isInsideOfParallelSplit`, which PED's
+// interrupting notification boundary event constructor requires, on every such
+// event in a mapped flow: true when it sits under a parallel split at any depth.
+//
+// It also refuses a notification boundary path the constructor would rewrite. Its
+// schema says, and Studio Pro 11.14 does, that an interrupting event's path is
+// forced to end in an End — or in a jump inside a split — by removing the other
+// terminator and appending its own; a non-interrupting path must end in the
+// end-of-path marker. Measured: a `jump to` outside a split is stored as an End,
+// and a path ending in the marker gets a second terminator appended and is
+// refused. mxbuild builds all of these, so the rules are Studio Pro's; each shape
+// is refused here with the remedy rather than rewritten or rejected after sending.
+func markNotificationEventsInSplits(v any, inSplit bool) error {
+	switch t := v.(type) {
+	case map[string]any:
+		typ, _ := t["$Type"].(string)
+		switch typ {
+		case "Workflows$InterruptingNotificationBoundaryEvent":
+			t["isInsideOfParallelSplit"] = inSplit
+			switch last := mappedFlowLastType(t["flow"]); {
+			case inSplit && last != "Workflows$JumpToActivity":
+				return fmt.Errorf("boundary event %v: over MCP, Studio Pro requires an interrupting notification boundary event inside a "+
+					"parallel split to end its path with `jump to <activity>` — its constructor appends a jump with no target otherwise", t["name"])
+			case !inSplit && last != "Workflows$EndWorkflowActivity":
+				return fmt.Errorf("boundary event %v: over MCP, Studio Pro requires an interrupting notification boundary event outside a "+
+					"parallel split to end its path with `end workflow;` — its constructor replaces a jump with an End, and refuses a path ending otherwise", t["name"])
+			}
+		case "Workflows$NonInterruptingNotificationBoundaryEvent":
+			if last := mappedFlowLastType(t["flow"]); last != "Workflows$EndOfBoundaryEventPathActivity" {
+				return fmt.Errorf("boundary event %v: over MCP, Studio Pro requires a non-interrupting notification boundary event's path "+
+					"to run to its end — remove the final `jump to`", t["name"])
+			}
+		}
+		childInSplit := inSplit || typ == "Workflows$ParallelSplitActivity"
+		keys := make([]string, 0, len(t))
+		for k := range t {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		for _, k := range keys {
+			if err := markNotificationEventsInSplits(t[k], childInSplit); err != nil {
+				return err
+			}
+		}
+	case []any:
+		for _, e := range t {
+			if err := markNotificationEventsInSplits(e, inSplit); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+// mappedFlowLastType returns the $Type of a mapped flow's last activity, "" for none.
+func mappedFlowLastType(flow any) string {
+	f, _ := flow.(map[string]any)
+	acts, _ := f["activities"].([]any)
+	if len(acts) == 0 {
+		return ""
+	}
+	last, _ := acts[len(acts)-1].(map[string]any)
+	typ, _ := last["$Type"].(string)
+	return typ
+}
+
+// taskBoundaryEvents is a single user task's boundary events, found at a PED path.
+type taskBoundaryEvents struct {
+	events  []*workflows.BoundaryEvent
+	inSplit bool
+}
+
+// singleUserTaskBoundaryEvents collects, by PED path, every single user task that
+// carries boundary events, at any depth of a flow.
+func singleUserTaskBoundaryEvents(flow *workflows.Flow, base string, inSplit bool, out map[string]taskBoundaryEvents) {
+	if flow == nil {
+		return
+	}
+	for i, a := range flow.Activities {
+		path := fmt.Sprintf("%s/%d", base, i)
+		boundary := func(events []*workflows.BoundaryEvent) {
+			for j, be := range events {
+				if be != nil {
+					singleUserTaskBoundaryEvents(be.Flow, fmt.Sprintf("%s/boundaryEvents/%d/flow/activities", path, j), inSplit, out)
+				}
+			}
+		}
+		conditions := func(outcomes []workflows.ConditionOutcome) {
+			for j, o := range outcomes {
+				if o != nil {
+					singleUserTaskBoundaryEvents(o.GetFlow(), fmt.Sprintf("%s/outcomes/%d/flow/activities", path, j), inSplit, out)
+				}
+			}
+		}
+		switch t := a.(type) {
+		case *workflows.UserTask:
+			var notification []*workflows.BoundaryEvent
+			for _, be := range t.BoundaryEvents {
+				if be != nil && be.IsNotification() {
+					notification = append(notification, be)
+				}
+			}
+			if !t.IsMulti && len(notification) > 0 {
+				out[path] = taskBoundaryEvents{events: notification, inSplit: inSplit}
+			}
+			for j, o := range t.Outcomes {
+				if o != nil {
+					singleUserTaskBoundaryEvents(o.Flow, fmt.Sprintf("%s/outcomes/%d/flow/activities", path, j), inSplit, out)
+				}
+			}
+			boundary(t.BoundaryEvents)
+		case *workflows.CallMicroflowTask:
+			conditions(t.Outcomes)
+			boundary(t.BoundaryEvents)
+		case *workflows.ExclusiveSplitActivity:
+			conditions(t.Outcomes)
+		case *workflows.ParallelSplitActivity:
+			for j, o := range t.Outcomes {
+				if o != nil {
+					singleUserTaskBoundaryEvents(o.Flow, fmt.Sprintf("%s/outcomes/%d/flow/activities", path, j), true, out)
+				}
+			}
+		case *workflows.CallWorkflowActivity:
+			boundary(t.BoundaryEvents)
+		case *workflows.WaitForNotificationActivity:
+			boundary(t.BoundaryEvents)
+		}
+	}
+}
+
+// applyUserTaskBoundaryEvents adds the notification boundary events Studio Pro
+// dropped from single user tasks. Measured on Studio Pro 11.14: the single user
+// task constructor drops `boundaryEvents` — timer and notification alike, at
+// create and when an update adds the task — and reports no error; a multi-user
+// task keeps them, and a notification event added afterwards at the task's
+// `boundaryEvents` is stored. Timer events are not re-added: the timer
+// constructor has no firstExecutionTime and rewrites the path's terminator, so a
+// re-add would fail on those instead. Only an empty stored list is filled, so a
+// server that keeps them gets nothing added twice.
+func (b *Backend) applyUserTaskBoundaryEvents(qn string, wf *workflows.Workflow) error {
+	found := map[string]taskBoundaryEvents{}
+	singleUserTaskBoundaryEvents(wf.Flow, "/flow/activities", false, found)
+	for i, esp := range wf.EventSubProcesses {
+		if esp != nil {
+			singleUserTaskBoundaryEvents(esp.Flow, fmt.Sprintf("/eventSubProcesses/%d/flow/activities", i), false, found)
+		}
+	}
+	paths := make([]string, 0, len(found))
+	for p := range found {
+		paths = append(paths, p)
+	}
+	sort.Strings(paths) // a task before anything nested in its own events
+	for _, path := range paths {
+		stored, err := b.workflowListCount(qn, path+"/boundaryEvents")
+		if err != nil {
+			return err
+		}
+		if stored > 0 {
+			continue
+		}
+		mapped, err := mapBoundaryEvents(found[path].events)
+		if err != nil {
+			return err
+		}
+		ops := make([]pedOpEntry, 0, len(mapped))
+		for _, e := range mapped {
+			if err := markNotificationEventsInSplits(e, found[path].inSplit); err != nil {
+				return err
+			}
+			ops = append(ops, pedOpEntry{Path: path + "/boundaryEvents", Operation: pedOperation{Type: "add", Value: e}})
+		}
+		if err := b.pedUpdateDoc(workflowDocType, qn, ops...); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (b *Backend) mapWorkflowContentShape(wf *workflows.Workflow, flow map[string]any, contextShape bool) (map[string]any, error) {
 	if contextShape {
 		title := wf.WorkflowName
 		if title == "" {
@@ -439,6 +693,14 @@ func mapWorkflowActivity(a workflows.WorkflowActivity) (map[string]any, error) {
 		return map[string]any{"$Type": "Workflows$EndOfParallelSplitPathActivity", "name": act.Name, "caption": act.Caption}, nil
 	case *workflows.EndOfBoundaryEventPathActivity:
 		return map[string]any{"$Type": "Workflows$EndOfBoundaryEventPathActivity", "name": act.Name, "caption": act.Caption}, nil
+	case *workflows.NotificationActivity:
+		return map[string]any{"$Type": "Workflows$NotificationActivity", "name": act.Name, "caption": act.Caption}, nil
+	case *workflows.EventSubProcessStartActivity:
+		m := map[string]any{"$Type": act.StorageType(), "name": act.Name, "caption": act.Caption}
+		if act.Timer {
+			m["firstExecutionTime"] = act.FirstExecutionTime
+		}
+		return m, nil
 	case *workflows.CallMicroflowTask:
 		outcomes, err := mapConditionOutcomes(act.Outcomes)
 		if err != nil {
@@ -864,7 +1126,10 @@ func mapBoundaryEvents(events []*workflows.BoundaryEvent) ([]any, error) {
 	}
 	out := make([]any, 0, len(events))
 	for _, be := range events {
-		el := boundaryEventElement(be.EventType, be.TimerDelay)
+		el, err := boundaryEventElement(be)
+		if err != nil {
+			return nil, err
+		}
 		if be.Flow != nil {
 			fm, err := mapWorkflowFlowValue(be.Flow)
 			if err != nil {
@@ -1386,7 +1651,15 @@ func (m *mcpWorkflowMutator) InsertBoundaryEvent(activityRef string, atPos int,
 		return ""
 	}).Activities
 	wfnames.Dedup(activities, loc.taken)
-	el := boundaryEventElement(eventType, delay)
+	be := &workflows.BoundaryEvent{EventType: eventType, TimerDelay: delay}
+	if be.IsNotification() {
+		// The op carries no name, and a notification event is reached by its name.
+		return fmt.Errorf("insert boundary event: %q boundary events cannot be inserted by ALTER WORKFLOW", eventType)
+	}
+	el, err := boundaryEventElement(be)
+	if err != nil {
+		return err
+	}
 	if err := attachSubFlow(el, activities); err != nil {
 		return err
 	}
@@ -1540,22 +1813,29 @@ func branchOutcomeElement(condition string) map[string]any {
 	}
 }
 
-// boundaryEventElement builds a timer boundary event (mirrors the MPR backend's
-// type mapping; PED auto-assigns $ID/PersistentId).
-func boundaryEventElement(eventType, delay string) map[string]any {
-	typeName := "Workflows$InterruptingTimerBoundaryEvent"
-	switch eventType {
-	case "NonInterruptingTimer":
-		typeName = "Workflows$NonInterruptingTimerBoundaryEvent"
-	case "Timer":
-		typeName = "Workflows$TimerBoundaryEvent"
+// boundaryEventElement builds a boundary event (the MPR backend's type mapping,
+// workflows.BoundaryEventStorageType; PED auto-assigns $ID/PersistentId). A
+// notification event's constructor takes a name and caption (ped_get_schema,
+// Studio Pro 11.14); the interrupting one's isInsideOfParallelSplit is set by
+// markNotificationEventsInSplits once the whole flow is mapped.
+func boundaryEventElement(be *workflows.BoundaryEvent) (map[string]any, error) {
+	typeName, ok := workflows.BoundaryEventStorageType(be.EventType)
+	if !ok {
+		return nil, fmt.Errorf("boundary event kind %q is not supported by the MCP backend", be.EventType)
+	}
+	if be.IsNotification() {
+		el := map[string]any{"$Type": typeName, "name": be.Name, "caption": be.Caption}
+		if !be.IsNonInterrupting() {
+			el["isInsideOfParallelSplit"] = false
+		}
+		return el, nil
 	}
 	el := map[string]any{"$Type": typeName, "caption": ""}
-	if delay != "" {
-		el["firstExecutionTime"] = delay
+	if be.TimerDelay != "" {
+		el["firstExecutionTime"] = be.TimerDelay
 	}
 	if typeName == "Workflows$NonInterruptingTimerBoundaryEvent" {
 		el["recurrence"] = nil
 	}
-	return el
+	return el, nil
 }
diff --git a/mdl/backend/mcp/workflow_esp_test.go b/mdl/backend/mcp/workflow_esp_test.go
new file mode 100644
index 0000000000..58bab1b970
--- /dev/null
+++ b/mdl/backend/mcp/workflow_esp_test.go
@@ -0,0 +1,276 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package mcp
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+func wfBase(name, caption string) workflows.BaseWorkflowActivity {
+	return workflows.BaseWorkflowActivity{Name: name, Caption: caption}
+}
+
+// The constructor content carries eventSubProcesses (ped_get_schema, Studio Pro
+// 11.14) with each start event first, the notification activity, and each
+// interrupting notification boundary event's isInsideOfParallelSplit — true only
+// under a split.
+func TestMapWorkflowContent_EventSubProcessesAndNotificationEvents(t *testing.T) {
+	interrupting := func(name string) *workflows.BoundaryEvent {
+		end := &workflows.EndWorkflowActivity{BaseWorkflowActivity: wfBase(name+"End", "End")}
+		return &workflows.BoundaryEvent{EventType: "InterruptingNotification", Name: name, Caption: name,
+			Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{end}}}
+	}
+	marker := func(name string) *workflows.Flow {
+		return &workflows.Flow{Activities: []workflows.WorkflowActivity{&workflows.EndOfBoundaryEventPathActivity{BaseWorkflowActivity: wfBase(name, "")}}}
+	}
+	wf := &workflows.Workflow{
+		Name: "W",
+		Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+			&workflows.NotificationActivity{BaseWorkflowActivity: wfBase("received", "Documents received")},
+			&workflows.WaitForNotificationActivity{BaseWorkflowActivity: wfBase("top", "top"),
+				BoundaryEvents: []*workflows.BoundaryEvent{interrupting("topEvent"),
+					{EventType: "NonInterruptingNotification", Name: "nudge", Caption: "Nudge", Flow: marker("nudgeEnd")}}},
+			&workflows.ParallelSplitActivity{BaseWorkflowActivity: wfBase("split", "split"),
+				Outcomes: []*workflows.ParallelSplitOutcome{{Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+					&workflows.WaitForNotificationActivity{BaseWorkflowActivity: wfBase("inSplit", "inSplit"),
+						BoundaryEvents: []*workflows.BoundaryEvent{splitEventEndingInJump()}},
+				}}}}},
+		}},
+		EventSubProcesses: []*workflows.EventSubProcess{{Name: "ESP_Expire", Caption: "Expire", Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+			&workflows.EventSubProcessStartActivity{BaseWorkflowActivity: wfBase("expireStart", "After 30 days"), Interrupting: true, Timer: true, FirstExecutionTime: "addDays([%CurrentDateTime%], 30)"},
+			&workflows.EndWorkflowActivity{BaseWorkflowActivity: wfBase("End", "End")},
+		}}}},
+	}
+	content, err := (&Backend{}).mapWorkflowContent(wf, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	esps, _ := content["eventSubProcesses"].([]any)
+	if len(esps) != 1 {
+		t.Fatalf("eventSubProcesses = %v", content["eventSubProcesses"])
+	}
+	esp := esps[0].(map[string]any)
+	start := esp["flow"].(map[string]any)["activities"].([]any)[0].(map[string]any)
+	if esp["$Type"] != "Workflows$EventSubProcess" || esp["name"] != "ESP_Expire" ||
+		start["$Type"] != "Workflows$InterruptingTimerEventSubProcessStartActivity" ||
+		start["firstExecutionTime"] != "addDays([%CurrentDateTime%], 30)" {
+		t.Errorf("sub-process mapped as %v", esp)
+	}
+
+	acts := content["flow"].(map[string]any)["activities"].([]any)
+	if n := acts[0].(map[string]any); n["$Type"] != "Workflows$NotificationActivity" || n["name"] != "received" {
+		t.Errorf("notification activity mapped as %v", n)
+	}
+	events := acts[1].(map[string]any)["boundaryEvents"].([]any)
+	top, nudge := events[0].(map[string]any), events[1].(map[string]any)
+	if top["$Type"] != "Workflows$InterruptingNotificationBoundaryEvent" || top["name"] != "topEvent" || top["isInsideOfParallelSplit"] != false {
+		t.Errorf("top-level interrupting event mapped as %v", top)
+	}
+	if _, has := nudge["isInsideOfParallelSplit"]; has || nudge["name"] != "nudge" {
+		t.Errorf("a non-interrupting event takes no isInsideOfParallelSplit: %v", nudge)
+	}
+	split := acts[2].(map[string]any)["outcomes"].([]any)[0].(map[string]any)["flow"].(map[string]any)["activities"].([]any)[0].(map[string]any)
+	if inner := split["boundaryEvents"].([]any)[0].(map[string]any); inner["isInsideOfParallelSplit"] != true {
+		t.Errorf("an event under a split must say so: %v", inner)
+	}
+}
+
+func splitEventEndingInJump() *workflows.BoundaryEvent {
+	jump := &workflows.JumpToActivity{BaseWorkflowActivity: wfBase("jumpBack", "jumpBack"), TargetActivity: "inSplit"}
+	return &workflows.BoundaryEvent{EventType: "InterruptingNotification", Name: "splitEvent", Caption: "splitEvent",
+		Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{jump}}}
+}
+
+// Outside a split Studio Pro's constructor forces an interrupting notification
+// path to end in an End (measured: a jump is replaced by one, the marker gets one
+// appended and is refused), and a non-interrupting path must end in the marker.
+// Each shape it would rewrite is refused before sending.
+func TestMapWorkflowContent_NotificationPathsStudioProWouldRewrite(t *testing.T) {
+	on := func(be *workflows.BoundaryEvent) *workflows.Workflow {
+		return &workflows.Workflow{Name: "W", Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+			&workflows.WaitForNotificationActivity{BaseWorkflowActivity: wfBase("w", "w"), BoundaryEvents: []*workflows.BoundaryEvent{be}},
+		}}}
+	}
+	path := func(acts ...workflows.WorkflowActivity) *workflows.Flow { return &workflows.Flow{Activities: acts} }
+	jump := &workflows.JumpToActivity{BaseWorkflowActivity: wfBase("j", "j"), TargetActivity: "w"}
+	end := &workflows.EndWorkflowActivity{BaseWorkflowActivity: wfBase("e", "End")}
+	mark := &workflows.EndOfBoundaryEventPathActivity{BaseWorkflowActivity: wfBase("m", "")}
+	cases := []struct {
+		name   string
+		be     *workflows.BoundaryEvent
+		refuse bool
+	}{
+		{"interrupting ending in end workflow", &workflows.BoundaryEvent{EventType: "InterruptingNotification", Name: "a", Flow: path(end)}, false},
+		{"interrupting ending in the marker", &workflows.BoundaryEvent{EventType: "InterruptingNotification", Name: "a", Flow: path(mark)}, true},
+		{"interrupting ending in a jump", &workflows.BoundaryEvent{EventType: "InterruptingNotification", Name: "a", Flow: path(jump)}, true},
+		{"non-interrupting ending in the marker", &workflows.BoundaryEvent{EventType: "NonInterruptingNotification", Name: "a", Flow: path(mark)}, false},
+		{"non-interrupting ending in a jump", &workflows.BoundaryEvent{EventType: "NonInterruptingNotification", Name: "a", Flow: path(jump)}, true},
+	}
+	for _, c := range cases {
+		_, err := (&Backend{}).mapWorkflowContent(on(c.be), true)
+		if (err != nil) != c.refuse {
+			t.Errorf("%s: refused = %v (%v), want %v", c.name, err != nil, err, c.refuse)
+		}
+	}
+}
+
+// Inside a parallel split Studio Pro wants the interrupting notification path to
+// end in a jump (measured: the marker form gets a target-less jump appended and is
+// refused). Refused before sending, naming the remedy; the jump form passes.
+func TestMapWorkflowContent_InterruptingNotificationInSplitNeedsJump(t *testing.T) {
+	split := func(be *workflows.BoundaryEvent) *workflows.Workflow {
+		return &workflows.Workflow{Name: "W", Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+			&workflows.ParallelSplitActivity{BaseWorkflowActivity: wfBase("split", "split"),
+				Outcomes: []*workflows.ParallelSplitOutcome{{Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+					&workflows.WaitForNotificationActivity{BaseWorkflowActivity: wfBase("inSplit", "inSplit"),
+						BoundaryEvents: []*workflows.BoundaryEvent{be}},
+				}}}}},
+		}}}
+	}
+	marker := &workflows.BoundaryEvent{EventType: "InterruptingNotification", Name: "splitEvent", Caption: "splitEvent",
+		Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{&workflows.EndOfBoundaryEventPathActivity{BaseWorkflowActivity: wfBase("end", "")}}}}
+	if _, err := (&Backend{}).mapWorkflowContent(split(marker), true); err == nil || !strings.Contains(err.Error(), "jump to") {
+		t.Errorf("a split path ending in the marker must be refused naming `jump to`, got %v", err)
+	}
+	if _, err := (&Backend{}).mapWorkflowContent(split(splitEventEndingInJump()), true); err != nil {
+		t.Errorf("a split path ending in a jump was refused: %v", err)
+	}
+}
+
+// applyUserTaskBoundaryEvents adds a single user task's notification boundary
+// events, at any depth, when the constructor left the stored list empty, and adds
+// nothing when it did not. Timer events are left alone.
+func TestApplyUserTaskBoundaryEvents(t *testing.T) {
+	task := func(name string) *workflows.UserTask {
+		return &workflows.UserTask{BaseWorkflowActivity: wfBase(name, name),
+			BoundaryEvents: []*workflows.BoundaryEvent{
+				{EventType: "InterruptingTimer", TimerDelay: "addDays([%CurrentDateTime%], 3)"},
+				{EventType: "NonInterruptingNotification", Name: name + "Nudge", Caption: "Nudge",
+					Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{&workflows.EndOfBoundaryEventPathActivity{BaseWorkflowActivity: wfBase(name+"End", "")}}}},
+			}}
+	}
+	multi := task("multi")
+	multi.IsMulti = true
+	wf := &workflows.Workflow{
+		Name: "W",
+		Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+			&workflows.StartWorkflowActivity{BaseWorkflowActivity: wfBase("Start", "Start")},
+			task("top"),
+			multi,
+		}},
+		EventSubProcesses: []*workflows.EventSubProcess{{Name: "ESP", Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+			&workflows.EventSubProcessStartActivity{BaseWorkflowActivity: wfBase("s", "s")},
+			task("nested"),
+		}}}},
+	}
+	for _, storedAlready := range []bool{false, true} {
+		f := newFakePED(t, func(name string, args map[string]any) (string, bool) {
+			if name == "ped_read_document" {
+				paths, _ := args["paths"].([]any)
+				result := "[]"
+				if storedAlready {
+					result = `[{"$Type":"Workflows$InterruptingTimerBoundaryEvent"}]`
+				}
+				return `{"results":[{"path":"` + paths[0].(string) + `","result":` + result + `}]}`, false
+			}
+			return "SUCCESS", false
+		})
+		b := &Backend{client: f.connectClient(t)}
+		if err := b.applyUserTaskBoundaryEvents("M.W", wf); err != nil {
+			t.Fatal(err)
+		}
+		added := map[string]int{}
+		for _, c := range f.calls {
+			if c.Name != "ped_update_document" {
+				continue
+			}
+			for _, o := range c.Args["operations"].([]any) {
+				entry := o.(map[string]any)
+				added[entry["path"].(string)]++
+			}
+		}
+		want := map[string]int{"/flow/activities/1/boundaryEvents": 1, "/eventSubProcesses/0/flow/activities/1/boundaryEvents": 1}
+		if storedAlready {
+			want = map[string]int{}
+		}
+		if !reflect.DeepEqual(added, want) {
+			t.Errorf("stored already %v: added %v, want %v (a multi-user task keeps its events)", storedAlready, added, want)
+		}
+	}
+}
+
+// An unknown boundary-event kind is an error, not an interrupting timer.
+func TestBoundaryEventElement_UnknownKindIsRefused(t *testing.T) {
+	if _, err := boundaryEventElement(&workflows.BoundaryEvent{EventType: "Escalation"}); err == nil {
+		t.Error("an unknown kind was mapped")
+	}
+}
+
+// A rewrite replaces the stored sub-processes with the statement's, as it does
+// the event handlers.
+func TestUpdateWorkflow_ReplacesEventSubProcesses(t *testing.T) {
+	f := newFakePED(t, func(name string, args map[string]any) (string, bool) {
+		switch name {
+		case "ped_check_errors":
+			return "No errors found.", false
+		case "ped_read_document":
+			paths, _ := args["paths"].([]any)
+			if len(paths) == 1 && paths[0] == "/onWorkflowEvent" {
+				return `{"results":[{"path":"/onWorkflowEvent","result":[]}]}`, false
+			}
+			if len(paths) == 1 && paths[0] == "/eventSubProcesses" {
+				return `{"results":[{"path":"/eventSubProcesses","result":[{"$Type":"Workflows$EventSubProcess"}]}]}`, false
+			}
+			return `{"results":[{"path":"/flow/activities","result":[
+				{"$Type":"Workflows$StartWorkflowActivity"},
+				{"$Type":"Workflows$EndWorkflowActivity"}]}]}`, false
+		}
+		return "SUCCESS", false
+	})
+	mod := &model.Module{Name: "M"}
+	mod.ID = "mod1"
+	b := &Backend{client: f.connectClient(t), sessionModules: []*model.Module{mod}}
+
+	wf := &workflows.Workflow{
+		Name: "WF",
+		Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+			&workflows.StartWorkflowActivity{BaseWorkflowActivity: wfBase("Start", "Start")},
+			&workflows.EndWorkflowActivity{BaseWorkflowActivity: wfBase("End", "End")},
+		}},
+		EventSubProcesses: []*workflows.EventSubProcess{{Name: "ESP", Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+			&workflows.EventSubProcessStartActivity{BaseWorkflowActivity: wfBase("espStart", "espStart"), Interrupting: true},
+			&workflows.EndWorkflowActivity{BaseWorkflowActivity: wfBase("End2", "End")},
+		}}}},
+	}
+	wf.ContainerID = "mod1"
+	wf.ID = "wfid"
+	if err := b.UpdateWorkflow(wf); err != nil {
+		t.Fatalf("UpdateWorkflow: %v", err)
+	}
+	call, ok := f.callByName("ped_update_document")
+	if !ok {
+		t.Fatal("no ped_update_document sent")
+	}
+	var adds, removes int
+	for _, o := range call.Args["operations"].([]any) {
+		entry := o.(map[string]any)
+		if path, _ := entry["path"].(string); !strings.HasPrefix(path, "/eventSubProcesses") {
+			continue
+		}
+		switch entry["operation"].(map[string]any)["type"] {
+		case "add":
+			adds++
+		case "remove":
+			removes++
+		}
+	}
+	if adds != 1 || removes != 1 {
+		t.Errorf("expected the stored sub-process removed and the statement's added, got %d adds / %d removes", adds, removes)
+	}
+}
diff --git a/mdl/backend/mcp/workflow_test.go b/mdl/backend/mcp/workflow_test.go
index d7287cdaf7..f11552b7fa 100644
--- a/mdl/backend/mcp/workflow_test.go
+++ b/mdl/backend/mcp/workflow_test.go
@@ -509,9 +509,9 @@ func TestUpdateWorkflow_ReplacesFlowAndProperties(t *testing.T) {
 		case "ped_check_errors":
 			return "No errors found.", false
 		case "ped_read_document":
-			// The stored workflow has no event handlers.
-			if paths, _ := args["paths"].([]any); len(paths) == 1 && paths[0] == "/onWorkflowEvent" {
-				return `{"results":[{"path":"/onWorkflowEvent","result":[]}]}`, false
+			// The stored workflow has no event handlers and no event sub-processes.
+			if paths, _ := args["paths"].([]any); len(paths) == 1 && (paths[0] == "/onWorkflowEvent" || paths[0] == "/eventSubProcesses") {
+				return `{"results":[{"path":"` + paths[0].(string) + `","result":[]}]}`, false
 			}
 			// The existing flow has 3 activities (Start, X, End).
 			return `{"results":[{"path":"/flow/activities","result":[
diff --git a/mdl/backend/modelsdk/testdata/TestApp.ZzMxcliExample_EventSubProcesses.bson b/mdl/backend/modelsdk/testdata/TestApp.ZzMxcliExample_EventSubProcesses.bson
new file mode 100644
index 0000000000000000000000000000000000000000..2966ddf1bc6b57c47f9c2dd7970816dac272ca0a
GIT binary patch
literal 7070
zcmb_hd0Z3M7QQA?S;Q68x`Ltww;zb>t4~QtK#)KL1kw6*NG@?S%;3y~09LDj2tKVy
z#ibzbigiJ>qUgf~p8HazTI;Le_N>)v)mLp@%eym~Aq)m36#hwuJNMl4o%7xAo_mtt
z6@cdMflAO8pug<s_PY44(f&K_<zqG!zilOPk4TD#paU9;BB`0N2GT^k3*Uf)To;EE
z8cYw-SArlJjKN6)NR*`37zYXdu^DSvqBKG!#z4S5$y5nwINTVcp-3&HX-I=)M*!M-
z0SS6n>J5&ePm5P`w)Q$zb$`2GUZwZ3D|-sR=Dq47@~VzWu}6MbJm*>)G{p}iw9w#6
z!C6K~GeGK(K!Hx81@oSE?()<8Ljfh1RJ&V2(`J4_cD4YXcIW2F<XQ$#z!@Ats6f~d
z1gROqOY~uZaI$U7wEgx^6q&b9XWKn42fW2GB8!0p11ZXgTqX1&B!kD|S}vk>poKFS
z#qjGUS;xsHvj(RY;t5a(Bq3NF1S|$f$D0Q^OQ5+1QZ!C8C?$b9GY@{tj$ZNEjoqpP
z>K*5cx(`-M!k_`Uk^t4XPG^7`5+@iSL#DhwK{*S@lVQyhkPZeX(TD|mmS#fbpC8MD
zQ%>4XxcU|8&SUR^Ua~|}Md*Zw_d_$&iNoSl8w)aE4N2<tv$HS8Z;_|=?p#djC#Bnh
z1ksjT2T>EK!ZlOPL9@0>Tn8iU9>2(cQ-Y%Tr~e}lu|YU2qEzL{^vKnV)avDQZi`#_
zd8v)(FpFAl)ZvV)F<!@RDQgVg7MVHn7<EULnYG`(;>n7S8^hpNXdz1$-^_Pg;Iw;{
z>Y(%J6uSYFxAPVi=p`X>w0j6iG#!aqs+xgPP{iTZXaI4T8>^SX2c}Fr=~I=f%EF$u
zmc;xp(w4-d?41ySj|5KLx@B}y7MB+vy1a*wHyMRn)q+wFgKx)8kCr8`@GG74qm#$H
z>i)I>5g6=%mSGvph0Gd(?+%^jZSvov-jx!)=0qvH4WvHczKFmv+bVBmEV(W(aaNY@
z?>_f(;|bi7btW+$rv&N-h!(1fY_*RJEcabA&a+4Br?V>?MqLTAVG&<Xq!JeDYW9_c
zAKXR-9GSXf>&2~xNZ#TI<cEd2wRszX$3e<=)n$1pk3|~p>f`0A!;)wq@y98eQ6)mH
zkv)G{yTA>-h3RxkH109EkDrmEknpl+BRkq>$^bOkQ!LizVAacX6VNmF25S8F_PL|_
z)xRvq7J|GZ)(6tgSNB*KrdmJRWbYICI;zQ-&Wp7fOFdMtfF^&#ijJXM#^iKx`L^q?
zwjdFxE{HYHFe``Kx;e+@jHtLgc7ylKiBVUQ3V?J7cqO9XFP{(I`|3%5#lC`h_X{#}
zJsQt-R>PDSZb(A)2C9{GkmBV!P_*D~=GMTA=VZaDfydon4X;|;FwV=~!}+RSMOXU%
z*+!YSSx?)wDW1$*{6xh0I&$4e+H>NP0I4LF^HwSE`XS1D3yg1v-bB(K#s{lj&O4Sr
zRvaI6!8hx?i$_?$Ow1OhAkLpg%UJZG>(L?8PnC@d$~$+aWwvajAZ>rWK;erm0Zl!u
z58XU(n%DROMOtf*+`T@}f^5Meu)aM4#0oseHDNt#LO;Q&6o#E0q%Ih+zhp6?cLBgo
zm8dlsb*MrF60~VZiV21Z&;VGO9*fF7Nbr>Hjkd5QXw{dBPY;NR2~A^iZrpmKDQ_5M
ztI&aGk?9Ii8uAAop8f5K<%%Ulvutno8v}WZuIMF;OmmD79vfUKc0@L;&$OZsD-NXY
z{d}8K@aBk&tiIp1dtggG5Vx+2Kz-Sw^}-4I2O;ZUogR60;_H<>sGcHFwTu1tV`6V&
z!u5(qnj)%;Sh}HG7#^DxCJb1CH|y=++Iwzs2~A7X^zD0~EZHV_KH!ZA-lxOqz*zmo
zkbgQGw>zF$b(@FRR|GE#!x?{)`XEY~f;193j7s8;UK+5)5q~EH65$HRGMzQ(8cR~H
zSbRK1CSV5sykyT96B?5X|F#0Z#js~Bd^Wd`=l<mQvSM*gH=E!O0Ri^4H^EBEEBWUg
zGyJl5;>YO)56gJ?>=7?;ly(nC*Es{6Ktn15qi0&pubte;kaC*F^@RED2#nH0hMfaI
z-LRZMH%vY(=&JmqsMKi}Wh$9epztf6_s4%mB}KUK4*7^2sw4Zg^CHTC^}A&YWGlp|
zLzjN@#lv0Xz)@v~n-y!~LjP6ScE&yVYZdPROHE5e-nly8K*JVUxQL!CLi1lwD*V;8
z+@Q>x&UZ{{b2{=CJw+Cgw1&otoY!E?bgQwhVG{CNkWaQ~h=ClcdPF*3cO1B1x*NC-
z+jF6CW0}kr+6b%ISyr(o&BNh<LN}*U-(`l0vX^cJtJzEBHBoR+wpsU0dxy6Hso2^%
zFU#j=@}clTb}hlJUC7#)TJ|K5!kOth3Ns0+-(BRvM&(`V?%STq>=FGJI276^HY~kA
zAiI|IiVxqnNiA1wzA{a@`^4hp5<{C#yv3$Dd}Ck@oO<%Q_(^8FVfj(P+Y;QCIy`*&
zv@v;Qb*k1%)^a-|z;L+I!9%soWvt7yGdZ&mB?LiZ&)G1TfJ0NAE}6Oczz$R9VQDDg
zM?rK`&~X9@Mxi0gK5>r5dd<yw7?iu`_Xv;jCHMJ2a(Y?Qy9*)BQ-Lhh$Y{wp)V7){
zsv<9lY<786b+_fCM~b|SvDKa#nqj<6apz4?Hr^sH3*$wGuKwYe_BzW^y)vk3)uev+
z9yE+M`~kpr)DY5l+f+w)jg3}Qr&Wc=z56LP?d&6o#0*9VnxnS^ND>t^Xa}8Vr`9w$
zjln&r=eZl@DYCYuzYw~?jRv$o{i8Jt3yXZyu2uh>(`8C<(*UCLzkcYIdRP5L&(3GR
zIlXlO4~XrwDKHj~4-hBlx5;klPRDmD))V80zDT&HZ#15p`?`GJyW{WUiio-AKYNkj
z-!yo(r!1ZN<@5ZYFRpZL_1snR_gV>>pf@C0&+4-7*-Jgr7mX`*>Xvo5qI;+fTT;rN
zuu4d4Dcs!f)r+!URQ<wvITov4mFF3;zO0~Gt!SxnEk(w1{q1muLML_vjEhG-Pt@4d
zU=-?{qHBGfiX;LiGUk3Z;MV1Oh2jNAY$2v6?u34;$47W&Tu%{NpX~l=f(5zGdyEKS
z8M$_D57~FVUlpI5{q*pa>pa5F=q1Yu!OjbVu@E&Lv=B%*Gi-%y;$>oxu%o#VAT>X-
z1qq4^P>L43ROI{k@qMX!b?#V6!NE<!c`sIo5K?Rc5qT&O7yl-&(lJ|>`v&go;6V(}
zgd2Fr|N1e&LRVurf%IR9KuuX-MN)cY3?4JeO);+I#;G-?@yjpRKt8mPS+d>Gw@Jxr
zbgjZwi5Q|0oXV-L=m!s3C?WV`mgL&iuC#`8V2&u<*OJEuOqsh<zU#<8Mmsnb{F@Jx
zGkQs|M!Q=kOH>4dGfChhG+vWk?h9%1){^M=21H@A)9g<Mf(bu<#G2-MX5aYUCw8`C
z*QE{fJ9RF>BoR1cFn6^+h*>HuQ2!Q{oGs90r;iHC#Gh}C8L`8w$+oD2u(ld97;3j+
rpvD_+<1Q4%x#x-VlBq|0LbqNV_E@^DnrH$y8pH}<C%73o7&-KRzG*$l

literal 0
HcmV?d00001

diff --git a/mdl/backend/modelsdk/workflow_esp_test.go b/mdl/backend/modelsdk/workflow_esp_test.go
new file mode 100644
index 0000000000..1cd24a6dc2
--- /dev/null
+++ b/mdl/backend/modelsdk/workflow_esp_test.go
@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+import (
+	"fmt"
+	"os"
+	"testing"
+
+	genWf "github.com/mendixlabs/mxcli/modelsdk/gen/workflows"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// The workflow Studio Pro 11.14 saved for ako/TestApp's
+// ZzMxcliExample_EventSubProcesses: one event sub-process per start kind, a
+// notification activity, and both notification boundary events on a user task.
+const eventSubProcessFixture = "testdata/TestApp.ZzMxcliExample_EventSubProcesses.bson"
+
+type espWant struct {
+	caption, startName, startCaption, firstExecutionTime string
+	interrupting, timer                                  bool
+}
+
+// The reader decodes the constructs gen has no type for — the two timer starts,
+// the notification activity, the notification boundary events — off the raw
+// document, and none of them is lost or read as a generic activity.
+func TestReadEventSubProcessesFromStudioProFixture(t *testing.T) {
+	raw, err := os.ReadFile(eventSubProcessFixture)
+	if err != nil {
+		t.Fatal(err)
+	}
+	g := genWf.NewWorkflow()
+	g.InitFromRaw(bson.Raw(raw))
+	wf := workflowFromGen(g, "")
+
+	want := map[string]espWant{
+		"ESP_Cancel":        {"Cancel request", "espCancelStart", "Cancel received", "", true, false},
+		"ESP_Audit":         {"Audit update", "espAuditStart", "Audit received", "", false, false},
+		"ESP_Expire":        {"Expire", "espExpireStart", "After 30 days", "addDays([%CurrentDateTime%], 30)", true, true},
+		"ESP_DailyReminder": {"Daily reminder", "espReminderStart", "Every day", "addDays([%CurrentDateTime%], 1)", false, true},
+	}
+	if len(wf.EventSubProcesses) != len(want) {
+		t.Fatalf("read %d event sub-processes, want %d", len(wf.EventSubProcesses), len(want))
+	}
+	for _, esp := range wf.EventSubProcesses {
+		w, ok := want[esp.Name]
+		if !ok {
+			t.Errorf("unexpected sub-process %q", esp.Name)
+			continue
+		}
+		start := esp.Start()
+		if start == nil {
+			t.Errorf("%s: no start event read", esp.Name)
+			continue
+		}
+		got := espWant{esp.Caption, start.Name, start.Caption, start.FirstExecutionTime, start.Interrupting, start.Timer}
+		if got != w {
+			t.Errorf("%s = %+v, want %+v", esp.Name, got, w)
+		}
+		if _, ok := esp.Flow.Activities[len(esp.Flow.Activities)-1].(*workflows.EndWorkflowActivity); !ok {
+			t.Errorf("%s: flow does not close with its End", esp.Name)
+		}
+	}
+
+	var notification *workflows.NotificationActivity
+	var review *workflows.UserTask
+	for _, a := range wf.Flow.Activities {
+		switch v := a.(type) {
+		case *workflows.NotificationActivity:
+			notification = v
+		case *workflows.UserTask:
+			review = v
+		case *workflows.GenericWorkflowActivity:
+			t.Errorf("activity %q read as generic %s", v.Name, v.TypeString)
+		}
+	}
+	if notification == nil || notification.Name != "notifyReceived" || notification.Caption != "Documents received" {
+		t.Errorf("notification activity = %+v", notification)
+	}
+	if review == nil || len(review.BoundaryEvents) != 2 {
+		t.Fatalf("review boundary events not read: %+v", review)
+	}
+	byName := map[string]*workflows.BoundaryEvent{}
+	for _, be := range review.BoundaryEvents {
+		byName[be.Name] = be
+	}
+	if be := byName["beNudge"]; be == nil || be.EventType != "NonInterruptingNotification" || be.Caption != "Nudge" || be.Flow == nil {
+		t.Errorf("beNudge = %+v", be)
+	}
+	if be := byName["beWithdrawn"]; be == nil || be.EventType != "InterruptingNotification" || be.Caption != "Withdrawn" || be.Flow == nil {
+		t.Errorf("beWithdrawn = %+v", be)
+	} else if _, ok := be.Flow.Activities[len(be.Flow.Activities)-1].(*workflows.EndWorkflowActivity); !ok {
+		t.Errorf("beWithdrawn flow does not end with its End: %+v", be.Flow.Activities)
+	}
+}
+
+// Every construct survives a write and a fresh read, stored the way Studio Pro
+// stores it: EventSubProcesses and BoundaryEvents as marker-2 lists, and a
+// notification boundary event with the Name a notify action targets.
+func TestCreateWorkflow_EventSubProcessesRoundTrip(t *testing.T) {
+	proj := copyFixture(t)
+	b := New()
+	if err := b.Connect(proj); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+	mod, err := b.GetModuleByName("MyFirstModule")
+	if err != nil || mod == nil {
+		t.Fatalf("GetModuleByName: %v", err)
+	}
+
+	base := func(name, caption string) workflows.BaseWorkflowActivity {
+		return workflows.BaseWorkflowActivity{Name: name, Caption: caption}
+	}
+	end := func(name string) *workflows.EndWorkflowActivity {
+		return &workflows.EndWorkflowActivity{BaseWorkflowActivity: base(name, "End")}
+	}
+	wait := &workflows.WaitForNotificationActivity{
+		BaseWorkflowActivity: base("waitApproval", "Wait for approval"),
+		BoundaryEvents: []*workflows.BoundaryEvent{
+			{EventType: "InterruptingNotification", Name: "withdrawn", Caption: "Withdrawn",
+				Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{end("withdrawnEnd")}}},
+			{EventType: "NonInterruptingNotification", Name: "nudge", Caption: "Nudge",
+				Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{&workflows.EndOfBoundaryEventPathActivity{BaseWorkflowActivity: base("nudgeEnd", "")}}}},
+		},
+	}
+	wf := &workflows.Workflow{
+		ContainerID: mod.ID, Name: "ZzEventSubProcesses",
+		Parameter: &workflows.WorkflowParameter{EntityRef: "MyFirstModule.Ctx"},
+		Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+			&workflows.StartWorkflowActivity{BaseWorkflowActivity: base("Start", "Start")},
+			&workflows.NotificationActivity{BaseWorkflowActivity: base("received", "Documents received")},
+			wait,
+			end("End"),
+		}},
+		EventSubProcesses: []*workflows.EventSubProcess{
+			{Name: "ESP_Cancel", Caption: "Cancel request", Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+				&workflows.EventSubProcessStartActivity{BaseWorkflowActivity: base("cancelStart", "Cancel received"), Interrupting: true},
+				end("cancelEnd"),
+			}}},
+			{Name: "ESP_Remind", Caption: "Daily reminder", Flow: &workflows.Flow{Activities: []workflows.WorkflowActivity{
+				&workflows.EventSubProcessStartActivity{BaseWorkflowActivity: base("remindStart", "Every day"), Timer: true, FirstExecutionTime: "addDays([%CurrentDateTime%], 1)"},
+				end("remindEnd"),
+			}}},
+		},
+	}
+	if err := b.CreateWorkflow(wf); err != nil {
+		t.Fatalf("CreateWorkflow: %v", err)
+	}
+
+	b2 := New()
+	if err := b2.Connect(proj); err != nil {
+		t.Fatalf("reconnect: %v", err)
+	}
+	t.Cleanup(func() { _ = b2.Disconnect() })
+	all, err := b2.ListWorkflows()
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got *workflows.Workflow
+	for _, w := range all {
+		if w.Name == "ZzEventSubProcesses" {
+			got = w
+		}
+	}
+	if got == nil {
+		t.Fatal("workflow not found after reconnect")
+	}
+
+	if len(got.EventSubProcesses) != 2 {
+		t.Fatalf("read back %d event sub-processes, want 2", len(got.EventSubProcesses))
+	}
+	if s := got.EventSubProcesses[0].Start(); s == nil || !s.Interrupting || s.Timer || s.Name != "cancelStart" || s.Caption != "Cancel received" {
+		t.Errorf("ESP_Cancel start = %+v", s)
+	}
+	if s := got.EventSubProcesses[1].Start(); s == nil || s.Interrupting || !s.Timer || s.FirstExecutionTime != "addDays([%CurrentDateTime%], 1)" {
+		t.Errorf("ESP_Remind start = %+v", s)
+	}
+	if n, ok := got.Flow.Activities[1].(*workflows.NotificationActivity); !ok || n.Name != "received" || n.Caption != "Documents received" {
+		t.Errorf("notification activity read back as %#v", got.Flow.Activities[1])
+	}
+	gotWait, ok := got.Flow.Activities[2].(*workflows.WaitForNotificationActivity)
+	if !ok || len(gotWait.BoundaryEvents) != 2 {
+		t.Fatalf("wait for notification read back as %#v", got.Flow.Activities[2])
+	}
+	for i, w := range wait.BoundaryEvents {
+		be := gotWait.BoundaryEvents[i]
+		if be.EventType != w.EventType || be.Name != w.Name || be.Caption != w.Caption || be.Flow == nil {
+			t.Errorf("boundary event %d = %+v, want %s %q %q with its flow", i, be, w.EventType, w.Name, w.Caption)
+		}
+	}
+
+	raw, err := b2.GetRawUnit(got.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	esps, _ := raw["EventSubProcesses"].([]any)
+	if len(esps) != 3 || fmt.Sprint(esps[0]) != "2" {
+		t.Errorf("EventSubProcesses stored as %v, want a marker-2 list of two", esps)
+	}
+	for _, a := range raw["Flow"].(map[string]any)["Activities"].([]any) {
+		m, ok := a.(map[string]any)
+		if !ok || m["Name"] != "waitApproval" {
+			continue
+		}
+		events, _ := m["BoundaryEvents"].([]any)
+		if len(events) != 3 || fmt.Sprint(events[0]) != "2" {
+			t.Fatalf("BoundaryEvents stored as %v, want a marker-2 list of two", events)
+		}
+		first := events[1].(map[string]any)
+		if first["$Type"] != "Workflows$InterruptingNotificationBoundaryEvent" || first["Name"] != "withdrawn" {
+			t.Errorf("first boundary event stored as %v", first)
+		}
+		if _, hasTimer := first["FirstExecutionTime"]; hasTimer {
+			t.Errorf("a notification boundary event must not carry a timer: %v", first)
+		}
+	}
+}
diff --git a/mdl/backend/modelsdk/workflow_read.go b/mdl/backend/modelsdk/workflow_read.go
index 2dcd338413..3c8681f10d 100644
--- a/mdl/backend/modelsdk/workflow_read.go
+++ b/mdl/backend/modelsdk/workflow_read.go
@@ -4,6 +4,7 @@ package modelsdkbackend
 
 import (
 	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/modelsdk/codec"
 	"github.com/mendixlabs/mxcli/modelsdk/element"
 	genMf "github.com/mendixlabs/mxcli/modelsdk/gen/microflows"
 	genWf "github.com/mendixlabs/mxcli/modelsdk/gen/workflows"
@@ -66,9 +67,31 @@ func workflowFromGen(g *genWf.Workflow, containerID model.ID) *workflows.Workflo
 		w.Flow = workflowFlowFromGen(f)
 	}
 	w.EventHandlers = workflowEventHandlersFromGen(g.OnWorkflowEventItems())
+	w.EventSubProcesses = eventSubProcessesFromGen(g.EventSubProcessesItems())
 	return w
 }
 
+// eventSubProcessesFromGen converts a workflow's event sub-processes. Each flow
+// is read like any other, so its start event arrives as an
+// EventSubProcessStartActivity (workflowSimpleActivityFromGen) — read from the
+// raw document, since gen has no type for the two timer starts.
+func eventSubProcessesFromGen(items []element.Element) []*workflows.EventSubProcess {
+	var out []*workflows.EventSubProcess
+	for _, el := range items {
+		e, ok := el.(*genWf.EventSubProcess)
+		if !ok {
+			continue
+		}
+		esp := &workflows.EventSubProcess{Name: e.Name(), Caption: e.Caption(), Annotation: annotationText(e.Annotation())}
+		esp.ID = model.ID(e.ID())
+		if f, ok := e.Flow().(*genWf.Flow); ok && f != nil {
+			esp.Flow = workflowFlowFromGen(f)
+		}
+		out = append(out, esp)
+	}
+	return out
+}
+
 // workflowEventHandlersFromGen converts a workflow's OnWorkflowEvent handlers.
 func workflowEventHandlersFromGen(items []element.Element) []*workflows.WorkflowEventHandler {
 	var out []*workflows.WorkflowEventHandler
@@ -314,7 +337,21 @@ func workflowSimpleActivityFromGen(el element.Element) workflows.WorkflowActivit
 		a := &workflows.WaitForNotificationActivity{}
 		setBase(&a.BaseWorkflowActivity)
 		return a
+	// Neither has a gen type that exposes its fields (NotificationActivity and the
+	// timer starts have no gen type at all), so both are read off the raw document.
+	case "Workflows$NotificationActivity":
+		a := &workflows.NotificationActivity{}
+		setBase(&a.BaseWorkflowActivity)
+		return a
 	default:
+		if interrupting, timer, ok := workflows.EventSubProcessStartFromStorageType(typeName); ok {
+			a := &workflows.EventSubProcessStartActivity{Interrupting: interrupting, Timer: timer}
+			setBase(&a.BaseWorkflowActivity)
+			if timer {
+				a.FirstExecutionTime = genWf.RawFieldString(raw, "FirstExecutionTime")
+			}
+			return a
+		}
 		t := &workflows.GenericWorkflowActivity{TypeString: typeName}
 		t.ID = model.ID(el.ID())
 		t.TypeName = typeName
@@ -488,6 +525,22 @@ func boundaryEventsFromGen(items []element.Element) []*workflows.BoundaryEvent {
 }
 
 func boundaryEventFromGen(el element.Element) *workflows.BoundaryEvent {
+	// Notification boundary events have no gen type: the element is a raw Base,
+	// so its fields — and its flow — are read off the stored document.
+	if eventType, ok := workflows.BoundaryEventTypeFromStorage(el.TypeName()); ok {
+		if be := (&workflows.BoundaryEvent{EventType: eventType}); be.IsNotification() {
+			raw := el.Raw()
+			be.ID = model.ID(el.ID())
+			be.Name = genWf.RawFieldString(raw, "Name")
+			be.Caption = genWf.RawFieldString(raw, "Caption")
+			if child, err := codec.DecodeChild(raw, "Flow"); err == nil {
+				if f, ok := child.(*genWf.Flow); ok && f != nil {
+					be.Flow = workflowFlowFromGen(f)
+				}
+			}
+			return be
+		}
+	}
 	// The three timer variants differ only in $Type, and gen gives each its own
 	// concrete type, so the shared shape is read through a small interface rather
 	// than repeated three times.
diff --git a/mdl/backend/modelsdk/workflow_write.go b/mdl/backend/modelsdk/workflow_write.go
index f6e8be60bd..16e74d2de6 100644
--- a/mdl/backend/modelsdk/workflow_write.go
+++ b/mdl/backend/modelsdk/workflow_write.go
@@ -29,15 +29,24 @@ func init() {
 		"Workflows$UserTaskOutcome", "Workflows$BooleanConditionOutcome",
 		"Workflows$EnumerationValueConditionOutcome", "Workflows$VoidConditionOutcome",
 		"Workflows$ParallelSplitOutcome",
+		// Measured on ako/TestApp (11.14.0): a notification activity leads a flow
+		// like any other, and a start activity leads every event sub-process flow.
+		"Workflows$NotificationActivity",
+		"Workflows$InterruptingNotificationEventSubProcessStartActivity",
+		"Workflows$NonInterruptingNotificationEventSubProcessStartActivity",
+		"Workflows$InterruptingTimerEventSubProcessStartActivity",
+		"Workflows$NonInterruptingTimerEventSubProcessStartActivity",
 	} {
 		codec.RegisterListMarker(t, 3)
 	}
-	// BoundaryEvents and ParameterMappings serialize with marker 2.
+	// BoundaryEvents, ParameterMappings and EventSubProcesses serialize with marker 2.
 	for _, t := range []string{
 		"Workflows$TimerBoundaryEvent", "Workflows$InterruptingTimerBoundaryEvent",
 		"Workflows$NonInterruptingTimerBoundaryEvent",
+		"Workflows$InterruptingNotificationBoundaryEvent", "Workflows$NonInterruptingNotificationBoundaryEvent",
 		"Workflows$MicroflowCallParameterMapping", "Workflows$WorkflowCallParameterMapping",
 		"Workflows$WorkflowEventHandler",
+		"Workflows$EventSubProcess",
 	} {
 		codec.RegisterListMarker(t, 2)
 	}
@@ -86,6 +95,13 @@ func init() {
 		"Workflows$JumpToActivity", "Workflows$WaitForTimerActivity",
 		"Workflows$StartWorkflowActivity", "Workflows$EndWorkflowActivity",
 		"Workflows$EndOfParallelSplitPathActivity", "Workflows$EndOfBoundaryEventPathActivity",
+		// Each stores Annotation: null (ako/TestApp, 11.14.0).
+		"Workflows$NotificationActivity", "Workflows$EventSubProcess",
+		"Workflows$InterruptingNotificationEventSubProcessStartActivity",
+		"Workflows$NonInterruptingNotificationEventSubProcessStartActivity",
+		"Workflows$InterruptingTimerEventSubProcessStartActivity",
+		"Workflows$NonInterruptingTimerEventSubProcessStartActivity",
+		"Workflows$InterruptingNotificationBoundaryEvent", "Workflows$NonInterruptingNotificationBoundaryEvent",
 	} {
 		codec.RegisterTypeDefaults(t, codec.TypeDefaults{NullFields: []string{"Annotation"}})
 	}
@@ -192,6 +208,15 @@ func workflowToGen(wf *workflows.Workflow) element.Element {
 	}
 	addStr(g, "Documentation", wf.Documentation)
 	addStr(g, "DueDate", wf.DueDate)
+	// EventSubProcesses: a marker-2 list. Studio Pro 11.14 writes it empty too,
+	// but the property only exists from 11.8, so an empty one is not invented.
+	if len(wf.EventSubProcesses) > 0 {
+		esps := make([]element.Element, 0, len(wf.EventSubProcesses))
+		for _, esp := range wf.EventSubProcesses {
+			esps = append(esps, eventSubProcessToGen(esp))
+		}
+		addPartList(g, "EventSubProcesses", esps)
+	}
 	addBool(g, "Excluded", wf.Excluded)
 	addStr(g, "ExportLevel", "Hidden")
 	flow := wf.Flow
@@ -291,11 +316,40 @@ func activityToGen(act workflows.WorkflowActivity) element.Element {
 		return simpleActivityToGen("Workflows$EndOfBoundaryEventPathActivity", &a.BaseWorkflowActivity)
 	case *workflows.WorkflowAnnotationActivity:
 		return annotationActivityToGen(a)
+	case *workflows.NotificationActivity:
+		return simpleActivityToGen("Workflows$NotificationActivity", &a.BaseWorkflowActivity)
+	case *workflows.EventSubProcessStartActivity:
+		g := newElem(a.StorageType(), activityID(&a.BaseWorkflowActivity))
+		addActivityBaseFields(g, a.Annotation)
+		addStr(g, "Caption", a.Caption)
+		if a.Timer {
+			addStr(g, "FirstExecutionTime", a.FirstExecutionTime)
+		}
+		addStr(g, "Name", a.Name)
+		return g
 	default:
 		return nil
 	}
 }
 
+// eventSubProcessToGen builds a Workflows$EventSubProcess in the key order
+// ako/TestApp (11.14.0) stores: Annotation, Caption, Flow, Name, PersistentId.
+func eventSubProcessToGen(esp *workflows.EventSubProcess) element.Element {
+	g := newElem("Workflows$EventSubProcess", activityIDOrFresh(string(esp.ID)))
+	if esp.Annotation != "" {
+		addPart(g, "Annotation", annotationElem(esp.Annotation))
+	}
+	addStr(g, "Caption", esp.Caption)
+	flow := esp.Flow
+	if flow == nil {
+		flow = &workflows.Flow{}
+	}
+	addPart(g, "Flow", flowToGen(flow))
+	addStr(g, "Name", esp.Name)
+	addFreshPersistentID(g)
+	return g
+}
+
 func userTaskToGen(a *workflows.UserTask) element.Element {
 	// UserTask → Single/MultiUserTaskActivity (UserTask was deleted in 10.12.0).
 	typeName := "Workflows$SingleUserTaskActivity"
@@ -616,21 +670,23 @@ func conditionOutcomeToGen(outcome workflows.ConditionOutcome) element.Element {
 func boundaryEventsToGen(events []*workflows.BoundaryEvent) []element.Element {
 	out := make([]element.Element, 0, len(events))
 	for _, ev := range events {
-		typeName := "Workflows$InterruptingTimerBoundaryEvent"
-		switch ev.EventType {
-		case "NonInterruptingTimer":
-			typeName = "Workflows$NonInterruptingTimerBoundaryEvent"
-		case "Timer":
-			typeName = "Workflows$TimerBoundaryEvent"
+		typeName, ok := workflows.BoundaryEventStorageType(ev.EventType)
+		if !ok {
+			// The reader and the builder only produce known kinds; writing an
+			// unknown one as some other kind would mistype it silently.
+			continue
 		}
 		g := newElem(typeName, activityIDOrFresh(string(ev.ID)))
 		addStr(g, "Caption", ev.Caption)
-		if ev.TimerDelay != "" {
+		if ev.TimerDelay != "" && !ev.IsNotification() {
 			addStr(g, "FirstExecutionTime", ev.TimerDelay)
 		}
 		if ev.Flow != nil {
 			addPart(g, "Flow", flowToGen(ev.Flow))
 		}
+		if ev.IsNotification() {
+			addStr(g, "Name", ev.Name)
+		}
 		addFreshPersistentID(g)
 		// Recurrence: null on NonInterrupting (via NullFields).
 		out = append(out, g)
diff --git a/mdl/backend/wfmutator/mutator.go b/mdl/backend/wfmutator/mutator.go
index a91dc830a8..e70dce45fb 100644
--- a/mdl/backend/wfmutator/mutator.go
+++ b/mdl/backend/wfmutator/mutator.go
@@ -503,12 +503,11 @@ func (m *Mutator) InsertBoundaryEvent(activityRef string, atPos int, eventType s
 		return err
 	}
 
-	typeName := "Workflows$InterruptingTimerBoundaryEvent"
-	switch eventType {
-	case "NonInterruptingTimer":
-		typeName = "Workflows$NonInterruptingTimerBoundaryEvent"
-	case "Timer":
-		typeName = "Workflows$TimerBoundaryEvent"
+	// Unknown kinds used to fall through to an interrupting timer. A notification
+	// event needs a name this op does not carry, so it is refused too.
+	typeName, ok := workflows.BoundaryEventStorageType(eventType)
+	if !ok || (&workflows.BoundaryEvent{EventType: eventType}).IsNotification() {
+		return fmt.Errorf("insert boundary event: %q boundary events cannot be inserted by ALTER WORKFLOW", eventType)
 	}
 
 	eventDoc := bson.D{
diff --git a/mdl/executor/cmd_alter_workflow.go b/mdl/executor/cmd_alter_workflow.go
index f8d1c32727..97f986b520 100644
--- a/mdl/executor/cmd_alter_workflow.go
+++ b/mdl/executor/cmd_alter_workflow.go
@@ -37,6 +37,12 @@ func execAlterWorkflow(ctx *ExecContext, s *ast.AlterWorkflowStmt) error {
 			return err
 		}
 	}
+	if workflowUsesNotificationEvents(alterWorkflowAddedActivities(s)) {
+		if err := checkFeature(ctx, "workflows", "notification_events", "notification activities and notification boundary events",
+			"these need Mendix 11.11 or later — use `wait for notification` on older projects"); err != nil {
+			return err
+		}
+	}
 
 	// Same exec-side guard as CREATE WORKFLOW: ALTER had no reference validation
 	// at all, so an inserted activity could name a microflow that exists nowhere
@@ -177,6 +183,12 @@ func execAlterWorkflow(ctx *ExecContext, s *ast.AlterWorkflowStmt) error {
 			}
 
 		case *ast.InsertBoundaryEventOp:
+			// The op carries no name, and a notification boundary event is only
+			// reachable by its name. Refused rather than written unnamed.
+			if (&workflows.BoundaryEvent{EventType: o.EventType}).IsNotification() {
+				return mdlerrors.NewUnsupported("insert boundary event: a notification boundary event cannot be inserted with ALTER WORKFLOW yet — " +
+					"restate the workflow with CREATE OR MODIFY WORKFLOW, which accepts `boundary event interrupting notification <name> '<caption>' { … }`")
+			}
 			acts := buildAndBindActivities(ctx, o.Activities)
 			if err := mutator.InsertBoundaryEvent(o.ActivityRef, o.AtPosition, o.EventType, o.Delay, acts); err != nil {
 				return mdlerrors.NewBackend("insert boundary event", err)
diff --git a/mdl/executor/cmd_workflows.go b/mdl/executor/cmd_workflows.go
index 572507d12c..a5f234abd4 100644
--- a/mdl/executor/cmd_workflows.go
+++ b/mdl/executor/cmd_workflows.go
@@ -230,6 +230,7 @@ func describeWorkflowToString(ctx *ExecContext, name ast.QualifiedName) (string,
 		actLines := formatMainFlowActivities(targetWf.Flow, "  ")
 		lines = append(lines, actLines...)
 	}
+	lines = append(lines, formatEventSubProcesses(targetWf.EventSubProcesses, "  ")...)
 
 	lines = append(lines, "end workflow")
 	lines = append(lines, "/")
@@ -290,6 +291,10 @@ func boundaryEventKeyword(eventType string) string {
 		return "boundary event interrupting timer"
 	case "NonInterruptingTimer":
 		return "boundary event non interrupting timer"
+	case "InterruptingNotification":
+		return "boundary event interrupting notification"
+	case "NonInterruptingNotification":
+		return "boundary event non interrupting notification"
 	default:
 		return "boundary event timer"
 	}
@@ -304,7 +309,18 @@ func formatBoundaryEvents(events []*workflows.BoundaryEvent, indent string) []st
 	var lines []string
 	for _, event := range events {
 		keyword := boundaryEventKeyword(event.EventType)
-		if event.TimerDelay != "" {
+		if event.IsNotification() {
+			// Its name is what `notify workflow … target` names, so it is always
+			// emitted; the string is the caption.
+			header := indent + keyword
+			if event.Name != "" {
+				header += " " + mdlIdent(event.Name)
+			}
+			if event.Caption != "" {
+				header += " " + mdlQuoted(event.Caption)
+			}
+			lines = append(lines, header)
+		} else if event.TimerDelay != "" {
 			lines = append(lines, fmt.Sprintf("%s%s %s", indent, keyword, mdlQuoted(event.TimerDelay)))
 		} else {
 			lines = append(lines, fmt.Sprintf("%s%s", indent, keyword))
@@ -320,6 +336,53 @@ func formatBoundaryEvents(events []*workflows.BoundaryEvent, indent string) []st
 	return lines
 }
 
+// formatEventSubProcesses emits each event sub-process as a block after the main
+// body. Its flow's End is implicit, like the main flow's — the builder appends
+// one when the body does not already end — so it is formatted as a main flow.
+func formatEventSubProcesses(esps []*workflows.EventSubProcess, indent string) []string {
+	var lines []string
+	for _, esp := range esps {
+		start := esp.Start()
+		if start == nil {
+			// Nothing MDL can state starts it; the rewrite guard refuses to drop it.
+			lines = append(lines, fmt.Sprintf("%s-- event subprocess %s has no start event, which MDL cannot state", indent, esp.Name), "")
+			continue
+		}
+		header := indent + "event subprocess " + mdlIdent(esp.Name)
+		if esp.Caption != "" {
+			header += " " + mdlQuoted(esp.Caption)
+		}
+		trigger := "non interrupting"
+		if start.Interrupting {
+			trigger = "interrupting"
+		}
+		if start.Timer {
+			header += fmt.Sprintf(" on %s timer %s", trigger, mdlQuoted(start.FirstExecutionTime))
+			if start.Name != "" {
+				header += " as " + mdlIdent(start.Name)
+			}
+			if start.Caption != "" {
+				header += " comment " + mdlQuoted(start.Caption)
+			}
+		} else {
+			header += fmt.Sprintf(" on %s notification", trigger)
+			if start.Name != "" {
+				header += " " + mdlIdent(start.Name)
+			}
+			if start.Caption != "" {
+				header += " " + mdlQuoted(start.Caption)
+			}
+		}
+		if esp.Annotation != "" {
+			lines = append(lines, formatAnnotation(esp.Annotation, indent))
+		}
+		lines = append(lines, header+" {")
+		lines = append(lines, formatMainFlowActivities(esp.Flow, indent+"  ")...)
+		lines = append(lines, indent+"};", "")
+	}
+	return lines
+}
+
 // formatWorkflowActivities generates MDL-like output for workflow activities.
 // formatWorkflowActivities formats a nested flow — an outcome, a branch, a path,
 // a boundary-event path — where an End is an `end workflow` the author wrote.
@@ -400,9 +463,24 @@ func formatFlowActivities(flow *workflows.Flow, indent string, mainFlow bool) []
 				workflowActivityNameClause(a.Name, caption), caption))
 			// BoundaryEvents
 			actLines = append(actLines, formatBoundaryEvents(a.BoundaryEvents, indent+"  ")...)
+		case *workflows.NotificationActivity:
+			if a.Annotation != "" {
+				actLines = append(actLines, formatAnnotation(a.Annotation, indent))
+			}
+			line := indent + "notification"
+			if a.Name != "" {
+				line += " " + mdlIdent(a.Name)
+			}
+			if a.Caption != "" {
+				line += " comment " + mdlQuoted(a.Caption)
+			}
+			actLines = append(actLines, line)
 		case *workflows.StartWorkflowActivity:
 			// Skip start activities - they are implicit
 			continue
+		case *workflows.EventSubProcessStartActivity:
+			// Stated in the `event subprocess … on …` header.
+			continue
 		case *workflows.EndWorkflowActivity:
 			if mainFlow {
 				// The main flow's End is implicit: `end workflow` closes the body.
diff --git a/mdl/executor/cmd_workflows_write.go b/mdl/executor/cmd_workflows_write.go
index a949872dfb..2dd6b76f31 100644
--- a/mdl/executor/cmd_workflows_write.go
+++ b/mdl/executor/cmd_workflows_write.go
@@ -68,6 +68,9 @@ func execCreateWorkflow(ctx *ExecContext, s *ast.CreateWorkflowStmt) error {
 	if vs := ValidateWorkflowCompletionRules(s); len(vs) > 0 {
 		return mdlerrors.NewValidationf("%s\n  → %s", vs[0].Message, vs[0].Suggestion)
 	}
+	if vs := ValidateWorkflowEventSubProcesses(s); len(vs) > 0 {
+		return mdlerrors.NewValidationf("%s\n  → %s", vs[0].Message, vs[0].Suggestion)
+	}
 	if vs := ValidateWorkflowEventTypes(s); len(vs) > 0 {
 		return mdlerrors.NewValidationf("%s\n  → %s", vs[0].Message, vs[0].Suggestion)
 	}
@@ -77,12 +80,15 @@ func execCreateWorkflow(ctx *ExecContext, s *ast.CreateWorkflowStmt) error {
 			return err
 		}
 	}
-	if workflowUsesAgentTask(s.Activities) {
+	if workflowUsesAgentTask(workflowStatementActivities(s)) {
 		if err := checkFeature(ctx, "workflows", "ai_agent_task", "call agent microflow",
 			"AI agent tasks need Mendix 11.9 or later — use `call microflow` on older projects"); err != nil {
 			return err
 		}
 	}
+	if err := checkEventSubProcessFeatures(ctx, s); err != nil {
+		return err
+	}
 
 	if refErrors := validateWorkflowStatementRefs(ctx, s, nil); len(refErrors) > 0 {
 		return mdlerrors.NewValidationf("workflow '%s' has reference errors:\n  - %s",
@@ -203,11 +209,21 @@ func execCreateWorkflow(ctx *ExecContext, s *ast.CreateWorkflowStmt) error {
 	// Auto-bind microflow/workflow parameters and sanitize names
 	autoBindWorkflowParameters(ctx, userActivities, s.ParameterVar)
 
+	// Event sub-processes. Their activities share the workflow's one namespace —
+	// a start event named like a main-flow activity is CE0495 — so they are
+	// deduplicated together with the main flow's.
+	wf.EventSubProcesses = buildEventSubProcesses(s.EventSubProcesses)
+	named := append([]workflows.WorkflowActivity{}, userActivities...)
+	for _, esp := range wf.EventSubProcesses {
+		autoBindWorkflowParameters(ctx, esp.Flow.Activities, s.ParameterVar)
+		named = append(named, esp.Flow.Activities...)
+	}
+
 	// Deduplicate activity names to avoid CE0495
 	// The implicit Start and End take part: an `end workflow` inside a branch is
 	// named after its caption, "End" by default, and colliding with the main
 	// flow's End is CE0495 "Duplicate name 'End'".
-	deduplicateActivityNames(userActivities, startAct.Name, endAct.Name)
+	deduplicateActivityNames(named, startAct.Name, endAct.Name)
 
 	// Compose: start + user activities + end
 	flow.Activities = make([]workflows.WorkflowActivity, 0, len(userActivities)+2)
@@ -293,6 +309,18 @@ func buildBoundaryEvents(nodes []ast.WorkflowBoundaryEventNode) []*workflows.Bou
 		event := &workflows.BoundaryEvent{
 			EventType:  be.EventType,
 			TimerDelay: be.Delay,
+			Name:       be.Name,
+			Caption:    be.Caption,
+		}
+		if event.IsNotification() {
+			// Mendix requires both: the name is what a notify action targets
+			// (unique in the workflow, made so by deduplicateActivityNames).
+			if event.Name == "" {
+				event.Name = "NotificationEvent"
+			}
+			if event.Caption == "" {
+				event.Caption = event.Name
+			}
 		}
 		event.ID = model.ID(generateWorkflowUUID())
 		if len(be.Activities) > 0 {
@@ -330,6 +358,8 @@ func buildWorkflowActivity(node ast.WorkflowActivityNode) workflows.WorkflowActi
 		return buildWaitForTimer(n)
 	case *ast.WorkflowWaitForNotificationNode:
 		return buildWaitForNotification(n)
+	case *ast.WorkflowNotificationNode:
+		return buildNotificationActivity(n)
 	case *ast.WorkflowEndNode:
 		return buildEndWorkflow(n)
 	case *ast.WorkflowAnnotationActivityNode:
@@ -751,6 +781,64 @@ func buildWaitForNotification(n *ast.WorkflowWaitForNotificationNode) *workflows
 	return act
 }
 
+// buildNotificationActivity builds an intermediate notification event. Mendix
+// requires a name (CE0725).
+func buildNotificationActivity(n *ast.WorkflowNotificationNode) *workflows.NotificationActivity {
+	act := &workflows.NotificationActivity{}
+	act.ID = model.ID(generateWorkflowUUID())
+	act.Name = n.Name
+	if act.Name == "" {
+		act.Name = "Notification"
+	}
+	act.Caption = n.Caption
+	if act.Caption == "" {
+		act.Caption = act.Name
+	}
+	return act
+}
+
+// buildEventSubProcesses builds each event sub-process's flow: its start event,
+// the body, and — as in the main flow — an implicit End when the body does not
+// already end. Measured on mxbuild 11.13.0: a flow with no end is CE0105, and one
+// that ends in a jump, or in branches that all end, takes no End after it
+// (CE6689 otherwise).
+func buildEventSubProcesses(nodes []ast.WorkflowEventSubProcessNode) []*workflows.EventSubProcess {
+	var out []*workflows.EventSubProcess
+	for _, n := range nodes {
+		esp := &workflows.EventSubProcess{Name: n.Name, Caption: n.Caption}
+		esp.ID = model.ID(generateWorkflowUUID())
+
+		start := &workflows.EventSubProcessStartActivity{
+			Interrupting:       n.Interrupting,
+			Timer:              n.Timer,
+			FirstExecutionTime: n.FirstExecutionTime,
+		}
+		start.ID = model.ID(generateWorkflowUUID())
+		start.Name = n.StartName
+		if start.Name == "" {
+			start.Name = n.Name + "Start"
+		}
+		start.Caption = n.StartCaption
+		if start.Caption == "" {
+			start.Caption = start.Name
+		}
+
+		flow := &workflows.Flow{}
+		flow.ID = model.ID(generateWorkflowUUID())
+		flow.Activities = append([]workflows.WorkflowActivity{start}, buildWorkflowActivities(n.Activities)...)
+		if !flowEnds(n.Activities) {
+			end := &workflows.EndWorkflowActivity{}
+			end.ID = model.ID(generateWorkflowUUID())
+			end.Caption = "End"
+			end.Name = "End"
+			flow.Activities = append(flow.Activities, end)
+		}
+		esp.Flow = flow
+		out = append(out, esp)
+	}
+	return out
+}
+
 func buildEndWorkflow(n *ast.WorkflowEndNode) *workflows.EndWorkflowActivity {
 	act := &workflows.EndWorkflowActivity{}
 	act.ID = model.ID(generateWorkflowUUID())
@@ -801,6 +889,7 @@ func deduplicateActivityNamesInFlow(activities []workflows.WorkflowActivity, nam
 			*workflows.ExclusiveSplitActivity, *workflows.ParallelSplitActivity,
 			*workflows.WaitForTimerActivity, *workflows.WaitForNotificationActivity,
 			*workflows.EndWorkflowActivity,
+			*workflows.NotificationActivity, *workflows.EventSubProcessStartActivity,
 			// The end-of-path markers carry names too, and Mendix holds them to the
 			// same uniqueness rule: every path of every split used to be written as
 			// "EndOfParallelSplitPath", which mxbuild refuses as CE0495.
@@ -808,6 +897,17 @@ func deduplicateActivityNamesInFlow(activities []workflows.WorkflowActivity, nam
 			if !jumpPass {
 				act.SetName(uniqueName(act.GetName(), nameCount))
 			}
+		}
+		// A notification boundary event's name is unique in the workflow too — it
+		// is what a notify action targets.
+		if !jumpPass {
+			for _, be := range activityBoundaryEvents(act) {
+				if be != nil && be.IsNotification() {
+					be.Name = uniqueName(be.Name, nameCount)
+				}
+			}
+		}
+		switch act.(type) {
 		case *workflows.JumpToActivity:
 			if jumpPass {
 				act.SetName(uniqueName(act.GetName(), nameCount))
@@ -860,6 +960,21 @@ func sanitizeActivityName(name string) string {
 	return result
 }
 
+// activityBoundaryEvents returns the boundary events an activity carries.
+func activityBoundaryEvents(act workflows.WorkflowActivity) []*workflows.BoundaryEvent {
+	switch a := act.(type) {
+	case *workflows.UserTask:
+		return a.BoundaryEvents
+	case *workflows.CallMicroflowTask:
+		return a.BoundaryEvents
+	case *workflows.CallWorkflowActivity:
+		return a.BoundaryEvents
+	case *workflows.WaitForNotificationActivity:
+		return a.BoundaryEvents
+	}
+	return nil
+}
+
 // nestedFlows returns every flow nested inside a workflow activity: condition
 // outcomes (a decision's and a call-microflow's), user-task outcomes, parallel
 // split paths, and boundary-event bodies.
diff --git a/mdl/executor/validate_workflow.go b/mdl/executor/validate_workflow.go
index fa1e465bd7..4bc5ef443c 100644
--- a/mdl/executor/validate_workflow.go
+++ b/mdl/executor/validate_workflow.go
@@ -66,7 +66,7 @@ func ValidateWorkflow(stmt *ast.CreateWorkflowStmt) []linter.Violation {
 		DocumentType: "workflow",
 		DocumentName: stmt.Name.Name,
 	}
-	walkWorkflowActivities(stmt.Activities, func(a ast.WorkflowActivityNode) {
+	walkWorkflowActivities(workflowStatementActivities(stmt), func(a ast.WorkflowActivityNode) {
 		switch n := a.(type) {
 		case *ast.WorkflowUserTaskNode:
 			label := workflowUserTaskLabel(n)
@@ -124,6 +124,7 @@ func ValidateWorkflow(stmt *ast.CreateWorkflowStmt) []linter.Violation {
 	out = append(out, ValidateWorkflowEnds(stmt)...)
 	out = append(out, ValidateWorkflowEventTypes(stmt)...)
 	out = append(out, ValidateWorkflowCompletionRules(stmt)...)
+	out = append(out, ValidateWorkflowEventSubProcesses(stmt)...)
 	return out
 }
 
diff --git a/mdl/executor/validate_workflow_completion.go b/mdl/executor/validate_workflow_completion.go
index ac3ede7338..45ea0ee161 100644
--- a/mdl/executor/validate_workflow_completion.go
+++ b/mdl/executor/validate_workflow_completion.go
@@ -28,7 +28,7 @@ import (
 
 // ValidateWorkflowCompletionRules applies MDL-WF13 to a CREATE WORKFLOW body.
 func ValidateWorkflowCompletionRules(stmt *ast.CreateWorkflowStmt) []linter.Violation {
-	return completionRuleViolations(stmt.Activities, workflowLocation(stmt.Name))
+	return completionRuleViolations(workflowStatementActivities(stmt), workflowLocation(stmt.Name))
 }
 
 // completionRuleViolations reports MDL-WF13 for every multi-user task, at any
diff --git a/mdl/executor/validate_workflow_end.go b/mdl/executor/validate_workflow_end.go
index 56ca6468c5..eebe9473f0 100644
--- a/mdl/executor/validate_workflow_end.go
+++ b/mdl/executor/validate_workflow_end.go
@@ -51,7 +51,7 @@ func collectEndBodies(b endBody, out *[]endBody) {
 	}
 	boundary := func(events []ast.WorkflowBoundaryEventNode) {
 		for _, e := range events {
-			child(e.Activities, false, e.EventType == "NonInterruptingTimer")
+			child(e.Activities, false, nonInterruptingEventType(e.EventType))
 		}
 	}
 	for _, a := range b.activities {
@@ -80,6 +80,12 @@ func collectEndBodies(b endBody, out *[]endBody) {
 	}
 }
 
+// nonInterruptingEventType reports whether a boundary event of this kind runs
+// alongside its activity (timer or notification).
+func nonInterruptingEventType(eventType string) bool {
+	return (&workflows.BoundaryEvent{EventType: eventType}).IsNonInterrupting()
+}
+
 // flowEnds reports whether control can never leave the end of a block.
 func flowEnds(acts []ast.WorkflowActivityNode) bool {
 	return len(acts) > 0 && activityEnds(acts[len(acts)-1])
@@ -142,6 +148,11 @@ func branchingLabel(a ast.WorkflowActivityNode) string {
 func ValidateWorkflowEnds(stmt *ast.CreateWorkflowStmt) []linter.Violation {
 	var bodies []endBody
 	collectEndBodies(endBody{activities: stmt.Activities, mainFlow: true}, &bodies)
+	// An event sub-process body is its own flow: `end workflow` may close it,
+	// and one that already ends takes no implicit End (the builder adds none).
+	for _, esp := range stmt.EventSubProcesses {
+		collectEndBodies(endBody{activities: esp.Activities}, &bodies)
+	}
 	return checkEndBodies(bodies, workflowLocation(stmt.Name))
 }
 
@@ -165,7 +176,7 @@ func ValidateAlterWorkflowEnds(stmt *ast.AlterWorkflowStmt) []linter.Violation {
 		case *ast.InsertPathOp:
 			collectEndBodies(endBody{activities: o.Activities, underSplit: true}, &bodies)
 		case *ast.InsertBoundaryEventOp:
-			collectEndBodies(endBody{activities: o.Activities, underNonInterrupting: o.EventType == "NonInterruptingTimer"}, &bodies)
+			collectEndBodies(endBody{activities: o.Activities, underNonInterrupting: nonInterruptingEventType(o.EventType)}, &bodies)
 		}
 	}
 	return checkEndBodies(bodies, workflowLocation(stmt.Name))
@@ -279,7 +290,7 @@ func validateAlterWorkflowEndAncestry(ctx *ExecContext, s *ast.AlterWorkflowStmt
 		case *ast.InsertBranchOp:
 			check("insert condition", o.ActivityRef, o.AtPosition, o.Activities)
 		case *ast.InsertBoundaryEventOp:
-			if o.EventType != "NonInterruptingTimer" { // that one is reported without a project
+			if !nonInterruptingEventType(o.EventType) { // that one is reported without a project
 				check("insert boundary event", o.ActivityRef, o.AtPosition, o.Activities)
 			}
 		}
@@ -320,7 +331,7 @@ func collectStoredPlacements(flow *workflows.Flow, ref string, at storedPlacemen
 		for _, b := range events {
 			if b != nil {
 				nested := at
-				nested.underNonInterrupting = at.underNonInterrupting || b.EventType == "NonInterruptingTimer"
+				nested.underNonInterrupting = at.underNonInterrupting || b.IsNonInterrupting()
 				collectStoredPlacements(b.Flow, ref, nested, out)
 			}
 		}
diff --git a/mdl/executor/validate_workflow_esp.go b/mdl/executor/validate_workflow_esp.go
new file mode 100644
index 0000000000..0b3bf9e457
--- /dev/null
+++ b/mdl/executor/validate_workflow_esp.go
@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// Event sub-processes and notification events. Measured against mxbuild 11.13.0
+// with Studio Pro-saved shapes (ako/TestApp), one construct per workflow,
+// verdict = the literal `mx check` line:
+//
+//	notification or timer start, interrupting or not, body ending in End     0 errors
+//	a body with activities, or ending in a jump within its sub-process       0 errors
+//	a body with no end                                                       CE0105  (the builder adds an End)
+//	a jump into another sub-process, or between one and the main flow        CE6682  MDL-WF05
+//	a timer start with no first execution time                               CE0126  MDL-WF14
+//	a start event named like another activity                                CE0495  (deduplicated)
+//	the boundary-path end marker inside a sub-process                        CE6692  (not authorable)
+//	a notification boundary event on a user task, multi-user task, call
+//	  microflow, wait for notification or wait for timer                     0 errors
+//	an interrupting notification path ending in the end-of-path marker       0 errors
+//	an interrupting notification path with no end                            CE0105  (the builder adds the marker)
+//	two interrupting boundary events on one activity                         CE6697  MDL-WF15
+//	a notification activity in the main flow                                 0 errors
+//
+// Which mxbuild knows which type, measured by loading each construct alone into
+// a blank project of that version (an unknown type is TypeCacheUnknownTypeException,
+// and the project does not load):
+//
+//	                                          11.10   11.11   11.12   11.13
+//	notification-started event sub-process    yes     yes     yes     yes     workflows.event_subprocesses (11.8, gen)
+//	notification activity / boundary events   no      yes     yes     yes     workflows.notification_events
+//	timer-started event sub-process           no      no      no      yes     workflows.timer_event_subprocesses
+package executor
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/mdl/linter"
+)
+
+// workflowStatementActivities returns every top-level block a statement writes:
+// the main body, then each event sub-process body. Rules and guards that walk
+// "the workflow's activities" must see both — a microflow called only from a
+// sub-process is still a reference, and a boundary event there is still stored.
+func workflowStatementActivities(stmt *ast.CreateWorkflowStmt) []ast.WorkflowActivityNode {
+	if len(stmt.EventSubProcesses) == 0 {
+		return stmt.Activities
+	}
+	out := append([]ast.WorkflowActivityNode{}, stmt.Activities...)
+	for _, esp := range stmt.EventSubProcesses {
+		out = append(out, esp.Activities...)
+	}
+	return out
+}
+
+// workflowUsesNotificationEvents reports whether activities hold a notification
+// activity or a notification boundary event.
+func workflowUsesNotificationEvents(activities []ast.WorkflowActivityNode) bool {
+	found := false
+	walkWorkflowActivities(activities, func(a ast.WorkflowActivityNode) {
+		var events []ast.WorkflowBoundaryEventNode
+		switch n := a.(type) {
+		case *ast.WorkflowNotificationNode:
+			found = true
+		case *ast.WorkflowUserTaskNode:
+			events = n.BoundaryEvents
+		case *ast.WorkflowCallMicroflowNode:
+			events = n.BoundaryEvents
+		case *ast.WorkflowWaitForNotificationNode:
+			events = n.BoundaryEvents
+		}
+		for _, e := range events {
+			if e.EventType == "InterruptingNotification" || e.EventType == "NonInterruptingNotification" {
+				found = true
+			}
+		}
+	})
+	return found
+}
+
+// checkEventSubProcessFeatures refuses what the project's Mendix version cannot
+// load (see the table above).
+func checkEventSubProcessFeatures(ctx *ExecContext, stmt *ast.CreateWorkflowStmt) error {
+	if len(stmt.EventSubProcesses) > 0 {
+		if err := checkFeature(ctx, "workflows", "event_subprocesses", "event subprocess",
+			"event sub-processes need Mendix 11.8 or later"); err != nil {
+			return err
+		}
+	}
+	for _, esp := range stmt.EventSubProcesses {
+		if esp.Timer {
+			if err := checkFeature(ctx, "workflows", "timer_event_subprocesses", "event subprocess … on … timer",
+				"a timer-started event sub-process needs Mendix 11.13 or later — start it with a notification on older projects"); err != nil {
+				return err
+			}
+			break
+		}
+	}
+	if workflowUsesNotificationEvents(workflowStatementActivities(stmt)) {
+		if err := checkFeature(ctx, "workflows", "notification_events", "notification activities and notification boundary events",
+			"these need Mendix 11.11 or later — use `wait for notification` on older projects"); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// ValidateWorkflowEventSubProcesses applies MDL-WF14 and MDL-WF15.
+func ValidateWorkflowEventSubProcesses(stmt *ast.CreateWorkflowStmt) []linter.Violation {
+	loc := workflowLocation(stmt.Name)
+	var out []linter.Violation
+	for _, esp := range stmt.EventSubProcesses {
+		if esp.Timer && strings.TrimSpace(esp.FirstExecutionTime) == "" {
+			out = append(out, linter.Violation{
+				RuleID:     "MDL-WF14",
+				Severity:   linter.SeverityError,
+				Location:   loc,
+				Message:    fmt.Sprintf("event subprocess %s starts on a timer with no first execution time — the build fails CE0126", esp.Name),
+				Suggestion: "Give the timer an expression, e.g. `on interrupting timer 'addDays([%CurrentDateTime%], 1)'`.",
+			})
+		}
+	}
+	walkWorkflowActivities(workflowStatementActivities(stmt), func(a ast.WorkflowActivityNode) {
+		var events []ast.WorkflowBoundaryEventNode
+		var label string
+		switch n := a.(type) {
+		case *ast.WorkflowUserTaskNode:
+			events, label = n.BoundaryEvents, "user task "+workflowUserTaskLabel(n)
+		case *ast.WorkflowCallMicroflowNode:
+			events, label = n.BoundaryEvents, "call microflow "+workflowCallMicroflowLabel(n)
+		case *ast.WorkflowWaitForNotificationNode:
+			name := n.Name
+			if name == "" {
+				name = n.Caption
+			}
+			events, label = n.BoundaryEvents, fmt.Sprintf("wait for notification '%s'", name)
+		}
+		interrupting := 0
+		for _, e := range events {
+			if e.EventType == "InterruptingTimer" || e.EventType == "InterruptingNotification" {
+				interrupting++
+			}
+		}
+		if interrupting > 1 {
+			out = append(out, linter.Violation{
+				RuleID:     "MDL-WF15",
+				Severity:   linter.SeverityError,
+				Location:   loc,
+				Message:    fmt.Sprintf("%s has %d interrupting boundary events — Mendix allows one per activity; the build fails CE6697", label, interrupting),
+				Suggestion: "Keep one interrupting boundary event and make the others `non interrupting`.",
+			})
+		}
+	})
+	return out
+}
diff --git a/mdl/executor/validate_workflow_jump.go b/mdl/executor/validate_workflow_jump.go
index f4827f1925..6715048088 100644
--- a/mdl/executor/validate_workflow_jump.go
+++ b/mdl/executor/validate_workflow_jump.go
@@ -38,9 +38,29 @@ func ValidateWorkflowJumpTargets(stmt *ast.CreateWorkflowStmt) []linter.Violatio
 	if stmt == nil {
 		return nil
 	}
-	built := buildWorkflowActivities(stmt.Activities)
-	targets := map[string]bool{}
-	collectJumpableNames(built, targets)
+
+	// Each flow is its own jump scope. Measured on mxbuild 11.13.0: a jump inside
+	// an event sub-process to an activity of the same sub-process, or to its start
+	// event, builds; a jump into another sub-process, or between one and the main
+	// flow, is CE6682 ("not possible to jump into or out of a Event sub-process
+	// path").
+	type jumpScope struct {
+		label      string
+		activities []ast.WorkflowActivityNode
+		targets    map[string]bool
+	}
+	mainTargets := map[string]bool{}
+	collectJumpableNames(buildWorkflowActivities(stmt.Activities), mainTargets)
+	scopes := []jumpScope{{label: "the main flow", activities: stmt.Activities, targets: mainTargets}}
+	for i, esp := range buildEventSubProcesses(stmt.EventSubProcesses) {
+		targets := map[string]bool{}
+		collectJumpableNames(esp.Flow.Activities, targets)
+		scopes = append(scopes, jumpScope{
+			label:      "event subprocess " + stmt.EventSubProcesses[i].Name,
+			activities: stmt.EventSubProcesses[i].Activities,
+			targets:    targets,
+		})
+	}
 
 	loc := linter.Location{
 		Module:       stmt.Name.Module,
@@ -49,25 +69,37 @@ func ValidateWorkflowJumpTargets(stmt *ast.CreateWorkflowStmt) []linter.Violatio
 	}
 
 	var out []linter.Violation
-	walkWorkflowActivities(stmt.Activities, func(a ast.WorkflowActivityNode) {
-		n, ok := a.(*ast.WorkflowJumpToNode)
-		if !ok || n.Target == "" {
-			return
-		}
-		if targets[n.Target] {
-			return
-		}
-		out = append(out, linter.Violation{
-			RuleID:   jumpTargetRule,
-			Severity: linter.SeverityError,
-			Location: loc,
-			Message: fmt.Sprintf("jump target %q does not match any activity in this workflow — "+
-				"Mendix resolves a jump by activity name, so this is written as a jump to itself and "+
-				"the build fails with CE6681 (\"not possible to jump to end activities or jump-to activities\")",
-				n.Target),
-			Suggestion: jumpTargetSuggestion(targets),
+	for _, sc := range scopes {
+		walkWorkflowActivities(sc.activities, func(a ast.WorkflowActivityNode) {
+			n, ok := a.(*ast.WorkflowJumpToNode)
+			if !ok || n.Target == "" || sc.targets[n.Target] {
+				return
+			}
+			for _, other := range scopes {
+				if other.targets[n.Target] {
+					out = append(out, linter.Violation{
+						RuleID:   jumpTargetRule,
+						Severity: linter.SeverityError,
+						Location: loc,
+						Message: fmt.Sprintf("jump target %q is in %s, but the jump is in %s — Mendix refuses a jump into or "+
+							"out of an event sub-process; the build fails CE6682", n.Target, other.label, sc.label),
+						Suggestion: "Jump only within the same flow. An event sub-process ends with `end workflow;`, and is started by notifying its start event.",
+					})
+					return
+				}
+			}
+			out = append(out, linter.Violation{
+				RuleID:   jumpTargetRule,
+				Severity: linter.SeverityError,
+				Location: loc,
+				Message: fmt.Sprintf("jump target %q does not match any activity in this workflow — "+
+					"Mendix resolves a jump by activity name, so this is written as a jump to itself and "+
+					"the build fails with CE6681 (\"not possible to jump to end activities or jump-to activities\")",
+					n.Target),
+				Suggestion: jumpTargetSuggestion(sc.targets),
+			})
 		})
-	})
+	}
 	return out
 }
 
@@ -132,6 +164,12 @@ func collectJumpableNames(acts []workflows.WorkflowActivity, out map[string]bool
 			}
 		case *workflows.WaitForTimerActivity:
 			add(a.Name)
+		case *workflows.NotificationActivity:
+			add(a.Name)
+		case *workflows.EventSubProcessStartActivity:
+			// Measured: a jump to its own start event builds (it resets the
+			// sub-process to waiting).
+			add(a.Name)
 		case *workflows.WaitForNotificationActivity:
 			add(a.Name)
 			collectBoundaryEventNames(a.BoundaryEvents, out)
diff --git a/mdl/executor/validate_workflow_refs.go b/mdl/executor/validate_workflow_refs.go
index ad943d066b..e15dca017a 100644
--- a/mdl/executor/validate_workflow_refs.go
+++ b/mdl/executor/validate_workflow_refs.go
@@ -39,7 +39,7 @@ func validateWorkflowParameterMappings(ctx *ExecContext, s *ast.CreateWorkflowSt
 	}
 
 	var errs []string
-	walkWorkflowActivities(s.Activities, func(act ast.WorkflowActivityNode) {
+	walkWorkflowActivities(workflowStatementActivities(s), func(act ast.WorkflowActivityNode) {
 		cm, ok := act.(*ast.WorkflowCallMicroflowNode)
 		if !ok {
 			return
@@ -181,14 +181,16 @@ func validateWorkflowStatementRefs(ctx *ExecContext, s *ast.CreateWorkflowStmt,
 			}
 		}
 	}
-	errs = append(errs, bareTimerBoundaryEventErrors(ctx, s.Activities, 0)...)
-	errs = append(errs, validateWorkflowReferences(ctx, s.Activities, sc)...)
+	// Event sub-process bodies reference microflows, pages and entities too.
+	activities := workflowStatementActivities(s)
+	errs = append(errs, bareTimerBoundaryEventErrors(ctx, activities, 0)...)
+	errs = append(errs, validateWorkflowReferences(ctx, activities, sc)...)
 	errs = append(errs, validateWorkflowEventHandlers(ctx, s, sc)...)
 	// Then the signatures of the page and targeting microflow each user task
 	// hands work to — names that resolve can still be the wrong shape (CE7410,
 	// CE7412, CE6677). A target that did not resolve is skipped there, so it is
 	// reported once, above.
-	return append(errs, validateWorkflowTaskSignatures(ctx, s.Activities, s.ParameterEntity.String(), sc)...)
+	return append(errs, validateWorkflowTaskSignatures(ctx, activities, s.ParameterEntity.String(), sc)...)
 }
 
 // bareTimerBoundaryEventErrors refuses `boundary event timer` without a kind
diff --git a/mdl/executor/validate_workflow_rewrite.go b/mdl/executor/validate_workflow_rewrite.go
index 9b54185504..ba0c6c8f21 100644
--- a/mdl/executor/validate_workflow_rewrite.go
+++ b/mdl/executor/validate_workflow_rewrite.go
@@ -11,6 +11,7 @@ import (
 	"github.com/mendixlabs/mxcli/mdl/ast"
 	mdlerrors "github.com/mendixlabs/mxcli/mdl/errors"
 	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
 
 	"go.mongodb.org/mongo-driver/bson/primitive"
 )
@@ -27,8 +28,9 @@ import (
 //
 // Boundary events ARE authorable (`boundary event interrupting timer '…' { … }`),
 // so a script that restates them is allowed straight through — that is the normal
-// way to edit a workflow that has one. Event sub-processes are not authorable in
-// MDL at all, so any stored one refuses the rewrite outright.
+// way to edit a workflow that has one. So are event sub-processes and
+// notification activities now; only a sub-process with no start event, which MDL
+// has no way to state, refuses the rewrite outright.
 //
 // The stored side is read from the raw unit rather than through the semantic
 // model deliberately: the reader is what was blind here in the first place, and a
@@ -49,8 +51,8 @@ func checkNoDroppedWorkflowConstructs(ctx *ExecContext, workflowID model.ID, qua
 	// Constructs MDL cannot express at all — a rewrite would lose them without a
 	// word. Refused outright, and every reason is listed at once.
 	var cannotExpress []string
-	if n := countEventSubProcesses(raw); n > 0 {
-		cannotExpress = append(cannotExpress, fmt.Sprintf("%d event sub-process(es), which it would delete", n))
+	if n := rawEventSubProcessesWithoutStart(raw); n > 0 {
+		cannotExpress = append(cannotExpress, fmt.Sprintf("%d event sub-process(es) with no start event, which it would delete", n))
 	}
 	cannotExpress = append(cannotExpress, studioProOnlyWorkflowState(raw)...)
 	if len(cannotExpress) > 0 {
@@ -61,6 +63,30 @@ func checkNoDroppedWorkflowConstructs(ctx *ExecContext, workflowID model.ID, qua
 			qualifiedName, strings.Join(cannotExpress, "\n  - ")))
 	}
 
+	// Every counter below walks the event sub-process bodies as well as the main
+	// body: the raw side counts the whole document.
+	authoredActs := workflowStatementActivities(stmt)
+
+	// Event sub-processes and notification activities MDL can now state. Before
+	// it could, describe printed a notification activity as a comment and left
+	// the sub-processes out, so a rewrite from that output would delete them.
+	if stored := countEventSubProcesses(raw); stored > len(stmt.EventSubProcesses) {
+		return mdlerrors.NewUnsupported(fmt.Sprintf(
+			"workflow %s has %d stored event sub-process(es) but this statement declares %d — rewriting it would "+
+				"delete the difference, along with each one's flow.\n"+
+				"  Restate them (`event subprocess <name> on interrupting notification <start> { … };`), which "+
+				"`describe workflow %s` now emits, or use ALTER WORKFLOW to change one activity at a time.",
+			qualifiedName, stored, len(stmt.EventSubProcesses), qualifiedName))
+	}
+	if stored, authored := countRawWorkflowNodesExact(raw, "Workflows$NotificationActivity"), countAuthoredNotificationActivities(authoredActs); stored > authored {
+		return mdlerrors.NewUnsupported(fmt.Sprintf(
+			"workflow %s has %d stored notification activit(ies) but this statement declares %d — rewriting it would "+
+				"delete the difference, and a notify action targeting one would target nothing.\n"+
+				"  Restate them (`notification <name> comment '…';`), which `describe workflow %s` now emits, or use "+
+				"ALTER WORKFLOW to change one activity at a time.",
+			qualifiedName, stored, authored, qualifiedName))
+	}
+
 	// Handlers MDL can now state, but a statement written before it could (or
 	// from an older describe) does not: the rewrite writes what the statement
 	// says, so an unstated handler is deleted and an unstated on-created
@@ -74,7 +100,7 @@ func checkNoDroppedWorkflowConstructs(ctx *ExecContext, workflowID model.ID, qua
 				"or use ALTER WORKFLOW to change one activity at a time.",
 			qualifiedName, len(stored), len(stmt.EventHandlers), strings.Join(stored, "\n  - "), qualifiedName))
 	}
-	if stored, authored := rawOnCreatedMicroflows(raw), countAuthoredOnCreated(stmt.Activities); len(stored) > authored {
+	if stored, authored := rawOnCreatedMicroflows(raw), countAuthoredOnCreated(authoredActs); len(stored) > authored {
 		return mdlerrors.NewUnsupported(fmt.Sprintf(
 			"workflow %s has %d user task(s) with an on-created microflow but this statement declares %d — rewriting "+
 				"it would reset the difference to none:\n  - %s\n"+
@@ -83,7 +109,7 @@ func checkNoDroppedWorkflowConstructs(ctx *ExecContext, workflowID model.ID, qua
 			qualifiedName, len(stored), authored, strings.Join(stored, "\n  - "), qualifiedName))
 	}
 
-	if stored, authored := rawAgentTasks(raw), countAuthoredAgentTasks(stmt.Activities); len(stored) > authored {
+	if stored, authored := rawAgentTasks(raw), countAuthoredAgentTasks(authoredActs); len(stored) > authored {
 		return mdlerrors.NewUnsupported(fmt.Sprintf(
 			"workflow %s has %d AI agent task(s) but this statement declares %d — rewriting it would delete the "+
 				"difference, along with each one's outcome flows:\n  - %s\n"+
@@ -99,7 +125,7 @@ func checkNoDroppedWorkflowConstructs(ctx *ExecContext, workflowID model.ID, qua
 	// a statement that does not restate stored values resets them. Participants
 	// and await were not guarded at all before; a rewrite reset both silently.
 	storedRules, storedParticipants, storedAwait := rawMultiUserTaskSettings(raw)
-	authoredRules, authoredParticipants, authoredAwait := countAuthoredMultiUserSettings(stmt.Activities)
+	authoredRules, authoredParticipants, authoredAwait := countAuthoredMultiUserSettings(authoredActs)
 	for _, g := range []struct {
 		stored   []string
 		authored int
@@ -123,8 +149,9 @@ func checkNoDroppedWorkflowConstructs(ctx *ExecContext, workflowID model.ID, qua
 	// delete every one — and a branch that ended the workflow would silently
 	// fall through into the main flow instead. The main flow's own End is not
 	// counted: the builder always writes it.
-	if storedEnds := countRawWorkflowNodesExact(raw, "Workflows$EndWorkflowActivity") - 1; storedEnds > 0 {
-		if authored := countAuthoredEnds(stmt.Activities); authored < storedEnds {
+	// An event sub-process's closing End is implicit too, like the main flow's.
+	if storedEnds := countRawWorkflowNodesExact(raw, "Workflows$EndWorkflowActivity") - 1 - rawImplicitSubProcessEnds(raw); storedEnds > 0 {
+		if authored := countAuthoredEnds(authoredActs); authored < storedEnds {
 			return mdlerrors.NewUnsupported(fmt.Sprintf(
 				"workflow %s has %d stored `end workflow` inside its branches but this statement declares %d — "+
 					"rewriting it would delete the difference, and each branch that ended the workflow would fall "+
@@ -139,7 +166,7 @@ func checkNoDroppedWorkflowConstructs(ctx *ExecContext, workflowID model.ID, qua
 	if storedBE == 0 {
 		return nil
 	}
-	authored := countAuthoredBoundaryEvents(stmt.Activities)
+	authored := countAuthoredBoundaryEvents(authoredActs)
 	if authored >= storedBE {
 		return nil
 	}
@@ -586,6 +613,71 @@ func orUnnamed(s string) string {
 	return s
 }
 
+// countAuthoredNotificationActivities counts the `notification` statements.
+func countAuthoredNotificationActivities(activities []ast.WorkflowActivityNode) int {
+	n := 0
+	walkWorkflowActivities(activities, func(act ast.WorkflowActivityNode) {
+		if _, ok := act.(*ast.WorkflowNotificationNode); ok {
+			n++
+		}
+	})
+	return n
+}
+
+// rawSubProcessActivities returns the top-level activities of each stored event
+// sub-process, in stored order.
+func rawSubProcessActivities(raw map[string]any) [][]map[string]any {
+	var out [][]map[string]any
+	for _, e := range rawList(raw["EventSubProcesses"]) {
+		esp, ok := e.(map[string]any)
+		if !ok {
+			continue
+		}
+		flow, _ := esp["Flow"].(map[string]any)
+		var acts []map[string]any
+		for _, a := range rawList(flow["Activities"]) {
+			if am, ok := a.(map[string]any); ok {
+				acts = append(acts, am)
+			}
+		}
+		out = append(out, acts)
+	}
+	return out
+}
+
+// rawEventSubProcessesWithoutStart counts stored event sub-processes whose flow
+// does not begin with a start event: MDL states a sub-process by its start, so
+// one without cannot be restated.
+func rawEventSubProcessesWithoutStart(raw map[string]any) int {
+	n := 0
+	for _, acts := range rawSubProcessActivities(raw) {
+		if len(acts) == 0 {
+			n++
+			continue
+		}
+		t, _ := acts[0]["$Type"].(string)
+		if _, _, ok := workflows.EventSubProcessStartFromStorageType(t); !ok {
+			n++
+		}
+	}
+	return n
+}
+
+// rawImplicitSubProcessEnds counts stored event sub-processes whose flow closes
+// with an End — the End a statement does not write, because the builder adds it.
+func rawImplicitSubProcessEnds(raw map[string]any) int {
+	n := 0
+	for _, acts := range rawSubProcessActivities(raw) {
+		if len(acts) == 0 {
+			continue
+		}
+		if t, _ := acts[len(acts)-1]["$Type"].(string); t == "Workflows$EndWorkflowActivity" {
+			n++
+		}
+	}
+	return n
+}
+
 // countEventSubProcesses counts a workflow's event sub-processes. The substring
 // match countRawWorkflowNodes uses also counts each one's start activity
 // (…NotificationEventSubProcessStartActivity lives inside it), so the reference
diff --git a/mdl/executor/validate_workflow_rewrite_test.go b/mdl/executor/validate_workflow_rewrite_test.go
index 1867f5ca4d..5ceb8024db 100644
--- a/mdl/executor/validate_workflow_rewrite_test.go
+++ b/mdl/executor/validate_workflow_rewrite_test.go
@@ -396,7 +396,7 @@ func TestWorkflowRewrite_CountsAnEventSubProcessOnce(t *testing.T) {
 		}},
 	}
 	err := checkNoDroppedWorkflowConstructs(rawWorkflowCtx(t, raw), "wf1", "M.W", parseWorkflowStmt(t, wfRewriteTwoTasks))
-	if err == nil || !strings.Contains(err.Error(), "1 event sub-process") {
+	if err == nil || !strings.Contains(err.Error(), "has 1 stored event sub-process") {
 		t.Fatalf("expected one event sub-process to be reported, got %v", err)
 	}
 }
diff --git a/mdl/executor/workflow_esp_test.go b/mdl/executor/workflow_esp_test.go
new file mode 100644
index 0000000000..77f996dba4
--- /dev/null
+++ b/mdl/executor/workflow_esp_test.go
@@ -0,0 +1,256 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+const espWorkflow = `create workflow M.W parameter $C: M.Ctx begin
+  notification received comment 'Documents received';
+  wait for notification waitApproval
+    boundary event interrupting notification withdrawn 'Withdrawn' { end workflow; }
+    boundary event non interrupting notification nudge 'Nudge' { call microflow M.Log; };
+  user task review 'Review' page M.P outcomes 'Good' { } 'Bad' { };
+  event subprocess ESP_Cancel 'Cancel request' on interrupting notification cancelStart 'Cancel received' {
+    call microflow M.Log;
+  };
+  event subprocess ESP_Loop on non interrupting notification loopStart {
+    call microflow M.Log as logIt;
+    jump to logIt;
+  };
+  event subprocess ESP_Expire 'Expire' on interrupting timer 'addDays([%CurrentDateTime%], 30)' as expireStart comment 'After 30 days' {
+  };
+end workflow;`
+
+// Each sub-process flow starts with its start event, and gets an End only when
+// its body does not already end: measured, a flow with no end is CE0105 and an
+// End after a jump is CE6689.
+func TestWorkflowESP_BuildsStudioProShapes(t *testing.T) {
+	esps := buildEventSubProcesses(parseWorkflowStmt(t, espWorkflow).EventSubProcesses)
+	if len(esps) != 3 {
+		t.Fatalf("built %d sub-processes, want 3", len(esps))
+	}
+	want := []struct {
+		storage, startName, startCaption string
+		endsWithEnd                      bool
+	}{
+		{"Workflows$InterruptingNotificationEventSubProcessStartActivity", "cancelStart", "Cancel received", true},
+		{"Workflows$NonInterruptingNotificationEventSubProcessStartActivity", "loopStart", "loopStart", false},
+		{"Workflows$InterruptingTimerEventSubProcessStartActivity", "expireStart", "After 30 days", true},
+	}
+	for i, w := range want {
+		start := esps[i].Start()
+		if start == nil || start.StorageType() != w.storage || start.Name != w.startName || start.Caption != w.startCaption {
+			t.Errorf("%s start = %+v, want %s %q %q", esps[i].Name, start, w.storage, w.startName, w.startCaption)
+		}
+		acts := esps[i].Flow.Activities
+		_, isEnd := acts[len(acts)-1].(*workflows.EndWorkflowActivity)
+		if isEnd != w.endsWithEnd {
+			t.Errorf("%s ends with %T, want an End: %v", esps[i].Name, acts[len(acts)-1], w.endsWithEnd)
+		}
+	}
+	if got := esps[2].Start().FirstExecutionTime; got != "addDays([%CurrentDateTime%], 30)" {
+		t.Errorf("timer expression = %q", got)
+	}
+
+	unnamed := buildEventSubProcesses(parseWorkflowStmt(t, `create workflow M.W begin
+  event subprocess ESP_X on interrupting notification { };
+end workflow;`).EventSubProcesses)
+	if s := unnamed[0].Start(); s.Name != "ESP_XStart" || s.Caption != "ESP_XStart" {
+		t.Errorf("unnamed start = %q/%q, want ESP_XStart", s.Name, s.Caption)
+	}
+}
+
+// A start event and a notification boundary event share the workflow's one name
+// space with its activities — a clash is CE0495, measured.
+func TestWorkflowESP_NamesAreUniqueAcrossFlows(t *testing.T) {
+	stmt := parseWorkflowStmt(t, `create workflow M.W begin
+  user task review 'Review' page M.P outcomes 'Good' { } 'Bad' { }
+    boundary event interrupting notification review;
+  event subprocess ESP on interrupting notification review { };
+end workflow;`)
+	acts := buildWorkflowActivities(stmt.Activities)
+	esps := buildEventSubProcesses(stmt.EventSubProcesses)
+	named := append([]workflows.WorkflowActivity{}, acts...)
+	named = append(named, esps[0].Flow.Activities...)
+	deduplicateActivityNames(named, "Start", "End")
+
+	task := acts[0].(*workflows.UserTask)
+	names := []string{task.Name, task.BoundaryEvents[0].Name, esps[0].Start().Name}
+	seen := map[string]bool{}
+	for _, n := range names {
+		if seen[n] {
+			t.Fatalf("names %v are not unique", names)
+		}
+		seen[n] = true
+	}
+	if task.Name != "review" {
+		t.Errorf("the user task, named first, must keep its name; got %q", task.Name)
+	}
+}
+
+// Describe → re-parse → describe is stable for every new construct.
+func TestWorkflowESP_DescribeRoundTrips(t *testing.T) {
+	format := func(stmt *ast.CreateWorkflowStmt) string {
+		lines := formatMainFlowActivities(&workflows.Flow{Activities: buildWorkflowActivities(stmt.Activities)}, "  ")
+		lines = append(lines, formatEventSubProcesses(buildEventSubProcesses(stmt.EventSubProcesses), "  ")...)
+		return strings.Join(lines, "\n")
+	}
+	first := format(parseWorkflowStmt(t, espWorkflow))
+	for _, want := range []string{
+		"notification received comment 'Documents received';",
+		"boundary event interrupting notification withdrawn 'Withdrawn'",
+		"boundary event non interrupting notification nudge 'Nudge'",
+		"event subprocess ESP_Cancel 'Cancel request' on interrupting notification cancelStart 'Cancel received' {",
+		"event subprocess ESP_Loop on non interrupting notification loopStart 'loopStart' {",
+		"event subprocess ESP_Expire 'Expire' on interrupting timer 'addDays([%CurrentDateTime%], 30)' as expireStart comment 'After 30 days' {",
+		"jump to logIt;",
+	} {
+		if !strings.Contains(first, want) {
+			t.Errorf("describe output lacks %q:\n%s", want, first)
+		}
+	}
+	again := format(parseWorkflowStmt(t, "create workflow M.W parameter $C: M.Ctx begin\n"+first+"\nend workflow;"))
+	if first != again {
+		t.Errorf("describe is not stable:\n--- first\n%s\n--- again\n%s", first, again)
+	}
+}
+
+// A jump stays in its own flow: into or out of an event sub-process is CE6682;
+// within one, to an activity or its start event, builds.
+func TestWorkflowESP_JumpScopes(t *testing.T) {
+	stmt := parseWorkflowStmt(t, `create workflow M.W begin
+  user task t 'T' page M.P outcomes 'Go' { jump to aLog; } 'Stop' { };
+  event subprocess A on interrupting notification aStart { call microflow M.Log as aLog; jump to aLog; };
+  event subprocess B on interrupting notification bStart { jump to aLog; };
+  event subprocess C on interrupting notification cStart { call microflow M.Log as cLog; jump to cStart; };
+end workflow;`)
+	var msgs []string
+	for _, v := range ValidateWorkflowJumpTargets(stmt) {
+		msgs = append(msgs, v.Message)
+	}
+	if len(msgs) != 2 {
+		t.Fatalf("got %d jump violations, want 2 (main → A, B → A):\n%s", len(msgs), strings.Join(msgs, "\n"))
+	}
+	for _, m := range msgs {
+		if !strings.Contains(m, "CE6682") {
+			t.Errorf("cross-flow jump reported as %q, want CE6682", m)
+		}
+	}
+}
+
+// MDL-WF14 (timer start with no expression, CE0126) and MDL-WF15 (two
+// interrupting boundary events on one activity, CE6697), both measured.
+func TestWorkflowESP_Rules(t *testing.T) {
+	rules := func(src string) map[string]int {
+		out := map[string]int{}
+		for _, v := range ValidateWorkflow(parseWorkflowStmt(t, src)) {
+			out[v.RuleID]++
+		}
+		return out
+	}
+	if got := rules(`create workflow M.W begin
+  event subprocess T on interrupting timer '' { };
+end workflow;`); got["MDL-WF14"] != 1 {
+		t.Errorf("empty timer: rules %v, want one MDL-WF14", got)
+	}
+	if got := rules(`create workflow M.W begin
+  user task t 'T' page M.P outcomes 'Go' { } 'Stop' { }
+    boundary event interrupting notification a
+    boundary event interrupting timer 'addDays([%CurrentDateTime%], 1)';
+end workflow;`); got["MDL-WF15"] != 1 {
+		t.Errorf("two interrupting events: rules %v, want one MDL-WF15", got)
+	}
+	if got := rules(espWorkflow); got["MDL-WF14"]+got["MDL-WF15"]+got["MDL-WF05"]+got["MDL-WF08"] != 0 {
+		t.Errorf("the valid workflow was refused: %v", got)
+	}
+	// A non-interrupting notification path cannot end the workflow (CE1844), like
+	// a non-interrupting timer's.
+	if got := rules(`create workflow M.W begin
+  user task t 'T' page M.P outcomes 'Go' { } 'Stop' { }
+    boundary event non interrupting notification n { end workflow; };
+end workflow;`); got["MDL-WF08"] != 1 {
+		t.Errorf("end under a non-interrupting notification path: rules %v, want one MDL-WF08", got)
+	}
+}
+
+const wfRewriteWithESP = `create or modify workflow M.W parameter $C: M.Ctx
+begin
+  user task review 'Review' page M.P outcomes 'Good' { } 'Bad' { }
+    boundary event interrupting notification withdrawn;
+  notification received;
+  event subprocess ESP on interrupting notification espStart {
+    user task nestedTask 'Nested' page M.P outcomes 'Good' { } 'Bad' { }
+      boundary event non interrupting notification nudge;
+  };
+end workflow;`
+
+// storedESPWorkflow is a stored workflow holding what wfRewriteWithESP states:
+// a main flow closing with its End, a notification activity, a boundary event
+// on the main flow and one inside the sub-process, whose flow closes with its
+// own (implicit) End.
+func storedESPWorkflow(start string) map[string]any {
+	be := func(typ string) map[string]any {
+		return map[string]any{"$Type": typ, "Flow": map[string]any{"$Type": "Workflows$Flow", "Activities": []any{3}}}
+	}
+	return map[string]any{
+		"$Type": "Workflows$Workflow",
+		"Flow": map[string]any{"$Type": "Workflows$Flow", "Activities": []any{3,
+			map[string]any{"$Type": "Workflows$StartWorkflowActivity"},
+			map[string]any{"$Type": "Workflows$SingleUserTaskActivity", "Name": "review",
+				"BoundaryEvents": []any{2, be("Workflows$InterruptingNotificationBoundaryEvent")}},
+			map[string]any{"$Type": "Workflows$NotificationActivity", "Name": "received"},
+			map[string]any{"$Type": "Workflows$EndWorkflowActivity"},
+		}},
+		"EventSubProcesses": []any{2, map[string]any{
+			"$Type": "Workflows$EventSubProcess",
+			"Flow": map[string]any{"$Type": "Workflows$Flow", "Activities": []any{3,
+				map[string]any{"$Type": start, "Name": "espStart"},
+				map[string]any{"$Type": "Workflows$SingleUserTaskActivity", "Name": "inner",
+					"BoundaryEvents": []any{2, be("Workflows$NonInterruptingNotificationBoundaryEvent")}},
+				map[string]any{"$Type": "Workflows$EndWorkflowActivity"},
+			}},
+		}},
+	}
+}
+
+// A statement restating everything is allowed: the sub-process's closing End is
+// not a stored `end workflow` the statement omits, and the boundary event inside
+// the sub-process is counted on both sides.
+func TestWorkflowRewrite_RestatedEventSubProcessesPass(t *testing.T) {
+	raw := storedESPWorkflow("Workflows$InterruptingNotificationEventSubProcessStartActivity")
+	if err := checkNoDroppedWorkflowConstructs(rawWorkflowCtx(t, raw), "wf1", "M.W", parseWorkflowStmt(t, wfRewriteWithESP)); err != nil {
+		t.Errorf("a statement restating every construct was refused: %v", err)
+	}
+}
+
+// Each construct that is not restated is refused, and a sub-process with no
+// start event — which MDL cannot state — is refused even when restated.
+func TestWorkflowRewrite_EventSubProcessesMustBeRestated(t *testing.T) {
+	raw := storedESPWorkflow("Workflows$InterruptingNotificationEventSubProcessStartActivity")
+	cases := []struct{ name, src, want string }{
+		{"sub-process dropped", strings.Replace(wfRewriteWithESP,
+			"  event subprocess ESP on interrupting notification espStart {\n    user task nestedTask 'Nested' page M.P outcomes 'Good' { } 'Bad' { }\n      boundary event non interrupting notification nudge;\n  };\n", "", 1),
+			"stored event sub-process"},
+		{"notification activity dropped", strings.Replace(wfRewriteWithESP, "  notification received;\n", "", 1), "notification activit"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			err := checkNoDroppedWorkflowConstructs(rawWorkflowCtx(t, raw), "wf1", "M.W", parseWorkflowStmt(t, c.src))
+			if err == nil || !strings.Contains(err.Error(), c.want) {
+				t.Errorf("expected a refusal naming %q, got %v", c.want, err)
+			}
+		})
+	}
+
+	startless := storedESPWorkflow("Workflows$UserTaskActivity")
+	err := checkNoDroppedWorkflowConstructs(rawWorkflowCtx(t, startless), "wf1", "M.W", parseWorkflowStmt(t, wfRewriteWithESP))
+	if err == nil || !strings.Contains(err.Error(), "no start event") {
+		t.Errorf("a sub-process with no start event must be refused, got %v", err)
+	}
+}
diff --git a/mdl/grammar/MDLLexer.g4 b/mdl/grammar/MDLLexer.g4
index 6e06f2e0fd..eef3a51618 100644
--- a/mdl/grammar/MDLLexer.g4
+++ b/mdl/grammar/MDLLexer.g4
@@ -772,6 +772,7 @@ AT_KW: A T;
 BOUNDARY: B O U N D A R Y;
 INTERRUPTING: I N T E R R U P T I N G;
 NON: N O N;
+SUBPROCESS: S U B P R O C E S S;
 MULTI: M U L T I;
 BY: B Y;
 READ: R E A D;
diff --git a/mdl/grammar/domains/MDLSettings.g4 b/mdl/grammar/domains/MDLSettings.g4
index e75a4fa60d..aebba76f3d 100644
--- a/mdl/grammar/domains/MDLSettings.g4
+++ b/mdl/grammar/domains/MDLSettings.g4
@@ -697,7 +697,7 @@ keyword
     | CONDITION | DATE | DECISION | DUE | GROUPS | INTERRUPTING | JUMP
     | LOCK | MULTI | NODE | NON | NOTIFICATION | NOTIFY
     | OPEN | OUTCOME | OUTCOMES | OVERVIEW | PARALLEL | PAUSE
-    | REASON | RESTART | RETRY | SPLIT | TARGETING | TASK | TIMER
+    | REASON | RESTART | RETRY | SPLIT | SUBPROCESS | TARGETING | TASK | TIMER
     | UNLOCK | UNPAUSE | WAIT | WORKFLOW | WORKFLOWS
 
     // Business events / settings
diff --git a/mdl/grammar/domains/MDLWorkflow.g4 b/mdl/grammar/domains/MDLWorkflow.g4
index 63f6cfac0c..7fb14616a6 100644
--- a/mdl/grammar/domains/MDLWorkflow.g4
+++ b/mdl/grammar/domains/MDLWorkflow.g4
@@ -22,7 +22,33 @@ createWorkflowStatement
       (OVERVIEW PAGE qualifiedName)?
       (DUE DATE_TYPE dueDate=STRING_LITERAL)?
       workflowEventHandlerClause*
-      BEGIN workflowMainBody END WORKFLOW SEMICOLON? SLASH?
+      BEGIN workflowMainBody workflowEventSubProcess* END WORKFLOW SEMICOLON? SLASH?
+    ;
+
+/**
+ * An event sub-process: a flow outside the main flow that its own start event
+ * triggers while the workflow runs — a `notify workflow … target <start>`, or a
+ * timer. Interrupting cancels every active path first; non-interrupting runs
+ * alongside. Written after the main body, because Studio Pro stores them in the
+ * workflow's EventSubProcesses list, not in its flow.
+ *
+ * The body's End is implicit, as in the main flow: the builder appends one when
+ * the body does not already end (in an End, a jump, or branches that all end).
+ */
+workflowEventSubProcess
+    : EVENT SUBPROCESS workflowActivityName STRING_LITERAL?
+      ON (INTERRUPTING | NON INTERRUPTING) workflowEventSubProcessTrigger
+      LBRACE workflowBody RBRACE SEMICOLON
+    ;
+
+/**
+ * The start event. A notification start is what `notify workflow … target`
+ * names; a timer start takes the first-execution-time expression, which Mendix
+ * requires (CE0126).
+ */
+workflowEventSubProcessTrigger
+    : NOTIFICATION workflowActivityName? STRING_LITERAL?
+    | TIMER STRING_LITERAL (AS workflowActivityName)? (COMMENT STRING_LITERAL)?
     ;
 
 /**
@@ -81,6 +107,7 @@ workflowActivityStmt
     | workflowJumpToStmt SEMICOLON
     | workflowWaitForTimerStmt SEMICOLON
     | workflowWaitForNotificationStmt SEMICOLON
+    | workflowNotificationStmt SEMICOLON
     | workflowAnnotationStmt SEMICOLON
     ;
 
@@ -162,6 +189,10 @@ workflowBoundaryEventClause
     : INTERRUPTING TIMER STRING_LITERAL? (LBRACE workflowBody RBRACE)?
     | NON INTERRUPTING TIMER STRING_LITERAL? (LBRACE workflowBody RBRACE)?
     | TIMER STRING_LITERAL? (LBRACE workflowBody RBRACE)?
+    // A notification boundary event is triggered by `notify workflow … target
+    // <name>`, so its name is what matters; the string is its caption.
+    | INTERRUPTING NOTIFICATION workflowActivityName? STRING_LITERAL? (LBRACE workflowBody RBRACE)?
+    | NON INTERRUPTING NOTIFICATION workflowActivityName? STRING_LITERAL? (LBRACE workflowBody RBRACE)?
     ;
 
 workflowUserTaskOutcome
@@ -221,6 +252,14 @@ workflowWaitForNotificationStmt
       (BOUNDARY EVENT workflowBoundaryEventClause ((BOUNDARY EVENT)? workflowBoundaryEventClause)*)?
     ;
 
+/**
+ * An intermediate notification event on a flow (Workflows$NotificationActivity):
+ * the point a `notify workflow … target <name>` reaches.
+ */
+workflowNotificationStmt
+    : NOTIFICATION workflowActivityName? (COMMENT STRING_LITERAL)?
+    ;
+
 workflowAnnotationStmt
     : ANNOTATION STRING_LITERAL
     ;
diff --git a/mdl/visitor/visitor_workflow.go b/mdl/visitor/visitor_workflow.go
index 6a5b947efe..c474dd5a09 100644
--- a/mdl/visitor/visitor_workflow.go
+++ b/mdl/visitor/visitor_workflow.go
@@ -107,6 +107,9 @@ func (b *Builder) ExitCreateWorkflowStatement(ctx *parser.CreateWorkflowStatemen
 	if body := ctx.WorkflowMainBody(); body != nil {
 		stmt.Activities = buildWorkflowMainBody(body)
 	}
+	for _, espCtx := range ctx.AllWorkflowEventSubProcess() {
+		stmt.EventSubProcesses = append(stmt.EventSubProcesses, buildWorkflowEventSubProcess(espCtx))
+	}
 
 	b.statements = append(b.statements, stmt)
 }
@@ -491,6 +494,9 @@ func buildWorkflowActivityStmt(ctx parser.IWorkflowActivityStmtContext) ast.Work
 	if wn := actCtx.WorkflowWaitForNotificationStmt(); wn != nil {
 		return buildWorkflowWaitForNotification(wn)
 	}
+	if n := actCtx.WorkflowNotificationStmt(); n != nil {
+		return buildWorkflowNotification(n)
+	}
 	if ann := actCtx.WorkflowAnnotationStmt(); ann != nil {
 		return buildWorkflowAnnotation(ann)
 	}
@@ -880,15 +886,29 @@ func buildWorkflowWaitForNotification(ctx parser.IWorkflowWaitForNotificationStm
 func buildBoundaryEventNode(beCtx parser.IWorkflowBoundaryEventClauseContext) ast.WorkflowBoundaryEventNode {
 	beCtx2 := beCtx.(*parser.WorkflowBoundaryEventClauseContext)
 	be := ast.WorkflowBoundaryEventNode{}
-	if beCtx2.NON() != nil {
+	notification := beCtx2.NOTIFICATION() != nil
+	switch {
+	case notification && beCtx2.NON() != nil:
+		be.EventType = "NonInterruptingNotification"
+	case notification:
+		be.EventType = "InterruptingNotification"
+	case beCtx2.NON() != nil:
 		be.EventType = "NonInterruptingTimer"
-	} else if beCtx2.INTERRUPTING() != nil {
+	case beCtx2.INTERRUPTING() != nil:
 		be.EventType = "InterruptingTimer"
-	} else {
+	default:
 		be.EventType = "Timer"
 	}
-	if beCtx2.STRING_LITERAL() != nil {
-		be.Delay = unquoteString(beCtx2.STRING_LITERAL().GetText())
+	// A timer's string is its delay; a notification event's is its caption.
+	if s := beCtx2.STRING_LITERAL(); s != nil {
+		if notification {
+			be.Caption = unquoteString(s.GetText())
+		} else {
+			be.Delay = unquoteString(s.GetText())
+		}
+	}
+	if notification {
+		be.Name = workflowActivityNameText(beCtx2.WorkflowActivityName())
 	}
 	if body := beCtx2.WorkflowBody(); body != nil {
 		be.Activities = buildWorkflowBody(body)
@@ -896,6 +916,50 @@ func buildBoundaryEventNode(beCtx parser.IWorkflowBoundaryEventClauseContext) as
 	return be
 }
 
+// buildWorkflowNotification builds `notification [<name>] [comment '<caption>']`.
+func buildWorkflowNotification(ctx parser.IWorkflowNotificationStmtContext) *ast.WorkflowNotificationNode {
+	c := ctx.(*parser.WorkflowNotificationStmtContext)
+	node := &ast.WorkflowNotificationNode{Name: workflowActivityNameText(c.WorkflowActivityName())}
+	if c.COMMENT() != nil && c.STRING_LITERAL() != nil {
+		node.Caption = unquoteString(c.STRING_LITERAL().GetText())
+	}
+	return node
+}
+
+// buildWorkflowEventSubProcess builds `event subprocess <name> ['<caption>'] on
+// [non] interrupting notification [<start>] ['<caption>'] { … }` and its timer
+// form, `… timer '<first execution time>' [as <start>] [comment '<caption>']`.
+func buildWorkflowEventSubProcess(ctx parser.IWorkflowEventSubProcessContext) ast.WorkflowEventSubProcessNode {
+	c := ctx.(*parser.WorkflowEventSubProcessContext)
+	node := ast.WorkflowEventSubProcessNode{
+		Name:         workflowActivityNameText(c.WorkflowActivityName()),
+		Interrupting: c.NON() == nil,
+	}
+	if s := c.STRING_LITERAL(); s != nil {
+		node.Caption = unquoteString(s.GetText())
+	}
+	if t, ok := c.WorkflowEventSubProcessTrigger().(*parser.WorkflowEventSubProcessTriggerContext); ok && t != nil {
+		node.Timer = t.TIMER() != nil
+		node.StartName = workflowActivityNameText(t.WorkflowActivityName())
+		strs := t.AllSTRING_LITERAL()
+		switch {
+		case node.Timer:
+			if len(strs) > 0 {
+				node.FirstExecutionTime = unquoteString(strs[0].GetText())
+			}
+			if t.COMMENT() != nil && len(strs) > 1 {
+				node.StartCaption = unquoteString(strs[1].GetText())
+			}
+		case len(strs) > 0:
+			node.StartCaption = unquoteString(strs[0].GetText())
+		}
+	}
+	if body := c.WorkflowBody(); body != nil {
+		node.Activities = buildWorkflowBody(body)
+	}
+	return node
+}
+
 // buildWorkflowAnnotation builds a WorkflowAnnotationActivityNode from the grammar context.
 func buildWorkflowAnnotation(ctx parser.IWorkflowAnnotationStmtContext) *ast.WorkflowAnnotationActivityNode {
 	annCtx := ctx.(*parser.WorkflowAnnotationStmtContext)
diff --git a/mdl/visitor/visitor_workflow_esp_test.go b/mdl/visitor/visitor_workflow_esp_test.go
new file mode 100644
index 0000000000..30573c0378
--- /dev/null
+++ b/mdl/visitor/visitor_workflow_esp_test.go
@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package visitor
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+)
+
+// Event sub-processes after the main body, both trigger kinds, with and without
+// the optional names and captions.
+func TestWorkflowVisitor_EventSubProcesses(t *testing.T) {
+	stmt := buildWorkflowStmt(t, `create workflow M.W
+begin
+  user task review 'Review' page M.P outcomes 'Good' { } 'Bad' { };
+  event subprocess ESP_Cancel 'Cancel request' on interrupting notification cancelStart 'Cancel received' {
+    call microflow M.Log;
+  };
+  event subprocess ESP_Audit on non interrupting notification {
+  };
+  event subprocess ESP_Expire 'Expire' on interrupting timer 'addDays([%CurrentDateTime%], 30)' as expireStart comment 'After 30 days' {
+    end workflow;
+  };
+  event subprocess ESP_Remind on non interrupting timer 'addDays([%CurrentDateTime%], 1)' {
+  };
+end workflow;`)
+	if len(stmt.Activities) != 1 {
+		t.Fatalf("main body has %d activities, want 1 — a sub-process leaked into it", len(stmt.Activities))
+	}
+	if len(stmt.EventSubProcesses) != 4 {
+		t.Fatalf("got %d event sub-processes, want 4", len(stmt.EventSubProcesses))
+	}
+	strip := func(n ast.WorkflowEventSubProcessNode) ast.WorkflowEventSubProcessNode {
+		n.Activities = nil
+		return n
+	}
+	want := []ast.WorkflowEventSubProcessNode{
+		{Name: "ESP_Cancel", Caption: "Cancel request", Interrupting: true, StartName: "cancelStart", StartCaption: "Cancel received"},
+		{Name: "ESP_Audit"},
+		{Name: "ESP_Expire", Caption: "Expire", Interrupting: true, Timer: true, StartName: "expireStart", StartCaption: "After 30 days", FirstExecutionTime: "addDays([%CurrentDateTime%], 30)"},
+		{Name: "ESP_Remind", Timer: true, FirstExecutionTime: "addDays([%CurrentDateTime%], 1)"},
+	}
+	for i, w := range want {
+		if got := strip(stmt.EventSubProcesses[i]); !reflect.DeepEqual(got, w) {
+			t.Errorf("sub-process %d = %+v, want %+v", i, got, w)
+		}
+	}
+	if _, ok := stmt.EventSubProcesses[0].Activities[0].(*ast.WorkflowCallMicroflowNode); !ok {
+		t.Errorf("ESP_Cancel body = %T, want the call microflow", stmt.EventSubProcesses[0].Activities[0])
+	}
+	if _, ok := stmt.EventSubProcesses[2].Activities[0].(*ast.WorkflowEndNode); !ok {
+		t.Errorf("ESP_Expire body = %T, want `end workflow`", stmt.EventSubProcesses[2].Activities[0])
+	}
+}
+
+// A notification activity and notification boundary events: the string after a
+// notification event's name is its caption, while a timer's is still its delay.
+func TestWorkflowVisitor_NotificationEvents(t *testing.T) {
+	stmt := buildWorkflowStmt(t, `create workflow M.W
+begin
+  notification received comment 'Documents received';
+  notification;
+  user task review 'Review' page M.P outcomes 'Good' { } 'Bad' { }
+    boundary event interrupting notification withdrawn 'Withdrawn' { end workflow; }
+    boundary event non interrupting notification nudge
+    boundary event non interrupting timer 'addHours([%CurrentDateTime%], 1)';
+end workflow;`)
+	if got, ok := stmt.Activities[0].(*ast.WorkflowNotificationNode); !ok || *got != (ast.WorkflowNotificationNode{Name: "received", Caption: "Documents received"}) {
+		t.Errorf("first activity = %#v", stmt.Activities[0])
+	}
+	if got, ok := stmt.Activities[1].(*ast.WorkflowNotificationNode); !ok || *got != (ast.WorkflowNotificationNode{}) {
+		t.Errorf("bare notification = %#v", stmt.Activities[1])
+	}
+	task := stmt.Activities[2].(*ast.WorkflowUserTaskNode)
+	if len(task.BoundaryEvents) != 3 {
+		t.Fatalf("got %d boundary events, want 3", len(task.BoundaryEvents))
+	}
+	check := func(i int, eventType, name, caption, delay string) {
+		t.Helper()
+		be := task.BoundaryEvents[i]
+		if be.EventType != eventType || be.Name != name || be.Caption != caption || be.Delay != delay {
+			t.Errorf("boundary event %d = %s/%q/%q/%q, want %s/%q/%q/%q", i, be.EventType, be.Name, be.Caption, be.Delay, eventType, name, caption, delay)
+		}
+	}
+	check(0, "InterruptingNotification", "withdrawn", "Withdrawn", "")
+	check(1, "NonInterruptingNotification", "nudge", "", "")
+	check(2, "NonInterruptingTimer", "", "", "addHours([%CurrentDateTime%], 1)")
+	if len(task.BoundaryEvents[0].Activities) != 1 {
+		t.Errorf("withdrawn body has %d activities, want 1", len(task.BoundaryEvents[0].Activities))
+	}
+}
diff --git a/sdk/versions/mendix-11.yaml b/sdk/versions/mendix-11.yaml
index e9f2b03288..bc34dbf73b 100644
--- a/sdk/versions/mendix-11.yaml
+++ b/sdk/versions/mendix-11.yaml
@@ -188,6 +188,18 @@ features:
       min_version: "10.7.0"
       mdl: "CREATE WORKFLOW … ON WORKFLOW EVENTS (…) MICROFLOW Module.Handler AS '…'"
       notes: "Workflow.onWorkflowEvent introduced in 10.7.0 (modelsdk gen). `ON ANY WORKFLOW EVENT` expands to the measured per-version type list and needs 11.6.0+."
+    event_subprocesses:
+      min_version: "11.8.0"
+      mdl: "EVENT SUBPROCESS ESP_Cancel ON INTERRUPTING NOTIFICATION espCancelStart { … };"
+      notes: "Workflow.eventSubProcesses introduced in 11.8.0 (modelsdk gen). Notification starts measured to load on the 11.10, 11.11, 11.12 and 11.13 mxbuilds."
+    timer_event_subprocesses:
+      min_version: "11.13.0"
+      mdl: "EVENT SUBPROCESS ESP_Remind ON NON INTERRUPTING TIMER 'addDays([%CurrentDateTime%], 1)' { … };"
+      notes: "(Non)InterruptingTimerEventSubProcessStartActivity: TypeCacheUnknownTypeException on the 11.10, 11.11 and 11.12 mxbuilds, loads on 11.13."
+    notification_events:
+      min_version: "11.11.0"
+      mdl: "NOTIFICATION Received; … BOUNDARY EVENT INTERRUPTING NOTIFICATION Withdrawn { … }"
+      notes: "Workflows$NotificationActivity and (Non)InterruptingNotificationBoundaryEvent: TypeCacheUnknownTypeException on the 11.10 mxbuild, load on 11.11, 11.12 and 11.13."
 
   navigation:
     profiles:
diff --git a/sdk/workflows/workflow.go b/sdk/workflows/workflow.go
index 5546327682..63023bc132 100644
--- a/sdk/workflows/workflow.go
+++ b/sdk/workflows/workflow.go
@@ -34,6 +34,9 @@ type Workflow struct {
 
 	// Flow contains the workflow activities
 	Flow *Flow `json:"flow,omitempty"`
+
+	// EventSubProcesses are the flows outside the main flow, in stored order.
+	EventSubProcesses []*EventSubProcess `json:"eventSubProcesses,omitempty"`
 }
 
 // GetName returns the workflow's name.
@@ -248,6 +251,78 @@ type WaitForNotificationActivity struct {
 // ActivityType returns the type name.
 func (a *WaitForNotificationActivity) ActivityType() string { return "WaitForNotification" }
 
+// NotificationActivity is an intermediate notification event on a flow — the
+// point a `notify workflow … target` reaches.
+type NotificationActivity struct {
+	BaseWorkflowActivity
+}
+
+// ActivityType returns the type name.
+func (a *NotificationActivity) ActivityType() string { return "Notification" }
+
+// EventSubProcess is a flow outside the main flow, started by its own start event
+// while the workflow runs. Its flow's first activity is the
+// EventSubProcessStartActivity.
+type EventSubProcess struct {
+	model.BaseElement
+	Name       string `json:"name,omitempty"`
+	Caption    string `json:"caption,omitempty"`
+	Annotation string `json:"annotation,omitempty"`
+	Flow       *Flow  `json:"flow,omitempty"`
+}
+
+// Start returns the sub-process's start event, nil when its flow has none.
+func (e *EventSubProcess) Start() *EventSubProcessStartActivity {
+	if e == nil || e.Flow == nil || len(e.Flow.Activities) == 0 {
+		return nil
+	}
+	s, _ := e.Flow.Activities[0].(*EventSubProcessStartActivity)
+	return s
+}
+
+// EventSubProcessStartActivity is one of Mendix's four event sub-process start
+// types: interrupting or not, triggered by a notification or a timer.
+type EventSubProcessStartActivity struct {
+	BaseWorkflowActivity
+	Interrupting       bool   `json:"interrupting"`
+	Timer              bool   `json:"timer"`
+	FirstExecutionTime string `json:"firstExecutionTime,omitempty"` // timer starts only
+}
+
+// ActivityType returns the type name, e.g. "InterruptingNotificationEventSubProcessStart".
+func (a *EventSubProcessStartActivity) ActivityType() string {
+	return strings.TrimSuffix(strings.TrimPrefix(a.StorageType(), "Workflows$"), "Activity")
+}
+
+// StorageType returns the $Type the start event is stored under.
+func (a *EventSubProcessStartActivity) StorageType() string {
+	kind := "Notification"
+	if a.Timer {
+		kind = "Timer"
+	}
+	prefix := "NonInterrupting"
+	if a.Interrupting {
+		prefix = "Interrupting"
+	}
+	return "Workflows$" + prefix + kind + "EventSubProcessStartActivity"
+}
+
+// EventSubProcessStartFromStorageType is StorageType's inverse; ok is false for
+// any other $Type.
+func EventSubProcessStartFromStorageType(typeName string) (interrupting, timer, ok bool) {
+	switch typeName {
+	case "Workflows$InterruptingNotificationEventSubProcessStartActivity":
+		return true, false, true
+	case "Workflows$NonInterruptingNotificationEventSubProcessStartActivity":
+		return false, false, true
+	case "Workflows$InterruptingTimerEventSubProcessStartActivity":
+		return true, true, true
+	case "Workflows$NonInterruptingTimerEventSubProcessStartActivity":
+		return false, true, true
+	}
+	return false, false, false
+}
+
 // EndOfParallelSplitPathActivity marks the end of a parallel split path (auto-generated by Mendix).
 type EndOfParallelSplitPathActivity struct {
 	BaseWorkflowActivity
@@ -429,10 +504,55 @@ type ParallelSplitOutcome struct {
 // BoundaryEvent represents a boundary event attached to a workflow activity.
 type BoundaryEvent struct {
 	model.BaseElement
+	Name       string `json:"name,omitempty"` // notification events: what `notify workflow … target` names
 	Caption    string `json:"caption,omitempty"`
 	Flow       *Flow  `json:"flow,omitempty"`       // Activities triggered by the boundary event
 	TimerDelay string `json:"timerDelay,omitempty"` // Timer delay expression (for timer boundary events)
-	EventType  string `json:"eventType,omitempty"`  // e.g. "InterruptingTimer", "NonInterruptingTimer"
+	// EventType is "InterruptingTimer", "NonInterruptingTimer", "Timer",
+	// "InterruptingNotification" or "NonInterruptingNotification".
+	EventType string `json:"eventType,omitempty"`
+}
+
+// boundaryEventStorageTypes maps EventType to the stored $Type. Every writer
+// reads it from here: three copies of this switch defaulted an unknown kind to
+// an interrupting TIMER, so a notification event would have been written as one.
+var boundaryEventStorageTypes = map[string]string{
+	"InterruptingTimer":           "Workflows$InterruptingTimerBoundaryEvent",
+	"NonInterruptingTimer":        "Workflows$NonInterruptingTimerBoundaryEvent",
+	"Timer":                       "Workflows$TimerBoundaryEvent",
+	"InterruptingNotification":    "Workflows$InterruptingNotificationBoundaryEvent",
+	"NonInterruptingNotification": "Workflows$NonInterruptingNotificationBoundaryEvent",
+}
+
+// BoundaryEventStorageType returns the $Type for an EventType. An empty
+// EventType is an interrupting timer, which is what the writers always assumed;
+// ok is false for anything else unknown.
+func BoundaryEventStorageType(eventType string) (typeName string, ok bool) {
+	if eventType == "" {
+		eventType = "InterruptingTimer"
+	}
+	typeName, ok = boundaryEventStorageTypes[eventType]
+	return typeName, ok
+}
+
+// BoundaryEventTypeFromStorage is BoundaryEventStorageType's inverse.
+func BoundaryEventTypeFromStorage(typeName string) (eventType string, ok bool) {
+	for k, v := range boundaryEventStorageTypes {
+		if v == typeName {
+			return k, true
+		}
+	}
+	return "", false
+}
+
+// IsNotification reports whether the event is triggered by a notification.
+func (b *BoundaryEvent) IsNotification() bool {
+	return strings.HasSuffix(b.EventType, "Notification")
+}
+
+// IsNonInterrupting reports whether the event runs alongside its activity.
+func (b *BoundaryEvent) IsNonInterrupting() bool {
+	return strings.HasPrefix(b.EventType, "NonInterrupting")
 }
 
 // ============================================================================

From 90fb7c6804170b4712b8dbe92a8577d3c938363b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 15 Sep 2026 12:35:40 +0000
Subject: [PATCH 22/24] Port cmd/mxcli's readers off sdk/mpr (Phase 4a, first
 slice)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five files, and the slice splits into two ports rather than one: the Phase 3
decision that raw tools keep raw access does NOT mean they keep sdk/mpr.

Raw tools move to modelsdk/mpr, the v2 RAW reader. bson dump, bson discover and
diag moved by import swap alone — ListRawUnits, GetRawUnitByName,
GetRawMicroflowByName, ListAllUnitIDs and ContentsDir have identical signatures
on both readers, and RawUnitInfo is field-for-field identical. So they honour
Phase 3 and land on v2 at the same time.

project_tree.go and debug_resolve.go go through the backend instead. The first
calls 36 semantic reads, every one already on FullBackend; the second needs
ParseMicroflowBSON, which is a backend method.

That also corrects the Phase 3 write-up, which called every remaining bypass a
raw-unit debugging tool. project_tree.go is not one, and the census could not
reveal the mistake: it lists only methods with NO implementation, so a caller
holding a concrete reader while calling only implemented methods never appears.
The complete list of bypasses is the sdk/mpr importer list, not the census.

A regression the port introduced, caught only by a baseline diff: project-tree
silently lost System.VerifyPassword — 131 bytes out of 78KB of JSON, build
clean and every test green. The System module's Java actions are platform
built-ins with no stored unit; sdk/mpr synthesized them and the codec backend
did not. The definitions move to modelsdk/meta beside the virtual System
module's entities, both codec listings append them, and sdk/mpr delegates rather
than keeping a second copy of a hand-maintained platform list.

The technique is the transferable part: build a binary from the pre-port commit
and require byte-identical output from every command whose reader changed. No
test caught this and none would have. A synthesized element is what a reader
swap loses, because it lives in one reader's code rather than in the data.

Regression tests cover both listings, with a control that the STORED actions are
still returned — without it they would pass against a backend that returns only
the synthesized ones. Reverting the fix fails with the reported symptom.

Importers 27 -> 22. Gates: build, vet (incl. -tags integration), go test ./...,
check-mdl (544), check-findings. project-tree, bson dump and bson discover are
byte-identical to the pre-port binary.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018hifgRSawfaRWXS44YKtSJ
---
 .../fix-issue/findings/mdl-backend.jsonl      |   1 +
 cmd/mxcli/cmd_bson_discover.go                |   2 +-
 cmd/mxcli/cmd_bson_dump.go                    |   2 +-
 cmd/mxcli/debug_resolve.go                    |  15 +-
 cmd/mxcli/diag.go                             |   2 +-
 cmd/mxcli/project_tree.go                     |  16 ++-
 docs/plans/2026-09-14-retire-legacy-engine.md |  36 +++++
 mdl/backend/modelsdk/java.go                  |   6 +
 mdl/backend/modelsdk/java_read.go             |   4 +
 mdl/backend/modelsdk/java_system_test.go      | 102 ++++++++++++++
 modelsdk/meta/system_java_actions.go          | 131 ++++++++++++++++++
 sdk/mpr/system_java_actions.go                | 113 ++-------------
 12 files changed, 312 insertions(+), 118 deletions(-)
 create mode 100644 mdl/backend/modelsdk/java_system_test.go
 create mode 100644 modelsdk/meta/system_java_actions.go

diff --git a/.claude/skills/fix-issue/findings/mdl-backend.jsonl b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
index bb78e9396a..4f76dc98c9 100644
--- a/.claude/skills/fix-issue/findings/mdl-backend.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
@@ -103,3 +103,4 @@
 {"area": "mdl/backend", "date": "2026-09-15", "symptom": "Five `TestConnect_*` tests in `mdl/backend/mcp/connect_reads_test.go` (added by ako/mxcli#468) fail in a devcontainer — on pristine origin/main — with `Connect: connect to MCP server \"http://127.0.0.1:NNNNN/mcp\": ... dial tcp 192.168.65.254:NNNNN: connect: connection refused`, while CI is green", "cause": "The tests built the backend with `New(ped.srv.URL+\"/mcp\", \"\")`. An empty dial address falls through to `defaultDial` → `dialFor` in `mdl/backend/mcp/client.go`, which rewrites a localhost endpoint to `host.docker.internal:<port>` whenever that name resolves — the intended convenience for reaching a Studio Pro on the Docker host. Inside a devcontainer it resolves, so the request goes to the host gateway and never reaches the httptest listener on the container's own 127.0.0.1. On a CI runner the name does not resolve and the rewrite is a no-op, which is why the suite was green there", "file": "`mdl/backend/mcp/connect_reads_test.go` (`backendFor`, used by `connected`, `TestConnect_GetWorkflowReadsASeededWorkflow`, `TestConnect_DisconnectIsIdempotent`); precedent `fakePED.connectClient` in `client_test.go`", "insight": "**A fake server must be dialled at the address it is listening on, never through production address resolution.** Any helper that takes an optional dial/host override and defaults to environment-sensitive logic (DNS lookups, proxy env, gateway rewrites) makes a test pass or fail by where it runs, not by what it tests — and CI is precisely the environment where such a rewrite is inert, so it cannot catch it. Pass the listener address explicitly (as `connectClient` already did) rather than changing `defaultDial`, which is correct for real connections. The tell in the error is the dialled IP differing from the URL's host. Control: revert the dial to `\"\"` in the devcontainer and the same five fail with the reported message; `TestConnect_TheSameWriteSucceedsReadWrite` passes either way because it never builds an MCP backend, which is what localises the defect to the constructor call", "refs": ["ako/mxcli#468"]}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"Six FullBackend methods sat on the unreachable census being treated as abstraction bypasses awaiting a port, when nothing anywhere wanted them: the whole WidgetSerializationBackend interface (SerializeWidget/ClientAction/DataSource/WorkflowActivity), GetUnitTypes and UpdateLayout. They had been superseded and simply never removed.","cause":"scripts/backend-reachability.sh reports DEAD for 'nothing calls this through a backend value', and that one verdict covers three different situations. The census header read all of them as bypasses, so the standing instruction was to port them — which for these would have meant implementing methods with no caller.","file":"mdl/backend/mutation.go","fix":"Deleted WidgetSerializationBackend, GetUnitTypes and UpdateLayout from the interface; regenerated unimplemented_gen.go and mcp/unsupported_gen.go (276 -> 270 methods); dropped the mock stubs and a duplicate *Backend impl. Census 11 -> 6, and the remaining six are genuine bypasses. Rewrote the census header and the probe script's own header to name the three causes.","insight":"A reachability probe that removes a method and rebuilds answers ONE question — is anything calling this through the interface — and DEAD has three causes wanting opposite fixes: BYPASS (a caller wants it but holds a concrete type; port the caller), ORPHAN (no caller anywhere; delete), DUPLICATE (callers exist but through a narrower package-local interface with a DIFFERENT SIGNATURE; delete). The probe cannot separate them; a grep for callers under any type can. DUPLICATE is the one that misleads, and it is worth knowing its two tells. First, a raw call-site count looks healthy — SerializeWidget had 6 and SerializeClientAction 4 — so the name reads as live; only comparing signatures shows the interface copy is unused (bson.D on the real path vs (any, error) on FullBackend). Second, the supersession is usually DOCUMENTED at the replacement, not at the corpse: WidgetBuilderBackend.SerializeWidgetToOpaque says 'This replaces the direct mpr.SerializeWidget call' — so grepping the NEW method's doc comment finds the old one faster than auditing the old one does. A stale comment on the dead method actively lies (the vestigial *Backend SerializeWorkflowActivity claimed the ALTER WORKFLOW paths used it; they use codecWorkflowDeps). Generalisable: when a helper has both an (any, error) and a concrete-typed variant, suspect the general-typed one is the abandoned interface obligation."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"Backend.CreateEntity and CreateAssociation left the caller's semantic element holding an EMPTY ID, so the very next call failed with \"entity not found: \" (note the blank). The legacy writer had populated them, so this was a silent behaviour difference across the engine swap that no test caught.","cause":"assignEntityIDs/assignAssociationIDs mint identities on the gen element built by entityToGen/assocToGen, and nothing copied them back to the *domainmodel.Entity the caller passed in. assignID only fills an EMPTY id, so api/ was unaffected (its builders pre-assign one) — which is exactly why no existing test saw it.","file":"mdl/backend/modelsdk/domainmodel_write.go","fix":"copyAssignedIDs writes the minted entity and attribute ids back onto the caller's element, matching attributes BY NAME rather than by position; CreateAssociation does the same for its own id. Both only fill an empty id, so a caller-assigned one is preserved.","insight":"Found by RUNNING examples/modify_project after repointing it, not by any test — the unit suite, check-mdl and the whole integration gate were green. That is the argument for keeping example programs runnable and actually running them: an example is the only caller that uses the API the way an outside user would, with no pre-assigned ids and no knowledge of internals. Two specifics worth carrying. (1) The empty-string ID makes the error message read \"entity not found: \" with nothing after the colon — a trailing-blank in an error is a strong tell that an identity was never populated rather than looked up and missed. (2) When copying minted ids back, match sub-elements BY NAME, never by index: entityToGen can add, skip or reorder (an audit pseudo-type becomes a System-module generalization, not an attribute), so an index-based copy hands the caller ANOTHER attribute's identity — which looks like it worked and is worse than the empty id it replaced. The control matters here too: a test that only asserts 'id is non-empty' passes against an implementation that overwrites a caller-assigned id, which would break api/; assert the reported id equals the STORED one, and add a companion test that a pre-assigned id survives."}
+{"area":"mdl/backend","date":"2026-09-15","symptom":"Moving cmd/mxcli/project_tree.go from a concrete sdk/mpr reader to the codec backend silently dropped System.VerifyPassword from `mxcli project-tree` output. Build clean, all tests green, 131 bytes missing from a 78KB JSON tree.","cause":"The System module's Java actions are platform built-ins with NO stored unit in the .mpr. sdk/mpr's ListJavaActions/ListJavaActionsFull appended them via BuildSystemJavaActions(); the codec backend only decoded stored units, so it reported them as absent.","file":"mdl/backend/modelsdk/java.go","fix":"Moved the System Java action definitions from sdk/mpr to modelsdk/meta (which already owns the virtual System module's entities and associations) and appended them in both codec ListJavaActions and ListJavaActionsFull; sdk/mpr now delegates rather than holding a second copy. Regression tests plus a control that the STORED actions are still returned.","insight":"Found by diffing the command's output against a binary built from the pre-port commit — not by any test, and no test would have caught it. That baseline-diff is the technique worth keeping for any reader swap: build the old binary first (git stash -u; make build; cp bin/mxcli /tmp/before), then require byte-identical output on every command whose reader you touched. A 131-byte difference in 78KB of JSON is invisible to eyeballing and to 'it still runs'. Two structural lessons. (1) A SYNTHESIZED element is the thing a reader swap loses, because it exists in one reader's code rather than in the data — grep the old reader for 'not stored in' / 'virtual' / 'Build*' helpers before trusting a port. (2) The census in unimplemented_reachability_test.go CANNOT catch this class of bypass: it only lists methods with no implementation, so a caller holding a concrete reader while calling only IMPLEMENTED methods is invisible to it. project_tree.go called 36 semantic methods, every one on FullBackend, and never appeared — which is also why the Phase 3 write-up wrongly described all remaining bypasses as raw-unit debugging tools. The complete list of bypasses is the sdk/mpr IMPORTER list, not the census."}
diff --git a/cmd/mxcli/cmd_bson_discover.go b/cmd/mxcli/cmd_bson_discover.go
index 29c19724bc..c5cdab9cb3 100644
--- a/cmd/mxcli/cmd_bson_discover.go
+++ b/cmd/mxcli/cmd_bson_discover.go
@@ -5,7 +5,7 @@ import (
 	"os"
 
 	bsondiscover "github.com/mendixlabs/mxcli/cmd/mxcli/bson"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
+	mpr "github.com/mendixlabs/mxcli/modelsdk/mpr"
 	"github.com/spf13/cobra"
 	"go.mongodb.org/mongo-driver/bson"
 )
diff --git a/cmd/mxcli/cmd_bson_dump.go b/cmd/mxcli/cmd_bson_dump.go
index 7c689faefc..fa15fa8bc9 100644
--- a/cmd/mxcli/cmd_bson_dump.go
+++ b/cmd/mxcli/cmd_bson_dump.go
@@ -9,7 +9,7 @@ import (
 	"strings"
 
 	bsondebug "github.com/mendixlabs/mxcli/cmd/mxcli/bson"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
+	mpr "github.com/mendixlabs/mxcli/modelsdk/mpr"
 	"github.com/spf13/cobra"
 	"go.mongodb.org/mongo-driver/bson"
 )
diff --git a/cmd/mxcli/debug_resolve.go b/cmd/mxcli/debug_resolve.go
index 61f82b1325..4781743641 100644
--- a/cmd/mxcli/debug_resolve.go
+++ b/cmd/mxcli/debug_resolve.go
@@ -11,8 +11,8 @@ import (
 	"strconv"
 	"strings"
 
+	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
 	"github.com/mendixlabs/mxcli/sdk/microflows"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
 )
 
 // debug_resolve.go turns a microflow name + activity selector into the model GUID
@@ -44,14 +44,17 @@ const (
 // objects, auto-detecting which it is (microflow first, then nanoflow). The
 // object-collection format is identical, so extractActivities handles both.
 func resolveFlowActivities(projectPath, qualifiedName string) ([]activityInfo, flowKind, error) {
-	r, err := mpr.Open(projectPath)
-	if err != nil {
+	// Through the backend rather than a concrete reader: this needs
+	// ParseMicroflowBSON, which is a backend method, so the raw reads come from
+	// the same place instead of straddling two readers.
+	r := modelsdkbackend.New()
+	if err := r.ConnectReadOnly(projectPath); err != nil {
 		return nil, "", err
 	}
-	defer r.Close()
+	defer func() { _ = r.Disconnect() }()
 
 	if contents, err := r.GetRawMicroflowByName(qualifiedName); err == nil {
-		mf, err := mpr.ParseMicroflowBSON(contents, "", "")
+		mf, err := r.ParseMicroflowBSON(contents, "", "")
 		if err != nil {
 			return nil, "", fmt.Errorf("parsing microflow %s: %w", qualifiedName, err)
 		}
@@ -59,7 +62,7 @@ func resolveFlowActivities(projectPath, qualifiedName string) ([]activityInfo, f
 	}
 	// Not a microflow — try a nanoflow (same ObjectCollection shape).
 	if u, err := r.GetRawUnitByName("nanoflow", qualifiedName); err == nil && u != nil {
-		nf, err := mpr.ParseMicroflowBSON(u.Contents, "", "")
+		nf, err := r.ParseMicroflowBSON(u.Contents, "", "")
 		if err != nil {
 			return nil, "", fmt.Errorf("parsing nanoflow %s: %w", qualifiedName, err)
 		}
diff --git a/cmd/mxcli/diag.go b/cmd/mxcli/diag.go
index 27d0c8d7b1..909c8a5fc8 100644
--- a/cmd/mxcli/diag.go
+++ b/cmd/mxcli/diag.go
@@ -16,7 +16,7 @@ import (
 	"time"
 
 	"github.com/mendixlabs/mxcli/mdl/diaglog"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
+	mpr "github.com/mendixlabs/mxcli/modelsdk/mpr"
 	"github.com/spf13/cobra"
 )
 
diff --git a/cmd/mxcli/project_tree.go b/cmd/mxcli/project_tree.go
index c16d441367..6a8c8d6474 100644
--- a/cmd/mxcli/project_tree.go
+++ b/cmd/mxcli/project_tree.go
@@ -8,10 +8,10 @@ import (
 	"os"
 	"sort"
 
+	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
 	"github.com/mendixlabs/mxcli/mdl/executor"
 	"github.com/mendixlabs/mxcli/mdl/types"
 	"github.com/mendixlabs/mxcli/model"
-	"github.com/mendixlabs/mxcli/sdk/mpr"
 	"github.com/spf13/cobra"
 )
 
@@ -68,13 +68,19 @@ Example:
 }
 
 func buildProjectTree(projectPath string) ([]*TreeNode, error) {
-	reader, err := mpr.Open(projectPath)
-	if err != nil {
+	// Through the backend, not a concrete reader: every call below is a semantic
+	// read (ListModules, ListMicroflows, ListWorkflows, …) already on
+	// FullBackend. This was never a raw-unit tool — the Phase 3 write-up in
+	// docs/plans/2026-09-14-retire-legacy-engine.md lumped it in with the bson
+	// dumpers, which was wrong, and the census could not catch the mistake
+	// because it only records bypasses that reach an UNIMPLEMENTED method.
+	reader := modelsdkbackend.New()
+	if err := reader.ConnectReadOnly(projectPath); err != nil {
 		return nil, fmt.Errorf("failed to open project: %w", err)
 	}
-	defer reader.Close()
+	defer func() { _ = reader.Disconnect() }()
 
-	h, err := executor.NewContainerHierarchy(reader)
+	h, err := executor.NewContainerHierarchyFromBackend(reader)
 	if err != nil {
 		return nil, fmt.Errorf("failed to build hierarchy: %w", err)
 	}
diff --git a/docs/plans/2026-09-14-retire-legacy-engine.md b/docs/plans/2026-09-14-retire-legacy-engine.md
index 7a37fc8d0e..1be4e6212d 100644
--- a/docs/plans/2026-09-14-retire-legacy-engine.md
+++ b/docs/plans/2026-09-14-retire-legacy-engine.md
@@ -355,6 +355,12 @@ same kind of caller: `cmd/mxcli`'s `bson dump` / `bson discover` / `diag` / `ext
 `examples/read_project`. Every one is a **raw-unit debugging or export command**, holding a concrete
 `sdk/mpr` reader because raw access is the thing it exists to provide.
 
+> **Corrected 2026-09-15 (§7.6).** "All the bypasses are raw tools" was wrong, and the census is
+> why: it lists only methods with **no implementation**, so a caller holding a concrete reader while
+> calling only *implemented* methods never appears in it. `cmd/mxcli/project_tree.go` is exactly
+> that — 36 semantic reads, every one on `FullBackend` — and it is a bypass the census could not
+> see. **The complete list of bypasses is the `sdk/mpr` importer list, not the census.**
+
 Porting them was considered and **declined**. The backend interface speaks the semantic model by
 [ADR-0005](../13-decisions/0005-semantic-model-interface-currency.md); routing a BSON dumper through
 it would either widen that interface with raw accessors — undoing the decision — or make the tools
@@ -434,3 +440,33 @@ does.
 **4a, then the `modelsdk.go` decision, then 4c (delete `sdk/mpr`), then 4b.** 4a is a proven move
 that deletes 41k lines; 4b is internal churn whose payoff is gated on 4a finishing anyway. Doing 4b
 first would convert a mutator layer that 4c might reshape.
+
+### Phase 4a, first slice — `cmd/mxcli`'s readers (2026-09-15)
+
+Five files off `sdk/mpr`, and the slice split into two ports rather than one, because the Phase 3
+decision ("raw tools keep raw access") does not mean "raw tools keep `sdk/mpr`":
+
+- **Raw tools → `modelsdk/mpr`**, the **v2 raw reader**. `bson dump`, `bson discover` and `diag`
+  moved by import swap alone: `ListRawUnits`, `GetRawUnitByName`, `GetRawMicroflowByName`,
+  `ListAllUnitIDs` and `ContentsDir` have **identical signatures** on both readers, and
+  `RawUnitInfo` is field-for-field identical (`modelsdk/mpr` aliases `types.RawUnitInfo`;
+  `sdk/mpr` declares a duplicate struct, which its own rule in CLAUDE.md forbids). This honours
+  Phase 3 *and* moves those files to v2 — 4a and 4b at once for them.
+- **Semantic bypass → the backend.** `project_tree.go` and `debug_resolve.go`. The first calls 36
+  semantic reads; the second needs `ParseMicroflowBSON`, which is a backend method, so straddling
+  two readers would have been the alternative.
+
+**A regression the port introduced, caught only by a baseline diff.** `project-tree` silently lost
+`System.VerifyPassword` — 131 bytes out of 78KB of JSON. The System module's Java actions are
+platform built-ins with **no stored unit**; `sdk/mpr` synthesized them and the codec backend did
+not. The definitions now live in `modelsdk/meta` beside the virtual System module's entities, both
+codec listings append them, and `sdk/mpr` delegates instead of holding a second copy.
+
+The technique is the transferable part: **build a binary from the pre-port commit first**
+(`git stash -u; make build; cp bin/mxcli /tmp/before`) and require byte-identical output from every
+command whose reader changed. No test caught this and none would have. Generalising: a
+**synthesized** element is what a reader swap loses, because it lives in one reader's code rather
+than in the data — grep the old reader for `virtual`, `not stored in`, and `Build*` helpers before
+trusting any port.
+
+**Importers: 27 → 22.**
diff --git a/mdl/backend/modelsdk/java.go b/mdl/backend/modelsdk/java.go
index 9eb709455f..bdbc26368e 100644
--- a/mdl/backend/modelsdk/java.go
+++ b/mdl/backend/modelsdk/java.go
@@ -8,6 +8,7 @@ import (
 
 	"github.com/mendixlabs/mxcli/mdl/types"
 	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/modelsdk/meta"
 )
 
 // ListJavaActions reads Java action units into the lightweight types.JavaAction
@@ -30,5 +31,10 @@ func (b *Backend) ListJavaActions() ([]*types.JavaAction, error) {
 		ja.ID = model.ID(u.Element.ID())
 		out = append(out, ja)
 	}
+	// The System module's built-in Java actions are not stored in the .mpr, so a
+	// reader that only decodes units reports them as absent. The legacy reader
+	// appended them; not doing so lost System.VerifyPassword from `project-tree`
+	// the moment it moved onto this backend.
+	out = append(out, meta.BuildSystemJavaActions()...)
 	return out, nil
 }
diff --git a/mdl/backend/modelsdk/java_read.go b/mdl/backend/modelsdk/java_read.go
index c30b432d90..5ef3ee7a4b 100644
--- a/mdl/backend/modelsdk/java_read.go
+++ b/mdl/backend/modelsdk/java_read.go
@@ -12,6 +12,7 @@ import (
 	"github.com/mendixlabs/mxcli/modelsdk/element"
 	genCa "github.com/mendixlabs/mxcli/modelsdk/gen/codeactions"
 	genJa "github.com/mendixlabs/mxcli/modelsdk/gen/javaactions"
+	"github.com/mendixlabs/mxcli/modelsdk/meta"
 	"github.com/mendixlabs/mxcli/modelsdk/mprread"
 	"github.com/mendixlabs/mxcli/sdk/javaactions"
 )
@@ -57,6 +58,9 @@ func (b *Backend) ListJavaActionsFull() ([]*javaactions.JavaAction, error) {
 	for _, u := range units {
 		out = append(out, javaActionFromGen(u.Element, u.ContainerID))
 	}
+	// Same reason as ListJavaActions: the System module's are platform built-ins
+	// with no stored unit, so they have to be synthesized or they vanish.
+	out = append(out, meta.BuildSystemJavaActionsFull()...)
 	return out, nil
 }
 
diff --git a/mdl/backend/modelsdk/java_system_test.go b/mdl/backend/modelsdk/java_system_test.go
new file mode 100644
index 0000000000..b3855c7c9a
--- /dev/null
+++ b/mdl/backend/modelsdk/java_system_test.go
@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+// The System module's Java actions are platform built-ins with no stored unit,
+// so a reader that only decodes units reports them as absent. The legacy
+// sdk/mpr reader synthesized them and this backend did not, which is a
+// difference nothing measured until `project-tree` moved onto the backend and
+// silently lost System.VerifyPassword from its output (Phase 4a).
+//
+// Caught by diffing the command against a pre-port binary, not by a test —
+// which is the argument for keeping that baseline around during a port.
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/modelsdk/meta"
+)
+
+func TestListJavaActions_IncludesSystemBuiltIns(t *testing.T) {
+	b := New()
+	if err := b.Connect(copyFixture(t)); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	got, err := b.ListJavaActions()
+	if err != nil {
+		t.Fatalf("ListJavaActions: %v", err)
+	}
+	names := map[string]bool{}
+	for _, ja := range got {
+		names[ja.Name] = true
+	}
+	for _, def := range meta.SystemJavaActions {
+		if !names[def.Name] {
+			t.Errorf("System.%s missing from ListJavaActions — a platform built-in "+
+				"has no stored unit, so it must be synthesized or it vanishes", def.Name)
+		}
+	}
+}
+
+func TestListJavaActionsFull_IncludesSystemBuiltIns(t *testing.T) {
+	b := New()
+	if err := b.Connect(copyFixture(t)); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	got, err := b.ListJavaActionsFull()
+	if err != nil {
+		t.Fatalf("ListJavaActionsFull: %v", err)
+	}
+	for _, def := range meta.SystemJavaActions {
+		var found bool
+		for _, ja := range got {
+			if ja.Name != def.Name {
+				continue
+			}
+			found = true
+			// Not just the name: the full variant is what the catalog stores, so
+			// an entry with no parameters or return type would satisfy a
+			// name-only check while being useless to every consumer.
+			if len(ja.Parameters) != len(def.Parameters) {
+				t.Errorf("System.%s has %d parameters, want %d",
+					def.Name, len(ja.Parameters), len(def.Parameters))
+			}
+			if def.ReturnType != "Void" && ja.ReturnType == nil {
+				t.Errorf("System.%s has no return type, want %s", def.Name, def.ReturnType)
+			}
+		}
+		if !found {
+			t.Errorf("System.%s missing from ListJavaActionsFull", def.Name)
+		}
+	}
+}
+
+// The control. Both tests above pass just as well against a backend that
+// returns ONLY the synthesized System actions and drops every stored one —
+// which would be a far worse regression than the one they were written for.
+func TestListJavaActions_StillReturnsStoredActions(t *testing.T) {
+	b := New()
+	if err := b.Connect(copyFixture(t)); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	got, err := b.ListJavaActions()
+	if err != nil {
+		t.Fatalf("ListJavaActions: %v", err)
+	}
+	var stored int
+	for _, ja := range got {
+		if string(ja.ContainerID) != meta.SystemModuleID {
+			stored++
+		}
+	}
+	if stored == 0 {
+		t.Fatalf("every returned Java action is a System built-in (%d total) — "+
+			"the stored ones were dropped", len(got))
+	}
+}
diff --git a/modelsdk/meta/system_java_actions.go b/modelsdk/meta/system_java_actions.go
new file mode 100644
index 0000000000..00776568ce
--- /dev/null
+++ b/modelsdk/meta/system_java_actions.go
@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package meta
+
+// The System module's built-in Java actions.
+//
+// These are NOT stored in the .mpr — Mendix ships them with the platform — so a
+// reader that only decodes stored units reports them as absent. The legacy
+// sdk/mpr reader synthesized them and the codec backend did not, which made
+// `project-tree` lose System.VerifyPassword the moment it moved onto the
+// backend (docs/plans/2026-09-14-retire-legacy-engine.md, Phase 4a).
+//
+// They live here rather than in mdl/types because the fully-typed builder needs
+// sdk/javaactions, and sdk/javaactions imports mdl/types — the other direction
+// would be a cycle. modelsdk/meta already owns the virtual System module's
+// entities and associations, so the Java actions belong beside them.
+
+import (
+	"github.com/mendixlabs/mxcli/mdl/types"
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/javaactions"
+)
+
+// SystemJavaParamDef defines a parameter of a System Java action.
+type SystemJavaParamDef struct {
+	Name string
+	Type string // "String", "Boolean", "Integer", "Long", "Decimal", "DateTime"
+}
+
+// SystemJavaActionDef defines a Java action in the System module.
+type SystemJavaActionDef struct {
+	Name          string
+	Documentation string
+	ReturnType    string // "Boolean", "String", "Integer", "Long", "Decimal", "DateTime", "Void"
+	Parameters    []SystemJavaParamDef
+}
+
+// SystemJavaActions lists all Java actions in the System module.
+// Extracted from Mendix Studio Pro 11.9.0 via
+// `mx dump-mpr --module-names=System --unit-type=JavaActions$JavaAction`.
+var SystemJavaActions = []SystemJavaActionDef{
+	{
+		Name:          "VerifyPassword",
+		Documentation: "Verifies that the specified user name/password combination is valid.",
+		ReturnType:    "Boolean",
+		Parameters: []SystemJavaParamDef{
+			{Name: "userName", Type: "String"},
+			{Name: "password", Type: "String"},
+		},
+	},
+}
+
+// BuildSystemJavaActions returns lightweight types.JavaAction entries.
+//
+// IDs are deterministic, so two readers describing the same project agree about
+// a System action's identity even though neither read it from storage.
+func BuildSystemJavaActions() []*types.JavaAction {
+	result := make([]*types.JavaAction, 0, len(SystemJavaActions))
+	for _, def := range SystemJavaActions {
+		ja := &types.JavaAction{
+			ContainerID:   model.ID(SystemModuleID),
+			Name:          def.Name,
+			Documentation: def.Documentation,
+		}
+		ja.ID = model.ID(types.GenerateDeterministicID("System." + def.Name))
+		result = append(result, ja)
+	}
+	return result
+}
+
+// BuildSystemJavaActionsFull returns fully-typed entries, for catalog insertion.
+func BuildSystemJavaActionsFull() []*javaactions.JavaAction {
+	result := make([]*javaactions.JavaAction, 0, len(SystemJavaActions))
+	for _, def := range SystemJavaActions {
+		ja := &javaactions.JavaAction{
+			ContainerID:   model.ID(SystemModuleID),
+			Name:          def.Name,
+			Documentation: def.Documentation,
+			ExportLevel:   "Hidden",
+		}
+		ja.ID = model.ID(types.GenerateDeterministicID("System." + def.Name))
+		ja.ReturnType = buildSystemReturnType(def.ReturnType)
+		for _, p := range def.Parameters {
+			param := &javaactions.JavaActionParameter{
+				Name:       p.Name,
+				IsRequired: true,
+			}
+			param.ID = model.ID(types.GenerateDeterministicID("System." + def.Name + "." + p.Name))
+			param.ParameterType = buildSystemParamType(p.Type)
+			ja.Parameters = append(ja.Parameters, param)
+		}
+		result = append(result, ja)
+	}
+	return result
+}
+
+func buildSystemReturnType(t string) javaactions.CodeActionReturnType {
+	switch t {
+	case "Boolean":
+		return &javaactions.BooleanType{}
+	case "String":
+		return &javaactions.StringType{}
+	case "Integer":
+		return &javaactions.IntegerType{}
+	case "Long":
+		return &javaactions.LongType{}
+	case "Decimal":
+		return &javaactions.DecimalType{}
+	case "DateTime":
+		return &javaactions.DateTimeType{}
+	default:
+		return &javaactions.VoidType{}
+	}
+}
+
+func buildSystemParamType(t string) javaactions.CodeActionParameterType {
+	switch t {
+	case "Boolean":
+		return &javaactions.BooleanType{}
+	case "Integer":
+		return &javaactions.IntegerType{}
+	case "Long":
+		return &javaactions.LongType{}
+	case "Decimal":
+		return &javaactions.DecimalType{}
+	case "DateTime":
+		return &javaactions.DateTimeType{}
+	default:
+		return &javaactions.StringType{}
+	}
+}
diff --git a/sdk/mpr/system_java_actions.go b/sdk/mpr/system_java_actions.go
index d5836a3557..e15ad6fefd 100644
--- a/sdk/mpr/system_java_actions.go
+++ b/sdk/mpr/system_java_actions.go
@@ -2,117 +2,22 @@
 
 package mpr
 
+// The System module's built-in Java actions now live in modelsdk/meta, beside
+// the virtual System module's entities and associations. This package keeps the
+// two names it exported so its own callers are unaffected, and delegates — two
+// copies of a hand-maintained platform list is exactly how the two readers
+// would come to disagree about what the System module contains.
+
 import (
 	"github.com/mendixlabs/mxcli/mdl/types"
-	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/modelsdk/meta"
 	"github.com/mendixlabs/mxcli/sdk/javaactions"
 )
 
-// systemJavaParamDef defines a parameter of a System Java action.
-type systemJavaParamDef struct {
-	Name string
-	Type string // "String", "Boolean", "Integer", "Long", "Decimal", "DateTime"
-}
-
-// systemJavaActionDef defines a Java action in the System module.
-type systemJavaActionDef struct {
-	Name          string
-	Documentation string
-	ReturnType    string // "Boolean", "String", "Integer", "Long", "Decimal", "DateTime", "Void"
-	Parameters    []systemJavaParamDef
-}
-
-// systemJavaActions lists all Java actions in the System module.
-// Extracted from Mendix Studio Pro 11.9.0 via mx dump-mpr --module-names=System --unit-type=JavaActions$JavaAction.
-var systemJavaActions = []systemJavaActionDef{
-	{
-		Name:          "VerifyPassword",
-		Documentation: "Verifies that the specified user name/password combination is valid.",
-		ReturnType:    "Boolean",
-		Parameters: []systemJavaParamDef{
-			{Name: "userName", Type: "String"},
-			{Name: "password", Type: "String"},
-		},
-	},
-}
-
 // BuildSystemJavaActions returns lightweight types.JavaAction entries for the System module.
-// These are built-in Java actions not stored in the MPR SQLite database.
-// Used by ListJavaActions() for executor reference validation.
-func BuildSystemJavaActions() []*types.JavaAction {
-	result := make([]*types.JavaAction, 0, len(systemJavaActions))
-	for _, def := range systemJavaActions {
-		ja := &types.JavaAction{
-			ContainerID:   model.ID(SystemModuleID),
-			Name:          def.Name,
-			Documentation: def.Documentation,
-		}
-		ja.ID = model.ID(GenerateDeterministicID("System." + def.Name))
-		result = append(result, ja)
-	}
-	return result
-}
+func BuildSystemJavaActions() []*types.JavaAction { return meta.BuildSystemJavaActions() }
 
 // BuildSystemJavaActionsFull returns fully-typed javaactions.JavaAction entries for the System module.
-// These are built-in Java actions not stored in the MPR SQLite database.
-// Used by ListJavaActionsFull() for catalog insertion.
 func BuildSystemJavaActionsFull() []*javaactions.JavaAction {
-	result := make([]*javaactions.JavaAction, 0, len(systemJavaActions))
-	for _, def := range systemJavaActions {
-		ja := &javaactions.JavaAction{
-			ContainerID:   model.ID(SystemModuleID),
-			Name:          def.Name,
-			Documentation: def.Documentation,
-			ExportLevel:   "Hidden",
-		}
-		ja.ID = model.ID(GenerateDeterministicID("System." + def.Name))
-		ja.ReturnType = buildSystemReturnType(def.ReturnType)
-		for _, p := range def.Parameters {
-			param := &javaactions.JavaActionParameter{
-				Name:       p.Name,
-				IsRequired: true,
-			}
-			param.ID = model.ID(GenerateDeterministicID("System." + def.Name + "." + p.Name))
-			param.ParameterType = buildSystemParamType(p.Type)
-			ja.Parameters = append(ja.Parameters, param)
-		}
-		result = append(result, ja)
-	}
-	return result
-}
-
-func buildSystemReturnType(t string) javaactions.CodeActionReturnType {
-	switch t {
-	case "Boolean":
-		return &javaactions.BooleanType{}
-	case "String":
-		return &javaactions.StringType{}
-	case "Integer":
-		return &javaactions.IntegerType{}
-	case "Long":
-		return &javaactions.LongType{}
-	case "Decimal":
-		return &javaactions.DecimalType{}
-	case "DateTime":
-		return &javaactions.DateTimeType{}
-	default:
-		return &javaactions.VoidType{}
-	}
-}
-
-func buildSystemParamType(t string) javaactions.CodeActionParameterType {
-	switch t {
-	case "Boolean":
-		return &javaactions.BooleanType{}
-	case "Integer":
-		return &javaactions.IntegerType{}
-	case "Long":
-		return &javaactions.LongType{}
-	case "Decimal":
-		return &javaactions.DecimalType{}
-	case "DateTime":
-		return &javaactions.DateTimeType{}
-	default:
-		return &javaactions.StringType{}
-	}
+	return meta.BuildSystemJavaActionsFull()
 }

From b071fcbf2bd40b2c65c7b084bb6c6e6bcee2d1ed Mon Sep 17 00:00:00 2001
From: Ako <andrej@koelewijn.net>
Date: Tue, 15 Sep 2026 13:03:19 +0000
Subject: [PATCH 23/24] =?UTF-8?q?feat(workflow):=20notify=20workflow=20?=
 =?UTF-8?q?=E2=80=A6=20target,=20and=20fix=20notify=20actions=20that=20cou?=
 =?UTF-8?q?ld=20not=20build?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 4b of PROPOSAL_workflow_studio_pro_constructs.md.

  $Notified = notify workflow $Workflow target Module.Workflow.ElementName;

The target names the element a notify resumes: a notification-started event
sub-process's start, a notification activity, a notification boundary event
or a wait for notification. Mendix stores a different NotifyTarget $Type for
each (ako/TestApp ZzMxcliExample_Notify, Studio Pro 11.14, now the reader's
fixture), so the executor looks the element up in the stored workflow and
writes the matching type; an element no notification reaches (a timer start,
a user task, a timer boundary event) is refused with the names that would
work. Before Mendix 11.7 the action names its wait for notification directly
(Activity), and that form is written there.

Measured on the 11.6, 11.10 and 11.13 mxbuilds, a notify without a target is
CE0166 — so every notify mxcli wrote failed the build, and describe dropped a
stored target so a rewrite removed it. A notify with no target is now
MDL-WF16, refused by check and exec.

Fixes the output variable being lost on read: modelsdk/gen bound it to the key
VariableName where Mendix stores OutputVariableName (11.6 metamodel and Studio
Pro 11.14 agree; under VariableName the variable is undefined, CE0109). Fixed
as a storage-name override on NotifyWorkflowAction only — other gen types bind
VariableName correctly.

MCP: the notify action is mapped (it was unsupported); the notifyTarget shape
matches what Studio Pro 11.14 returns for TestApp's saved actions.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../fix-issue/findings/mdl-backend.jsonl      |   1 +
 .../fix-issue/findings/mdl-executor.jsonl     |   1 +
 .../skills/mendix/write-workflows/SKILL.md    |   8 +-
 CHANGELOG.md                                  |   4 +
 cmd/mxcli/lsp_completions_gen.go              |   1 +
 cmd/mxcli/syntax/features_workflow.go         |  20 +-
 docs-site/src/language/workflow-activities.md |   8 +
 docs/01-project/MDL_QUICK_REFERENCE.md        |   2 +
 ...PROPOSAL_workflow_studio_pro_constructs.md |  63 +++++--
 .../doctype-tests/24-workflow-examples.mdl    |  22 +++
 mdl/ast/ast_microflow_workflow.go             |   3 +-
 mdl/backend/mcp/microflow.go                  |  20 ++
 mdl/backend/mcp/microflow_notify_test.go      |  39 ++++
 mdl/backend/modelsdk/microflow_notify_test.go | 120 ++++++++++++
 .../modelsdk/microflow_read_actions.go        |  11 +-
 .../modelsdk/microflow_workflow_write.go      |  11 ++
 .../TestApp.ZzMxcliExample_Notify.bson        | Bin 0 -> 6833 bytes
 mdl/executor/cmd_microflows_builder_notify.go | 174 ++++++++++++++++++
 .../cmd_microflows_builder_workflow.go        |   3 +
 mdl/executor/cmd_microflows_format_action.go  |  12 +-
 mdl/executor/microflow_notify_test.go         | 168 +++++++++++++++++
 mdl/executor/validate.go                      |   3 +
 mdl/executor/validate_microflow.go            |  16 ++
 mdl/grammar/MDLLexer.g4                       |   1 +
 mdl/grammar/domains/MDLMicroflow.g4           |   7 +-
 mdl/grammar/domains/MDLSettings.g4            |   2 +-
 mdl/visitor/visitor_microflow_workflow.go     |   3 +
 mdl/visitor/visitor_notify_test.go            |  41 +++++
 modelsdk/gen/microflows/types.go              |   8 +-
 sdk/microflows/microflows_actions.go          |  26 +++
 sdk/versions/mendix-11.yaml                   |   4 +
 31 files changed, 780 insertions(+), 22 deletions(-)
 create mode 100644 mdl/backend/mcp/microflow_notify_test.go
 create mode 100644 mdl/backend/modelsdk/microflow_notify_test.go
 create mode 100644 mdl/backend/modelsdk/testdata/TestApp.ZzMxcliExample_Notify.bson
 create mode 100644 mdl/executor/cmd_microflows_builder_notify.go
 create mode 100644 mdl/executor/microflow_notify_test.go
 create mode 100644 mdl/visitor/visitor_notify_test.go

diff --git a/.claude/skills/fix-issue/findings/mdl-backend.jsonl b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
index 3a3633c226..8d3adf0695 100644
--- a/.claude/skills/fix-issue/findings/mdl-backend.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
@@ -100,3 +100,4 @@
 {"area":"mdl/backend","date":"2026-09-15","symptom":"The MCP backend held a concrete *mpr.Reader for its local reads, keeping three methods (GetDomainModelByID, GetWorkflow, ListNavigationDocuments) on FullBackend with no caller through a backend value — and 190 tests in the package, not one of which called Connect, so swapping the reader underneath it would have landed unverified with the suite green.","cause":"Those three reads had no codec-backend implementation, so MCP could not compose a backend and kept a legacy reader instead. Each was a re-keying or widening of a read the package already did, not new decoding.","file":"mdl/backend/mcp/backend.go","fix":"Implemented the three on the codec backend (mdl/backend/modelsdk/mcp_bypass_reads.go), sharing domainModelFromGen / workflowFromGen / navProfileFromGen with their siblings; added Backend.ConnectReadOnly and pointed MCP's reader field at backend.FullBackend. Wrote mdl/backend/mcp/connect_reads_test.go — the first test to call Connect at all.","insight":"A test can be vacuous in two different ways in one file, and the second is the one you miss. The read-only assertion SKIPPED (MyFirstModule has no entities), which the runner prints — so it was obvious. The GetWorkflow assertion looped over the listing and the fixture has ZERO workflows, so the loop body never ran and the test reported PASS having called nothing. Same failure class as #808, but silent. The fixes differ by shape: for the skip, pick a probe needing nothing pre-existing (CreateEntity, not AddAttribute); for the empty loop, SEED the thing through a read-write backend, then reconnect read-only and assert a specific named item is in the listing BEFORE fetching it — that guard is what converts a future vacuous pass into a failure. Cheapest way to find both: print the counts a test loops over before trusting it. MCP's read-only constraint also has a real control: revert ConnectReadOnly to Connect and the write-refusal test fails with the reported symptom, and the companion TestConnect_TheSameWriteSucceedsReadWrite proves the probe write is not failing for an unrelated reason."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"Deleting the legacy sdk/mpr backend (mdl/backend/mpr) turned up three things the removal plan had not sized: a runtime error telling users to rerun on the engine that had just been deleted, an integration suite that had been exercising the retired engine rather than the default one, and a cross-engine parity test whose comparison became vacuous.","cause":"Each is a reference to the second engine that was invisible while two engines existed. errUnimplemented's message named MXCLI_ENGINE=legacy as the fallback; setupTestEnv in mdl/executor/roundtrip_helpers_test.go hardcoded mprbackend.New() as its default, so most of the package's integration tests ran on legacy; TestODataService_EngineWriteParity compared writer A's key set against writer B's.","file":"mdl/backend/modelsdk/backend.go","fix":"errUnimplemented now asks for a bug report instead of naming a fallback. setupTestEnv defaults to the codec backend. The parity test keeps its value assertion (a published OData service retains AllowedModuleRoles) and drops the comparison, renamed to match. --engine/MXCLI_ENGINE kept as a warning-only no-op; `bson compare` and mdl/enginecompare deleted.","insight":"Deleting one of two implementations is not finished when the code compiles — grep for the deleted thing in three places the compiler cannot reach. (1) RUNTIME STRINGS: an error message naming a removed fallback is strictly worse than no fallback, because the user follows it and gets a second failure; this one had been shipping the instruction 'rerun with MXCLI_ENGINE=legacy' from 19 generated stubs. (2) TEST DEFAULTS: a shared setup helper's hardcoded choice of implementation decides what a whole package actually covers, and here it silently pointed most of mdl/executor's integration tests at the engine being retired — deleting the other one moved them onto the default engine for the first time, which is coverage gained, not lost. (3) DIFFERENTIAL TESTS: a test that compares A to B has no meaning with one implementation, but the PROPERTY it was a means to usually does — for the OData one, that a service keeps its role grants, which mx check reports as 0 errors either way. Drop the comparison, keep the property, rename the file so the next reader is not misled. One counter-case worth noting: the doctype gate's engine MATRIX was kept at one entry rather than collapsed, because its selection function still converts a stale MXCLI_TEST_ENGINES=legacy into a loud failure instead of a gate that selects zero engines and reports success."}
 {"area": "mdl/backend/mcp", "date": "2026-09-15", "symptom": "Over MCP against Studio Pro 11.14, `create workflow` with any `multi user task` fails: `ped_create_document …: {\"/flow/activities/1/taskPage\":\"Expected an object, but the value is missing.\"}`", "cause": "The 11.14 Workflows$MultiUserTaskActivity CONSTRUCTOR takes `taskPage: Element<'Workflows$PageReference'>`; mapWorkflowActivity sent the older bare `pageReference` string. Same class as the workflow constructor's `context` change in the same release", "file": "`mdl/backend/mcp/workflow.go` (`multiUserTaskConstructorTakesTaskPage`, `adaptMultiUserTaskPages`)", "insight": "PED constructor shapes drift per Studio Pro release independently of the element (update) shapes, and serverInfo.version is frozen at 1.0.0, so probe the constructor schema text rather than gating on a version. When one constructor of a document family changed shape in a release, check the others in that family before trusting the mapper — this one surfaced only because a phase-3 live probe used a multi-user task"}
+{"area":"mdl/backend/modelsdk","date":"2026-09-15","symptom":"`describe microflow` prints a notify action as `notify workflow $Workflow;` with no `$X =` output variable, although the stored action has one; a rewrite from that output drops it","cause":"`modelsdk/gen` binds NotifyWorkflowAction.outputVariableName to the BSON key \"VariableName\"; Studio Pro 11.14 and the 11.6 metamodel store \"OutputVariableName\". The reader used gen's accessor and got nothing; the hand-built writer wrote the right key, so only reads were wrong","file":"`modelsdk/gen/microflows/types.go` (`initNotifyWorkflowAction`, STORAGE-NAME OVERRIDE), `mdl/backend/modelsdk/microflow_read_actions.go`","insight":"A property whose writer is hand-built and whose reader goes through gen can be wrong in one direction only, which a write-then-read test on the codec cannot catch — both sides agree with themselves. Read a Studio Pro-saved document instead (ako/TestApp's ZzMxcliExample_Notify is the fixture). 16 gen types bind `VariableName`, and most are right (the metamodel stores `variableName` for aggregate, cast and create actions), so fix by type against the metamodel, never by search-and-replace. Settled on mxbuild 11.6/11.10/11.13: under `VariableName` the variable is undefined (CE0109)."}
diff --git a/.claude/skills/fix-issue/findings/mdl-executor.jsonl b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
index 54f79dc5c5..3d07a4aeb2 100644
--- a/.claude/skills/fix-issue/findings/mdl-executor.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
@@ -621,3 +621,4 @@
 {"area": "mdl/executor", "date": "2026-09-15", "symptom": "`describe workflow` → `create or modify` → `describe` differs: a call microflow authored with `comment 'Summarise'` comes back captioned with the microflow's name (`-- ACT_Summarise`)", "cause": "`formatCallMicroflowTask` printed the caption only as a trailing `-- caption` MDL comment, which the parser discards; re-execution then fell back to the builder's default caption (the microflow's short name)", "file": "`mdl/executor/cmd_workflows.go` (`formatCallMicroflowTask`)", "insight": "A trailing `--` comment in describe output is documentation, not data — anything round-trippable must be a grammar clause. Emit `comment '…'` only when the caption differs from the derived default, matching jump/wait (issuetracker #16), so an unauthored caption does not start appearing as authored. Only an end-to-end describe → exec → describe with an AUTHORED caption catches it; fixtures without captions pass either way"}
 {"area": "mdl/executor", "date": "2026-09-15", "symptom": "`create or modify workflow` over a workflow whose multi-user task needs 3 participants / 80 percent, or waits for all users, succeeds and the task afterwards needs all participants and does not wait — no refusal, `mx check` clean", "cause": "The rebuild writes `TargetUserInput: AllUserInput` and `AwaitAllUsers: false` for every multi-user task, and the guard-don't-drop check (`checkNoDroppedWorkflowConstructs`) only inspected `CompletionCriteria`; TargetUserInput and AwaitAllUsers were neither expressible nor guarded", "file": "`mdl/executor/validate_workflow_rewrite.go` (`rawMultiUserTaskSettings`, `rawReplaceLosses`)", "insight": "When auditing a guard, list every property the rebuild writes as a constant, not just the ones that look like 'configuration' — a constant default in the writer is exactly the set a rewrite silently resets. Found by diffing Studio Pro's saved multi-user task (ako/TestApp) key by key against mxcli's writer while adding completion rules. Once a property becomes authorable, the guard changes from 'cannot express' to 'restated?' (count stored non-defaults vs authored clauses)"}
 {"area":"mdl/executor","date":"2026-09-15","symptom":"`create or modify workflow` from `describe workflow` output deletes every notification activity (`Workflows$NotificationActivity`) and reports \"Created workflow\" — no refusal, `mx check` clean","cause":"The reader had no case for NotificationActivity, so it became a GenericWorkflowActivity that describe prints as a `-- [Workflows$NotificationActivity]` comment; the rewrite guard (`checkNoDroppedWorkflowConstructs`) counted boundary events, ends and sub-processes but not this activity, so nothing noticed it was missing from the statement","file":"`mdl/executor/validate_workflow_rewrite.go` (`countAuthoredNotificationActivities`), `mdl/backend/modelsdk/workflow_read.go` (`workflowSimpleActivityFromGen`)","insight":"A `-- [Workflows$…]` comment in describe output is a guard gap until proven otherwise: whatever describe cannot state, a rewrite from that output deletes. Grep the describer's generic fallback against the guard's counters when adding either. Measured with the previous build on an 11.13 copy: one stored activity, zero after the rewrite; the ESP guard had masked it in the Studio Pro reference workflow, which also held a sub-process."}
+{"area":"mdl/executor","date":"2026-09-15","symptom":"Every microflow with `notify workflow $Workflow;` written by mxcli fails the build: CE0166 \"The 'Target' property is required\" on the Notify workflow activity (11.10, 11.13; \"'Activity'\" on 11.6). `mxcli check` and `exec` passed","cause":"A notify must name the element it reaches (NotifyTarget from 11.7, Activity before), and MDL had no clause for it; describe also omitted a stored target, so rewriting a Studio Pro microflow removed it","file":"`mdl/executor/validate_microflow.go` (MDL-WF16), `mdl/executor/cmd_microflows_builder_notify.go` (target resolution), `mdl/grammar/domains/MDLMicroflow.g4`","insight":"The shipped statement was syntax for an action Mendix cannot build — nothing in the doctype tests or the skills exercised it, so it was never put through mx check. When a statement writes an action, check a Studio Pro-saved instance for properties the writer does not set: a required reference the grammar cannot express is a build failure waiting for the first user. The target's stored $Type depends on the element's kind, so resolve it against the workflow rather than asking the author to spell the type."}
diff --git a/.claude/skills/mendix/write-workflows/SKILL.md b/.claude/skills/mendix/write-workflows/SKILL.md
index b42d253ba6..74cc5e743f 100644
--- a/.claude/skills/mendix/write-workflows/SKILL.md
+++ b/.claude/skills/mendix/write-workflows/SKILL.md
@@ -322,7 +322,13 @@ workflow / its tasks. They are easy to miss — there is no `complete task`:
 - `set task outcome $Task 'Approve';` — completes a `System.WorkflowUserTask` with a
   named outcome. This is how a microflow (e.g. a task page's button) finishes a task
   and does the domain work; the outcome branches still record which one was chosen.
-- `open user task $Task`, `notify workflow $Wf`, `lock workflow $Wf`, and
+- `$Notified = notify workflow $Wf target Module.Workflow.Name;` resumes the element
+  it names — a notification-started event sub-process, a notification activity, a
+  notification boundary event or a wait for notification. **The target is
+  required**: a notify without one fails the build (CE0166, MDL-WF16). Name the
+  element as `Module.Workflow.ElementName`; mxcli works out which kind it is and
+  refuses one a notification cannot reach (a timer start, a user task).
+- `open user task $Task`, `lock workflow $Wf`, and
   `workflow operation abort|pause|restart|retry|continue $Wf` are also statements.
 
 A common shape: the task page's buttons call a microflow that does the change and
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0939896e30..9de48b88de 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- **`notify workflow … target Module.Workflow.Name`** (docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md, phase 4b) — names the element a notify reaches: a notification-started event sub-process, a notification activity, a notification boundary event or a wait for notification. The statement names the element and mxcli looks up what it is, because Mendix stores a different target type for each (captured from ako/TestApp, whose saved notify microflow is the reader's fixture). An element no notification can reach — a timer-started sub-process, a user task, a timer boundary event — is refused with what it is and the names that would work. Before Mendix 11.7 the action names its wait for notification directly (`Activity`), and mxcli writes that form there. Describe emits the clause, and the action is now writable over MCP.
+
 - **Workflow event sub-processes and notification events** (docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md, phase 4) — `event subprocess <name> on [non] interrupting notification|timer … { … };` after the main body, `notification <name>;`, and `boundary event [non] interrupting notification <name> { … }`. Until now `describe workflow` left event sub-processes out, printed a notification activity as a comment and dropped notification boundary events, so a workflow with any of them could only be edited in Studio Pro. The shapes come from ako/TestApp, built in Studio Pro 11.14 and saved; the saved document is the reader's fixture, which matters because gen has no type for the timer starts, the notification activity or the notification boundary events. Measured on mxbuild 11.13.0: a sub-process body with no end is CE0105, so mxcli appends the End as it does for the main flow; a jump into or out of a sub-process is CE6682 (MDL-WF05, which now checks each flow as its own scope); a timer start without its expression is CE0126 (MDL-WF14); two interrupting boundary events on one activity are CE6697 (MDL-WF15); a start event named like an activity is CE0495, so names are made unique across the flows. The version gates were measured by loading each construct alone into a blank project: notification-started sub-processes load from 11.10 (11.8 per gen), the notification activity and boundary events from 11.11, timer-started sub-processes only from 11.13. A rewrite must restate them; `alter workflow … insert boundary event` refuses the notification kinds for now. Over MCP they go into the constructor, and a rewrite replaces the stored sub-processes.
 
 - **Multi-user task completion rules: `participants`, `decide by`, `await all users`** (docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md, phase 3) — how many participants must respond (`all`, a number, a percentage), how their outcomes decide the task (`consensus`, `majority more than half`, `majority most chosen`, `threshold <n> percent|votes`, each with `fallback '<outcome>'`; `veto '<outcome>'`; `microflow M`), and whether it waits for everyone. The shapes were captured from Studio Pro rather than read off gen: the examples were built in Studio Pro 11.14 over MCP, saved to ako/TestApp, and the saved document is now the reader's fixture — which is how "more than half" is known to be an Absolute majority and a percentage threshold a Relative one, and that both outcome pointers hold the outcome's `$ID`. Measured on mxbuild 11.13.0: a fallback is required for consensus, majority and threshold (CE1866) and a veto needs its outcome (CE1867), both refused by `check` as MDL-WF13 along with a name that is none of the task's outcomes; a decision microflow must return String (CE5012), its parameters are free; and the build does **not** range-check thresholds or participant counts, so neither does mxcli. Over MCP the backend works around two constructor quirks it measured: PED's default consensus has no fallback, and a more-than-half majority's fallback is dropped and has to be set by `$ID` afterwards.
@@ -18,6 +20,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Fixed
 
+- **Every `notify workflow` mxcli wrote failed the build, and its output variable was lost on read.** Mendix requires a notify to name its target — measured on the 11.6, 11.10 and 11.13 mxbuilds, one without is CE0166 ("The 'Target' property is required"; "'Activity'" on 11.6) — and MDL had no way to name one, while describe dropped the stored target so a rewrite removed it. `check` and `exec` now refuse a notify with no target (MDL-WF16). Separately, `modelsdk/gen` bound the output variable to the key `VariableName` where Mendix stores `OutputVariableName` (the 11.6 metamodel and Studio Pro 11.14 agree), so the reader returned it empty; under that key the variable is undefined in the build (CE0109). Fixed as a storage-name override.
+
 - **A workflow rewrite deleted every notification activity without a word.** `describe workflow` printed a `Workflows$NotificationActivity` as a `-- [Workflows$NotificationActivity]` comment and the rewrite guard did not count them, so `create or modify` from that output removed it and reported "Created workflow". Measured with the previous build: one stored, zero after the rewrite. Notification activities are described as statements now, and a rewrite that does not restate them is refused.
 
 - **Over MCP, a user task's notification boundary events would have been lost without a word.** Studio Pro 11.14's single user task constructor drops `boundaryEvents` — at create and when an update adds the task — and reports "No errors found." Measured live; a multi-user task keeps them, and a notification event added afterwards at the task's `boundaryEvents` is stored, so the backend adds them after each create and update when the stored list is empty. Its interrupting constructors also rewrite a boundary path's ending (a `jump to` outside a parallel split becomes an End), so a notification path Studio Pro would rewrite is refused with the ending it needs. Timer boundary events are affected by the same constructors and are not yet handled.
diff --git a/cmd/mxcli/lsp_completions_gen.go b/cmd/mxcli/lsp_completions_gen.go
index 5740127241..f6ef41c76a 100644
--- a/cmd/mxcli/lsp_completions_gen.go
+++ b/cmd/mxcli/lsp_completions_gen.go
@@ -591,6 +591,7 @@ var mdlGeneratedKeywords = []protocol.CompletionItem{
 	{Label: "OUTCOME", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "OUTCOMES", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "TARGETING", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
+	{Label: "TARGET", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "NOTIFICATION", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "TIMER", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
 	{Label: "JUMP", Kind: protocol.CompletionItemKindKeyword, Detail: "Keyword"},
diff --git a/cmd/mxcli/syntax/features_workflow.go b/cmd/mxcli/syntax/features_workflow.go
index a7cd1cd714..74b08961fe 100644
--- a/cmd/mxcli/syntax/features_workflow.go
+++ b/cmd/mxcli/syntax/features_workflow.go
@@ -431,7 +431,25 @@ func init() {
 			"-- purpose and works on every version.",
 		Example:    "notification DocumentsReceived comment 'Documents received';",
 		MinVersion: "11.11.0",
-		SeeAlso:    []string{"workflow.event-subprocess", "workflow.boundary-event"},
+		SeeAlso:    []string{"workflow.event-subprocess", "workflow.boundary-event", "workflow.notify"},
+	})
+
+	Register(SyntaxFeature{
+		Path:    "workflow.notify",
+		Summary: "Notify a running workflow — resume the element the notification targets",
+		Keywords: []string{
+			"notify workflow", "notify", "notify target", "resume workflow", "trigger event sub-process",
+		},
+		Syntax: "[$Notified =] NOTIFY WORKFLOW $Workflow TARGET Module.Workflow.ElementName;\n\n" +
+			"-- A microflow statement. The target names a notification-started event\n" +
+			"-- sub-process's start, a notification activity, a notification boundary event\n" +
+			"-- or a wait for notification; mxcli looks up which it is and refuses an element\n" +
+			"-- a notification cannot reach (a timer start, a user task). The target is\n" +
+			"-- required: without one the build fails CE0166 (MDL-WF16). $Notified is a\n" +
+			"-- Boolean. Before Mendix 11.7 only a wait for notification can be named.",
+		Example:    "$Cancelled = notify workflow $Workflow target HR.Leave.espCancelStart;",
+		MinVersion: "11.7.0",
+		SeeAlso:    []string{"workflow.event-subprocess", "workflow.notification", "workflow.boundary-event"},
 	})
 
 	Register(SyntaxFeature{
diff --git a/docs-site/src/language/workflow-activities.md b/docs-site/src/language/workflow-activities.md
index d5fbe76490..bc5b3f30f8 100644
--- a/docs-site/src/language/workflow-activities.md
+++ b/docs-site/src/language/workflow-activities.md
@@ -238,6 +238,14 @@ USER TASK Review 'Review'
 
 An activity may carry only one interrupting boundary event (CE6697). `ALTER WORKFLOW … INSERT BOUNDARY EVENT` cannot add a notification boundary event yet.
 
+A microflow reaches any of these with `NOTIFY WORKFLOW`, naming the element:
+
+```sql
+$Notified = NOTIFY WORKFLOW $Workflow TARGET HR.Leave.Withdrawn;
+```
+
+The target is required — a notify without one fails the build (CE0166). It may name a notification activity, a notification boundary event, a wait for notification, or the start of a notification-started event sub-process; mxcli works out which, and refuses anything a notification cannot reach.
+
 ## Event Sub-Processes
 
 A flow outside the main flow, started by its own start event while the workflow runs. Written after the main body, before `END WORKFLOW`:
diff --git a/docs/01-project/MDL_QUICK_REFERENCE.md b/docs/01-project/MDL_QUICK_REFERENCE.md
index 38aff290e3..ba1e6b0295 100644
--- a/docs/01-project/MDL_QUICK_REFERENCE.md
+++ b/docs/01-project/MDL_QUICK_REFERENCE.md
@@ -681,6 +681,8 @@ Nested folders use `/` separator: `'Parent/Child/Grandchild'`. Missing folders a
 - `end workflow [comment '<caption>'];` — only inside a `{ }` block; ends the whole workflow
 - Boundary events, after `outcomes`: `boundary event [non] interrupting timer '<expr>' { … }` or `boundary event [non] interrupting notification <name> ['<caption>'] { … }` (11.11+). One interrupting event per activity (CE6697, MDL-WF15).
 
+**Notifying a workflow** (a microflow statement): `[$Notified =] notify workflow $Workflow target Module.Workflow.ElementName;` — the element is a notification-started event sub-process's start, a notification activity, a notification boundary event or a wait for notification, and mxcli resolves which. The target is required (CE0166, MDL-WF16).
+
 **Event sub-processes**, after the main body: `event subprocess <name> ['<caption>'] on [non] interrupting notification [<start>] ['<caption>'] { … };` (11.8+) or `… on [non] interrupting timer '<first-execution-time>' [as <start>] [comment '<caption>'] { … };` (11.13+). The body's End is implicit; a `jump to` stays in its own sub-process (CE6682, MDL-WF05); a timer needs its expression (CE0126, MDL-WF14).
 
 **Workflow event handlers.** `on workflow events (UserTaskStarted, UserTaskEnded)
diff --git a/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md b/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
index 17accf878b..2eebe2c3ff 100644
--- a/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
+++ b/docs/11-proposals/PROPOSAL_workflow_studio_pro_constructs.md
@@ -1,6 +1,6 @@
 # Proposal: Workflow constructs only Studio Pro could author
 
-**Status:** Phases 1–3 and 4a (event sub-processes, notification events) implemented; 4b (`notify workflow … target`) designed
+**Status:** Phases 1–4 implemented (4a event sub-processes and notification events, 4b `notify workflow … target`)
 **Date:** 2026-09-14
 
 ## Problem Statement
@@ -378,17 +378,56 @@ backend refuses each shape the constructor would rewrite, naming the ending it
 needs, and re-adds a single user task's notification events after every create
 and update. The timer-event losses predate this phase and are tracked separately.
 
-## Phase 4b — notify targets
-
-`NotifyWorkflowAction.NotifyTarget` (11.7.0) names what a microflow notifies:
-`Workflows$(Non)InterruptingNotificationEventSubProcessStartActivityTarget`,
-`NotifyNotificationActivityTarget`, `NotifyWaitForNotificationActivityTarget`
-(each `Activity: "Module.Workflow.name"`) and `NotifyNotificationBoundaryEventTarget`
-(`BoundaryEvent: …`). Reference: ako/TestApp `workflow.ZzMxcliExample_Notify`.
-Syntax: `$Notified = notify workflow $Workflow target HR.Leave.espCancelStart;`.
-Two bugs to fix with it: the reader takes the output variable from gen's
-`VariableName` key where Studio Pro stores `OutputVariableName`, and a rewrite drops
-the target.
+## Phase 4b — notify targets (implemented)
+
+### Reference document (ako/TestApp `workflow.ZzMxcliExample_Notify`, Studio Pro 11.14)
+
+One notify action per target type, each `{ErrorHandlingType, NotifyTarget,
+OutputVariableName, WorkflowVariable}`:
+
+| Element named | `NotifyTarget.$Type` | Name under |
+|---|---|---|
+| interrupting notification start | `Workflows$InterruptingNotificationEventSubProcessStartActivityTarget` | `Activity` |
+| non-interrupting notification start | `Workflows$NonInterruptingNotificationEventSubProcessStartActivityTarget` | `Activity` |
+| notification activity | `Workflows$NotifyNotificationActivityTarget` | `Activity` |
+| wait for notification | `Workflows$NotifyWaitForNotificationActivityTarget` | `Activity` |
+| notification boundary event | `Workflows$NotifyNotificationBoundaryEventTarget` | `BoundaryEvent` |
+
+The name is `Module.Workflow.ElementName`. Before 11.7 the action held the name
+directly as `Activity` (a wait for notification only).
+
+### MDL syntax
+
+```sql
+$Notified = notify workflow $Workflow target HR.Leave.espCancelStart;
+```
+
+The statement names the element, not its kind; mxcli looks the element up in the
+stored workflow and writes the matching type, refusing an element a notification
+cannot reach (a timer-started sub-process's start, a user task, a timer boundary
+event) with the names that would work.
+
+### Measured (mxbuild, one notify per shape)
+
+| Shape | 11.6 | 11.10 | 11.13 |
+|---|---|---|---|
+| no target | CE0166 "'Activity' required" | CE0166 "'Target' required" | CE0166 "'Target' required" |
+| output variable under `OutputVariableName` | defined | defined | defined |
+| output variable under gen's `VariableName`, or absent | CE0109 undefined | CE0109 | CE0109 |
+| every target type, microflow built by mxcli | | | 0 errors |
+
+So the target is required, not optional — every notify mxcli wrote before this
+failed the build — and gen's `VariableName` binding is simply wrong (the 11.6
+metamodel stores `outputVariableName` too): fixed as a storage-name override. A
+notify with no target is MDL-WF16, refused by check and exec. That also covers
+the rewrite: describe used to drop the target, and a statement without one is now
+refused rather than written.
+
+### MCP
+
+`notifyTarget` is `{$Type, activity | boundaryEvent: "<qualified name>"}` (ped_get_schema,
+Studio Pro 11.14); the action was unmapped before, so a notify could not be written
+over MCP at all.
 
 ## Test plan (phase 1)
 
diff --git a/mdl-examples/doctype-tests/24-workflow-examples.mdl b/mdl-examples/doctype-tests/24-workflow-examples.mdl
index 9e0223f6c3..7372777181 100644
--- a/mdl-examples/doctype-tests/24-workflow-examples.mdl
+++ b/mdl-examples/doctype-tests/24-workflow-examples.mdl
@@ -792,3 +792,25 @@ begin
   };
 end workflow;
 /
+
+-- @version: 11.11+
+-- ############################################################################
+-- PART K: NOTIFY WORKFLOW — targets (Mendix 11.11+ for these elements)
+-- ############################################################################
+--
+-- A notify names the element it resumes: a notification-started event
+-- sub-process's start, a notification activity, a notification boundary event or
+-- a wait for notification. Without a target the build fails (CE0166).
+
+create microflow WFTest.ACT_NotifyOrder (
+  $Workflow: System.Workflow
+)
+returns boolean as $Cancelled
+begin
+  $Cancelled = notify workflow $Workflow target WFTest.WithNotifications.CancelStart;
+  $Audited = notify workflow $Workflow target WFTest.WithNotifications.AuditStart;
+  $Received = notify workflow $Workflow target WFTest.WithNotifications.DocumentsReceived;
+  $Withdrawn = notify workflow $Workflow target WFTest.WithNotifications.Withdrawn;
+  return $Cancelled and $Audited and $Received and $Withdrawn;
+end;
+/
diff --git a/mdl/ast/ast_microflow_workflow.go b/mdl/ast/ast_microflow_workflow.go
index 2300c4cf3f..425f94bdb1 100644
--- a/mdl/ast/ast_microflow_workflow.go
+++ b/mdl/ast/ast_microflow_workflow.go
@@ -78,10 +78,11 @@ type OpenUserTaskStmt struct {
 
 func (*OpenUserTaskStmt) isMicroflowStatement() {}
 
-// NotifyWorkflowStmt represents: [$Result =] NOTIFY WORKFLOW $WorkflowVar
+// NotifyWorkflowStmt represents: [$Result =] NOTIFY WORKFLOW $WorkflowVar [TARGET Module.Workflow.Name]
 type NotifyWorkflowStmt struct {
 	OutputVariable   string
 	WorkflowVariable string
+	Target           string // Module.Workflow.ElementName; "" when the clause is absent
 	ErrorHandling    *ErrorHandlingClause
 	Annotations      *ActivityAnnotations
 }
diff --git a/mdl/backend/mcp/microflow.go b/mdl/backend/mcp/microflow.go
index 2f17a51a33..6871e6a18d 100644
--- a/mdl/backend/mcp/microflow.go
+++ b/mdl/backend/mcp/microflow.go
@@ -632,6 +632,26 @@ func mapMicroflowAction(a microflows.MicroflowAction) (map[string]any, error) {
 			m["node"] = act.LogNodeName
 		}
 		return m, nil
+	case *microflows.NotifyWorkflowAction:
+		// ped_get_schema, Studio Pro 11.14: workflowVariable, outputVariableName and
+		// notifyTarget, whose reference is a qualified name under `activity` — or
+		// `boundaryEvent` for a boundary-event target.
+		m := map[string]any{
+			"$Type":              "Microflows$NotifyWorkflowAction",
+			"workflowVariable":   act.WorkflowVariable,
+			"outputVariableName": act.OutputVariableName,
+		}
+		if act.ErrorHandlingType != "" {
+			m["errorHandlingType"] = string(act.ErrorHandlingType)
+		}
+		if t := act.Target; t != nil {
+			key := "activity"
+			if t.Key() == "BoundaryEvent" {
+				key = "boundaryEvent"
+			}
+			m["notifyTarget"] = map[string]any{"$Type": t.TypeName, key: t.Name}
+		}
+		return m, nil
 	default:
 		return nil, fmt.Errorf("microflow action %T is not yet supported by the MCP backend", a)
 	}
diff --git a/mdl/backend/mcp/microflow_notify_test.go b/mdl/backend/mcp/microflow_notify_test.go
new file mode 100644
index 0000000000..eb2c535505
--- /dev/null
+++ b/mdl/backend/mcp/microflow_notify_test.go
@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package mcp
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/sdk/microflows"
+)
+
+// The notify action maps onto ped_get_schema's NotifyWorkflowAction (Studio Pro
+// 11.14): its target reference sits under `activity`, or `boundaryEvent` for a
+// boundary-event target. It was unmapped, so a notify could not be written over
+// MCP at all.
+func TestMapMicroflowAction_NotifyWorkflow(t *testing.T) {
+	cases := []struct {
+		target microflows.NotifyTarget
+		want   map[string]any
+	}{
+		{microflows.NotifyTarget{TypeName: "Workflows$NotifyNotificationActivityTarget", Name: "M.W.received"},
+			map[string]any{"$Type": "Workflows$NotifyNotificationActivityTarget", "activity": "M.W.received"}},
+		{microflows.NotifyTarget{TypeName: "Workflows$NotifyNotificationBoundaryEventTarget", Name: "M.W.withdrawn"},
+			map[string]any{"$Type": "Workflows$NotifyNotificationBoundaryEventTarget", "boundaryEvent": "M.W.withdrawn"}},
+	}
+	for _, c := range cases {
+		target := c.target
+		m, err := mapMicroflowAction(&microflows.NotifyWorkflowAction{WorkflowVariable: "Workflow", OutputVariableName: "Notified", Target: &target})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if m["$Type"] != "Microflows$NotifyWorkflowAction" || m["workflowVariable"] != "Workflow" || m["outputVariableName"] != "Notified" {
+			t.Errorf("action mapped as %v", m)
+		}
+		if got, _ := m["notifyTarget"].(map[string]any); !reflect.DeepEqual(got, c.want) {
+			t.Errorf("notifyTarget = %v, want %v", got, c.want)
+		}
+	}
+}
diff --git a/mdl/backend/modelsdk/microflow_notify_test.go b/mdl/backend/modelsdk/microflow_notify_test.go
new file mode 100644
index 0000000000..dafe032fae
--- /dev/null
+++ b/mdl/backend/modelsdk/microflow_notify_test.go
@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+import (
+	"os"
+	"testing"
+
+	"go.mongodb.org/mongo-driver/v2/bson"
+
+	"github.com/mendixlabs/mxcli/modelsdk/codec"
+	"github.com/mendixlabs/mxcli/modelsdk/element"
+	genMf "github.com/mendixlabs/mxcli/modelsdk/gen/microflows"
+	"github.com/mendixlabs/mxcli/sdk/microflows"
+)
+
+// ako/TestApp's ZzMxcliExample_Notify (Studio Pro 11.14): one notify action per
+// target type, each targeting ZzMxcliExample_EventSubProcesses.
+const notifyFixture = "testdata/TestApp.ZzMxcliExample_Notify.bson"
+
+// Every target type and output variable is read off the Studio Pro document. The
+// output variable was read under gen's "VariableName" key, where Studio Pro
+// stores "OutputVariableName", so it came back empty; the target was not read.
+func TestReadNotifyTargetsFromStudioProFixture(t *testing.T) {
+	raw, err := os.ReadFile(notifyFixture)
+	if err != nil {
+		t.Fatal(err)
+	}
+	root, err := codec.NewDecoder(codec.DefaultRegistry).Decode(bson.Raw(raw))
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := map[string]*microflows.NotifyWorkflowAction{}
+	element.Walk(root, func(e element.Element) bool {
+		if _, ok := e.(*genMf.NotifyWorkflowAction); ok {
+			if a, ok := actionFromGen(e).(*microflows.NotifyWorkflowAction); ok {
+				got[a.OutputVariableName] = a
+			}
+		}
+		return true
+	})
+
+	const wf = "workflow.ZzMxcliExample_EventSubProcesses."
+	want := map[string]microflows.NotifyTarget{
+		"NotifiedCancel":    {TypeName: "Workflows$InterruptingNotificationEventSubProcessStartActivityTarget", Name: wf + "espCancelStart"},
+		"NotifiedAudit":     {TypeName: "Workflows$NonInterruptingNotificationEventSubProcessStartActivityTarget", Name: wf + "espAuditStart"},
+		"NotifiedDocuments": {TypeName: "Workflows$NotifyNotificationActivityTarget", Name: wf + "notifyReceived"},
+		"NotifiedWithdrawn": {TypeName: "Workflows$NotifyNotificationBoundaryEventTarget", Name: wf + "beWithdrawn"},
+		"NotifiedApproval":  {TypeName: "Workflows$NotifyWaitForNotificationActivityTarget", Name: wf + "waitApproval"},
+	}
+	if len(got) != len(want) {
+		t.Fatalf("read %d notify actions by output variable, want %d: %v", len(got), len(want), got)
+	}
+	for variable, w := range want {
+		a := got[variable]
+		if a == nil || a.Target == nil || *a.Target != w || a.WorkflowVariable != "Workflow" {
+			t.Errorf("%s read back as %+v, want target %+v", variable, a, w)
+		}
+	}
+}
+
+// A notify action is written the way Studio Pro stores it — the output variable
+// under OutputVariableName, the target as a NotifyTarget whose name sits under
+// Activity or BoundaryEvent — and reads back unchanged. Before Mendix 11.7 the
+// target is the Activity string, which round-trips too.
+func TestNotifyWorkflowAction_WritesStudioProKeys(t *testing.T) {
+	encode := func(t *testing.T, a microflows.MicroflowAction) bson.Raw {
+		t.Helper()
+		raw, err := (&codec.Encoder{}).Encode(microflowActionToGen(a))
+		if err != nil {
+			t.Fatalf("encode: %v", err)
+		}
+		return bson.Raw(raw)
+	}
+	decode := func(t *testing.T, raw bson.Raw) *microflows.NotifyWorkflowAction {
+		t.Helper()
+		el, err := codec.NewDecoder(codec.DefaultRegistry).Decode(raw)
+		if err != nil {
+			t.Fatalf("decode: %v", err)
+		}
+		a, ok := actionFromGen(el).(*microflows.NotifyWorkflowAction)
+		if !ok {
+			t.Fatalf("read back as %T", actionFromGen(el))
+		}
+		return a
+	}
+
+	for _, target := range []microflows.NotifyTarget{
+		{TypeName: "Workflows$NotifyNotificationBoundaryEventTarget", Name: "M.W.withdrawn"},
+		{TypeName: "Workflows$InterruptingNotificationEventSubProcessStartActivityTarget", Name: "M.W.cancelStart"},
+	} {
+		action := &microflows.NotifyWorkflowAction{WorkflowVariable: "Workflow", OutputVariableName: "Notified", Target: &target}
+		action.ID = "id-notify"
+		raw := encode(t, action)
+		if v, err := raw.LookupErr("OutputVariableName"); err != nil || v.StringValue() != "Notified" {
+			t.Errorf("OutputVariableName not stored under its Studio Pro key: %v", raw)
+		}
+		if _, err := raw.LookupErr("VariableName"); err == nil {
+			t.Errorf("gen's wrong key VariableName was written: %v", raw)
+		}
+		key := target.Key()
+		if v, err := raw.LookupErr("NotifyTarget", key); err != nil || v.StringValue() != target.Name {
+			t.Errorf("NotifyTarget.%s not stored: %v", key, raw)
+		}
+		got := decode(t, raw)
+		if got.OutputVariableName != "Notified" || got.Target == nil || *got.Target != target {
+			t.Errorf("read back as %+v, want output Notified and target %+v", got, target)
+		}
+	}
+
+	legacy := &microflows.NotifyWorkflowAction{WorkflowVariable: "Workflow", Activity: "M.W.waitApproval"}
+	legacy.ID = "id-legacy"
+	raw := encode(t, legacy)
+	if _, err := raw.LookupErr("NotifyTarget"); err == nil {
+		t.Errorf("a pre-11.7 notify must not store a NotifyTarget: %v", raw)
+	}
+	if got := decode(t, raw); got.Activity != "M.W.waitApproval" || got.Target != nil {
+		t.Errorf("pre-11.7 notify read back as %+v", got)
+	}
+}
diff --git a/mdl/backend/modelsdk/microflow_read_actions.go b/mdl/backend/modelsdk/microflow_read_actions.go
index 2b4a02b822..33ec330bd5 100644
--- a/mdl/backend/modelsdk/microflow_read_actions.go
+++ b/mdl/backend/modelsdk/microflow_read_actions.go
@@ -12,6 +12,7 @@ import (
 	genDb "github.com/mendixlabs/mxcli/modelsdk/gen/databaseconnector"
 	genMf "github.com/mendixlabs/mxcli/modelsdk/gen/microflows"
 	genTexts "github.com/mendixlabs/mxcli/modelsdk/gen/texts"
+	genWf "github.com/mendixlabs/mxcli/modelsdk/gen/workflows"
 	"github.com/mendixlabs/mxcli/sdk/microflows"
 )
 
@@ -638,11 +639,19 @@ func actionFromGen(el element.Element) microflows.MicroflowAction {
 		return out
 
 	case *genMf.NotifyWorkflowAction:
-		// NOTIFY WORKFLOW $Workflow. Mirrors legacy parseNotifyWorkflowAction.
+		// NOTIFY WORKFLOW $Workflow TARGET Module.Workflow.Name. Two of the five
+		// target types have no gen type, so the target is read off its raw document
+		// by $Type, like any of them.
 		out := &microflows.NotifyWorkflowAction{
 			ErrorHandlingType:  microflows.ErrorHandlingType(a.ErrorHandlingType()),
 			OutputVariableName: a.OutputVariableName(),
 			WorkflowVariable:   a.WorkflowVariable(),
+			Activity:           a.ActivityQualifiedName(),
+		}
+		if t := a.NotifyTarget(); t != nil && t.TypeName() != "" {
+			target := &microflows.NotifyTarget{TypeName: t.TypeName()}
+			target.Name = genWf.RawFieldString(t.Raw(), target.Key())
+			out.Target = target
 		}
 		out.ID = model.ID(a.ID())
 		return out
diff --git a/mdl/backend/modelsdk/microflow_workflow_write.go b/mdl/backend/modelsdk/microflow_workflow_write.go
index 8f2ced4a64..74b32f37c2 100644
--- a/mdl/backend/modelsdk/microflow_workflow_write.go
+++ b/mdl/backend/modelsdk/microflow_workflow_write.go
@@ -61,8 +61,19 @@ func workflowMicroflowActionToGen(act microflows.MicroflowAction) element.Elemen
 		addStr(g, "UserTaskVariable", a.UserTaskVariable)
 		return g
 	case *microflows.NotifyWorkflowAction:
+		// Key order as ako/TestApp (Studio Pro 11.14) stores it: ErrorHandlingType,
+		// NotifyTarget, OutputVariableName, WorkflowVariable. Before 11.7 the target
+		// was the Activity string instead; the executor sets whichever applies.
 		g := newElem("Microflows$NotifyWorkflowAction", string(a.ID))
+		if a.Activity != "" {
+			addStr(g, "Activity", a.Activity)
+		}
 		addStr(g, "ErrorHandlingType", orDefault(string(a.ErrorHandlingType), "Rollback"))
+		if t := a.Target; t != nil {
+			target := newElem(t.TypeName, "")
+			addStr(target, t.Key(), t.Name)
+			addPart(g, "NotifyTarget", target)
+		}
 		addStr(g, "OutputVariableName", a.OutputVariableName)
 		addStr(g, "WorkflowVariable", a.WorkflowVariable)
 		return g
diff --git a/mdl/backend/modelsdk/testdata/TestApp.ZzMxcliExample_Notify.bson b/mdl/backend/modelsdk/testdata/TestApp.ZzMxcliExample_Notify.bson
new file mode 100644
index 0000000000000000000000000000000000000000..0ac099bd1d7f5c7608da44134ab278ee1a766c6f
GIT binary patch
literal 6833
zcmd5>dsGzX75~_Uif?P;TjQE+bD%bKSp?-_BD?G^t1NI>9>!?Mu=9Z<!wk*?Sld%E
zA!-wAJeq?h*Z`Vh<wz_i8YF4c)>B&(wM}g8BhjRdd9<E1hgjQ+NlouJkKLUuq+r4U
z|3G%;e)skJ&7I$6yXPVlXZ7ZwX$bz!IlH@E*!N-flhdlxPv7>?Hj}kDSc}mNxaDI4
z0$<7U^`bTOD~iu%;fj;z0<s`rPI5KifGjaQhhk!tTbTCow9Minp2Z@X1b(L3Pz(tb
zpIuwa23?%QNWttt0E;3*rjVyV&?N}G5RRmrF^BGJx8W33g;6K?3m0+u;_Kd?dG72-
z-mr?xn+|W+ikJvS#kfHdt>h<)^-8!#L>yd&l+5s-IT@839A#w`j_aU)wX*lh-`DS(
zzU3#Hqv>Hs0>z0er4($+qqr&=vT^b>MqdFN%$1k;kx7ZBqz~6jIeb8_fljH1)K0h>
z0<2798g9E9YI#A*!*!TN<G?<bp=r#aST|`rvW|~Tb_<*iSN&rC+0rLoyW7)x%GcOf
z`{Acrva`WSsEeZ2k2lJg3t-|8#X2bwmr|@8hQ<WuXnGD7C5BT{gpPAKKq~ZdG;UBD
zMQq|CYzldXldzyt=&|0vWi5W|n~olQVA190#{1&Eq5@?u#nCJnA#)zXVbn-`gm||)
z@q1-mAN2VS{_v>X@yNFGTJp2NC?a_W-o#+RDGPNN8fnN;5_q;0^5g{+3x{l(He@Og
zm@0;Y0tUE=ribnt%F}U*Q*Rq8yHd0RUvElrZk^EncE>;DPGq(tBL-VNHy2Xxr+S|{
zx_rskGnOA1Ees|WwstSu{H%B9xBq$U$A4&P9ufvWEm|!+ZwjnxWcwd%>7Ki0Okxnt
zE@V!L!r*HAX?xtY&8~KP@%K;vYjeeDVX$WHug|@ApwQ85lA3}?zj1s>7{uROa;9s0
z!pfHW?i7M=Pwp9$7(}xRnU_Ri5F=ekY>kOu(c|gabHUTzJz5xCoRQTwGwZMJgWo!^
z*L1>f9ufw3wcYS!UN85yjtl(z;w$4{8<QABvkRG1qcFe=*L6;+f6w#WJ@z*<*s^J(
zg~6%qvs-@axtiN5*{liNOgtnEVwjj~vDfGO9$z=^r4w!ME*g^<M6(N-)1oj~IRBHg
zGYY=rZT#h|`ArZ1{>W%y@Oowcg*T))Pm{Fq$fUf<JBNh9{rf&UIc2BQxhLbuTWg<O
zePv8y5X~;ol|D+S&K65VqNgT=)I+wWVJdlK4qYt5k}PnF#9eOCBMWx@`E1>sitJ~0
z-S@#l>&pAJ+HV7+97>|d3DH{0GqiFRnewR`jAp{!HJf}O<``E4Ra492@_b%mDuc*e
zP_Y5TiIZnpRZF3hQzGThmac6t|14!e!Qm_v=ub<uXyLvF4nw&{$nO8~7OP$n(FSlE
zR<kaHKt#o}KKn&`f}`nN`8z+C*4nfncMKAwkP@IMBI`hERZ=o5DN0cl?*q!%TuLmZ
z1cs_$G3kc`W6rrAL@@yZ7*_<+lM&!UjM^^HvZ#y~s>x1)OhuUJ=sN5J!OLPrcPRom
z*=EbMgP8L(n^aYuV#`bcy{<=60C)ggg~eq0&8O}?Klh^J(B6jM{prDLJG4T{5)%eb
z?U-`fq%I+feDw!KSPPOud4XKDqm2gl(K1kTPtcD5%P&!a<f;RuKX7gFV6N5{S)5%d
zmWY~aP~zc|qGgX36Lz=Am@3D~&pKGDkXikVBm)gDHE#aR)kD22AHI=v;@nmL^O`G*
z(UnSEy$zZpQ&`9|T$R#00wU~oYy}mlMrQR?F(p)C3B3Tf!WHyq(ywx-cIQ3Q+qa@S
zHQ1+xb%Bu{MYMX!8X?HFuzXZ0zL<crgeZOV%N2zJPZmX`w|bdcG?V@rrGv|QjaNxg
z&tsG$EGA*G)=9xa#41i<11pfFS{b+=CNi1|9@TU(tr{bfp0sX=40ML=R+e}V=CD9X
z*hxV}uoEMb1KLz2@G?ikEP!2wut0mdVENU|2&!rrOM<dkX&te+{Dp}qK8F#>BL)xE
zKu_U-4-yGuPbJ*a$wqd|WMEsG4H&)z@dma<3%p^mO*XLYg_|FJTD<#i=ix);?Ku<M
z7LOR)PC!9nw&insGN$C0=03h?|GZ0+I*w~$bHPXlPPFEeo%Ty0+%oVwEW%~WG$VZu
z-(ZM`_@>y7DBTu7G$o29f#bP*zC6Y)QKs2|j7vq>z_@5RJ1oYnGcYc(KkwMdk4y8P
z_;}9ohc3I@MvQU$p>JWv^*uV%m)u<Md$#D+q>oly+OLIO3`UWRBXS^evguRn3r;ak
z(HTWJfZ-KNCc^+zjQrV3pJMu7p~Mko7AZay$s%ak5t>08w9#&%wAa<GPqx(bK_^=p
zT5I50v}7L^&u9bB=%suAa{flYr+ISk9$(GvT_eV`g9e^8fAa2|Yur0mb-8=JXZlWc
zXklTDe=g4)<eftaLFEOglg)4urGbl~kFg3|#z^aFfvP9(wf{r6u<1y?H|LQa=t)@;
zDzuU<n5eK@r`OW7LFu&=l^f_4y^RcuUX+1esV(nJ?fhe%yQBUU`yIO;(^mou)EJ>M
zmFGFA4;V5`KxPb2rnQ5|@EGfw#~piM!j4s2?>f`@zN587tH4fLt7$6o;v{3NjAA4=
zFQ_9$)oFuHv!!r;=-jFY&+zSlz}Hdiz~uTW_)`O8I%GML+*$+y^+1*clAxuM7c5-F
zB)fHnrNd4$h%{S<njvx+pXg0q!{>G|ilBvyqm>7J=n9dj*JRr=Ee~}sj@<V`>zB5n
z04%yugir<sL$aW3K%aVP_4|O?t^fH!-P5h^ts8jf%TvGmBU6dMs!L=n{N~4$5Lh4D
THH}{pP0%T)65Gqc@{axs;WaIC

literal 0
HcmV?d00001

diff --git a/mdl/executor/cmd_microflows_builder_notify.go b/mdl/executor/cmd_microflows_builder_notify.go
new file mode 100644
index 0000000000..d059630717
--- /dev/null
+++ b/mdl/executor/cmd_microflows_builder_notify.go
@@ -0,0 +1,174 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/mendixlabs/mxcli/sdk/microflows"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// setNotifyTarget resolves `notify workflow … target Module.Workflow.Name` and
+// stores it the way the project's Mendix version does.
+//
+// The statement names the element, not its kind, and the stored target type
+// depends on the kind (ako/TestApp, Studio Pro 11.14):
+//
+//	interrupting notification start       Workflows$InterruptingNotificationEventSubProcessStartActivityTarget
+//	non-interrupting notification start   Workflows$NonInterruptingNotificationEventSubProcessStartActivityTarget
+//	notification activity                 Workflows$NotifyNotificationActivityTarget
+//	wait for notification                 Workflows$NotifyWaitForNotificationActivityTarget
+//	notification boundary event           Workflows$NotifyNotificationBoundaryEventTarget (key BoundaryEvent)
+//
+// so the element is looked up in the stored workflow. Before Mendix 11.7 the
+// action held the name directly (Activity), and only a wait for notification
+// could be named.
+func (fb *flowBuilder) setNotifyTarget(action *microflows.NotifyWorkflowAction, target string) {
+	i := strings.LastIndex(target, ".")
+	if strings.Count(target, ".") < 2 || i == len(target)-1 {
+		fb.errors = append(fb.errors, fmt.Sprintf(
+			"notify workflow target %q: name the element as Module.Workflow.Name", target))
+		return
+	}
+	if fb.backend != nil {
+		if pv := fb.backend.ProjectVersion(); pv != nil && !pv.IsAtLeast(11, 7) {
+			action.Activity = target
+			return
+		}
+	}
+	wf := fb.findWorkflow(target[:i])
+	if wf == nil {
+		if fb.backend != nil {
+			fb.errors = append(fb.errors, fmt.Sprintf(
+				"workflow not found: %s (referenced by notify workflow target %s)", target[:i], target))
+		}
+		return
+	}
+	name := target[i+1:]
+	typeName, problem, found := notifyTargetType(wf, name)
+	switch {
+	case !found:
+		fb.errors = append(fb.errors, fmt.Sprintf(
+			"notify workflow target %s: workflow %s has no element named %q. A notify reaches %s",
+			target, target[:i], name, notifyTargetCandidates(wf)))
+	case problem != "":
+		fb.errors = append(fb.errors, fmt.Sprintf(
+			"notify workflow target %s is %s — a notify reaches a notification start, a notification activity, "+
+				"a notification boundary event or a wait for notification", target, problem))
+	default:
+		action.Target = &microflows.NotifyTarget{TypeName: typeName, Name: target}
+	}
+}
+
+// findWorkflow returns the stored workflow with this qualified name, nil when
+// there is none or no backend to ask.
+func (fb *flowBuilder) findWorkflow(qualifiedName string) *workflows.Workflow {
+	if fb.backend == nil || fb.hierarchy == nil {
+		return nil
+	}
+	all, err := fb.backend.ListWorkflows()
+	if err != nil {
+		return nil
+	}
+	for _, wf := range all {
+		if fb.hierarchy.GetModuleName(fb.hierarchy.FindModuleID(wf.ContainerID))+"."+wf.Name == qualifiedName {
+			return wf
+		}
+	}
+	return nil
+}
+
+// notifyTargetType returns the stored target type for the element named name.
+// found reports whether any element has that name; problem describes an element
+// a notification cannot reach.
+func notifyTargetType(wf *workflows.Workflow, name string) (typeName, problem string, found bool) {
+	visit := func(acts []workflows.WorkflowActivity) bool { return false }
+	visit = func(acts []workflows.WorkflowActivity) bool {
+		for _, act := range acts {
+			for _, be := range activityBoundaryEvents(act) {
+				if be != nil && be.Name == name {
+					found = true
+					if be.IsNotification() {
+						typeName = microflows.NotifyBoundaryEventTargetType
+					} else {
+						problem = "a timer boundary event"
+					}
+					return true
+				}
+			}
+			if act.GetName() == name {
+				found = true
+				switch a := act.(type) {
+				case *workflows.EventSubProcessStartActivity:
+					switch {
+					case a.Timer:
+						problem = "a timer-started event sub-process's start"
+					case a.Interrupting:
+						typeName = "Workflows$InterruptingNotificationEventSubProcessStartActivityTarget"
+					default:
+						typeName = "Workflows$NonInterruptingNotificationEventSubProcessStartActivityTarget"
+					}
+				case *workflows.NotificationActivity:
+					typeName = "Workflows$NotifyNotificationActivityTarget"
+				case *workflows.WaitForNotificationActivity:
+					typeName = "Workflows$NotifyWaitForNotificationActivityTarget"
+				default:
+					problem = "a " + act.ActivityType() + " activity"
+				}
+				return true
+			}
+			for _, f := range nestedFlows(act) {
+				if visit(f.Activities) {
+					return true
+				}
+			}
+		}
+		return false
+	}
+	if wf.Flow != nil && visit(wf.Flow.Activities) {
+		return typeName, problem, found
+	}
+	for _, esp := range wf.EventSubProcesses {
+		if esp != nil && esp.Flow != nil && visit(esp.Flow.Activities) {
+			return typeName, problem, found
+		}
+	}
+	return "", "", false
+}
+
+// notifyTargetCandidates lists what the workflow offers a notify, for the error.
+func notifyTargetCandidates(wf *workflows.Workflow) string {
+	var names []string
+	collect := func(acts []workflows.WorkflowActivity) {}
+	collect = func(acts []workflows.WorkflowActivity) {
+		for _, act := range acts {
+			if t, problem, _ := notifyTargetType(wf, act.GetName()); t != "" && problem == "" {
+				names = append(names, act.GetName())
+			}
+			for _, be := range activityBoundaryEvents(act) {
+				if be != nil && be.IsNotification() {
+					names = append(names, be.Name)
+				}
+			}
+			for _, f := range nestedFlows(act) {
+				collect(f.Activities)
+			}
+		}
+	}
+	if wf.Flow != nil {
+		collect(wf.Flow.Activities)
+	}
+	for _, esp := range wf.EventSubProcesses {
+		if esp != nil && esp.Flow != nil {
+			collect(esp.Flow.Activities)
+		}
+	}
+	if len(names) == 0 {
+		return "a notification start, notification activity, notification boundary event or wait for notification, and this workflow has none."
+	}
+	sort.Strings(names)
+	return "one of: " + strings.Join(names, ", ") + "."
+}
diff --git a/mdl/executor/cmd_microflows_builder_workflow.go b/mdl/executor/cmd_microflows_builder_workflow.go
index a8d41d4156..b5b32bba49 100644
--- a/mdl/executor/cmd_microflows_builder_workflow.go
+++ b/mdl/executor/cmd_microflows_builder_workflow.go
@@ -189,6 +189,9 @@ func (fb *flowBuilder) addNotifyWorkflowAction(s *ast.NotifyWorkflowStmt) model.
 		OutputVariableName: s.OutputVariable,
 		WorkflowVariable:   s.WorkflowVariable,
 	}
+	if s.Target != "" {
+		fb.setNotifyTarget(action, s.Target)
+	}
 	return fb.wrapAction(action, s.ErrorHandling)
 }
 
diff --git a/mdl/executor/cmd_microflows_format_action.go b/mdl/executor/cmd_microflows_format_action.go
index e5084465d2..744958f7b6 100644
--- a/mdl/executor/cmd_microflows_format_action.go
+++ b/mdl/executor/cmd_microflows_format_action.go
@@ -895,10 +895,18 @@ func formatAction(
 		return fmt.Sprintf("open user task $%s;", a.UserTaskVariable)
 
 	case *microflows.NotifyWorkflowAction:
+		// The target used to be left out, so a rewrite from describe output wrote a
+		// notify the build refuses (CE0166).
+		target := ""
+		if a.Target != nil && a.Target.Name != "" {
+			target = " target " + a.Target.Name
+		} else if a.Activity != "" {
+			target = " target " + a.Activity
+		}
 		if a.OutputVariableName != "" {
-			return fmt.Sprintf("$%s = notify workflow $%s;", a.OutputVariableName, a.WorkflowVariable)
+			return fmt.Sprintf("$%s = notify workflow $%s%s;", a.OutputVariableName, a.WorkflowVariable, target)
 		}
-		return fmt.Sprintf("notify workflow $%s;", a.WorkflowVariable)
+		return fmt.Sprintf("notify workflow $%s%s;", a.WorkflowVariable, target)
 
 	case *microflows.OpenWorkflowAction:
 		return fmt.Sprintf("open workflow $%s;", a.WorkflowVariable)
diff --git a/mdl/executor/microflow_notify_test.go b/mdl/executor/microflow_notify_test.go
new file mode 100644
index 0000000000..1bb244f61b
--- /dev/null
+++ b/mdl/executor/microflow_notify_test.go
@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/mdl/backend/mock"
+	"github.com/mendixlabs/mxcli/mdl/types"
+	"github.com/mendixlabs/mxcli/mdl/visitor"
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/microflows"
+	"github.com/mendixlabs/mxcli/sdk/workflows"
+)
+
+// notifyTestBuilder returns a flow builder whose project holds M.W: every kind of
+// element a notify can and cannot reach, on the given Mendix minor of 11.
+func notifyTestBuilder(minor int) *flowBuilder {
+	base := func(name string) workflows.BaseWorkflowActivity { return workflows.BaseWorkflowActivity{Name: name} }
+	flow := func(acts ...workflows.WorkflowActivity) *workflows.Flow { return &workflows.Flow{Activities: acts} }
+	wf := &workflows.Workflow{
+		Name: "W",
+		Flow: flow(
+			&workflows.NotificationActivity{BaseWorkflowActivity: base("received")},
+			&workflows.WaitForNotificationActivity{BaseWorkflowActivity: base("waitApproval"), BoundaryEvents: []*workflows.BoundaryEvent{
+				{EventType: "InterruptingNotification", Name: "withdrawn"},
+				{EventType: "InterruptingTimer", Name: "timeout"},
+			}},
+			&workflows.UserTask{BaseWorkflowActivity: base("review"), Outcomes: []*workflows.UserTaskOutcome{
+				{Value: "Go", Flow: flow(&workflows.NotificationActivity{BaseWorkflowActivity: base("nestedReceived")})},
+			}},
+		),
+		EventSubProcesses: []*workflows.EventSubProcess{
+			{Name: "ESP_Cancel", Flow: flow(&workflows.EventSubProcessStartActivity{BaseWorkflowActivity: base("cancelStart"), Interrupting: true})},
+			{Name: "ESP_Audit", Flow: flow(&workflows.EventSubProcessStartActivity{BaseWorkflowActivity: base("auditStart")})},
+			{Name: "ESP_Expire", Flow: flow(&workflows.EventSubProcessStartActivity{BaseWorkflowActivity: base("expireStart"), Interrupting: true, Timer: true})},
+		},
+	}
+	wf.ContainerID = "mod1"
+	mb := &mock.MockBackend{
+		ListWorkflowsFunc:  func() ([]*workflows.Workflow, error) { return []*workflows.Workflow{wf}, nil },
+		ProjectVersionFunc: func() *types.ProjectVersion { return &types.ProjectVersion{MajorVersion: 11, MinorVersion: minor} },
+	}
+	h := &ContainerHierarchy{moduleIDs: map[model.ID]bool{"mod1": true}, moduleNames: map[model.ID]string{"mod1": "M"}}
+	return &flowBuilder{backend: mb, hierarchy: h}
+}
+
+// The statement names an element; the stored target type follows from what the
+// element is (ako/TestApp, Studio Pro 11.14), at any depth and in sub-processes.
+// An element no notification reaches is refused, naming what it is.
+func TestNotifyTarget_ResolvesEachKind(t *testing.T) {
+	cases := []struct {
+		target, wantType, wantError string
+	}{
+		{"M.W.received", "Workflows$NotifyNotificationActivityTarget", ""},
+		{"M.W.nestedReceived", "Workflows$NotifyNotificationActivityTarget", ""},
+		{"M.W.waitApproval", "Workflows$NotifyWaitForNotificationActivityTarget", ""},
+		{"M.W.withdrawn", "Workflows$NotifyNotificationBoundaryEventTarget", ""},
+		{"M.W.cancelStart", "Workflows$InterruptingNotificationEventSubProcessStartActivityTarget", ""},
+		{"M.W.auditStart", "Workflows$NonInterruptingNotificationEventSubProcessStartActivityTarget", ""},
+		{"M.W.expireStart", "", "timer-started"},
+		{"M.W.timeout", "", "timer boundary event"},
+		{"M.W.review", "", "UserTask"},
+		{"M.W.nothing", "", "no element named"},
+		{"M.Other.received", "", "workflow not found"},
+		{"M.W", "", "Module.Workflow.Name"},
+	}
+	for _, c := range cases {
+		t.Run(c.target, func(t *testing.T) {
+			fb := notifyTestBuilder(14)
+			action := &microflows.NotifyWorkflowAction{WorkflowVariable: "Workflow"}
+			fb.setNotifyTarget(action, c.target)
+			errs := strings.Join(fb.errors, "\n")
+			if c.wantError != "" {
+				if !strings.Contains(errs, c.wantError) || action.Target != nil {
+					t.Errorf("want an error containing %q and no target, got %q / %+v", c.wantError, errs, action.Target)
+				}
+				return
+			}
+			if errs != "" || action.Target == nil || action.Target.TypeName != c.wantType || action.Target.Name != c.target {
+				t.Errorf("target = %+v, errors %q; want %s %s", action.Target, errs, c.wantType, c.target)
+			}
+		})
+	}
+
+	fb := notifyTestBuilder(14)
+	fb.setNotifyTarget(&microflows.NotifyWorkflowAction{}, "M.W.nothing")
+	for _, name := range []string{"auditStart", "cancelStart", "received", "waitApproval", "withdrawn"} {
+		if !strings.Contains(strings.Join(fb.errors, ""), name) {
+			t.Errorf("the unknown-name error does not list %s: %v", name, fb.errors)
+		}
+	}
+}
+
+// Before Mendix 11.7 the action names its wait for notification directly
+// (Activity); there is no NotifyTarget to write.
+func TestNotifyTarget_BeforeElevenSevenIsTheActivity(t *testing.T) {
+	fb := notifyTestBuilder(6)
+	action := &microflows.NotifyWorkflowAction{}
+	fb.setNotifyTarget(action, "M.W.waitApproval")
+	if action.Activity != "M.W.waitApproval" || action.Target != nil || len(fb.errors) != 0 {
+		t.Errorf("11.6 notify = %+v, errors %v", action, fb.errors)
+	}
+}
+
+// MDL-WF16, measured on the 11.6, 11.10 and 11.13 mxbuilds: a notify with no
+// target fails the build (CE0166). Refused at check without a project, and by
+// exec, which enforces the rule.
+func TestNotifyWorkflow_MDLWF16(t *testing.T) {
+	parse := func(body string) *ast.CreateMicroflowStmt {
+		prog, errs := visitor.Build("create microflow M.N ($Workflow: System.Workflow)\nbegin\n" + body + "\nend;")
+		if len(errs) > 0 {
+			t.Fatalf("parse errors: %v", errs)
+		}
+		return prog.Statements[0].(*ast.CreateMicroflowStmt)
+	}
+	cases := []struct {
+		body string
+		want string // the MDL-WF16 message expected; "" = no violation
+	}{
+		{"notify workflow $Workflow;", "names no target"},
+		{"notify workflow $Workflow target M.W;", "must name the element inside its workflow"},
+		{"$Notified = notify workflow $Workflow target M.W.received;", ""},
+	}
+	for _, c := range cases {
+		stmt := parse(c.body)
+		var msgs []string
+		for _, v := range ValidateMicroflow(stmt) {
+			if v.RuleID == "MDL-WF16" {
+				msgs = append(msgs, v.Message)
+			}
+		}
+		got := strings.Join(msgs, "\n")
+		if c.want == "" && got != "" || c.want != "" && (len(msgs) != 1 || !strings.Contains(got, c.want)) {
+			t.Errorf("%s: MDL-WF16 = %q, want one violation containing %q", c.body, got, c.want)
+		}
+		err := validateMicroflowRules(stmt)
+		if refused := err != nil && strings.Contains(err.Error(), "MDL-WF16"); refused != (c.want != "") {
+			t.Errorf("%s: exec refusal = %v, want refused=%v", c.body, err, c.want != "")
+		}
+	}
+}
+
+// Describe emits the target, so a rewrite from describe output keeps it; it used
+// to print a bare `notify workflow $W;`, which the build refuses.
+func TestNotifyWorkflow_DescribeRoundTripsTarget(t *testing.T) {
+	for _, action := range []*microflows.NotifyWorkflowAction{
+		{WorkflowVariable: "Workflow", OutputVariableName: "Notified",
+			Target: &microflows.NotifyTarget{TypeName: "Workflows$NotifyNotificationBoundaryEventTarget", Name: "M.W.withdrawn"}},
+		{WorkflowVariable: "Workflow", Activity: "M.W.waitApproval"},
+	} {
+		line := formatAction(nil, action, nil, nil)
+		prog, errs := visitor.Build("create microflow M.N ($Workflow: System.Workflow)\nbegin\n" + line + "\nend;")
+		if len(errs) > 0 {
+			t.Fatalf("%q does not parse: %v", line, errs)
+		}
+		stmt := prog.Statements[0].(*ast.CreateMicroflowStmt).Body[0].(*ast.NotifyWorkflowStmt)
+		want := action.Activity
+		if action.Target != nil {
+			want = action.Target.Name
+		}
+		if stmt.Target != want || stmt.OutputVariable != action.OutputVariableName {
+			t.Errorf("%q re-parsed as %+v, want target %s", line, *stmt, want)
+		}
+	}
+}
diff --git a/mdl/executor/validate.go b/mdl/executor/validate.go
index 35ee9fee38..0dcf5f50c7 100644
--- a/mdl/executor/validate.go
+++ b/mdl/executor/validate.go
@@ -1289,6 +1289,9 @@ var execEnforcedMicroflowRules = map[string]bool{
 	// otherwise `check` catches the typo and the write that follows does not.
 	"MDL059": true,
 	"MDL060": true,
+	// MDL-WF16: a notify workflow with no target is CE0166 at build time,
+	// measured on the 11.6, 11.10 and 11.13 mxbuilds.
+	"MDL-WF16": true,
 }
 
 // validateMicroflowRules runs the MDL0xx microflow rule set (ValidateMicroflow)
diff --git a/mdl/executor/validate_microflow.go b/mdl/executor/validate_microflow.go
index 17d5073b06..f9e4f1e49f 100644
--- a/mdl/executor/validate_microflow.go
+++ b/mdl/executor/validate_microflow.go
@@ -199,6 +199,22 @@ func (v *microflowValidator) walkBody(body []ast.MicroflowStatement) {
 		v.checkErrorHandlingContinueSupported(s)
 		v.checkErrorHandlingSupported(s)
 		switch stmt := s.(type) {
+		case *ast.NotifyWorkflowStmt:
+			// MDL-WF16. A notify reaches one named element of the workflow, and the
+			// build refuses one that names none: CE0166 "The 'Target' property is
+			// required" on the 11.10 and 11.13 mxbuilds ("'Activity'" on 11.6). The
+			// target used to be neither writable nor described, so every notify
+			// mxcli wrote failed the build.
+			switch {
+			case stmt.Target == "":
+				v.addViolation("MDL-WF16", linter.SeverityError,
+					fmt.Sprintf("notify workflow $%s names no target — Mendix needs the element it notifies; the build fails CE0166", stmt.WorkflowVariable),
+					"Add `target Module.Workflow.Name`, naming a notification start, notification activity, notification boundary event or wait for notification.")
+			case strings.Count(stmt.Target, ".") < 2:
+				v.addViolation("MDL-WF16", linter.SeverityError,
+					fmt.Sprintf("notify workflow target %q must name the element inside its workflow", stmt.Target),
+					"Write the target as Module.Workflow.Name.")
+			}
 		case *ast.ValidationFeedbackStmt:
 			if isEmptyMessage(stmt.Message) {
 				v.addViolation("MDL007", linter.SeverityWarning,
diff --git a/mdl/grammar/MDLLexer.g4 b/mdl/grammar/MDLLexer.g4
index eef3a51618..02d8b4c270 100644
--- a/mdl/grammar/MDLLexer.g4
+++ b/mdl/grammar/MDLLexer.g4
@@ -754,6 +754,7 @@ SPLIT: S P L I T;
 OUTCOME: O U T C O M E;
 OUTCOMES: O U T C O M E S;
 TARGETING: T A R G E T I N G;
+TARGET: T A R G E T;
 NOTIFICATION: N O T I F I C A T I O N;
 TIMER: T I M E R;
 JUMP: J U M P;
diff --git a/mdl/grammar/domains/MDLMicroflow.g4 b/mdl/grammar/domains/MDLMicroflow.g4
index fb23b46c4a..03982170b4 100644
--- a/mdl/grammar/domains/MDLMicroflow.g4
+++ b/mdl/grammar/domains/MDLMicroflow.g4
@@ -588,9 +588,12 @@ openUserTaskStatement
     : OPEN USER TASK VARIABLE onErrorClause?
     ;
 
-// NOTIFY WORKFLOW $Wf;
+// [$Notified =] NOTIFY WORKFLOW $Wf TARGET Module.Workflow.Name;
+// The target names the notification start, notification activity, notification
+// boundary event or wait-for-notification the action reaches. It is optional here
+// and required by check (MDL-WF16): Mendix refuses a notify with none (CE0166).
 notifyWorkflowStatement
-    : (VARIABLE EQUALS)? NOTIFY WORKFLOW VARIABLE onErrorClause?
+    : (VARIABLE EQUALS)? NOTIFY WORKFLOW VARIABLE (TARGET qualifiedName)? onErrorClause?
     ;
 
 // OPEN WORKFLOW $Wf;
diff --git a/mdl/grammar/domains/MDLSettings.g4 b/mdl/grammar/domains/MDLSettings.g4
index aebba76f3d..db1e8aa1a6 100644
--- a/mdl/grammar/domains/MDLSettings.g4
+++ b/mdl/grammar/domains/MDLSettings.g4
@@ -697,7 +697,7 @@ keyword
     | CONDITION | DATE | DECISION | DUE | GROUPS | INTERRUPTING | JUMP
     | LOCK | MULTI | NODE | NON | NOTIFICATION | NOTIFY
     | OPEN | OUTCOME | OUTCOMES | OVERVIEW | PARALLEL | PAUSE
-    | REASON | RESTART | RETRY | SPLIT | SUBPROCESS | TARGETING | TASK | TIMER
+    | REASON | RESTART | RETRY | SPLIT | SUBPROCESS | TARGET | TARGETING | TASK | TIMER
     | UNLOCK | UNPAUSE | WAIT | WORKFLOW | WORKFLOWS
 
     // Business events / settings
diff --git a/mdl/visitor/visitor_microflow_workflow.go b/mdl/visitor/visitor_microflow_workflow.go
index 79be79e5fa..00b291954f 100644
--- a/mdl/visitor/visitor_microflow_workflow.go
+++ b/mdl/visitor/visitor_microflow_workflow.go
@@ -197,6 +197,9 @@ func buildNotifyWorkflowStatement(ctx parser.INotifyWorkflowStatementContext) *a
 	} else if len(vars) >= 1 {
 		stmt.WorkflowVariable = strings.TrimPrefix(vars[0].GetText(), "$")
 	}
+	if qn := c.QualifiedName(); qn != nil {
+		stmt.Target = getQualifiedNameText(qn)
+	}
 	if errClause := c.OnErrorClause(); errClause != nil {
 		stmt.ErrorHandling = buildOnErrorClause(errClause)
 	}
diff --git a/mdl/visitor/visitor_notify_test.go b/mdl/visitor/visitor_notify_test.go
new file mode 100644
index 0000000000..736dfc4adf
--- /dev/null
+++ b/mdl/visitor/visitor_notify_test.go
@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package visitor
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+)
+
+// `target` takes the element's three-part name; without the clause the target is
+// empty (and MDL-WF16 refuses it at check).
+func TestNotifyWorkflowStatement_Target(t *testing.T) {
+	prog, errs := Build(`create microflow M.Notify ($Workflow: System.Workflow)
+begin
+  $Notified = notify workflow $Workflow target HR.Leave.espCancelStart;
+  notify workflow $Workflow target HR."Leave".withdrawn;
+  notify workflow $Workflow;
+end;`)
+	if len(errs) > 0 {
+		t.Fatalf("parse errors: %v", errs)
+	}
+	mf := prog.Statements[0].(*ast.CreateMicroflowStmt)
+	want := []ast.NotifyWorkflowStmt{
+		{OutputVariable: "Notified", WorkflowVariable: "Workflow", Target: "HR.Leave.espCancelStart"},
+		{WorkflowVariable: "Workflow", Target: "HR.Leave.withdrawn"},
+		{WorkflowVariable: "Workflow"},
+	}
+	if len(mf.Body) != len(want) {
+		t.Fatalf("body has %d statements, want %d", len(mf.Body), len(want))
+	}
+	for i, w := range want {
+		got, ok := mf.Body[i].(*ast.NotifyWorkflowStmt)
+		if !ok {
+			t.Fatalf("statement %d is %T", i, mf.Body[i])
+		}
+		if got.OutputVariable != w.OutputVariable || got.WorkflowVariable != w.WorkflowVariable || got.Target != w.Target {
+			t.Errorf("statement %d = %+v, want %+v", i, *got, w)
+		}
+	}
+}
diff --git a/modelsdk/gen/microflows/types.go b/modelsdk/gen/microflows/types.go
index 7a41915bf4..6da0160443 100644
--- a/modelsdk/gen/microflows/types.go
+++ b/modelsdk/gen/microflows/types.go
@@ -15495,7 +15495,13 @@ func initNotifyWorkflowAction() *NotifyWorkflowAction {
 	o.activity.Bind(&o.Base, 2)
 	o.notifyTarget = property.NewPart[element.Element]("NotifyTarget")
 	o.notifyTarget.Bind(&o.Base, 3)
-	o.outputVariableName = property.NewPrimitive[string]("VariableName", property.DecodeString)
+	// STORAGE-NAME OVERRIDE: BSON key is "OutputVariableName", not "VariableName"
+	// (generated/metamodel tags it `json:"outputVariableName"`, and ako/TestApp's
+	// Studio Pro 11.14 notify actions store "OutputVariableName"). Measured on the
+	// 11.6, 11.10 and 11.13 mxbuilds: under "VariableName" the output variable is
+	// undefined (CE0109). A Primitive uses its bound name for both decode and
+	// encode, so this one literal covers InitFromRaw too.
+	o.outputVariableName = property.NewPrimitive[string]("OutputVariableName", property.DecodeString)
 	o.outputVariableName.Bind(&o.Base, 4)
 	o.SetProperties([]element.Property{o.errorHandlingType, o.workflowVariable, o.activity, o.notifyTarget, o.outputVariableName})
 	return o
diff --git a/sdk/microflows/microflows_actions.go b/sdk/microflows/microflows_actions.go
index fa8a82eb52..d2e77b44d5 100644
--- a/sdk/microflows/microflows_actions.go
+++ b/sdk/microflows/microflows_actions.go
@@ -1301,10 +1301,36 @@ type NotifyWorkflowAction struct {
 	ErrorHandlingType  ErrorHandlingType `json:"errorHandlingType,omitempty"`
 	OutputVariableName string            `json:"outputVariableName,omitempty"`
 	WorkflowVariable   string            `json:"workflowVariable,omitempty"`
+	// Target is what the action notifies, Mendix 11.7+. nil when none is stored —
+	// which the build refuses (CE0166).
+	Target *NotifyTarget `json:"target,omitempty"`
+	// Activity is the target before Mendix 11.7: a wait-for-notification activity
+	// by qualified name (Module.Workflow.Name).
+	Activity string `json:"activity,omitempty"`
 }
 
 func (NotifyWorkflowAction) isMicroflowAction() {}
 
+// NotifyTarget is a notify action's NotifyTarget: the workflow element it reaches.
+type NotifyTarget struct {
+	// TypeName is the stored $Type, e.g. "Workflows$NotifyNotificationActivityTarget".
+	TypeName string `json:"typeName"`
+	// Name is the element's qualified name, Module.Workflow.ElementName.
+	Name string `json:"name"`
+}
+
+// NotifyBoundaryEventTargetType is the one target type that names its element
+// under BoundaryEvent rather than Activity.
+const NotifyBoundaryEventTargetType = "Workflows$NotifyNotificationBoundaryEventTarget"
+
+// Key returns the stored key that holds the element's name.
+func (t *NotifyTarget) Key() string {
+	if t.TypeName == NotifyBoundaryEventTargetType {
+		return "BoundaryEvent"
+	}
+	return "Activity"
+}
+
 // OpenWorkflowAction opens the workflow admin page.
 type OpenWorkflowAction struct {
 	model.BaseElement
diff --git a/sdk/versions/mendix-11.yaml b/sdk/versions/mendix-11.yaml
index bc34dbf73b..2c2a4c7b65 100644
--- a/sdk/versions/mendix-11.yaml
+++ b/sdk/versions/mendix-11.yaml
@@ -200,6 +200,10 @@ features:
       min_version: "11.11.0"
       mdl: "NOTIFICATION Received; … BOUNDARY EVENT INTERRUPTING NOTIFICATION Withdrawn { … }"
       notes: "Workflows$NotificationActivity and (Non)InterruptingNotificationBoundaryEvent: TypeCacheUnknownTypeException on the 11.10 mxbuild, load on 11.11, 11.12 and 11.13."
+    notify_target:
+      min_version: "11.7.0"
+      mdl: "$Notified = NOTIFY WORKFLOW $Workflow TARGET Module.Workflow.espCancelStart;"
+      notes: "NotifyWorkflowAction.notifyTarget introduced in 11.7.0 (modelsdk gen), replacing Activity. Not a refusal: before 11.7 mxcli writes the Activity form. A notify with no target is CE0166 on 11.6, 11.10 and 11.13."
 
   navigation:
     profiles:

From 692bafa3362d68490b00036a73b8763f5de46a5d Mon Sep 17 00:00:00 2001
From: Ako <andrej@koelewijn.net>
Date: Tue, 15 Sep 2026 15:00:41 +0000
Subject: [PATCH 24/24] fix(workflow): resolve ALTER WORKFLOW activity refs by
 name before caption

Every ALTER WORKFLOW op failed with `ambiguous activity "X" (2 matches)`
whenever the workflow contained `jump to X`. buildJumpTo defaults a jump's
caption to its target's name, and both activity resolvers (MCP
mcpWorkflowMutator.searchActivities, MPR wfmutator) matched name OR caption
into one pool, so the jump's caption shadowed the target. Measured live over
MCP against Studio Pro 11.14.

Resolve in two tiers in both backends: name matches win; captions are
consulted only when no activity carries that name. Ambiguity and @N are
judged within the chosen tier, in the same DESCRIBE traversal order.

The jump's default caption is left unchanged: existing projects already
carry that shape, and changing it would rewrite every mxcli-authored jump on
the next re-run.

Tests in both backends fail with the reported message against the pooled
resolver (control) and pass with the fix.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../fix-issue/findings/mdl-backend.jsonl      |  1 +
 mdl/backend/mcp/workflow.go                   | 36 ++++++++----
 mdl/backend/mcp/workflow_test.go              | 55 +++++++++++++++++++
 mdl/backend/wfmutator/mutator.go              | 54 ++++++++++++------
 mdl/backend/wfmutator/mutator_test.go         | 30 ++++++++++
 5 files changed, 149 insertions(+), 27 deletions(-)

diff --git a/.claude/skills/fix-issue/findings/mdl-backend.jsonl b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
index 2f7b97177b..ee9ecbcb90 100644
--- a/.claude/skills/fix-issue/findings/mdl-backend.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-backend.jsonl
@@ -105,3 +105,4 @@
 {"area":"mdl/backend","date":"2026-09-15","symptom":"Six FullBackend methods sat on the unreachable census being treated as abstraction bypasses awaiting a port, when nothing anywhere wanted them: the whole WidgetSerializationBackend interface (SerializeWidget/ClientAction/DataSource/WorkflowActivity), GetUnitTypes and UpdateLayout. They had been superseded and simply never removed.","cause":"scripts/backend-reachability.sh reports DEAD for 'nothing calls this through a backend value', and that one verdict covers three different situations. The census header read all of them as bypasses, so the standing instruction was to port them — which for these would have meant implementing methods with no caller.","file":"mdl/backend/mutation.go","fix":"Deleted WidgetSerializationBackend, GetUnitTypes and UpdateLayout from the interface; regenerated unimplemented_gen.go and mcp/unsupported_gen.go (276 -> 270 methods); dropped the mock stubs and a duplicate *Backend impl. Census 11 -> 6, and the remaining six are genuine bypasses. Rewrote the census header and the probe script's own header to name the three causes.","insight":"A reachability probe that removes a method and rebuilds answers ONE question — is anything calling this through the interface — and DEAD has three causes wanting opposite fixes: BYPASS (a caller wants it but holds a concrete type; port the caller), ORPHAN (no caller anywhere; delete), DUPLICATE (callers exist but through a narrower package-local interface with a DIFFERENT SIGNATURE; delete). The probe cannot separate them; a grep for callers under any type can. DUPLICATE is the one that misleads, and it is worth knowing its two tells. First, a raw call-site count looks healthy — SerializeWidget had 6 and SerializeClientAction 4 — so the name reads as live; only comparing signatures shows the interface copy is unused (bson.D on the real path vs (any, error) on FullBackend). Second, the supersession is usually DOCUMENTED at the replacement, not at the corpse: WidgetBuilderBackend.SerializeWidgetToOpaque says 'This replaces the direct mpr.SerializeWidget call' — so grepping the NEW method's doc comment finds the old one faster than auditing the old one does. A stale comment on the dead method actively lies (the vestigial *Backend SerializeWorkflowActivity claimed the ALTER WORKFLOW paths used it; they use codecWorkflowDeps). Generalisable: when a helper has both an (any, error) and a concrete-typed variant, suspect the general-typed one is the abandoned interface obligation."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"Backend.CreateEntity and CreateAssociation left the caller's semantic element holding an EMPTY ID, so the very next call failed with \"entity not found: \" (note the blank). The legacy writer had populated them, so this was a silent behaviour difference across the engine swap that no test caught.","cause":"assignEntityIDs/assignAssociationIDs mint identities on the gen element built by entityToGen/assocToGen, and nothing copied them back to the *domainmodel.Entity the caller passed in. assignID only fills an EMPTY id, so api/ was unaffected (its builders pre-assign one) — which is exactly why no existing test saw it.","file":"mdl/backend/modelsdk/domainmodel_write.go","fix":"copyAssignedIDs writes the minted entity and attribute ids back onto the caller's element, matching attributes BY NAME rather than by position; CreateAssociation does the same for its own id. Both only fill an empty id, so a caller-assigned one is preserved.","insight":"Found by RUNNING examples/modify_project after repointing it, not by any test — the unit suite, check-mdl and the whole integration gate were green. That is the argument for keeping example programs runnable and actually running them: an example is the only caller that uses the API the way an outside user would, with no pre-assigned ids and no knowledge of internals. Two specifics worth carrying. (1) The empty-string ID makes the error message read \"entity not found: \" with nothing after the colon — a trailing-blank in an error is a strong tell that an identity was never populated rather than looked up and missed. (2) When copying minted ids back, match sub-elements BY NAME, never by index: entityToGen can add, skip or reorder (an audit pseudo-type becomes a System-module generalization, not an attribute), so an index-based copy hands the caller ANOTHER attribute's identity — which looks like it worked and is worse than the empty id it replaced. The control matters here too: a test that only asserts 'id is non-empty' passes against an implementation that overwrites a caller-assigned id, which would break api/; assert the reported id equals the STORED one, and add a companion test that a pre-assigned id survives."}
 {"area":"mdl/backend","date":"2026-09-15","symptom":"Moving cmd/mxcli/project_tree.go from a concrete sdk/mpr reader to the codec backend silently dropped System.VerifyPassword from `mxcli project-tree` output. Build clean, all tests green, 131 bytes missing from a 78KB JSON tree.","cause":"The System module's Java actions are platform built-ins with NO stored unit in the .mpr. sdk/mpr's ListJavaActions/ListJavaActionsFull appended them via BuildSystemJavaActions(); the codec backend only decoded stored units, so it reported them as absent.","file":"mdl/backend/modelsdk/java.go","fix":"Moved the System Java action definitions from sdk/mpr to modelsdk/meta (which already owns the virtual System module's entities and associations) and appended them in both codec ListJavaActions and ListJavaActionsFull; sdk/mpr now delegates rather than holding a second copy. Regression tests plus a control that the STORED actions are still returned.","insight":"Found by diffing the command's output against a binary built from the pre-port commit — not by any test, and no test would have caught it. That baseline-diff is the technique worth keeping for any reader swap: build the old binary first (git stash -u; make build; cp bin/mxcli /tmp/before), then require byte-identical output on every command whose reader you touched. A 131-byte difference in 78KB of JSON is invisible to eyeballing and to 'it still runs'. Two structural lessons. (1) A SYNTHESIZED element is the thing a reader swap loses, because it exists in one reader's code rather than in the data — grep the old reader for 'not stored in' / 'virtual' / 'Build*' helpers before trusting a port. (2) The census in unimplemented_reachability_test.go CANNOT catch this class of bypass: it only lists methods with no implementation, so a caller holding a concrete reader while calling only IMPLEMENTED methods is invisible to it. project_tree.go called 36 semantic methods, every one on FullBackend, and never appeared — which is also why the Phase 3 write-up wrongly described all remaining bypasses as raw-unit debugging tools. The complete list of bypasses is the sdk/mpr IMPORTER list, not the census."}
+{"area": "mdl/backend", "date": "2026-09-15", "symptom": "Every ALTER WORKFLOW op addressing an activity (e.g. `insert boundary event on bugSplitJump …`) failed with `ambiguous activity \"bugSplitJump\" (2 matches); use @N to disambiguate` whenever the workflow also contained `jump to bugSplitJump`. Measured live over MCP against Studio Pro 11.14; `bugSplitJump@1` worked.", "cause": "buildJumpTo (mdl/executor/cmd_workflows_write.go) names every jump `JumpTo` and, with no MDL caption, sets Caption = the target's name. Both activity resolvers — mcpWorkflowMutator.searchActivities and wfmutator's findActivitiesRecursive/findActivityIndexRecursive — matched `name == ref || caption == ref` into ONE pool, so the jump's caption shadowed its target's name. Same defect in the MPR mutator, it was only reported over MCP.", "file": "mdl/backend/mcp/workflow.go", "fix": "Resolve in two tiers in both backends: collect name matches and caption matches separately in the same walk, use the name tier when non-empty, else the caption tier; ambiguity and @N are judged within the chosen tier. The jump's default caption was left alone — existing projects already carry that shape, and changing it would rewrite every mxcli-authored jump on the next re-run.", "insight": "A reference that can match either an identity (name, deduplicated) or a label (caption, free text) must rank them, never pool them — any label that happens to repeat an identity turns a unique name ambiguous, and mxcli's own defaults manufacture exactly that collision. The tell is `N matches` where N counts a jump/marker you did not think of as a candidate. When fixing a resolver, grep for its twin in the other backend (wfmutator vs mcp): the two were written to agree on @N numbering and had the same bug. Controls: both new tests fail with the reported message against the pooled resolver."}
diff --git a/mdl/backend/mcp/workflow.go b/mdl/backend/mcp/workflow.go
index 76d22330d7..c0ad325563 100644
--- a/mdl/backend/mcp/workflow.go
+++ b/mdl/backend/mcp/workflow.go
@@ -1272,12 +1272,22 @@ type wfLocation struct {
 // resolve finds an activity reference (caption or name, optional 1-based @position)
 // anywhere in the flow tree and returns its location plus the workflow's
 // activity-name set.
+//
+// A name match wins over a caption match: captions are consulted only when no
+// activity is named ref. A name is an activity's identity; a caption is a label
+// that may repeat another activity's name — buildJumpTo defaults a jump's
+// caption to its target — so pooling the two made every jump target ambiguous.
+// @N counts within the tier that was chosen. wfmutator resolves the same way.
 func (m *mcpWorkflowMutator) resolve(ref string, atPos int) (wfLocation, error) {
-	var matches []activityRefMatch
+	var byName, byCaption []activityRefMatch
 	taken := map[string]bool{}
-	if err := m.searchActivities("/flow/activities", ref, &matches, taken); err != nil {
+	if err := m.searchActivities("/flow/activities", ref, &byName, &byCaption, taken); err != nil {
 		return wfLocation{}, err
 	}
+	matches := byName
+	if len(matches) == 0 {
+		matches = byCaption
+	}
 	var pick activityRefMatch
 	switch {
 	case len(matches) == 0:
@@ -1303,27 +1313,33 @@ func (m *mcpWorkflowMutator) resolve(ref string, atPos int) (wfLocation, error)
 
 // searchActivities walks an activities array and every descendant sub-flow
 // (each activity's outcome flows, then its boundary-event flows, in order),
-// appending every activity whose name or caption equals ref and recording every
-// activity name it passes in taken. The depth-first, in-order traversal matches
-// DESCRIBE, so @N numbering lines up.
+// appending every activity whose name equals ref to byName, every other one
+// whose caption does to byCaption, and recording every activity name it passes
+// in taken. The depth-first, in-order traversal matches DESCRIBE, so @N
+// numbering lines up.
 //
 // Name collection rides along on the search rather than being its own pass
 // because each level costs a PED round-trip; the two consumers always want both.
-func (m *mcpWorkflowMutator) searchActivities(arrayPath, ref string, matches *[]activityRefMatch, taken map[string]bool) error {
+func (m *mcpWorkflowMutator) searchActivities(arrayPath, ref string, byName, byCaption *[]activityRefMatch, taken map[string]bool) error {
 	acts, err := m.readArrayRaw(arrayPath)
 	if err != nil {
 		return err
 	}
 	for i, a := range acts {
-		if name := mapString(a, "name"); name != "" {
+		name := mapString(a, "name")
+		if name != "" {
 			taken[name] = true
 		}
-		if mapString(a, "name") == ref || mapString(a, "caption") == ref {
-			*matches = append(*matches, activityRefMatch{arrayPath: arrayPath, index: i, name: mapString(a, "name")})
+		match := activityRefMatch{arrayPath: arrayPath, index: i, name: name}
+		switch {
+		case name == ref:
+			*byName = append(*byName, match)
+		case mapString(a, "caption") == ref:
+			*byCaption = append(*byCaption, match)
 		}
 		actPath := fmt.Sprintf("%s/%d", arrayPath, i)
 		for _, sub := range m.subFlowArrays(actPath, mapString(a, "$Type")) {
-			if err := m.searchActivities(sub, ref, matches, taken); err != nil {
+			if err := m.searchActivities(sub, ref, byName, byCaption, taken); err != nil {
 				return err
 			}
 		}
diff --git a/mdl/backend/mcp/workflow_test.go b/mdl/backend/mcp/workflow_test.go
index f11552b7fa..bf4250f965 100644
--- a/mdl/backend/mcp/workflow_test.go
+++ b/mdl/backend/mcp/workflow_test.go
@@ -350,6 +350,61 @@ func wfMutatorFake(t *testing.T) (*fakePED, *mcpWorkflowMutator) {
 	return f, &mcpWorkflowMutator{backend: b, moduleName: "M", workflowName: "WF"}
 }
 
+// jumpShadowFake scripts a flow holding an activity and a jump back to it. The
+// jump carries the shape buildJumpTo writes when the MDL gives no caption:
+// name "JumpTo", caption = the target's name.
+func jumpShadowFake(t *testing.T) (*fakePED, *mcpWorkflowMutator) {
+	t.Helper()
+	acts := `[{"$Type":"Workflows$SingleUserTaskActivity","name":"bugSplitJump","caption":"Split the jump"},
+		{"$Type":"Workflows$CallMicroflowTask","name":"Other","caption":"Twin"},
+		{"$Type":"Workflows$CallMicroflowTask","name":"Other2","caption":"Twin"},
+		{"$Type":"Workflows$JumpToActivity","name":"JumpTo","caption":"bugSplitJump","targetActivity":"bugSplitJump"}]`
+	f := newFakePED(t, func(name string, args map[string]any) (string, bool) {
+		if name == "ped_check_errors" {
+			return "No errors found.", false
+		}
+		if name != "ped_read_document" {
+			return "SUCCESS", false
+		}
+		paths, _ := args["paths"].([]any)
+		p, _ := paths[0].(string)
+		v := "null"
+		if p == "/flow/activities" {
+			v = acts
+		}
+		return fmt.Sprintf(`{"results":[{"path":%q,"result":%s}]}`, p, v), false
+	})
+	b := &Backend{client: f.connectClient(t)}
+	return f, &mcpWorkflowMutator{backend: b, moduleName: "M", workflowName: "WF"}
+}
+
+// Measured live on Studio Pro 11.14: `insert boundary event on bugSplitJump`
+// failed with `ambiguous activity "bugSplitJump" (2 matches)` because the jump's
+// caption matched the reference as well as the target's name.
+func TestWFResolve_NameBeatsJumpCaption(t *testing.T) {
+	f, m := jumpShadowFake(t)
+	if err := m.InsertBoundaryEvent("bugSplitJump", 0, "NonInterruptingTimer", "addHours([%CurrentDateTime%], 1)", nil); err != nil {
+		t.Fatal(err)
+	}
+	if ops := wfUpdateOps(t, f); !strings.Contains(ops, `"path":"/flow/activities/0/boundaryEvents"`) {
+		t.Errorf("boundary event not added to the named activity: %s", ops)
+	}
+
+	// Captions still resolve when no name matches ...
+	_, m2 := jumpShadowFake(t)
+	loc, err := m2.resolve("Split the jump", 0)
+	if err != nil || loc.index != 0 {
+		t.Errorf("caption fallback: index %d, err %v", loc.index, err)
+	}
+	// ... and two caption-only matches are still ambiguous, addressable by @N.
+	if _, err := m2.resolve("Twin", 0); err == nil || !strings.Contains(err.Error(), "ambiguous") {
+		t.Errorf("two caption matches should be ambiguous, got %v", err)
+	}
+	if loc, err := m2.resolve("Twin", 2); err != nil || loc.index != 2 {
+		t.Errorf("Twin@2: index %d, err %v", loc.index, err)
+	}
+}
+
 func wfUpdateOps(t *testing.T, f *fakePED) string {
 	t.Helper()
 	call, ok := f.callByName("ped_update_document")
diff --git a/mdl/backend/wfmutator/mutator.go b/mdl/backend/wfmutator/mutator.go
index e70dce45fb..4f69b6126b 100644
--- a/mdl/backend/wfmutator/mutator.go
+++ b/mdl/backend/wfmutator/mutator.go
@@ -614,8 +614,9 @@ func (m *Mutator) findActivityByCaption(caption string, atPosition int) (bson.D,
 		return nil, fmt.Errorf("workflow has no Flow")
 	}
 
-	var matches []bson.D
-	findActivitiesRecursive(flow, caption, &matches)
+	var byName, byCaption []bson.D
+	findActivitiesRecursive(flow, caption, &byName, &byCaption)
+	matches := preferNameMatches(byName, byCaption)
 
 	if len(matches) == 0 {
 		return nil, fmt.Errorf("activity %q not found", caption)
@@ -638,21 +639,37 @@ func (m *Mutator) findActivityByCaption(caption string, atPosition int) (bson.D,
 	return matches[atPosition-1], nil
 }
 
-// findActivitiesRecursive collects all activities matching caption in a flow and nested sub-flows.
-func findActivitiesRecursive(flow bson.D, caption string, matches *[]bson.D) {
+// preferNameMatches picks the tier an activity reference resolves against: the
+// activities whose Name equals it when there are any, otherwise those whose
+// Caption does. A name is an activity's identity (deduplicated within the
+// workflow); a caption is a label that may repeat another activity's name —
+// buildJumpTo defaults a jump's caption to its target's name — so letting the
+// two tiers pool made every jump target ambiguous. @N counts within the chosen
+// tier, in the same depth-first order DESCRIBE walks.
+func preferNameMatches[T any](byName, byCaption []T) []T {
+	if len(byName) > 0 {
+		return byName
+	}
+	return byCaption
+}
+
+// findActivitiesRecursive collects the activities whose name, and separately
+// whose caption, equals ref in a flow and its nested sub-flows.
+func findActivitiesRecursive(flow bson.D, ref string, byName, byCaption *[]bson.D) {
 	activities := bsonnav.DGetArrayElements(bsonnav.DGet(flow, "Activities"))
 	for _, elem := range activities {
 		actDoc, ok := elem.(bson.D)
 		if !ok {
 			continue
 		}
-		actCaption := bsonnav.DGetString(actDoc, "Caption")
-		actName := bsonnav.DGetString(actDoc, "Name")
-		if actCaption == caption || actName == caption {
-			*matches = append(*matches, actDoc)
+		switch {
+		case bsonnav.DGetString(actDoc, "Name") == ref:
+			*byName = append(*byName, actDoc)
+		case bsonnav.DGetString(actDoc, "Caption") == ref:
+			*byCaption = append(*byCaption, actDoc)
 		}
 		for _, nestedFlow := range getNestedFlows(actDoc) {
-			findActivitiesRecursive(nestedFlow, caption, matches)
+			findActivitiesRecursive(nestedFlow, ref, byName, byCaption)
 		}
 	}
 }
@@ -697,8 +714,9 @@ func (m *Mutator) findActivityIndex(caption string, atPosition int) (int, []any,
 		return -1, nil, nil, fmt.Errorf("workflow has no Flow")
 	}
 
-	var matches []activityIndexMatch
-	findActivityIndexRecursive(flow, caption, &matches)
+	var byName, byCaption []activityIndexMatch
+	findActivityIndexRecursive(flow, caption, &byName, &byCaption)
+	matches := preferNameMatches(byName, byCaption)
 
 	if len(matches) == 0 {
 		return -1, nil, nil, fmt.Errorf("activity %q not found", caption)
@@ -716,20 +734,22 @@ func (m *Mutator) findActivityIndex(caption string, atPosition int) (int, []any,
 	return am.idx, am.activities, am.flow, nil
 }
 
-func findActivityIndexRecursive(flow bson.D, caption string, matches *[]activityIndexMatch) {
+func findActivityIndexRecursive(flow bson.D, ref string, byName, byCaption *[]activityIndexMatch) {
 	activities := bsonnav.DGetArrayElements(bsonnav.DGet(flow, "Activities"))
 	for i, elem := range activities {
 		actDoc, ok := elem.(bson.D)
 		if !ok {
 			continue
 		}
-		actCaption := bsonnav.DGetString(actDoc, "Caption")
-		actName := bsonnav.DGetString(actDoc, "Name")
-		if actCaption == caption || actName == caption {
-			*matches = append(*matches, activityIndexMatch{idx: i, activities: activities, flow: flow})
+		match := activityIndexMatch{idx: i, activities: activities, flow: flow}
+		switch {
+		case bsonnav.DGetString(actDoc, "Name") == ref:
+			*byName = append(*byName, match)
+		case bsonnav.DGetString(actDoc, "Caption") == ref:
+			*byCaption = append(*byCaption, match)
 		}
 		for _, nestedFlow := range getNestedFlows(actDoc) {
-			findActivityIndexRecursive(nestedFlow, caption, matches)
+			findActivityIndexRecursive(nestedFlow, ref, byName, byCaption)
 		}
 	}
 }
diff --git a/mdl/backend/wfmutator/mutator_test.go b/mdl/backend/wfmutator/mutator_test.go
index 29b38391d2..5d840b3107 100644
--- a/mdl/backend/wfmutator/mutator_test.go
+++ b/mdl/backend/wfmutator/mutator_test.go
@@ -265,6 +265,36 @@ func TestWorkflowMutator_FindActivity_Ambiguous(t *testing.T) {
 	}
 }
 
+// A jump's caption defaults to its target's name (buildJumpTo), so a reference
+// to the target used to match both and fail as ambiguous. A name is an activity's
+// identity; a caption is a label — the name wins, and captions are only consulted
+// when no name matches.
+func TestWorkflowMutator_FindActivity_NameBeatsJumpCaption(t *testing.T) {
+	target := makeWfActivity("Workflows$UserTask", "Split the jump", "bugSplitJump")
+	jump := makeWfActivity("Workflows$JumpToActivity", "bugSplitJump", "JumpTo")
+	m := newMutator(makeWorkflowDoc(target, jump))
+
+	got, err := m.findActivityByCaption("bugSplitJump", 0)
+	if err != nil {
+		t.Fatalf("findActivityByCaption: %v", err)
+	}
+	if name := bsonnav.DGetString(got, "Name"); name != "bugSplitJump" {
+		t.Errorf("resolved to %q, want the named activity", name)
+	}
+	idx, _, _, err := m.findActivityIndex("bugSplitJump", 0)
+	if err != nil {
+		t.Fatalf("findActivityIndex: %v", err)
+	}
+	if idx != 0 {
+		t.Errorf("index = %d, want 0", idx)
+	}
+	// The caption still addresses an activity whose name does not match.
+	got, err = m.findActivityByCaption("Split the jump", 0)
+	if err != nil || bsonnav.DGetString(got, "Name") != "bugSplitJump" {
+		t.Errorf("caption fallback: got %v, %v", got, err)
+	}
+}
+
 func TestWorkflowMutator_FindActivity_AtPosition(t *testing.T) {
 	act1 := makeWfActivity("Workflows$UserTask", "Review", "task1")
 	act2 := makeWfActivity("Workflows$UserTask", "Review", "task2")