feat(mdl): alter microflow target resolver and describe … with handles

[ako]

Closes #713. This is the first step of alter microflow (plan item 4.2a, ADR-0012 decision 2).

What it adds

• mdl/backend/mfmutator: a content-addressed target resolver that works on the stored object collection, loop bodies included. A target can be:

  • an output variable ($IsValidEmail),
  • a custom caption ('Email is Valid?'),
  • a statement pattern where * matches any run of words.

  Any of them can end in @n. When there is no match, the error gives hints. When several activities match and no @n is given, the error lists them (<target> @n -- <statement> at (x, y)); it never guesses.

• describe microflow M.X with handles prints -- handle: <target> above each activity. The handles are comments, so the output still runs unchanged. Every handle is checked by resolving it back. It refuses to combine with normalized.

Design choices (not settled by the ADRs)

1. The address forms never fall back on each other. $Var only means an output variable, and a quoted string only means a caption.
2. A pattern must match the whole statement. commit $Order does not match commit $Order with events; write commit $Order *.
3. Matching is word by word, not by exact text. Keywords and names match regardless of case; $variables and string literals match exactly.
4. A pattern matches both the printed and the stored form of a statement, because describe prints some ifs with a negated condition.
5. Ordinals follow the order describe prints the activities.
6. Only custom captions address an activity.
7. with handles and normalized cannot be combined.
8. A caption containing a line break falls back to its statement as the handle.

Tests

• Unit tests in mdl/backend/mfmutator and in executor tests on the mock backend. They cover each address form, ambiguity errors, ordinals, whole-statement matching, the round trip from handle to activity, and a control showing that output minus the handle lines equals plain describe.
• PedApp tests on the Studio Pro-authored FeedbackModule.VAL_Feedback (gated by MXCLI_PEDAPP_MPR until Round-trip harness: describe → exec on the Studio Pro PedApp fixture must write nothing #725's fixture lands):
  • every form resolves to the right activity;
  • set $ValidFeedback = false is refused, listing its three matches;
  • all 16 handles resolve to the activity whose @position follows them.
• Revert checks:
  • removing SetPrinted breaks the resolver and negated-if tests;
  • moving the warnings in front of the line numbers puts handles above the wrong activities.

Checks run

• Rebased onto main (after skills: choose the edit mode by document owner (#711) #723, fix(mdl): refuse throw, float/currency/date and the parenthesised association; warn on unstored index names and enum-value docs #724 and fix(describe): round-trip quoted strings, MCP blocks, workflow captions; stop printing secrets (#707) #728).
• make build passed.
• make lint passed (Go and TypeScript).
• go test ./... -timeout 45m passed in every package, with MXCLI_PEDAPP_MPR pointing at a pristine PedApp.

Follow-ups

• Graph splice and placement (4.2b, 4.2c), then the insert/replace/drop statements on the generic alter (Generic alter <type> X { set / insert / replace / drop } with per-doctype target resolvers #712).
• describe nanoflow … with handles.
• Point the PedApp test at testdata/pedapp once Round-trip harness: describe → exec on the Studio Pro PedApp fixture must write nothing #725 merges.
• Pre-existing bug: the ELK source map in renderMicroflowMDL is off by the number of prepended warning lines.

🤖 Generated with Claude Code