Implement structured control-flow constructs (ADR-0031): loop container / parallel block / try-catch

[xuyushun441-sys]

Tracks the implementation of ADR-0031 (docs/adr/0031-advanced-flow-node-executors-and-dag.md, merged): adopt structured control-flow constructs as the native + AI-authored flow model, with BPMN gateways/boundary kept in the protocol as the import/export representation.

Decision recap

• loop = structured iteration container (bounded body region + after-path) — not a back-edge, not a subflow.
• parallel = structured block with implicit join at block end (engine-synchronized) — no author-visible split/join gateways.
• errors = structured try/catch/retry, surfacing the existing fault edge + errorHandling.retry.
• DAG invariant kept — ordinary edges acyclic; iteration/parallel are scoped containers.
• BPMN parallel_gateway/join_gateway/boundary_event retained for interop only, mapped onto the constructs.
• AI authoring generates constructs from the live registry (/automation/actions + configSchema); valid-by-construction.

Open question (decide in task 1)

Representation of structured containers in the nodes[]+edges[] model:

• (A) marker-delimited scoped regions (recommended start; flat graph + single-entry/single-exit validation), or
• (B) nested sub-structure (config.body; cleaner AST, diverges from flat graph).

Roadmap (each = own PR: spec/engine change + tests + showcase example, per multi-agent discipline in AGENTS.md — never push main, branch+PR only, mind shared engine.ts)

• 1. Spec-define the constructs — loop container, parallel block, try/catch/retry: schema + configSchema + well-formedness validation (single-entry/single-exit regions; bounded loop). Pick representation (A) vs (B).
• 2. Loop container — engine execution (bounded iteration over a collection) + designer + e2e. (Highest value; replaces the current no-op loop stub.)
• 3. Parallel block — implicit-join execution (per-run, race-free synchronization) + designer + e2e.
• 4. Try/catch/retry — surface existing fault + retry as a structured construct in spec + designer.
• 5. BPMN mapping — bpmn-interop import/export ↔ structured constructs.

Already shipped (this line of work)

• wait executor (feat(automation): implement the wait node executor (durable timer/signal pause) #1469) — durable timer/signal pause.
• subflow executor — synchronous reusable invoke (depth-guarded; nested pause → clear error). Reuse primitive, not the loop mechanism.

Out of scope / non-goals

• Author-visible low-level BPMN gateway/boundary as the native model (interop only).
• Relaxing the DAG invariant to allow arbitrary cycles.
• Runtime BPMN boundary events (timer/signal) — interop representation retained.

[os-zhuang]

✅ ADR-0031 roadmap complete — all five tasks are merged to main.

#	Task	PR
1	Spec-define constructs + representation decision: (B) nested sub-structure	#1482
2	Loop container — engine execution (replaces the no-op stub)	#1482
3	Parallel block — implicit-join execution	#1489
4	Try/catch/retry — execution	#1499
5	BPMN ⇄ constructs mapping (model level)	#1500

Also along the way: docs for the constructs + a doc-generator fix (#1497).

Outcome: loop / parallel / try_catch are now the native, AI-authored control-flow model — well-formed by construction, validated at registerFlow() (single-entry/single-exit regions, acyclic, bounded loop), DAG invariant preserved, all engine-executed. BPMN gateway/boundary/multi-instance is retained for interop and bridged by automation/bpmn-mapping.ts (round-trippable via the osConstruct marker).

Deliberately deferred (own issues / repos):

• BPMN 2.0 XML (de)serialization plugin on top of the mapping → BPMN 2.0 XML (de)serialization plugin on top of the construct mapping (ADR-0031 follow-up) #1504 (ADR marks XML "Priority: Low").
• Per-iteration / per-region step logs in run observability (TODO in runRegion) → Surface per-iteration / per-region step logs in run observability (ADR-0031 follow-up) #1505.
• Designer rendering of the nested constructs lives in ../objectui (out of this repo) — to be tracked there.

Closing as completed.

---

Generated by Claude Code