Lecture 04. Four Shapes Cover Almost Everything

On the contract-review graph, one early node picked a contract's next step from three fixed outcomes: file it, send it to deeper review, or escalate to a human. An engineer built it to keep re-running itself whenever the model's confidence read low — try again, check confidence, try again — the same way you'd retry a flaky network call.

Illustrative composite. Over one overnight batch of forty contracts, that node re-ran an average of 3.6 times per contract before anyone noticed, adding roughly forty minutes to the batch and about $180 in repeated model calls. Not one contract ended up on a different outcome than its first run would have picked.

The node's three outcomes were fixed the moment the model read the contract. Retrying didn't change which of the three a contract landed on; it only delayed the landing, because the shape being built — a node repeating itself, waiting for a better answer — was the wrong shape for a decision that had already been made once and never needed remaking. The team fixing it that night asked the useful version of the pattern question, not "which named topology should we use" but "what shape is this node actually, and does our code match it?"

Almost every graph that survives contact with real work is a combination of four shapes, and the contract-review graph (like most production graphs) uses all four in different places without needing a fifth.

The chain

Where each step genuinely needs the last. Inside one contract, extract liability → check liability is a chain: you cannot check a clause you haven't pulled out yet. Chains are the rarest of the four shapes in practice, and usually shorter than people expect once the audit from Lecture 02 has removed the fake edges padding them out.

extract liability → check liability

The fan

Where one job splits into independent branches that run together and merge at the end. fetch contract → four extract nodes running at once is a fan. So is the batch itself: forty contracts, each an independent branch, all reporting to one batch report join. This is the workhorse shape: most of the wall-clock time saved by graph engineering comes from correctly identifying fans that were previously drawn as chains.

┌── extract liability fetch ─────┼── extract termination ├── extract data-handling └── extract auto-renewal

The router

Where the graph inspects something and picks a path. A contract's risk classification decides what happens next: a clean, low-risk contract goes straight to filing; a contract with an unusual liability cap goes to a deeper review path; a contract missing required clauses goes to a human. Three different downstream paths, chosen by one upstream decision.

classify risk ──low───→ file ──medium─→ deeper review ──high───→ human escalation

Lecture 06 covers the router in depth, specifically the split between what a model is allowed to judge and what a deterministic table is allowed to decide. For now, the shape is what matters: one node's output selects one of several downstream paths. The retry-until-confident node from this lecture's opening was exactly this shape, misdrawn: three fixed destinations, mistaken for a node that needed to repeat.

The controlled cycle

Where a node repeats until evidence says it's done. Not until it feels done. extract liability returning clause_not_found routing back to a re-extraction attempt, capped at two retries before escalating to a human, is a controlled cycle. The word "controlled" is doing real work here: an uncapped cycle is a bug, not a shape.

extract ──not found──→ re-extract (attempt 2 of 2) ──still not found──→ human review ↑___________________________|

Which shape you're looking at

Ask these four questions, in this order, one segment at a time:

1. Does step B read step A's specific output, and nothing else feeds B? Then it's a chain. check liability cannot start until extract liability has produced something to check.
2. Does one input split into branches that don't need each other's results to proceed? Then it's a fan. Four extract nodes read the same fetched contract; none waits on the others.
3. Does one node's output pick exactly one of several downstream nodes, with no expectation of returning to that node? Then it's a router. classify risk doesn't repeat itself; it picks once.
4. Does a node's own failure route back to another attempt at itself, with a stated point where it stops? Then it's a controlled cycle — only if the stop condition is real, or it's a bug wearing a shape's name.

Observable signal	Shape	Cost of building the wrong one
B needs A's specific output before it can run	Chain	Treating a fan as a chain serializes work that could have run in parallel — wasted wall-clock time
One input, independent branches, no branch needs another's result	Fan	Treating a router as a fan runs every downstream path instead of the one the label picked — wasted spend on paths never meant to run
A label picks exactly one of several next steps, once	Router	Treating a router as a cycle re-runs a decision that was already final — this lecture's opening failure: $180 and forty minutes for zero change in outcome
A node's own failure routes back to itself, with a stated stop condition	Controlled cycle	Treating a chain as a cycle without a stop condition turns one honest retry into a loop that never ends

A segment that answers "yes" to none of the four questions isn't a fifth shape. It's two segments you haven't separated yet — recheck the reads/writes audit from Lecture 02 before reaching for new vocabulary.

The contract-review graph, fully classified

Before the diagram, here's the node list as it actually shipped, in call order:

fetch → extract liability, extract termination, extract data-handling, extract auto-renewal extract liability →(not found)→ extract liability (retry 1 of 2) →(still not found)→ human review extract liability, extract termination, extract data-handling, extract auto-renewal → classify risk classify risk →(low)→ file | (medium)→ deeper review | (high)→ human escalation

Decide now: before reading further, name the shape at classify risk — chain, fan, router, or controlled cycle — and write one sentence on what building it as the wrong shape would cost. Then check your answer against this lecture's opening: that exact node, built as a cycle instead of a router, is the misdrawn node whose repeated re-runs bought zero change in which contract ended up on which path.

Put all four shapes on the same diagram and the whole graph reads clearly:

diagramsource

drawing

Fan out of fetch, chain inside each extract → check pair, controlled cycle on extract liability's retry, router at classify risk. No fifth shape was needed anywhere in this diagram, and none is needed for the overwhelming majority of production graphs.

Naming the shape is the point

The exercise isn't decorative. A segment labeled "fan" tells the next reader (including future you) that these branches are independent and safe to run concurrently. A segment labeled "controlled cycle" tells them there's a stop condition to verify, not an infinite loop waiting to happen. Unlabeled, the same diagram just looks like boxes and arrows; labeled by shape, it tells you what to check.

Key takeaways

• Four shapes cover almost everything: chain, fan, router, controlled cycle. Production graphs are combinations of these, not novel topologies.
• The chain is the rarest shape in practice. Once fake edges are audited out (Lecture 02), most apparent chains turn out to be fans.
• The fan is the workhorse. Most of the time graph engineering saves comes from correctly spotting independent branches that were drawn as a chain out of habit.
• "Controlled" cycle means a stated stop condition. A retry loop with no cap and no escalation path is a bug wearing a shape's name.
• Label every segment with its shape. The label tells the next reader what to verify: independence for a fan, a stop condition for a cycle, a complete route table for a router.

What You Have Now

Your graph re-classified into chain, fan, router, and cycle segments — one shape per segment, named. The labels sit directly on the diagram in your design document, telling any later reader what to verify in each segment. This begins the Route stage: naming the shape is what makes the join and routing decisions in the next lectures possible.

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

Exercises

1. Classify your graph. Take the dependency map from Lecture 02's exercise and label every segment: chain, fan, router, or controlled cycle. If a segment doesn't fit any of the four cleanly, re-check whether it's actually two segments you haven't separated yet.
2. Audit your cycles specifically. Find every loop in a real workflow you run. For each one, write down its stop condition in one sentence. If you can't, it's not a controlled cycle yet.

Check your understanding