plan

type BriefJournal func(graph *Graph, nodeID int, brief store.NodeBrief)

type CapacityEvidence struct {
	Worker   string
	Runs     int
	Overruns int
	Rate     float64
}

type Check struct {
	// Kind is "run" or "read". Universal across harnesses: a condition is
	// either settled by executing something and reading an outcome, or by
	// reading the artifact and finding something present.
	Kind   string `json:"kind"`
	Check  string `json:"check"`
	Expect string `json:"expect"`
}

type ClaimContext struct {
	// Landed is what each finished dependency produced, in admission order.
	Landed []Landed
	// Criterion is what must be true of this node when it is finished.
	Criterion Done
}

type Completer interface {
	CompleteWithMessages(ctx context.Context, messages []ai.Message, options ...ai.Option) (*ai.Response, error)
}

type Constraint struct {
	// Text is the person's own words for this rule, verbatim. It is what the
	// leaf is shown, what the gate quotes when it refuses, and the only thing
	// anybody is ever held to.
	Text string `json:"text"`
	// Kind is the mechanical reading: one of the three constants below. An
	// unrecognised kind normalizes to ConstraintOther, which is the weaker
	// claim — a rule nothing mechanical settles is still a rule the leaf reads
	// and the judge is shown.
	Kind string `json:"kind"`
	// Paths are the places a ConstraintPathsOnly rule allows, in the person's
	// own spelling, cleaned to workspace-relative slash paths. Empty on every
	// other kind.
	Paths []string `json:"paths,omitempty"`
}

type ContractPlaybook func(Node) string

type Done struct {
	// Produces names the identifiable outputs by the names they will carry, so
	// a reader holding only the criterion can tell whether they exist.
	Produces   []string `json:"produces,omitempty"`
	Conditions []Check  `json:"conditions,omitempty"`
}

type Graph struct {
	Goal string `json:"goal"`

	// Asked are the separable requests the person's own ask contained, in
	// their own words, as the call that read the whole ask reported them.
	//
	// They are a reading of the ask and never a layout of the plan. There was
	// once a second road out of that reading — two or more requests laid flat
	// with an assembler behind them, no planner anywhere — and it was a worse
	// planner with a hardcoded shape: the one judgment it could not make was
	// whether one of the requests is written over what the others produce, and
	// the layout it committed to had no way to say so. That is the question
	// this package's passes exist to answer, so the reading is handed to them
	// as evidence and the shape stays theirs.
	//
	// Fewer than two is the ordinary ask and renders nothing at all, which is
	// the whole of the compatibility story: every prompt below sends the bytes
	// it sent before this field existed. Persisted with the graph for the same
	// reason the settled points are — a document revised later is revised
	// against the premises it was built from.
	Asked []string `json:"asked,omitempty"`

	// Settled are the goal's free variables, bound once so that every parallel
	// call works from the same premise. Open are the ones that cannot be bound
	// in advance because they are the answer to the work — they exist to tell
	// the binder what must become a real dependency rather than an assumption.
	//
	// A settlement is the variable and the values together (see Settlement), so
	// that "bound" is a slice length rather than a reading of a sentence. A graph
	// written before that split decodes its strings into the same type and
	// renders them unchanged.
	Settled []Settlement `json:"settled,omitempty"`
	Open    []string     `json:"open,omitempty"`

	// Evidence is the standard of support the goal warrants — reading and
	// citing, running and measuring, or building and demonstrating. It is
	// settled with the scope and for the same reason: left unsaid, each subtree
	// picks its own and the expensive answer wins, which is how a short written
	// report became a benchmarking project.
	Evidence string `json:"evidence,omitempty"`

	// FileShaped says the ask names its own deliverable — a file or document by
	// name, or a change to material that already exists — which is the one case
	// where filing the result is delivery rather than an evasion of it. It rides
	// the graph because it is one fact about the goal and three passes need the
	// same answer: the instruction the deliverable owner receives, the working
	// method written for it, and anything later that judges what came back.
	//
	// False is the safe default and the shape almost every ask has, so a caller
	// that has not made the judgment leaves every prompt exactly as it was.
	//
	// Intended wiring: the chat session sets Options.FileShaped on plan.Build, or
	// graph.FileShaped before plan.Briefs/plan.Contracts, from the same judgment
	// its delivery gate already makes about the request — the bit that decides
	// whether a leaf is offered a workspace path at all (leafOutputHint). Nothing
	// here matches a phrase against the goal.
	FileShaped bool `json:"file_shaped,omitempty"`

	// Continues says this plan is the remainder of work that already happened —
	// a repair, an extension, a continuation — as opposed to a plan for work
	// nobody has started.
	//
	// It is a separate fact from Records and not derivable from it, because the
	// two questions it separates are the ones that were being collapsed. A plan
	// that continues nothing has no record because there is nothing to have a
	// record OF, and telling its method writer that no record was handed in
	// would be answering a question nobody asked. A plan that continues work and
	// still has no readable record is the case that goes wrong: its agents will
	// be asked to state facts about work they cannot see, and the method they are
	// held to has to say so out loud rather than leave them to improvise.
	Continues bool `json:"continues,omitempty"`

	// Records are the files the work this plan continues left behind, which the
	// agents it plans can open and read: the text of a change, a measurement, a
	// transcript. Empty is a plan that continues nothing, which is nearly every
	// plan there is.
	//
	// It rides the graph because the pass that needs it is not the one that
	// receives it. What a remainder can KNOW is settled four calls before any
	// leaf runs, in the pass that writes each leaf's working method, and that
	// pass had no way to tell "the agent will be handed the record and must read
	// it" from "the agent will be handed nothing and must say so". Handed
	// neither, it wrote methods that instructed inference — and one of them
	// offered an illustrative root cause that the leaf then shipped verbatim as
	// a real one, into a person's answer, past a gate holding only file names.
	//
	// It is a roster of what EXISTS, never an instruction about what to write
	// with it. What the method pass makes of a roster, empty or full, is that
	// pass's own business. See contract.go.
	Records []string `json:"records,omitempty"`

	// Terrain is the workspace this run stands on, drawn in code at build start
	// and frozen. It is persisted with the graph for the same reason the settled
	// points are: a graph read back off disk is revised against the premises it
	// was built from, and a reviser that lost the picture would be judging what
	// happened against a workspace it was told about but cannot see.
	Terrain string `json:"terrain,omitempty"`

	// ContextTokens is the window of the model that structures this job: the
	// one that planned it, and the ones that later revise it and judge whether
	// it is finished. Zero means unknown, which is the honest answer for a graph
	// nobody told and never a claim that the model is small.
	//
	// It is persisted for the same reason Terrain is. The passes that read this
	// document after the build — the revision sentinel, the growth gate — are
	// reached through signatures that carry the document and nothing else, and a
	// graph read back off disk that had lost the window would quietly go back to
	// showing a 200k-token reviser 4 KiB of what has happened.
	ContextTokens int `json:"context_tokens,omitempty"`

	// Invoice is the measured price list rendered by the caller before the build
	// starts, and it is what the three passes that judge division are given in
	// place of guessing what a split costs. See invoice.go.
	//
	// It rides the graph rather than the options because expansion and the
	// sizing pass inside it are reached through the document alone, and a
	// sub-planner that lost the prices would be weighing a division against
	// nothing — which is the state this whole block exists to end.
	//
	// Empty is a machine with nothing measured yet, and it is also the whole of
	// the compatibility story: every prompt below renders exactly the bytes it
	// rendered before invoices existed. It is deliberately NOT persisted: prices
	// move every time a leaf lands, and a graph read back off disk a day later
	// carrying yesterday's prices would be quoting a measurement as a fact when
	// the measurement has since changed.
	Invoice string `json:"-"`

	// Workspace is the directory the terrain above was drawn from, and it is
	// here so that the material a node names can be weighed. See reach.go: the
	// sizing pass runs against the document rather than against the options, so
	// a graph that lost the directory would have no way to check a verdict
	// against the material the node it sized actually names — and no way to
	// state the goal's own measurement in the prompt every pass shares.
	//
	// Empty is a run with no workspace, which measures nothing and changes no
	// verdict and no prompt byte anywhere.
	Workspace string `json:"workspace,omitempty"`

	// Named is the frozen measurement of what this GOAL names by name, weighed
	// against what one worker holds and rendered once at build start. It is the
	// whole-plan reading and never a node's: a node's own verdict is
	// Node.BeyondReach above, computed where its siblings are visible.
	//
	// It is frozen for the reason the terrain beside it is: it joins the prefix
	// every pass shares, and workers write into the workspace while passes are
	// still running, so a figure re-read mid-build would move the prefix under
	// calls in flight and leave two of them planning against two different
	// readings of the same disk.
	Named string `json:"named,omitempty"`

	Stages []Stage `json:"stages"`
	Nodes  []Node  `json:"nodes"`
	NextID int     `json:"next_id"`
	Usage  Usage   `json:"usage"`
}

type Grounding struct {
	Settled  []Settlement
	Open     []string
	Evidence string
}

type Invoice struct {
	// Worker names whose price list this is. Prices are kept per worker because
	// capacity is a property of the executor, and a price list that averaged
	// over several of them would describe none of them.
	Worker string
	// Shapes are the per-size rows, in the order sizes are worth reading.
	Shapes []InvoiceShape
	// Floor is what the cheapest leaf this worker has ever run cost, and it is
	// the closest thing to a measured fixed price of a child there is: whatever
	// a piece costs before it does any work of its own — being told the subject,
	// being told the working method, claiming the node and saying it is done.
	// A split of N ways pays it N times whatever else it buys.
	Floor int
	// FloorKnown separates a measured floor from an unmeasured one. A zero
	// floor is not a free child; it is a worker nobody has watched yet.
	FloorKnown bool
	// JoinTokens is the fan-in tax: what a leaf that consumed earlier results
	// has actually cost, over the runs that recorded how many results they
	// consumed. JoinInputs is the median number of results those runs read.
	// A join re-reads every branch's digest, so this is the price the width
	// itself adds at the far end and it is the one cost a fan-out prompt never
	// sees.
	JoinTokens int
	JoinInputs int
	JoinRuns   int
}

type InvoiceShape struct {
	Shape  string
	Runs   int
	Turns  int
	Tokens int
	Cost   float64
}

type Kind string

type Landed struct {
	Title  string
	Result string
}

type Measurement struct {
	Files int
	Bytes int
	Reach int
}

type Node struct {
	ID     int `json:"id"`
	Stage  int `json:"stage"`
	Depth  int `json:"depth"`
	Parent int `json:"parent,omitempty"`

	Title   string `json:"title"`
	Summary string `json:"summary"`

	// Sources are the distinct things this node must touch to be done — pages,
	// documents, datasets, vendors, decisions. They are collected because
	// enumeration is something a model does reliably and effort estimation is
	// not, so they stand in as evidence of size. They are dual-use: the same
	// list is a real hint to whatever eventually executes the node.
	Sources []string `json:"sources,omitempty"`

	// Parts are the pieces this node would break into that could genuinely run
	// at the same time. They are named during sizing, which costs nothing extra,
	// and they are the cheap pre-check on expansion: a node that cannot name two
	// parallel parts is not worth spending a fan-out call on, because whatever
	// comes back will be rejected for not shrinking anything. Naming is the test
	// — a split nobody can describe concretely is a split that does not exist.
	Parts []string `json:"parts,omitempty"`

	// Undivided is why this node was left whole, written at the moment the
	// refusal was made rather than inferred afterwards from the shape that
	// resulted — the shape is the thing being explained. It follows the pattern
	// the scale gate already set for the job-level reading (see
	// store.RecordScaleGate): diagnosis, not control. Nothing reads it back to
	// decide anything, and losing it costs an explanation and nothing else.
	//
	// It answers the question a finished graph otherwise cannot: a node that
	// stayed a leaf because nobody could name two pieces and a node that stayed
	// a leaf because the pieces would have run one after another look identical
	// once the run is over, and the reading that separated them is a model's and
	// does not repeat. Empty means no split was ever considered for this node.
	Undivided string `json:"undivided,omitempty"`

	// BeyondReach is the measurement's finished verdict on this node: the
	// material it will read is larger than one worker's window AND it is not a
	// lane of a division. It is a stored answer rather than a question each
	// reader asks for itself, and THAT IS THE POINT — see correctBeyondReach,
	// which is the one place that computes it.
	//
	// It is here because two seams act on the same fact and only one of them
	// can see the graph. The sizing correction weighs a node's material against
	// its siblings'; the split judgment reads one node and the options and
	// cannot see a sibling at all. While the split judgment measured for itself
	// it reached the opposite verdict on exactly the nodes the exemption exists
	// for: three lanes over one register were spared by the correction, sized
	// atomic, and then journaled "its named material exceeds what one worker
	// holds" by the expansion pass a moment later. THE TWO SEAMS MAY NEVER
	// DISAGREE, so there is one verdict and both read it.
	//
	// False is every graph that was never measured — no workspace, nothing
	// named, nothing weighed — which is every prompt byte and every branch
	// exactly as they were before any of this existed. A graph written to disk
	// before this field existed reads back false and behaves that way too, and
	// a node the sizing pass never reached (frozen: already running, already
	// done) keeps whatever it carried, because it is not a candidate for
	// division any more.
	BeyondReach bool `json:"beyond_reach,omitempty"`

	Needs []int  `json:"needs"`
	Size  Size   `json:"size,omitempty"`
	State State  `json:"state"`
	Kind  Kind   `json:"kind"`
	Brief string `json:"brief,omitempty"`

	// Subharness names the worker that takes this node whole. There is one, so
	// a node built by this harness carries "linear" or nothing; the column
	// stays because a graph written by an older build names what it named, and
	// it travels with the node from the file the graph is persisted to through
	// the splice that admits it to the store.
	//
	// Empty is a different fact from "linear": nobody wrote this column at all,
	// and only that fact lets a reader downstream supply an answer of its own.
	Subharness string `json:"subharness,omitempty"`

	// Contract is the working method for this leaf: how an agent should work
	// this particular kind of job, as distinct from the Brief, which says what
	// the job is. A generic loop with a per-task contract is what lets one
	// executor match a specialised harness on any given leaf without the
	// harness itself changing.
	Contract string `json:"contract,omitempty"`

	// Skills is the ordered list of skill names the brief pass attached to this
	// leaf from the shelf the caller handed the build: skills the goal names
	// outright first, retrieval candidates behind them. Order is precedence —
	// earlier-listed skills win conflicts — and the same order is journaled on
	// the node brief and rendered into the worker's instruction. Empty attaches
	// nothing and renders nothing.
	Skills []string `json:"skills,omitempty"`

	// Spec is the same two facts as an object, plus the one nothing carried
	// before: the criterion this node's work is judged finished against.
	//
	// Brief and Contract stay the source of truth for one release and Spec is
	// written beside them — dual-write, single read — so rolling the wave back
	// is a one-line swap at each reader rather than a migration. What the
	// object buys is the retry path: a replacement node inherits Done verbatim
	// instead of re-authoring a spec from failure context, which is how the
	// module name, the filename and the acceptance check used to disappear the
	// moment a leaf was re-aimed at a different worker.
	Spec Spec `json:"spec,omitzero"`

	// Result is what this node produced and is what its dependents receive. It
	// is the deliverable itself rather than a report about it, so that routing
	// it downstream needs no further interpretation. Artifacts are referenced by
	// path instead of inlined: a large output would otherwise be pasted into
	// every dependent's context at once, which is the exact pollution the
	// dependency list exists to prevent.
	Result    string   `json:"result,omitempty"`
	Artifacts []string `json:"artifacts,omitempty"`
	Turns     int      `json:"turns,omitempty"`

	// Tokens and Cost are recorded per node because a run's total says nothing
	// about where it went. One leaf was 54% of a run's input tokens and that had
	// to be inferred from turn counts afterwards rather than read off, which is
	// exactly the measurement the calibration loop needs.
	Tokens int     `json:"tokens,omitempty"`
	Cost   float64 `json:"cost,omitempty"`
	Stop   string  `json:"stop,omitempty"`

	// Verdict is how the leaf ended, as distinct from State. State answers "may
	// its dependents run", and StateDone answers yes to a leaf that stopped
	// halfway because it ran out of budget — correctly, since the dependents
	// still need whatever it produced. Verdict answers the other question, the
	// one nothing could ask before: was that a success. Anything that learns
	// from a run reads this field and never State.
	Verdict provider.Reading `json:"verdict,omitempty"`

	// FanIn is how many earlier results actually landed in this node, measured
	// by whoever claimed it rather than counted off this document.
	//
	// Needs is the plan's intention and is very nearly the same number; this is
	// what a surface with a live store observed instead, which differs where an
	// edge was spliced in after planning or where a dependency settled without
	// producing anything. Nil means nobody measured, and the reader falls back
	// to len(Needs) — never to Sources, which is the touch-list and was the
	// number the join price was mistakenly read off for as long as it existed.
	FanIn *int `json:"fan_in,omitempty"`

	// Calibration is what the worker said about its own fit for this node. It is
	// carried for one reader: the profile record this node becomes when the run
	// lands, and through it the call that rewrites the ruler. Empty on every
	// node that said nothing about its own fit, which is nearly all of them.
	Calibration []string `json:"calibration,omitempty"`

	// Checked is what this node's own worker ran to check itself, and what each
	// one found — one clause, already composed by whoever observed it.
	//
	// It is here for exactly one reader: the pass that looks at a job's
	// remainder and decides whether anything more is worth adding. A node that
	// changed files and whose suite came back green is finished, and that fact
	// existed only inside the worker — so the reviser, seeing a title and a
	// state, kept proposing children to run the tests again and re-investigate
	// what was already proved. Between 48% and 57% of a run's measured cost went
	// there. This is not a rule telling the reviser what to conclude; it is the
	// evidence it was reasoning without.
	Checked string `json:"checked,omitempty"`

	Failure string `json:"failure,omitempty"`
}

type Operation struct {
	Op      string `json:"op"`
	Node    int    `json:"node"`
	Title   string `json:"title"`
	Summary string `json:"summary"`
	Needs   []int  `json:"needs"`
	Reason  string `json:"reason"`
	Applied bool   `json:"applied"`
	Refused string `json:"refused,omitempty"`
}

type Options struct {
	// Recall is folded history relevant to this goal. Empty preserves the
	// pre-memory prompt byte for byte; populated memory is consumed only by the
	// ground pass, before parallel planning can reinterpret the goal.
	Recall []store.RecallHit

	// Terrain is what the run's workspace holds, rendered by the caller with
	// RenderTerrain before the build starts. Empty is the whole of the
	// compatibility story: a caller with no workspace sends the prompt bytes it
	// has always sent.
	//
	// The caller renders it, not this package, and renders it exactly once. This
	// block joins the frozen preamble that every fan-out, bind, size, audit and
	// brief call shares, so re-reading the directory mid-build — where a worker
	// may already be writing into it — would change the prefix under passes that
	// are still running, cost every cache hit behind it, and leave two calls
	// planning from two different pictures of the same workspace. It is a
	// snapshot taken at build start and frozen for the build.
	Terrain string

	// Workspace is the directory the terrain above was drawn from. It is what
	// makes the terrain measurable rather than only readable: the words of the
	// goal and of every node name files, and this is where they are looked up.
	// See reach.go.
	//
	// It is read exactly once, onto the graph at build start, because the pass
	// that weighs a node's material against its siblings' runs off the document
	// and not off these options. See Graph.Workspace and reach.go.
	//
	// Empty measures nothing, renders nothing, and changes no verdict — a
	// caller with no workspace plans exactly as it always did, on the prompt
	// bytes it always sent.
	Workspace string

	// Asked are the separable requests the caller's reading of the ask found in
	// it, in the person's own words. Fewer than two is the ordinary ask and
	// changes no prompt byte anywhere.
	//
	// It is handed to the build rather than acted on by the caller, and that is
	// the whole of this field. A caller that acts on it is a second planner
	// with one shape in it: it can lay the requests side by side, and it cannot
	// answer the one question a flat layout destroys — whether one of them is
	// written over what the others produce. Here the reading reaches the passes
	// whose job that question already is. See Graph.Asked.
	Asked []string

	// SpineSamples is how many spines to draw before choosing one. The spine is
	// the only call whose framing every later pass inherits, so it is the only
	// one worth sampling; the samples run concurrently and cost no wall clock.
	SpineSamples int

	// MaxDepth bounds recursion. It is the guard that matters most, because
	// depth is the only cost of decomposition that is genuinely serial — a
	// level costs four call-rounds however many nodes expand within it.
	MaxDepth int

	// BuildDepth is how many of those levels the *build* runs for itself, for
	// a caller that intends to carry the rest later.
	//
	// Zero means MaxDepth, which is every caller that has ever existed and is
	// the whole of the rollback: a build asked nothing new answers exactly as
	// it did. A scheduler that expands at claim time sets it low and keeps
	// MaxDepth where it was — the difference between the two is not a smaller
	// graph, it is the same depth decided later, against dependencies that have
	// landed instead of against their titles. Every level the build skips is
	// one it would have decided at t=0 with the least information it will ever
	// have, and one whose four serial call-rounds it would have made the person
	// wait through before the first leaf started.
	BuildDepth int

	// NodeBudget is the hard ceiling the model cannot argue with. Every other
	// stop condition is pressure applied through a prompt; this one is
	// arithmetic, and it is what guarantees termination.
	NodeBudget int

	// Briefs turns on per-leaf instruction writing. It is opt-in because it
	// costs one call per leaf and only matters once something is going to
	// execute them.
	Briefs bool

	// Skills is the active shelf, read once by the caller from the store it
	// already holds ([store.SkillFacts] with the active status) and handed in
	// frozen, the way the terrain and the invoice are: the brief pass composes
	// each leaf's attachment from it — skills the goal names outright first,
	// retrieval candidates behind them — and journals the same order on the
	// node brief. Nil is the whole of the compatibility story: a caller with
	// no shelf attaches nothing and changes no prompt byte anywhere.
	Skills []store.Fact

	// FileShaped carries the delivery-law bit onto the graph, for the case where
	// briefs are written inside the build and the caller never sees the graph
	// before they are. See Graph.FileShaped and DeliveryLaw.
	FileShaped bool

	// Continues says this plan is the remainder of work that already happened.
	// See Graph.Continues.
	Continues bool

	// Records are the files the work this plan continues left behind, which the
	// agents it plans can open and read. See Graph.Records.
	Records []string

	// Undivided stops the build at the spine when the spine says there is
	// nothing to divide. It exists for the remainder path and it is opt-in
	// because it is the wrong answer for a fresh project: a one-stage project
	// still has parallel parts inside that stage, and finding them is the
	// point.
	//
	// A remainder is different in kind. It is what is left of one leaf's
	// assignment after a reviewer named a gap, so it is by construction
	// smaller than work one agent was already given. Measured: planning one
	// such remainder — "run pytest and show the output" — cost 13,828 prompt
	// tokens across seven planner passes, and another cost 23,964. That is
	// five to eight times the entire structuring cost of the original job, to
	// produce a graph of one node.
	//
	// The judgement stays the model's and the structure stays the code's, and
	// the judgement is the RULER'S REACH. The spine is asked what has to wait
	// for what, which is advice about the shape of a fresh plan; for a
	// remainder its answer is a list of the steps one worker would take, so
	// however many stages come back they are folded into one node and the ruler
	// is asked whether that node is within one worker. Within reach, this stops
	// there and hands back one worker; past it, the full pipeline runs exactly
	// as before and the stages inform the fan-out as they always did. Nothing
	// matches a phrase against anything, and the stage count divides nothing.
	Undivided bool

	// Ensemble chooses between the two ways of spending parallelism: splitting
	// work by subject, or doing one judgment several times over independently
	// and merging. 0 lets the planner decide from the goal, -1 never asks, and
	// N >= 2 forces a panel of N. See ensemble.go.
	Ensemble int

	// ContextTokens is the window of the model that reads this package's
	// prompts — the planner, and afterwards the reviser and the completion gate
	// that read the same document. Zero means nobody could say, and every
	// budget sized from it then falls back to the literal it always used.
	//
	// It rides onto the graph at build so that the passes which happen later,
	// through signatures that carry a document and not an options struct, size
	// themselves from the same number the build did. See Graph.ContextTokens.
	ContextTokens int

	// Invoice is the measured price list for this model's workers, rendered by
	// the caller with RenderInvoice before the build starts. Empty is a machine
	// with nothing measured yet and leaves every prompt byte for byte as it was.
	//
	// The caller renders it for the same reason it renders the terrain: this
	// package holds no profile directory and no model name, and the block must
	// be one snapshot frozen for the build rather than a figure that moves under
	// passes still running. See Graph.Invoice and invoice.go.
	Invoice string

	// CapacitySamples and CapacityOverrunRate are the journal's measured answer
	// to how often one-worker leaves exceeded their envelope. Zero is no
	// measurement and preserves the old decision exactly; callers only populate
	// them behind the swarm gate. The sample count remains separate because a
	// dramatic rate from one run is an anecdote, not a reason to buy more work.
	CapacitySamples     int
	CapacityOverrunRate float64

	Report Report

	// Progress is called at pass boundaries. Nil keeps planning behavior and
	// output unchanged.
	Progress Progress

	// OnReady fires the instant a node is final and has nothing to wait for.
	// Those nodes are dispatchable at once — a linear harness could be running
	// them while the rest of the graph is still being planned — so the moment
	// we know is the moment worth telling someone. The node is passed by value:
	// the graph is still being appended to, and a pointer into it can go stale.
	OnReady func(node Node, elapsed time.Duration)

	// Journal, when set, writes one node_briefed event per briefed node as the
	// brief pass lands — the rendered instruction, the sufficiency sentence
	// (Spec.Done) — so a run's stopping condition is
	// queryable from its own artifacts rather than only as a field inside the
	// plan blob. The caller forms the store id; see BriefJournal. Nil leaves
	// briefs exactly as durable as they were before this existed, which is the
	// one-shot `codeaf plan` path and every caller with no store to journal to.
	Journal BriefJournal
}

type Panel struct {
	Mode   string `json:"mode"`
	Reason string `json:"reason"`

	PassTitle   string   `json:"pass_title"`
	PassSummary string   `json:"pass_summary"`
	PassSources []string `json:"pass_sources"`

	SetupTitle   string `json:"setup_title"`
	SetupSummary string `json:"setup_summary"`

	Deliverable string `json:"deliverable"`
}

type Point struct {
	Behaviour string `json:"behaviour"`
	Quote     string `json:"quote"`
	// Kind is PointBehaviour or PointAction. It is omitempty and normalised to
	// PointBehaviour when it is neither, so a point written before this field
	// existed — a rehydrated plan, a journal row, a caller in another package —
	// is still mapped and still counted, which is the fail-safe direction: the
	// cost of reading an action as a behaviour is one false finding, and the
	// cost of reading a behaviour as an action is a stated requirement nothing
	// ever checks.
	Kind string `json:"kind,omitempty"`
}

type Progress func(ProgressUpdate)

type ProgressUpdate struct {
	Phase  string `json:"phase"`
	Done   int    `json:"done"`
	Total  int    `json:"total"`
	Latest string `json:"latest"`
}

type Reach struct {
	Dir   string
	Bytes int
}

type Report func(pass string, elapsed time.Duration, detail string)

type Satisfaction struct {
	Complete  bool        `json:"complete"`
	Uncovered []Uncovered `json:"uncovered,omitempty"`
}

type Settlement struct {
	// Variable names what the goal left free — "the three cities", "the vendors
	// compared", "the period covered".
	Variable string `json:"variable"`
	// Values are what it is bound to, by name. Empty means nothing was bound,
	// which is not a settlement however it is worded.
	Values []string `json:"values"`
}

type Size string

type SkillEntry struct {
	Name      string
	Doc       string
	ShelfPath string

	// BodyInPath says ShelfPath is the skill's readable body — the SKILL.md of
	// an agentskills folder — rather than a directory holding something to
	// run. The render says so in the line itself, because a worker handed a
	// bare path cannot tell a file it should read from a directory it should
	// run things out of, and `read` refuses a directory outright.
	BodyInPath bool
}

type Spec struct {
	Instruction string   `json:"instruction,omitempty"`
	Method      string   `json:"method,omitempty"`
	Done        Done     `json:"done,omitzero"`
	Sources     []string `json:"sources,omitempty"`
	// Accept is the acceptance checklist: the behaviours the REQUEST states,
	// read from the request before any work existed. Done is the criterion the
	// planner wrote about what the work will produce; this is what the person
	// asked for, and the two are different objects because they answer to
	// different authors. See accept.go.
	//
	// It travels here rather than beside the gate for the reason Done does: this
	// is the one object in the system carried forward verbatim through a retry
	// (RetargetSpec), so a repair round is judged against the same checklist its
	// predecessor was. Render deliberately omits it — the worker is never shown
	// the list it will be checked on.
	Accept []Point `json:"accept,omitempty"`
	// Constraints are the rules the person stated about what the run may or may
	// not DO. Unlike Accept, which belongs to the node that delivers, these are
	// stamped on every node of the job: the person said it about the run, so
	// every worker the run starts is under it. See constraint.go, and Render
	// below, which puts them FIRST.
	Constraints []Constraint `json:"constraints,omitempty"`
}

type SpineChoice struct {
	Stages  []Stage
	Samples int
	Drawn   []int // stage count of each sample as written, ascending
	Spread  []int // stage count of each sample after levelling, ascending
	Agreed  bool  // every sample proposed the same number of stages
}

type SplitVerdict struct {
	Divide bool
	Reason string
}

type Stage struct {
	Title   string `json:"title"`
	Summary string `json:"summary"`
	Needs   []int  `json:"needs,omitempty"`
}

type State string

type Uncovered struct {
	Condition string `json:"condition"`
	Missing   string `json:"missing"`
}

type Usage struct {
	Calls            int     `json:"calls"`
	PromptTokens     int     `json:"prompt_tokens"`
	CompletionTokens int     `json:"completion_tokens"`
	CachedTokens     int     `json:"cached_tokens"`
	Cost             float64 `json:"cost"`
}