Unit 11.00: Designing the graph and its state

The capstone starts where Module 2 said it should: with the graph written as data, before any node body exists.

Four structural checks on the design

State fields with their reducers and purposes, the node list, which nodes are terminal, where the human gate sits, and which steps are irreversible.

The code prints the design and then runs four checks against it.

import json

DESIGN = {
    "state": {
        "question": "str -- the request, never mutated",
        "findings": "list -- appended by research, reducer: add",
        "draft": "str -- last write wins",
        "approved": "bool -- set only by a human",
        "published": "bool -- guard flag for the irreversible step",
        "attempts": "int -- ceiling for the revise loop",
        "error": "str -- empty means no failure",
    },
    "nodes": ["research", "draft", "review", "publish", "handle_error"],
    "terminal": ["publish", "handle_error"],
    "human_gate": "before publish",
    "irreversible": ["publish"],
}
print(json.dumps(DESIGN, indent=2))

print("\nchecks on the design before any node is written:")
for check, ok in [
    ("every irreversible step has a guard flag", "published" in DESIGN["state"]),
    ("every loop has a counter", "attempts" in DESIGN["state"]),
    ("failure has its own terminal node", "handle_error" in DESIGN["terminal"]),
    ("approval is a state field, not a prompt", "approved" in DESIGN["state"]),
]:
    print(f"  {'OK  ' if ok else 'FAIL'} {check}")

Each check corresponds to a failure from an earlier module. A guard flag for the irreversible step is Module 5. A counter for the loop is Module 4. A terminal node for failure is Module 4 again. Approval as a state field rather than a prompt instruction is Module 7.

All four are checkable before a single node is implemented, which is the point of writing the design as data. Each one costs minutes here and hours after the graph exists.

The mistake this prevents

The mistake is treating this as documentation to be written afterwards. Written afterwards it describes what you built and every check passes trivially, because the design was reverse-engineered from the code. Its value is entirely in being written while the answers are still open.

Takeaway

Write the state, nodes, terminals, gate and irreversible steps as data first, then run structural checks against it. Four checks catch the four failures this course has spent modules on.

Mark complete