Skip to content

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

Description

@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)

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.

Activity

  1. os-zhuang commented on Jun 2, 2026

    @os-zhuang
    Contributor

    ✅ 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):

    Closing as completed.


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions