Loop Control System

A drawn graph is acyclic, but an agent must loop — observe, act, observe again. The loop control system is the one structure that expresses iteration: a paired iterIn / iterOut, the loop pivots. iterIn opens each iteration and hands the body its inputs; iterOut closes it, collects what carries forward, and decides whether to go round again. This page is the deep reference on that subsystem — the pivots, what flows between them, and how nested loops (scopes) are analysed. How the executor actually schedules the firing is Graph Executor; the JSON schema is Graph System.

1. What a loop pivot is

Plain dataflow stops when data stops flowing — fine for a pipeline, not for an agent. The engine recognises exactly one looping structure: a paired iterIn and iterOut. They are not wired to each other; they are linked by id (config.pairedWith), and the executor hands iterOut's collected values back to iterIn between iterations. Everything drawn between them — predict, env step, whatever — is the loop body, ordinary nodes with no special treatment. Each pivot is two-sided: iterIn has an init side (run-start inputs) and an output side (per-iteration values to the body); iterOut has an input side (loop-carry values + a stop signal) and a final side (values emitted once, when the loop ends).

2. The smallest loop

One iterIn, one iterOut, one carried value (obs), and a stop signal from the body. The three handle families you'll meet — init_*, iterout_*, final_* — all appear here:

Its two configs — note there is no edge between the pivots, only pairedWith:

// iterIn — declares the init side; output handles are synthesised at load
{ "id": "iterIn_1", "type": "iterIn", "config": {
    "version": 3, "pairedWith": "iterOut_1",
    "initPorts": [ { "name": "obs", "wire_type": "TEXT", "persist": false } ] } }

// iterOut — carry ports on the input side, stop halt input, final_* on the output side
{ "id": "iterOut_1", "type": "iterOut", "config": {
    "pairedWith": "iterIn_1",
    "ports": [ { "name": "obs", "wire_type": "TEXT", "persist": true } ] } }

3. The four-moment mental model

Hold the whole subsystem as four moments in the life of a value:

§4 details seed and carry (the port-synthesis machinery), §5 stop, §6 finalise. The runtime timing of these — the order in which the boundary phases run — belongs to the executor (Graph Executor §4.3); here we describe the contract, not the schedule.

4. Port synthesis & the persist matrix

iterIn never carries a hand-written port list. Its effective config.ports is synthesised at load by _synthesize_iterin_ports from two writers, with prefixes that keep the two value sources distinct on the same iterIn:

• iterIn's own initPorts → handles prefixed init_<name>, default persist=false (one-shot: the slot empties after iteration 0).
• the paired iterOut's config.ports → handles prefixed iterout_<name>, default persist=true (refreshed every iteration).

A direct canvas edge into iterIn that targets an undeclared handle is also accepted as an init-writer surrogate (the handle name is used verbatim). The persist flag and the writer origin give four legal per-port configurations:

A name may legitimately appear on both sides (init_X for iteration 0, iterout_X for 1+) — that's the normal pattern for an observation that the entry node seeds and the loop then refreshes. It is only safe when the init entry is one-shot; §10 has the freeze hazard if it isn't.

5. Loop-carry & the stop signal

At each iteration boundary the executor reads iterOut's collected outputs and routes every config.ports value X into the paired iterIn's iterout_X slot, then re-queues iterIn. A persist=false slot clears after its consumer fires; a persist=true slot holds until overwritten. That transfer is the loop — there is no drawn back-edge.

Termination is decided once per iteration, at the iterOut boundary, from iterOut's own stop input (a class-level optional BOOL). If stop is truthy the scope ends after the current iteration; if it's unwired, the loop runs purely to its step_budget. stop is special only in that it does not participate in loop-carry (it isn't mirrored to the final side and a bare stop arrival doesn't make iterOut ready — readiness still needs the carry ports). There is no separate termination node and no termination condition string; the halt is just this BOOL.

6. The final side & the after-loop band

When a scope terminates, iterOut emits once on its final side: one final_<name> per carry port (mirroring the terminal iteration's values) plus a constant final_stop=True. These are real wires — verdict nodes (evaluate, graphOut) connect to them with ordinary edges — but they deliver exactly once, at the end.

The set of nodes downstream of a root iterOut's final_* edges is the after-loop band: the verdict stage that runs once, after the loop. Its defining rule (enforced by the validator, §9) is purity — a band node may take inputs only from the final side or from other band nodes, never from the loop body. Anything the verdict needs must ride the pivot: expose it as an iterOut carry port and read it from final_<name>. This is what makes “the verdict reflects the terminal iteration” a structural guarantee rather than a scheduling accident — the rationale is in ADR-dataflow-009, the runtime drain in Graph Executor §5.1.

7. Scopes: what a loop is, in code

A scope is one iterIn/iterOut pair together with the body it bounds. The executor and validator work in terms of a ScopeInfo (scope_analysis.py), keyed by the iterIn node id:

@dataclass
class ScopeInfo:                    # scope_analysis.py — one (iterIn, iterOut) pair
    scope_id: str                   # the iterIn node id — canonical key for the scope
    iter_out_id: str                # its paired iterOut
    parent_scope_id: str | None     # None = root scope
    child_scope_ids: list[str]      # scopes nested directly inside this one
    member_node_ids: set[str]       # body nodes, by innermost membership
    graphin_node_ids: list[str]     # graphIn boundary nodes serving this scope
    graphout_node_ids: list[str]    # graphOut boundary / latch nodes
    step_budget: int | None         # resolved from iter_in.config.step_budget

Nodes outside any pivot pair belong to the implicit graph scope (id GRAPH_SCOPE_ID = "") — entry nodes and the after-loop band live there. A graph with zero or one scopes is is_single_scope, and the executor takes a fast path that mirrors the pre-nesting behaviour exactly; multi-scope graphs go through the general machinery of §8.

8. Nested scopes & the forest

Loops can nest — an outer planning loop containing an inner action loop. analyze_scopes(graph) builds the full ScopeForest (and returns any topology errors) by a pure analysis of the flat graph:

1. Membership — a node belongs to a scope if it is reachable forward from that iterIn and backward from its iterOut; the intersection is the body. A node in several nested bodies is assigned to the innermost one (member_node_ids).
2. Nesting — scopes are arranged by pivot containment: the parent is the innermost scope whose body contains this scope's pivots, giving parent_scope_id / child_scope_ids and the root_scope_ids at the top.
3. Boundaries — graphIn/graphOut nodes are attached to the scope they serve; an inner scope's graphOut acts as a latch so the outer body can read the inner loop's result.
4. Validation — cross-scope wires that bypass the graphIn/graphOut boundary, duplicate pairedWith, or unpaired pivots are reported as errors.

The forest also writes a per-node node_to_scope map and the graph_scope_node_ids (everything outside any author scope). The executor consults all of this to run each scope's boundary independently. This nesting machinery is ADR-dataflow-007 + ADR-executor-003.

9. Validator contract (loop-specific)

validate_graph_connectivity (graph_def.py) enforces the loop rules at graph load; the full catalogue (and the non-loop rules) is in Graph System §4.2. The loop-specific ones:

• Removed pivots rejected — an initialize or termination node fails with a migration hint (init values → iterIn initPorts; halt → iterOut stop).
• Pairing integrity — every iterIn's pairedWith points at an iterOut and vice-versa; no duplicate or dangling pairing.
• iterIn handles — legacy init_ports/loop_ports schemas rejected; outgoing edges may only reference synthesised init_*/iterout_* handles (plus step).
• iterOut handles — non-empty config.ports; incoming edges target carry ports or stop; outgoing edges source only from final_*/final_stop.
• After-loop band purity — band nodes are graph-scope and take inputs only from the final side or other band nodes (§6).

10. Edge cases & hazards

• Dual-wire freeze. Wiring both init_X and iterout_X into the same consumer input with the init entry set persist=true freezes that input at its iteration-0 value (the persisted init slot keeps winning). Keep the init entry one-shot when a name is dual-sided. This was the root cause of the 2026-05-05 CMA “100% LEFT spin”.
• Run-invariants must persist. The mirror trap: anything the body reads every iteration that comes only from the init side must be persist=true, or it vanishes after iteration 0.
• Budget-only loops. Leave stop unwired and the loop runs to step_budget — intended for fixed-length rollouts.
• Signals don't filter by scope. State-container reset_on matches a signal name, not a scope, so an inner scope's step_end can clear an outer node's step-lifetime slot — see State Containers §6.

11. References

• ADR-dataflow-008 — two-sided iterIn (init side); initialize node removed.
• ADR-dataflow-009 — two-sided iterOut (stop input + final side); termination node removed; after-loop band.
• ADR-dataflow-007 + ADR-executor-003 — multi-scope iteration & execution.
• ADR-dataflow-006 + ADR-executor-002 — the superseded three-pivot model (historical context for the 008/009 collapse).
• Graph Executor — how the pivots actually fire; Graph System — the JSON schema & validation; State Containers — loop-carried vs container state.
• Source: scope_analysis.py (analyze_scopes, ScopeForest, ScopeInfo, GRAPH_SCOPE_ID), graph_def.py (_synthesize_iterin_ports, validate_graph_connectivity), builtin_nodes.py (IterInNode, IterOutNode), graph_executor.py (boundary, transfer, final emission), portResolution.ts (frontend synthesis mirror).