Practice project: Project 02. Add a Verifier and Durable State

Lecture 08. State Is the Part the Diagram Hides

The contract-review batch had run smoothly for three hundred contracts overnight when the process crashed — an out-of-memory error, unrelated to anything in the graph itself. Restarting it the next morning surfaced the actual problem: the system had no record of which contracts had already been reviewed. Rerunning the whole batch would re-review three hundred contracts that had already produced verdicts, burning the same model calls twice for no reason. Skipping ahead blind risked missing whichever contracts were mid-flight when the crash hit. Nobody could answer, with any confidence, "which contracts are actually done?"

Every diagram in this course up to now has shown nodes and edges — the shape of the work. None of them showed where the graph's memory lives while it's running. That's not an oversight in the diagrams; it's the part a box-and-arrow picture structurally can't show, and it's exactly the part that decides whether a crash costs you five minutes or a full re-run.

What Durable State Actually Holds

A graph that runs in production keeps a record, external to any single node's context, of:

• Which node is current, for every branch still in flight.
• Which nodes have completed, and what they produced.
• What artifacts exist — extracted clauses, check verdicts, the eventual risk note — and where to find them.
• What decisions were made and on what evidence — which risk label a contract got, and which verdicts fed that classification.
• What budget is left — how many model calls, how much of a cost ceiling, how much time.
• How many retries have been spent on any node currently in a controlled cycle (Lecture 04).
• Which human approvals are recorded, for any node waiting on one.

interface BatchState {
  batchId: string;
  contracts: Record<ContractId, {
    currentNode: string;
    completedNodes: string[];
    artifacts: { extractLiability?: string; extractTermination?: string /* ... */ };
    riskLabel: RiskLabel | null;
    retriesSpent: number;
    humanApproval: "pending" | "approved" | "rejected" | null;
  }>;
  budgetSpent: number;
  budgetCeiling: number;
}

At any moment, this state should be able to answer three questions on its own, without re-running anything: what has already happened, why was this route taken, and where can execution safely resume? If it can't answer all three, the graph is a demo with good diagrams — not something you can leave running unattended.

The graph diagram shows what runs; this store is where the run remembers what already happened.

Two Rules That Make State Survivable

Rule one: don't pass transcripts between nodes — pass references. extract liability shouldn't hand check liability a copy of its full reasoning trace; it should write its ExtractedClause to the state store and return a reference. check liability reads the artifact directly from the store, not a summary that's been retold once already by whatever passed it along.

// Weak: pass the full artifact through every hop, retold at each step
function extractLiability(contract: string): ExtractedClause { /* ... */ }

// Durable: write to the store, return a reference
function extractLiability(contract: string, store: ArtifactStore): ArtifactRef {
  const result = /* ... */;
  return store.write(`clause:liability:${contractId}`, result);
}

A reference survives a crash. A value sitting only in one node's return value, mid-handoff, does not.

Rule two: make writes idempotent. If the batch job crashes right after extract liability writes its result but before it confirms the write to the orchestrator, the safe recovery is to run extract liability again — which means writing the same artifact twice must not produce two copies, two IDs, or two conflicting verdicts.

function writeArtifact(store: ArtifactStore, key: string, value: ExtractedClause): void {
  store.set(key, value);   // keyed by contract + node — a retry overwrites, never duplicates
}

Keying every write by a stable identifier (contract ID plus node name, here) is what makes "just run it again" a safe answer instead of a data-corruption risk.

The Diagram and the State Are Two Different Documents

A graph.md from Lecture 04 shows the shape. A state schema like BatchState shows the memory. Both are required, and neither substitutes for the other — a beautifully drawn graph with no durable state behind it is still a system that forgets everything the moment the process dies, no matter how correct its edges are.

Key Takeaways

• State is what a diagram structurally can't show. Nodes and edges describe shape; durable state describes memory — where the graph's progress lives while it's running.
• Three questions durable state must answer at any moment: what has already happened, why was this route taken, where can execution safely resume. Missing any one means the graph can't survive an interruption.
• Pass references, not transcripts. Write artifacts to a store and hand downstream nodes a reference to read directly — not a retelling of what an earlier node produced.
• Make writes idempotent, keyed by a stable identifier. A retry after a crash should overwrite the same key, never create a duplicate or a conflicting second answer.

What You Have Now

A durable state schema for your graph: current node, completed nodes, artifact references, budget, retries. It lives alongside the graph diagram in your design document as the record of what the graph knows while it's running, not just how it's shaped. It backs the Verify stage's guarantee that a crash costs a resume, not a re-run.

Save it as graph/lecture-08.md; the lab's checker looks for that file at that path.

Exercises

1. Answer the three questions cold. For a workflow you run today, without looking at logs or re-running anything: can you say what's already happened, why the last routing decision was made, and where execution would resume after a crash? Wherever you can't, that's a gap in your durable state design.
2. Find a passed transcript. In that same workflow, find one place where a full result or reasoning trace gets handed from one step to the next instead of written to a store and referenced. Redesign it as a reference-based handoff.

Check your understanding