4Nested Graph System

Any canvas graph can be saved as a graph node and dragged onto another canvas as a reusable block. This page explains the data model, boundary nodes, flattening algorithm, and storage.

Design doc: Graph System

1. Concepts

2. Data Model

A GraphDefinition is recursive — nodes can contain sub-GraphDefinitions:

GraphDefinition
  ├── nodes: NodeDef[]
  │     └── subgraph: GraphDefinition | None   ← nesting
  ├── edges: EdgeDef[]
  ├── containers: ContainerDef[]
  ├── access_grants: AccessGrantDef[]          ← node ↔ container grants (ADR-dataflow-004)
  └── step_budget, terminationCondition, ...

access_grants replaced the earlier state_edges in ADR-dataflow-004. The dedicated top-level graph_state field is also gone — a graph-level blackboard is now an ordinary ContainerDef in containers with the well-known id "graph_state", plus one AccessGrantDef per node that needs it.

A composite node on the canvas has kind = "composite" (ClassVar on the BaseCanvasNode subclass) and carries its inner graph in the JSON-side NodeDef.subgraph field (the docstring on BaseCanvasNode sometimes calls this the node's children, but the wire-level / persisted field name is subgraph — see graph_def.py:NodeDef). The inner graph uses the same node/edge types as the root canvas — full recursion to arbitrary depth.

3. GraphIn / GraphOut Boundaries

GraphIn and GraphOut are special control nodes that define a composite's external ports:

Parent canvas:
  [NodeA] ──→ [Composite] ──→ [NodeB]
                   │
Inside composite:  │
  [GraphIn: "input"] → [ProcessNode] → [GraphOut: "output"]

• GraphIn config: { "portName": "input" } — maps to a target handle on the composite's input
• GraphOut config: { "portName": "output" } — maps to a source handle on the composite's output

These are not IterIn/IterOut — GraphIn/GraphOut define composite boundaries, while IterIn/IterOut handle iteration cycles.

4. Flatten Algorithm

The GraphExecutor expects a flat graph. Before execution, flatten.py recursively expands all composites:

Input:  [A] → [Composite{P_in → X → Y → P_out}] → [B]

Output: [A] → [X] → [Y] → [B]
        (GraphIn/GraphOut removed, edges rewired)

4.1 Steps

1. Walk all nodes — identify those with a non-empty subgraph
2. Prefix inner node IDs with {composite_id}__ for uniqueness
3. Identify GraphIn/GraphOut boundary nodes
4. Rewire parent edges: - Incoming edges targeting the composite → target the GraphIn's downstream nodes - Outgoing edges from the composite → source from GraphOut's upstream nodes
5. Remove GraphIn/GraphOut nodes and their internal edges
6. Collect inner containers and access grants — container id is prefixed with {composite_id}__; each AccessGrantDef gets its id and container_id prefixed, and its node_id remapped through the same id_map as the inner nodes (flatten.py:103–114)
7. Recurse if any flattened nodes also have subgraphs

4.2 FlattenMap

The FlattenMap records flat_id → (composite_path, original_id) for error tracing:

fmap.trace("agentLoop__step3__llmCall")
# → "agentLoop > step3 > llmCall"

When a node fails during execution, the error log shows the original composite path, not the flattened ID.

5. Storage: Graphs vs Graph Nodes

Two storage kinds serve different purposes (ADR-canvas-003):

5.1 Graph (Editable Template)

# Save
POST /api/graphs { name, description, nodes, edges }

# Load (opens in editor tab)
GET /api/graphs/{graph_id}

5.2 Graph Node (Frozen Composite)

"Save as Graph Node" takes a snapshot of a graph or selection. The snapshot is frozen — editing the source graph doesn't affect existing graph node instances on other canvases. This is snapshot semantics.

// workspace/graph_nodes/llm_step.json
{
  "name": "LLM Step",
  "description": "Wraps an LLM call as a reusable composite block",
  "kind": "node",
  "group": "planning",
  "nodes": [
    { "id": "gin", "type": "graphIn", "config": {"portName": "observation"} },
    { "id": "llm", "type": "llmCall" },
    { "id": "gout", "type": "graphOut", "config": {"portName": "response"} }
  ],
  "edges": [...]
}

6. Key Files

Status