ADR-dataflow-001
Recursive composite node system (replacing fixed two-layer canvas)
Context
The two-layer canvas (ADR-legacy-001) limits composability. Researchers can't group nodes into reusable blocks, nest deeper than one level, or save/share reasoning sub-graphs. As agent architectures grow more complex (multi-step reasoning, tool use, backtracking), the inner graph risks the same clutter that motivated the two-layer split. ComfyUI's subgraph system validates the recursive approach at scale.
Decision
Evolve from fixed two layers to recursive composite nodes. Any group of nodes can become a reusable composite with defined I/O (PortIn/PortOut boundary nodes), nestable to arbitrary depth. Key design choices: (1) PortIn/PortOut separate from IterIn/IterOut — I/O boundary vs. iteration are distinct concerns. (2) Flatten-before-execute — backend receives nested graph, flattens recursively, GraphExecutor stays unchanged. (3) Navigation stack with breadcrumbs replaces binary layer toggle. (4) Saved composites stored in workspace/graphs/ and auto-discovered by WorkspaceComponentRegistry. (5) One system from the start — no legacy/modern coexistence.
Alternatives
(a) Keep two layers, add collapsible groups within inner graph. (b) Hierarchical execution (each composite spawns sub-executor). (c) ComfyUI-style legacy group nodes (limited to one level).
Rationale
Recursive composition matches the natural abstraction hierarchy of agent design (researchers think in nested concepts: "my agent has a planning phase that uses a VLM caption step"). Flatten-before-execute keeps the backend simple (validated by ComfyUI — zero backend changes needed). PortIn/PortOut separation from IterIn/IterOut avoids the dual-purpose confusion of the current system where IterIn serves as both "graph input" and "iteration start". ADR-legacy-001 is not superseded — the outer/inner distinction remains as the default template (Agent Loop presets), but it's no longer a hard architectural boundary.
Affected docs
architecture.md, glossary.md, roadmap.md