store

type Acceptance struct {
	Points []AcceptancePoint `json:"points"`
}

type AcceptancePoint struct {
	Behaviour string `json:"behaviour"`
	Quote     string `json:"quote"`
	// Kind is "behaviour" or "action" — whether this point is something the
	// finished work must be, or something the RUN does on the way. It is the
	// classification the settlement acts on, and it is journaled so an autopsy
	// of a run whose coverage finding fired on nothing checkable can see which
	// way each point was read. Empty on a row written before the reading
	// existed, which every reader takes as behaviour.
	Kind string `json:"kind,omitempty"`
}

type AgentQuestion struct {
	Seq              int64
	SessionID        string
	Text             string
	OriginNodeID     string
	OriginCharterID  string
	OriginCommandSeq int64
	Urgency          QuestionUrgency
	Class            QuestionClass
	Status           AgentQuestionStatus
	Options          []QuestionOption
	Category         QuestionCategory
	DefaultAnswer    string
	CreatedAt        time.Time
	AskedAt          time.Time
	ResolvedAt       time.Time
	ExpiresAt        time.Time
	Resolution       string
	AskedMessageSeq  int64
	AnswerMessageSeq int64
	UpdatedSeq       int64
}

type AgentQuestionStatus string

type ArtifactPart struct {
	Path string `json:"path"`
	MIME string `json:"mime,omitempty"`
	// Bytes is the length of the file at the moment it was referenced.
	Bytes int64 `json:"bytes,omitempty"`
	// NodeID is the work this artifact came out of, empty when the head made it
	// directly in conversation.
	NodeID string `json:"node_id,omitempty"`
}

type AsidePart struct {
	Question string `json:"question"`
	Answer   string `json:"answer"`
	// Model is what served the answer, recorded for the same reason a reply
	// records it: an aside is a real provider call that really cost money, and
	// "which model said that" is unanswerable afterwards without this.
	Model string `json:"model,omitempty"`
}

type BindingScope string

type Brief struct {
	SinceSeq      int64 `json:"since_seq"`
	ThroughSeq    int64 `json:"through_seq"`
	Done          int   `json:"done,omitempty"`
	Failed        int   `json:"failed,omitempty"`
	Cancelled     int   `json:"cancelled,omitempty"`
	Questions     int   `json:"questions,omitempty"`
	CharterFired  int   `json:"charter_fired,omitempty"`
	FactsLearned  int   `json:"facts_learned,omitempty"`
	SkillsLearned int   `json:"skills_learned,omitempty"`
	// Waiting counts the standing rows — what is stopped on the user now, not
	// what happened in the window. Every other total is a fact about the past.
	Waiting int         `json:"waiting,omitempty"`
	CostUSD float64     `json:"cost_usd,omitempty"`
	Items   []BriefItem `json:"items"`
}

type BriefItem struct {
	Kind BriefItemKind `json:"kind"`
	Body string        `json:"body"`
	Ref  string        `json:"ref,omitempty"`
}

type BriefItemKind string

type CardPart struct {
	NodeID string `json:"node_id"`
}

type CategoryStats struct {
	Category       QuestionCategory
	N              int
	Accepted       int
	Different      int
	AcceptanceRate float64
	MeanReworkCost float64
	ExpectedRegret float64
}

type ChangedDefinition struct {
	Name string `json:"name"`
	File string `json:"file,omitempty"`
	// Sites is how many usage sites were found outside the lines this run
	// changed, and Shapes is those sites grouped by what they DO with the name.
	Sites  int             `json:"sites"`
	Shapes []ConsumerShape `json:"shapes,omitempty"`
}

type ChannelSurvival struct {
	Kind        FactKind
	Channel     FactChannel
	N           int
	Survived    int
	Reversed    int
	Raw         float64
	Global      float64
	Credibility float64
}

type Charter struct {
	ID            string
	Invariant     string
	Watch         WatchSpec
	SentinelHint  string
	Action        CharterAction
	Status        CharterStatus
	Autonomy      CharterAutonomy
	GreenFirings  int
	Demotions     int
	Ratification  Ratification
	ProposalShape string

	// Spec and the adjacent fields are the head's lossless ratification card.
	// The structured engine fields above remain the executable source of truth.
	SessionID        string
	Spec             CharterSpec
	SourceCommandSeq int64
	CreatedAt        time.Time

	LastWake time.Time
	// LastChecked and LastCheckLine are the quiet half of a standing watch: the
	// moment a sentinel last looked, and the sentence it wrote when it did.
	// Both were journaled and neither was ever materialized or read, so a watch
	// that had checked faithfully for thirty mornings and correctly found
	// nothing rendered byte-identically to a watch that had never run once —
	// "last fired never · 0 today". Diligence and death are not the same state
	// and the user must be able to tell them apart without being told anything
	// on the days there is nothing to tell.
	LastChecked     time.Time
	LastCheckLine   string
	NextDue         time.Time
	WakeSeq         int64
	WakePending     bool
	SentinelYes     bool
	WakeEvidence    string
	FileFingerprint string
	GraphCursor     int64
	GraphDay        string
	GraphTriggered  bool
	CreatedSeq      int64
	UpdatedSeq      int64
	// contains filtered or unexported fields
}

type CharterAction struct {
	Template string `json:"template"`
	SayOnly  bool   `json:"say_only,omitempty"`
}

type CharterAutonomy string

type CharterFiringAssessment struct {
	CharterID string
	WakeSeq   int64
	JobID     string
	Decided   bool
	Success   bool
	Reason    string
	CostUSD   float64
}

type CharterRails struct {
	PerFiringBudgetUSD float64    `json:"per_firing_budget_usd"`
	MaxFiringsPerDay   int        `json:"max_firings_per_day"`
	ExpiresAt          *time.Time `json:"expires_at,omitempty"`

	// Compiler-facing standing drafts predate the M3 execution rails. These
	// fields preserve that public contract; NewCharter uses the fields above.
	EstimatedCostUSD       float64 `json:"estimated_cost_usd,omitempty"`
	MaxPerDay              int     `json:"max_per_day,omitempty"`
	MaxPerDayJustification string  `json:"max_per_day_justification,omitempty"`
	Expiry                 string  `json:"expiry,omitempty"`
}

type CharterSpec struct {
	Invariant string           `json:"invariant"`
	Watch     CharterWatch     `json:"watch"`
	Sentinel  string           `json:"sentinel"`
	Action    string           `json:"action"`
	SayOnly   bool             `json:"say_only,omitempty"`
	Rails     CharterSpecRails `json:"rails"`
}

type CharterSpecRails struct {
	EstimatedCostUSD       float64 `json:"estimated_cost_usd"`
	MaxPerDay              int     `json:"max_per_day"`
	MaxPerDayJustification string  `json:"max_per_day_justification"`
	Expiry                 string  `json:"expiry"`
}

type CharterStatus string

type CharterWatch struct {
	Kind     WatchKind `json:"kind"`
	Cadence  string    `json:"cadence"`
	Schedule string    `json:"schedule,omitempty"`
	Spec     WatchSpec `json:"spec,omitempty"`
}

type CharterWatchState struct {
	NextDue         time.Time `json:"next_due"`
	FileFingerprint string    `json:"file_fingerprint,omitempty"`
	GraphCursor     int64     `json:"graph_cursor,omitempty"`
	GraphDay        string    `json:"graph_day,omitempty"`
	GraphTriggered  bool      `json:"graph_triggered,omitempty"`
}

type Claim struct {
	ID    string
	Owner string
	Token uint64
}

type Command struct {
	Seq       int64
	Time      time.Time
	SessionID string
	Kind      CommandKind
	// Issuer names who asked — see issuer.go. Empty is the legacy value and
	// reads as IssuerUser, which is what every command written before the axis
	// existed actually was.
	Issuer CommandIssuer
	// Reflex asks the reconciler to admit exactly one verbatim micro-leaf
	// without compiling or planning it. It remains a splice command so a
	// promotion can enqueue the ordinary path with the same instruction.
	Reflex bool
	// Fresh is the person asking for this one to be worked out from scratch
	// rather than the way it has been done before. It is a reading of what they
	// meant — "don't use the template this time", "plan this one properly" —
	// made where every other reading of a message is made, and carried here
	// because the engine that would reach for learned know-how runs long after
	// the sentence is gone.
	Fresh bool
	// Deliberate is the person saying, in so many words, that this ask runs
	// BESIDE work already under way — the one override on the duplicate guard
	// in admission.go. It is transient: no column, no replay, no meaning past
	// the moment of admission, because what it records is a fact about the
	// sentence rather than a property of the work.
	Deliberate bool
	Target     string
	// Instruction is the ASK: the person's words for this piece of work and
	// nothing else. Everything that treats a command as "what they said" reads
	// this field, which is why the conversation a fork inherits is no longer
	// allowed anywhere near it (ask.go).
	Instruction string
	// Context is the conversation this ask came out of, carried so PLANNING is
	// well-informed. It is evidence about what the ask meant, never more ask:
	// see [Command.Brief], which is the only composition of the two, and the
	// only reader of it is the compiler.
	Context     string
	Attachments []string
	Status      CommandStatus
	Result      string
	UpdatedSeq  int64
}

type CommandIssuer string

type CommandKind string

type CommandStatus string

type CompetenceClass string

type CompetenceMap struct {
	Scopes []ScopeCompetence `json:"scopes"`
}

type CompetenceOptions struct {
	Profile    *profile.Profile
	Thresholds *CompetenceThresholds
	Now        time.Time
}

type CompetenceThresholds struct {
	EstablishedSamples int
	StrongFailureBelow float64
	FrontierFailureMin float64
	FrontierFailureMax float64
	WeakFailureAbove   float64
	LowSurpriseMax     float64
	TrendWindow        int
	TrendMinSamples    int
	TrendDelta         float64
	StaleAfter         time.Duration
}

type ConsumerShape struct {
	Shape  string   `json:"shape"`
	Count  int      `json:"count"`
	Sample []string `json:"sample,omitempty"`
}

type ConsumersReading struct {
	// Weighed is how many changed definitions were read. Zero with no rows is a
	// real answer — the run touched no declaration this program can read — and
	// it is not the same answer as no row at all.
	Weighed int                 `json:"weighed"`
	Changed []ChangedDefinition `json:"changed,omitempty"`
}

type ConversationHit struct {
	MessageHit
	// Title is the conversation's name (internal/session's title.go, kept in the
	// sessions table). Empty for a thread nobody has named yet, or one that
	// posted messages without ever opening a session row — which is unknown and
	// not "untitled": a page draws the project or the first line instead, and
	// never a word this store made up.
	Title string
}

type CorrectionStyleValue struct {
	Style              string  `json:"style"`
	MeanLatencySeconds float64 `json:"mean_latency_seconds"`
}

type CostCardT struct {
	RunTokens      int64 `json:"run,omitempty"`
	ReadTokens     int64 `json:"read,omitempty"`
	DelegateTokens int64 `json:"delegate,omitempty"`
}

type CraftForged struct {
	Name    string `json:"name"`
	Commit  string `json:"commit,omitempty"`
	Refined bool   `json:"refined,omitempty"`
	// Because is the evidence line the commit carries, kept short. It is what
	// lets a digest say what the new version answers without a git call.
	Because string `json:"because,omitempty"`
}

type CronKind string

type CronSchedule struct {
	Kind     CronKind `json:"kind"`
	Interval int      `json:"interval,omitempty"`
	Hour     int      `json:"hour,omitempty"`
	Minute   int      `json:"minute,omitempty"`
	// Weekday is read only by CronWeekly. Sunday is the zero value, so a
	// weekly schedule on a Sunday round-trips through JSON without the field.
	Weekday time.Weekday `json:"weekday,omitempty"`
	At      time.Time    `json:"at,omitempty"`
}

type DailyRail struct {
	Base      float64
	Raised    float64
	Spend     float64
	Pending   float64
	Ceiling   float64
	Unlimited bool
	Reached   bool
}

type DefaultAcceptanceValue map[QuestionCategory]struct {
	Rate float64 `json:"rate"`
	N    int     `json:"n"`
}

type DeferredOverrun struct {
	Seq       int64    `json:"-"`
	NodeID    string   `json:"-"`
	Partial   string   `json:"partial,omitempty"`
	Gap       string   `json:"gap,omitempty"`
	Artifacts []string `json:"artifacts,omitempty"`
	Prefix    string   `json:"prefix"`
	// State is the dead leaf's structured findings, carried across the rail
	// for the same reason everything else here is: the continuation needs it
	// to resume rather than restart, and a repair that resumed without it
	// would re-read everything the dead leaf already diagnosed.
	State string `json:"state,omitempty"`
}

type DeliveryGate struct {
	Pass         bool     `json:"pass"`
	Gap          string   `json:"gap,omitempty"`
	PolishClosed bool     `json:"polish_closed"`
	Quote        string   `json:"quote,omitempty"`
	Quotes       []string `json:"quotes,omitempty"`
	Round        int      `json:"round,omitempty"`
	Extended     bool     `json:"extended,omitempty"`
	Refused      string   `json:"refused,omitempty"`
	Mechanical   bool     `json:"mechanical,omitempty"`

	// Finding names WHICH MEASUREMENT raised this gap — `regression`,
	// `own-checks-failing`, `removed-public-name`, `removed-checks` — and
	// Quotes above holds the names it cited. Empty where a model judge read the
	// request rather than the world.
	//
	// The pair is what makes a finding comparable ACROSS ROUNDS, and until it
	// existed the only identity a finding had was its sentence — with a bounded
	// list of names glued into the middle, so one finding raised over two
	// different tails read as two. happy-dom's v4-flash s13 raised the identical
	// removed-checks finding on four consecutive rounds, each round bought a
	// repair, no repair could close it, and no reader of this event could say
	// the four were one thing (2026-08-29, bench/deepswe).
	Finding string `json:"finding,omitempty"`

	// Unclosed says the gap STANDS: the repair that would have closed it was
	// never bought, so nothing ran and nothing about the shortfall changed.
	//
	// It is the distinction the exit code turns on, and it is recorded rather
	// than read out of the refusal sentence because those are two categorically
	// different refusals wearing the same field. A gap refused as ungrounded, or
	// as one somebody already paid to close, is the GATE being wrong and caught
	// at it — the deliverable stands whole. A gap whose repair a governor would
	// not fund, or that nothing could plan, is the gate being RIGHT and
	// unaffordable: the thing it named is still missing, and a run that hands
	// that over is handing over less than it promised. One measured run shipped
	// "Deliverable is empty - contains no implementation" over exit 0 because
	// the two were one field (2026-08-28, meta/muse-spark-1.1).
	Unclosed bool `json:"unclosed,omitempty"`

	// Unjudged says NOBODY EVER READ THIS DELIVERY. The gate was asked and could
	// not be reached — a dead route, a refused account, a service that was down —
	// so the work shipped with no verdict behind it at all.
	//
	// It is a field of its own beside Refused because the two refusals it
	// separates are what a battery comparing runs has to tell apart. `{Refused,
	// Unclosed}` on its own is the gate that was NEVER ASKED: the harness stopped
	// spending once nothing was changing, and declined to buy a judgement. This
	// one was asked, twice where the wall allowed it, and the answer never came
	// back. A run that declined to check and a run whose checker was unreachable
	// are different facts about the same missing verdict, and a rig that reads
	// one row for both learns nothing from either.
	//
	// It was measured costing two graded runs their whole meaning. reef-145's
	// repair leaf finished its work, both of the gate's calls were refused 404,
	// the door ended `ok` at exit 0, and the store held no gate row for the
	// delivered leaf at all — so the rig compared an unchecked delivery against
	// runs that had been judged and read it as a clean pass (2026-09-02,
	// codeaf-14 anchor 1; #514). Whole below spends it, so the exit code
	// cannot report a delivery nobody read as one that stands.
	Unjudged bool `json:"unjudged,omitempty"`

	// Overturned says the refusal was CHECKED AGAINST THE WORLD and the finding
	// lost: the file the review says is missing is on disk under the name the
	// request used, or the things it says are absent are in the delivered text.
	//
	// It is the other half of the distinction Unclosed opened, and it is the one
	// the exit code should have been reading all along. Refused holds refusals
	// of two categorically different kinds. One looks at the filesystem or at
	// the deliverable and finds the review wrong — that acquits, and charging it
	// a non-zero code would teach a harness to distrust the gate's own
	// corrections. The other looks only at where the review's words came from
	// and declines to BUY a round; it settles nothing about whether the work
	// landed, because no ruling on a citation makes missing work appear.
	//
	// Recorded rather than inferred from the sentence, for the reason every
	// other field here is: the exit code turns on it, and a sentence is not a
	// field. Seven of eight measured runs exited 0 over a provenance refusal
	// while the review that named the missing work was right every time
	// (2026-08-28, bench/deepswe; see docs/design/gate/SETTLEMENT.md §2).
	//
	// THE WORLD IS THE DISK, A READING, OR THE RECORD — NEVER THE DELIVERABLE'S
	// OWN PROSE. The deliverable is the component the gate is checking, and a
	// refusal that reads it is FAILSAFE clause 2 broken in the strict sense the
	// clause states it. One measured run set this field because the words of the
	// request appeared in a summary the worker had written about work it had not
	// done, and shipped 1 of 20 hidden checks over exit 0 (2026-08-29,
	// bench/deepswe textual s5; SETTLEMENT.md §6). The delivered text may settle
	// a finding only where it IS the whole of what the run left behind — a
	// question answered in prose, whose message is its own artifact.
	Overturned bool `json:"overturned,omitempty"`

	// Unmoved says the repair round that was judged here LEFT THE TREE EXACTLY AS
	// THE FINDING FOUND IT: same files, same sizes, same modification times, stamped
	// on either side of the round.
	//
	// It is recorded because it is the fact that explains a PolishClosed which is
	// absent — and, on the runs that made this necessary, one which is present and
	// should not have been. A composed repair (revision.Compose) rewrites the
	// account of work that already landed and runs nothing, so it cannot change what
	// the world says; ink s5 and ofetch s5 both composed a better summary over a
	// finding about the substance of the work, were re-judged on the summary, and
	// settled whole at 7 of 25 and 44 of 47 hidden checks (2026-08-29,
	// bench/deepswe; docs/design/gate/SETTLEMENT.md §8).
	//
	// A round that moved nothing may still close a finding whose only ground was the
	// delivered text — that is what writing can honestly fix — so this is a fact
	// about the round and never a verdict on its own. The verdict is PolishClosed,
	// which the wiring sets only where the two agree.
	Unmoved bool `json:"unmoved,omitempty"`

	// Exercised is the acceptance mapping as the gate settled it: one row per
	// behaviour the request stated, naming the check that exercises it, or
	// naming nothing when no check does.
	//
	// It is recorded rather than reduced to the finding it produced, because the
	// mapping is the evidence and the finding is only its conclusion. A run that
	// passed with every point exercised and a run that passed because the
	// checklist was empty are the same event without it, and telling those two
	// apart is the whole of what an autopsy of this mechanism has to do.
	Exercises []ExercisedPoint `json:"exercises,omitempty"`

	// Unexercised is the behaviours the request stated that no check exercises,
	// one entry per line of the request they were read from.
	//
	// It is the FINDING; Exercised above is the evidence it is a conclusion of.
	// They are two fields because a mapping with three empty rows and a finding
	// naming three behaviours are the same fact only to a reader who already
	// knows this mechanism exists, and the person watching the run is not that
	// reader. igel s6 journaled the mapping and never the finding: the gate event
	// carried "exercises: 17 rows, 3 unmapped" and the coverage gap survived only
	// as a paragraph inside `gap`, where the stream's own line — firstLine(gap) —
	// could not reach it and no repair round was ever aimed at it.
	Unexercised []string `json:"unexercised,omitempty"`

	// Unasserted is the behaviours the request stated that a check NAMES and no
	// assertion WEIGHS, one entry per line of the request they were read from,
	// each naming the observables nothing asserted.
	//
	// It is a finding of its own beside Unexercised because the two are answered
	// by different evidence and a repair round is aimed at them differently.
	// Unexercised says write a check; this says the check you wrote runs the
	// behaviour and asserts nothing about it, and names which identifier to
	// assert on. textual s13's gate had said `no check exercises:
	// RichLog.write(expand=True) …` in round one; round two wrote a check that
	// called `write("short", expand=True)` and asserted `len(lines) > 0`, the
	// mapping paired the two, and the run passed at exit 0 with the hidden check
	// for that behaviour red.
	//
	// It stands exactly as Unexercised does — it leaves the delivery short in
	// Whole below, and it empties the one way a measurement empties: a later
	// reading finds an assertion that names the observable.
	Unasserted []string `json:"unasserted,omitempty"`

	// OwnFailing is the checks THIS WORK WROTE that are red: names the baseline
	// roster never held, so nothing that was working stopped.
	//
	// It is a field beside Unexercised rather than prose inside Gap because the
	// distinction it carries is the one happy-dom's nemotron n1 run lost. That
	// gate read `This work broke checks that were passing before it:
	// IntersectionObserver initial observation queuing …` over eighteen checks
	// the run had written that hour, on a tree the grader scored 9 of 9. A run
	// that broke the repository and a run that has not finished its own tests
	// are two different states, and an autopsy with one list could not tell them
	// apart.
	OwnFailing []string `json:"own_failing,omitempty"`

	// Unmeasured says the gate held a checklist and could settle none of it:
	// the project declares no verification this run could read and the change
	// produced no readable diff, so nothing could be matched to what the
	// request asked for.
	//
	// It is a field rather than a silence because NOBODY LOOKED IS NOT NOTHING
	// WRONG, and the two are the same event without it. A delivery that
	// satisfied every point and one that was measured against nothing both
	// journal a passing gate; only this tells them apart, and an autopsy of
	// this mechanism has nothing else to read.
	Unmeasured string `json:"unmeasured,omitempty"`

	// Unreadable says the project DECLARED a way of checking itself and this run
	// could not read it. It is the half of Unmeasured that leaves the delivery
	// short, and it is what Whole below spends.
	Unreadable bool `json:"unreadable,omitempty"`

	// Consumers is the finding the changed-definition reading produced: one line
	// per definition this run reshaped that the rest of the project still uses,
	// naming the shape its callers expect and how many of them there are.
	//
	// It is the FINDING; EventConsumers is the evidence it is a conclusion of,
	// and they are two records for the reason Unexercised and Exercises are two:
	// a finding that lives only as a paragraph inside `gap` is journaled by
	// nothing and reachable by nothing. igel s12 changed `configs` from a dict
	// to an instance of a class it wrote and the whole store held not one word
	// about it (2026-08-29, bench/deepswe).
	Consumers []string `json:"consumers,omitempty"`

	// Unbound is the finding the unbound-reference reading produced: one line
	// per name the run's own sources READ that nothing in the tree binds, each
	// naming the file and line it is read at.
	//
	// It is a field beside Consumers because it is the same kind of fact one
	// question further back. Consumers is a name that exists and no longer
	// answers to how it is used; this is a name that does not exist at all —
	// igel s14 imported `temp_post_req_data_path` from a module that had stopped
	// binding it, and the run's whole record of that was that its own checks
	// were red, never WHICH name was missing (2026-08-29, bench/deepswe).
	Unbound []string `json:"unbound,omitempty"`

	// Subject is WHAT THIS GATE JUDGED, in the words the gate keeps them:
	// "tree (6 files)" where the run changed the repository and the change was
	// the deliverable, "claim" where the run left nothing behind and the
	// worker's message was the whole of what it produced.
	//
	// It is a field because an autopsy has nothing else to read. Three gates on
	// one run refused a delivery for what the worker's final MESSAGE was — "the
	// fenced text contains only {"contract": …}" — while forty-two kilobytes of
	// changed Python sat in the worktree and the artifact record named every
	// file of it (2026-08-29, bench/deepswe textual-richlog-follow-state
	// nemotron n1). Afterwards those three events were indistinguishable from
	// three refusals over a real reading of the world, and the only way to tell
	// was to reconstruct the prompt from the transcript.
	//
	// Empty on every gate journaled before this existed, which reads as
	// unrecorded rather than as either answer.
	Subject string `json:"subject,omitempty"`

	// HeldPoint is WHICH BEHAVIOUR OF THE REQUEST this gate was held to: the
	// span a refusal was built on, the size of the list a pass was weighed
	// against, or "checklist: empty" where the request states none and the
	// requirement was off.
	//
	// Subject says what the gate read; this says what it was allowed to
	// convict on. textual v4-flash s13 journaled two gates with the subject
	// right and the quote a verbatim behaviour of the request, and nothing in
	// the event could tell whether the quote had passed the checklist or there
	// had been no checklist to pass — the mechanism working and the mechanism
	// switched off, wearing one event.
	//
	// Empty on a claim-subject gate, where there is no such list, and on every
	// gate journaled before this existed.
	HeldPoint string `json:"held_point,omitempty"`

	// Constraint is the rules the person SET that this work broke, one entry
	// per rule: their own words, then the files the run changed in spite of
	// them. It is the finding of a gate law rather than of a review — the words
	// are the person's by construction, so there is no citation to weigh — and
	// it is a list of its own for the reason Unexercised is one: a finding that
	// travels as prose inside somebody else's gap is journaled by nothing and
	// reachable by nothing.
	//
	// A delivery carrying one is not whole, and no round is bought to close it:
	// the work did the thing it was told not to do, and more work is not the
	// answer to that. See revision.HoldConstraints and revision.ExtendForGap.
	Constraint []string `json:"constraint,omitempty"`

	// Receipt is the positive sentence this delivery earned, in the words the
	// person reads: that the request was met as stated, or that the work's own
	// checks were green and coverage could not be measured.
	//
	// IT IS THE OPPOSITE OF EVERY OTHER FIELD ON THIS ROW, which is why it is
	// one. Everything else here says what a gate found wanting; a run that ends
	// because the thing that was asked for is in hand has a fact of its own to
	// record, and without it a delivery that stopped for the right reason and
	// one that stopped because the rounds ran out are the same event. It is
	// deliberately NOT read by Whole below: a receipt is a statement about why
	// the run ended, and whether the delivery is whole is still settled by the
	// pass, the repair and the world-doors exactly as it was.
	Receipt string `json:"receipt,omitempty"`

	// Missing is what the request asked for that the request-met question found
	// absent, in the request's own words, on a run where that question was put
	// and answered no.
	//
	// It rides beside the gap rather than inside it. The gap is the judge's
	// finding and a repair round is briefed with it verbatim; folding a second
	// reader's sentence into that string would hand the round a requirement
	// nobody weighed against the person's words, which is the laundering the
	// admission rules exist to prevent.
	Missing string `json:"missing,omitempty"`
}

type DependencyFanIn struct {
	Count int
	Bytes int
}

type DependencyInput struct {
	NodeID    string
	Digest    string
	Artifacts []string
	// Handle is the absolute path of a file holding this dependency's complete
	// text, and it is set exactly when the digest above is short of it.
	//
	// It was written on the belief that pushing was what cost 37× — that a
	// window-sized pot had been handing every join every upstream result in
	// full. That belief was wrong, and the measurement says so: the join that
	// billed 163k tokens was handed 2.3 KB, and this field was never once set in
	// either benchmark run, because a fan-in of one-sentence summaries is never
	// large enough to overrun anything. What actually cost was the opposite, the
	// pulling: a consumer handed paths instead of results went and read them.
	//
	// So the digest carries the product now, and this is what remains true of
	// the handle: a fan-in genuinely too large for its reader is clipped, and
	// every withheld byte is one ordinary path away instead of gone. It is the
	// exception it was always meant to be rather than the rule it silently was.
	//
	// The path is content-addressed, so the same settled result yields the same
	// handle on every read: a prompt prefix built from these does not move
	// underneath a cache that is counting on it not moving.
	Handle string
}

type Edge struct {
	From         string
	To           string
	Kind         EdgeKind
	CreatedSeq   int64
	CreatedOrder int
}

type EdgeKind string

type EndKind string

type EndedPart struct {
	How          EndKind `json:"how"`
	FinishReason string  `json:"finish_reason,omitempty"`
}

type ErrandSpend struct {
	Work   SpendSlice
	Spine  SpendSlice
	Shared bool
}

type Event struct {
	Seq     int64
	Time    time.Time
	NodeID  string
	Kind    EventKind
	Payload json.RawMessage
}

type EventKind string

type ExercisedPoint struct {
	Point string `json:"point"`
	Check string `json:"check,omitempty"`

	// Observables is what the behaviour was weighed against: the identifiers the
	// request spelled, bound, or named in words against the tree's own public
	// surface. It is journaled beside the finding because the RESOLUTION is the
	// half an autopsy cannot reconstruct — "vertical scrollbar position" became
	// `ScrollBar.position` by a reading of a tree that has since moved on, and
	// without the row there is no way to ask whether the door was asking about
	// the right thing at all.
	Observables []string `json:"observables,omitempty"`

	// Unasserted is the behaviour's own observables — the identifiers the
	// request spelled — that the mapped check's ASSERTIONS never name. A row
	// with a check and an unasserted list is a pairing the world admits and the
	// check does not earn: the check runs the behaviour and weighs nothing about
	// it.
	//
	// It is journaled beside the pairing rather than reduced to the finding it
	// produces, for the reason Exercises itself is. textual s13 shipped at exit
	// 0 with three such rows, and afterwards there was no way to ask which
	// observable had been skipped — `expand` and `min_width` were named in the
	// request, called in the check, and asserted nowhere, and the mapping said
	// only that a check existed. See revision.WeighAssertions.
	Unasserted []string `json:"unasserted,omitempty"`
}

type ExplorationToleranceValue struct {
	TrialCorrectionRate float64 `json:"trial_correction_rate"`
	PlainCorrectionRate float64 `json:"plain_correction_rate"`
	Tolerance           float64 `json:"tolerance"`
}

type Fact struct {
	Seq          int64
	Time         time.Time
	NodeID       string // the node whose work taught this
	Scope        string // what it is about: user, env, tool:x, repo:/p, file:/p/f, domain:x
	Kind         FactKind
	Channel      FactChannel
	Body         string
	Status       string
	StatusSeq    int64
	EvidenceSeq  int64
	StatusOrigin FactChangeOrigin

	// Unsettled is present only when Kind is FactUnsettled. Body is its
	// readable projection; this payload is what code branches on.
	Unsettled *UnsettledPair

	// Artifact points at a skill candidate's teaching directory, then at its
	// installed directory after execution promotion. StatusNote records why a
	// candidate or active skill was retired.
	Artifact   string
	StatusNote string

	// Uses and LastUsed are retrieval telemetry for consolidation, not
	// journaled truth: Rebuild resets them, deliberately, and so does the facts
	// migration. Nothing ranks on them — a value the journal cannot rebuild may
	// inform a human reading the table, never a retrieval deciding what a model
	// sees. FactOutcomes answers "has this been useful" from the journal.
	Uses     int
	LastUsed time.Time
	// Confidence is the current shrunk survival rate for Kind x Channel.
	Confidence float64

	// Trust is the provenance tier for skill facts: "authored" (default),
	// "imported-provisional", or "forged". Empty is stored and read back as
	// "authored" by SkillFactAccessors.
	Trust string
	// CostCard is the measured token budget for read/run/delegate operations.
	CostCard CostCardT
	// Digest is the content-addressable digest of the payload directory,
	// computed at install time from all files' contents.
	Digest string
}

type FactChangeOrigin string

type FactChannel string

type FactKind string

type FactOutcome struct {
	FactSeq      int64
	Rides        int
	Bad          int
	LatestBadSeq int64
}

type FactQuery struct {
	// Cues are scope keys to match exactly, in priority order — the caller
	// walks hierarchies (file → folder → repo) into this list.
	Cues []string
	// Terms feed FTS5/BM25 and may be empty.
	Terms string
	// Kind restricts retrieval to one fact kind. Empty includes every kind.
	Kind FactKind
	// PreferUseful orders proven matches first and newest matches next: a fact
	// that has ridden into real work and come back without a failed gate
	// outranks one that has not. Scope cue order remains the primary match
	// signal when this is false.
	PreferUseful bool
	// MaxBytes bounds the returned scope-and-body bullet lines. Zero is
	// unbounded; the small per-line allowance covers "- [scope] body\n".
	MaxBytes int
	Limit    int
}

type FactWriter string

type FileWatch struct {
	Glob    string        `json:"glob"`
	Cadence time.Duration `json:"cadence"`
}

type FireDisposition string

type GraphPredicate string

type GraphWatch struct {
	Predicate    GraphPredicate `json:"predicate"`
	Title        string         `json:"title,omitempty"`
	Scope        string         `json:"scope,omitempty"`
	ThresholdUSD float64        `json:"threshold_usd,omitempty"`
	Cadence      time.Duration  `json:"cadence"`
}

type GrowthFinding struct {
	Kind  string `json:"kind,omitempty"`
	Names string `json:"names,omitempty"`
}

type JobGrowth struct {
	Reason  string `json:"reason"`
	Lineage string `json:"lineage,omitempty"`
	Adding  int    `json:"adding,omitempty"`
	Round   int    `json:"round"`
	Allowed bool   `json:"allowed"`
	Refused string `json:"refused,omitempty"`
	// Cause is the machine-readable half of Refused: which governor spoke.
	Cause string `json:"cause,omitempty"`

	// Produced is how many files the work this round grows FROM left behind
	// THAT THIS JOB IS ABOUT — the workspace's own before-and-after reading,
	// narrowed to the change's own focus, and never the worker's account of
	// itself. It is journaled because it is the only evidence the next round
	// can be weighed against: a lineage whose last two bodies of work both
	// changed nothing relevant is not making slow progress, it is at a
	// standstill, and no round after that buys anything.
	//
	// IT COUNTS WHAT MATTERS AND NOT WHAT MOVED. It used to be every path the
	// tree gained, which is a count a stuck model raises for free: ink s10
	// spent its whole 5400-second wall over eight exhaustions of one lineage
	// while the only thing any round wrote was `debug-grid.ts`,
	// `debug-grid10.ts`, `debug-yoga.ts` and eleven more of the same beside a
	// change that never moved. Every one of those is a file, so every round
	// looked productive to a detector asking "did anything change" — and the
	// standstill rule, which was right, never got a chance to speak.
	Produced int `json:"produced,omitempty"`

	// Scratch is the rest of what the round wrote: files outside the focus,
	// which are not progress and are not nothing either.
	//
	// It is a separate count rather than a subtraction because the two facts
	// answer different questions. Produced answers "did this round move the
	// work"; this answers "then what WAS it doing", and a person reading a
	// refusal is owed the second — a round that wrote fourteen files and moved
	// none of them is a specific, recognisable failure and the count is what
	// makes it recognisable.
	Scratch int `json:"scratch,omitempty"`

	// Moved names the files inside the focus that the round did change, bounded
	// the same way. It is what the run's closing line points at when it says
	// what the last real change was — a person told "nothing has moved for
	// three rounds" is owed the name of the last thing that did.
	Moved []string `json:"moved,omitempty"`

	// Wrote names those files, bounded. The count says a round wrote nothing
	// that mattered; this says WHAT it wrote instead, which is the whole of
	// what an autopsy of a fruitless round has to work with — and it was, in
	// s10, only recoverable by reading resume payloads out of the transcript.
	Wrote []string `json:"wrote,omitempty"`

	// Unexercised, Red and Standing are the job's own shortfall as its record
	// stood when this round was weighed: how many stated behaviours no check
	// exercises, how many checks the newest reading found red, and a digest of
	// the review finding that still stands.
	//
	// They are journaled because MOVING A FILE IS NOT THE ONLY WAY TO MOVE THE
	// WORK. A round that closed a regression, answered a standing finding, or
	// brought a behaviour under a check has made progress even where the focus
	// gained nothing, and a rule that could not see it would refuse the round
	// after the one that finally started working. Each is compared against the
	// row before it and only ever for a FALL — a shortfall reworded is not a
	// shortfall closed, which is the same distinction Remainder draws below.
	Unexercised int `json:"unexercised,omitempty"`
	Red         int `json:"red,omitempty"`
	// Lost is the symbol-level half of the same shortfall: public names the
	// finished tree no longer spells. See SurfaceReading.
	Lost     int    `json:"lost,omitempty"`
	Standing string `json:"standing,omitempty"`

	// Measured says somebody actually looked, so a Produced of zero reads as
	// "nothing was written" rather than as "nobody counted". A row written
	// before this field existed decodes false, which is the honest reading of
	// it: nothing counted anything.
	Measured bool `json:"measured,omitempty"`

	// CoveredDespite names the standing evidence that stopped the coverage
	// question from refusing this round: the kinds the WORLD still says are
	// wrong with the job, when the plan-level reading said everything it is
	// judged on was already covered.
	//
	// It is journaled because the two readings DISAGREED and the disagreement is
	// the measurement. Coverage is a claim about the plan — acceptance points
	// mapped onto work that has landed — and it can be perfectly true of a job
	// whose checks are red and whose stated behaviours nothing exercises,
	// because none of those is a point on the plan. A row carrying this is a row
	// where a model said "nothing left" over a tree that was demonstrably not
	// finished, and an autopsy asking how often that happens has nothing else to
	// read. Empty is every round where the two agreed or the question was never
	// put.
	CoveredDespite []string `json:"covered_despite,omitempty"`

	// Finding is the REVIEW FINDING this round was bought for: what kind of
	// finding it is and which names it cites, as the structured record holds
	// them rather than as the review's paragraph spells them.
	//
	// It is journaled because A FINDING HAS ITS OWN FIXED POINT and nothing
	// else in this row can see it. Remainder below is a digest of the review's
	// PROSE, so a finding restated in fresh words reads as new work; Produced
	// is a fact about the tree, so a round that rewrote half a repository and
	// left the finding exactly where it found it reads as progress. happy-dom
	// v4-flash s13 is the measured case: four gate events carrying one
	// identical finding — the same four check names, word for word — bought
	// four rounds, every one of them journaled as productive, and the finding
	// they were bought FOR never moved at all (2026-08-29, bench/deepswe).
	//
	// Empty is every round nobody bought for a finding: an overrun, a
	// cooperative split, a resumption. Those keep exactly the governors they
	// had.
	Finding GrowthFinding `json:"finding,omitempty"`

	// BoughtFor is every NAME that finding stood on when this round was bought:
	// the behaviours no check exercises, the checks the run left red, the public
	// names the change deleted. A round bought for a set is a round bought for
	// every name in it.
	//
	// It is journaled as names and not as a count because THE FINDING IS EACH
	// NAME AND NOT THE SET. A gate cites whichever subset of the request it
	// happened to weigh, and the subset rotates: ofetch v4-flash s15 raised four
	// unexercised findings whose sets digested to four different values while
	// `Count a circuit failure for body-read/stream-consumption errors` sat in
	// every one of them, unclosed, for four rounds and the whole run. Nothing
	// that compares sets can see that; the names can.
	BoughtFor []string `json:"bought_for,omitempty"`

	// Spent is the names that had already had their two rounds when this
	// decision was taken — the ones that may not buy another. A refused round
	// carries the whole set here, which is what makes the refusal legible: the
	// person is told which things were worked on twice and still stand.
	Spent []string `json:"spent,omitempty"`

	// Remainder is a digest of the work this round was planned to finish. Two
	// consecutive rounds handed the same remainder are a fixed point: the round
	// that just ran was aimed at exactly this and did not move it. The digest
	// rather than the text because the text is unbounded and this is only ever
	// compared for equality.
	Remainder string `json:"remainder,omitempty"`
}

type JobGrowthRound struct {
	JobGrowth
	At time.Time
}

type JobLife struct {
	NodeID string
	Status Status
	// Admitted is the journal stamp of the event that created this node — the
	// moment the work was spliced in. Zero only for a node whose creating event
	// predates the journal it was rebuilt from, which is absence and not "now".
	Admitted time.Time
	// Attempt is the node's claim counter: 1 is the first go at it, 2 the first
	// restart. Zero means never claimed.
	Attempt uint64
	// AttemptStarted is the CURRENT attempt's start stamp, the column a restart
	// resets. It is carried so a caller can say when the restart happened, never
	// so it can pass for the job's age.
	AttemptStarted time.Time
	FinishedAt     time.Time
}

type JobSpend struct {
	JobID  string
	Title  string
	Runs   int
	Cost   float64
	Last   time.Time
	Models []string
}

type JobUsage struct {
	NodeCount        int
	Runs             int
	PromptTokens     int
	CompletionTokens int
	Cost             float64
	SurpriseSamples  int
	SurpriseTokens   int
	ExpectedTokens   int
	Surprise         *float64
}

type LastCall struct {
	Model string
	At    time.Time
}

type LeafExhausted struct {
	// Attempt is which try this was within the claim, counted from one.
	Attempt int `json:"attempt"`
	// Bound names what ran out in the executor's own vocabulary — the
	// exec.StopReason, so "deadline", "turn-cap", "budget", "overrun" or
	// "tool-timeouts". It is carried verbatim rather than reworded because the
	// words a person reads are composed at the surface and the record keeps the
	// fact.
	Bound string `json:"bound"`
	// Allowed is the room it was given, spelled as the surface granted it
	// ("15m0s", "200 turns"). Empty when the surface did not say.
	Allowed string `json:"allowed,omitempty"`
	// Turns is how many turns it had taken when it stopped.
	Turns int `json:"turns,omitempty"`
	// Meter, Reached, Allowance and Unit are the bound that actually fired,
	// named, with its own two numbers.
	//
	// Bound above is the executor's StopReason, and three different ceilings
	// used to share one of those: a leaf could be landed by its cost grant, by
	// an undiscounted ceiling three times that grant, or by a cumulative bound
	// on prompt sent, and every one of them journaled "budget". So the record
	// said "it ran out of its tokens" and Allowed printed the grant — which in
	// the ink run of 2026-08-29 was 150,000 against three leaves landed at
	// 240,000 by a different meter, and no reading of the store could tell.
	//
	// Empty on an attempt whose executor does not name its bounds, which reads
	// as "not said" rather than as a bound called "".
	Meter     string `json:"meter,omitempty"`
	Reached   int    `json:"reached,omitempty"`
	Allowance int    `json:"allowance,omitempty"`
	Unit      string `json:"unit,omitempty"`
	// Reason is the one sentence a person is shown.
	Reason string `json:"reason"`
}

type LeafMode struct {
	Mode string `json:"mode"`
	// Deps is how many settled results fed this node.
	Deps int `json:"deps,omitempty"`
	// Pushed is how many bytes of them went into the prompt, and Handles how
	// many of them were too large for it and travelled as a path instead. A
	// single handle is enough to disqualify a fold: a node told to assemble
	// material it holds only a pointer to has to go and get it.
	Pushed  int `json:"pushed,omitempty"`
	Handles int `json:"handles,omitempty"`
	// Turns and Tokens are the grant this decision bought.
	Turns  int `json:"turns,omitempty"`
	Tokens int `json:"tokens,omitempty"`
}

type LeafResumed struct {
	// Turns is how many recorded turns the seed carries. Zero never reaches the
	// journal: a claim that resumed from nothing did not resume.
	Turns int `json:"turns"`
	// Files are the paths the earlier attempts were SEEN to change — the
	// workspace's own before-and-after reading, not the worker's claim about it
	// (FAILSAFE.md rule 2). Bounded by the caller.
	Files []string `json:"files,omitempty"`
}

type LeafSelfClose struct {
	// Kinds names the findings the leaf raised against itself, in this
	// program's own vocabulary: "lost public names", "unbound names",
	// "its own checks", "checks it turned red".
	Kinds []string `json:"kinds"`
	// Names is a bounded sample of what the findings are ABOUT. A kind alone
	// sends a reader to run a suite; the name is the whole diagnosis, and it
	// was readable off the tree for nothing.
	Names []string `json:"names,omitempty"`
	// Turns is how many turns the leaf had taken when it read its own work. It
	// is the turns USED and not the turns a close was granted: the room a close
	// may spend is whatever the leaf has left of its own meter, so subtracting
	// this row from the leaf's final turn count is what says how much one cost.
	Turns int `json:"turns,omitempty"`
	// Closed says the leaf was actually held back and asked. False is the floor
	// arm and is journaled just as loudly: the finding stands, the leaf lands
	// with it, and the gate weighs it exactly as it did before — because the
	// leaf had already closed this kind once, or because its meter was spent.
	Closed bool `json:"closed"`
	// Why is the one sentence saying which of those it was, for a person and
	// for an autopsy. Empty on the arm that closed.
	Why string `json:"why,omitempty"`
}

type LeafStopped struct {
	// Token is the claim this worker held. It is the identity that matters: a
	// node id alone cannot say WHICH of a node's workers stopped, and telling
	// them apart is the entire reason this row exists.
	Token uint64 `json:"token"`
	// Reason is why it was asked to stop, carried from the sweep that asked.
	Reason string `json:"reason,omitempty"`
}

type Memory struct {
	ID     string
	Type   string
	Scope  string
	Title  string
	Text   string
	Tags   []string
	Status string
	// UseCount is how often this memory HELPED, and MissCount is how often it
	// was put in front of a model and bore on nothing.
	//
	// THE COUNTER MEASURES HELP, NOT INJECTION. It used to be incremented for
	// every id the router named, which credited a memory for being retrieved
	// rather than for being worth retrieving — RoMeRL (arXiv 2608.02508) names
	// that the "memory-reward trap": when several memories are co-retrieved,
	// all of them receive credit. So the two counters are written together,
	// from one confirmation after the turn, and they are the same bargain
	// internal/session's fixstore.go already keeps for a suggested fix: a
	// patch that was offered and then failed is counted AGAINST itself, or the
	// store would rank a line that has never once mattered at the top of its
	// own ranking forever.
	//
	// Neither is journaled per write, for the reason [EventMemoryRanking]
	// states; a snapshot on an interval is what carries them through a Rebuild.
	UseCount  int
	MissCount int
	// UpdatedAt is when the event that last touched this memory was journaled —
	// transaction time, resolved from updated_seq inside the same statement
	// that reads the row rather than by a second read per row.
	//
	// It is what lets a reader SHOW a memory's age. A model cannot judge
	// staleness it cannot see, and LongMemEval (ICLR 2025) measures time-aware
	// expansion as the single largest category lever it ablated (+11.3%
	// recall). Zero is unknown provenance — an old row whose event predates the
	// column — and renders as nothing.
	UpdatedAt     time.Time
	CreatedSeq    int64
	UpdatedSeq    int64
	SourceSession string
	SourceSeq     int64
}

type MemoryShelf struct {
	// Scope is `user`, `project` or `env` — the raw word, for a caller that
	// filters on it. [MemoryShelfWord] is what a person reads.
	Scope string
	// Label is the shelf's heading in words a person uses.
	Label string
	// Memories are this shelf's rows, NEWEST TOUCHED FIRST, and they are a
	// SAMPLE where the snapshot's limit bit: the counts below are over the whole
	// shelf and this list may be shorter than any of them.
	Memories []Memory
	// Held, LetGo and Superseded are this shelf's whole population by status —
	// `active`, `forgotten` and `superseded` in the words screen 2d uses. Every
	// memory on the shelf is in exactly one of the three.
	Held       int
	LetGo      int
	Superseded int
	// ByType counts every memory on the shelf by its kind — `fact`,
	// `preference`, `decision`, `correction`, `project_state` — whatever its
	// status, so a section line can say what a shelf is MADE of. A kind nobody
	// has used is absent rather than zero.
	ByType map[string]int
}

type MemoryShelves struct {
	// Shelves are in the order `user`, `project`, `env`, and a shelf with
	// nothing on it is NOT here — an empty shelf is not a shelf. The three
	// scopes are a closed enum, so a page that wants to name a missing one can.
	Shelves []MemoryShelf
	// The machine's totals, by the same three statuses.
	Held       int
	LetGo      int
	Superseded int
	// Shown is how many rows the shelves actually carry, and Total is how many
	// exist. Shown < Total is the snapshot's limit biting, and a page quoting a
	// figure off the rows rather than off the counts has to know.
	Shown int
	Total int
}

type MemoryStub struct{ ID, Title, Type, Scope string }

type Message struct {
	Seq         int64
	Time        time.Time
	SessionID   string
	Role        Role
	Body        string
	Attachments []string
	// Model is chat-lane metadata. On a user message it requests the model for
	// that one conversational turn; on an agent message it records the model
	// that actually produced the reply. Empty preserves the ordinary talk lane.
	Model string
	// NodeID optionally anchors the message to a graph node (a fold
	// announcement, an ask, a completion report).
	NodeID string
	// CommandSeq optionally links the message to the command it acknowledges
	// or reports on.
	CommandSeq int64
	// QuestionSeq links an agent ask or the user's answer to the durable
	// agent-question lifecycle it belongs to. It is separate from Options:
	// free-text questions need the same unambiguous answer routing.
	QuestionSeq int64
	// Answers is the newest user turn this line answers, and it exists because
	// one reply is no longer one message. A run of messages typed in one breath
	// is folded into a single turn and answered once, so a surface counting what
	// it is still owed cannot read that count off the replies alone: it would
	// wait forever for answers that were never going to come separately. Zero
	// everywhere except the head's own replies, where it is the seq of the last
	// user row the turn covered.
	Answers int64
	// Options is the ordered set of selectable answers for an askback.
	// Nil means the question accepts free text only.
	Options []QuestionOption
	// Brief is non-nil only for the resident's folded arrival summary.
	Brief *Brief
	// Progress is non-nil only for a replaceable compile-progress post. The
	// body remains a readable journal line; these fields let surfaces present
	// the current phase and real generated titles without parsing prose.
	Progress *MessageProgress
	// Parts is the ordered list of typed blocks this message carries — see
	// message_parts.go. Nil is a legacy prose message and is what almost every
	// message in a real database is; Body remains the whole rendered line
	// either way, so a surface that has never heard of parts renders exactly
	// what it rendered before.
	Parts []MessagePart
}

type MessageHit struct {
	// Complete is true only when the reader returned the entire indexed body.
	// Older excerpt-only readers leave it false.
	Complete  bool
	Seq       int64
	SessionID string
	Role      Role
	Body      string
	Time      time.Time
	Age       string
}

type MessagePart struct {
	Kind     PartKind
	Text     string
	Question *QuestionPart
	Card     *CardPart
	Progress *ProgressPart
	Artifact *ArtifactPart
	Ended    *EndedPart
	Aside    *AsidePart
	// contains filtered or unexported fields
}

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

type ModelRebinding struct {
	Root    string
	Model   string
	Nodes   []string
	Running int
}

type ModelRole string

type NamedTrait struct {
	Name        string
	Measurement TraitMeasurement
}

type Need struct {
	NodeID string   `json:"node_id"`
	Kind   EdgeKind `json:"kind"`
}

type Node struct {
	ID     string
	Parent string
	Brief  string
	Title  string
	Group  string
	// Subharness is the settled answer to "what runs this leaf": the node's own
	// choice where it made one, the splice's otherwise. It is resolved once, at
	// admission, so every dispatch path reads one field and cannot disagree
	// with another about which worker a node was promised.
	Subharness string
	// Ran is the worker that actually executed this node, written by the
	// dispatch path at the moment it builds the executor and again whenever an
	// escalation builds a different one. Subharness above is what the node was
	// ASKED to run on and is empty wherever nobody answered; this is what ran,
	// and it is never empty for a node that ran — the generalist says "linear"
	// out loud rather than leaving a blank that four other things also mean.
	Ran string
	// Spec is the planner's task object as it was admitted, journal-derived
	// like every other field on this view. Readers that do not know what a spec
	// is pass it along; the one that does decodes it.
	Spec       json.RawMessage
	Stage      int
	Status     Status
	Owner      string
	ClaimToken uint64
	Attempt    uint64
	Summary    string
	Error      string
	// Held and CancelRequested are journal-derived scheduling controls. They
	// intentionally do not add presentation-only statuses to the graph.
	Held            bool
	CancelRequested bool
	Priority        int

	Provenance   Provenance
	CreatedSeq   int64
	CreatedOrder int
	UpdatedSeq   int64
	StartedAt    time.Time
	FinishedAt   time.Time

	// Folded marks historical nodes replaced in the active view. FoldRoot is
	// the compact representative that remains visible in place of its subtree.
	Folded       bool
	FoldRoot     bool
	FoldDigest   string
	FoldPointers []string
}

type NodeBrief struct {
	Node      int    `json:"node"`
	Brief     string `json:"brief"`
	Criterion string `json:"criterion"`
	// Fault names why the model did not write this brief, on the nodes where it
	// did not. The brief beside it is then composed from what the plan already
	// knew about the node rather than absent, so the only way an autopsy can
	// tell a written instruction from a composed one is this field — and
	// without it a plan that quietly briefed itself reads exactly like a plan
	// every call answered. Empty is the ordinary case.
	Fault      string `json:"fault,omitempty"`
	Subharness string `json:"subharness,omitempty"`
	// Skills is the ordered list of skill names attached to this node.
	// Pinned skills (named by the person) come first, followed by retrieval
	// candidates. Order is precedence: earlier-listed skills win conflicts.
	Skills []string `json:"skills,omitempty"`
}

type NodeControl struct {
	CancelRequested bool
	Held            bool
}

type NodeReceipt struct {
	NodeID string
	// Parent is the node's own parent, which may point outside the subtree when
	// the receipt is the root's. It is carried because a tree is drawn from it
	// and re-reading the node to learn it would defeat the single query.
	Parent string
	Status Status
	// Folded says this node is history in the active view. It is reported rather
	// than filtered: see the second law above.
	Folded bool

	// Runs is how many usage rows name this node. It is the presence bit —
	// see Billed — and not decoration.
	Runs             int
	Cost             float64
	PromptTokens     int
	CompletionTokens int
	CachedTokens     int
	// LastBilled is the newest usage row against this node, or the zero time
	// when there is none. It is the journal's own stamp, so two surfaces asking
	// the same question agree about when the money moved.
	LastBilled time.Time

	StartedAt  time.Time
	FinishedAt time.Time
}

type NodeSpec struct {
	ID     string `json:"id"`
	Parent string `json:"parent,omitempty"`
	Brief  string `json:"brief"`
	Stage  int    `json:"stage"`
	Needs  []Need `json:"needs,omitempty"`

	// Title is a few-word display name for surfaces that cannot afford the
	// brief; empty is valid and means "derive from the brief".
	Title string `json:"title,omitempty"`

	// Group names the planning container this node expanded out of. It is
	// provenance for display — execution reads only Parent and Needs.
	Group string `json:"group,omitempty"`

	// Subharness names the worker this one node was sized for. There is one
	// worker, so a node written by this build carries "linear" or nothing;
	// only an empty name — nobody wrote the column — inherits the splice's own
	// choice. Both facts are kept because a graph written by a build that had
	// more than one worker still has to read back what it recorded, and
	// "nobody wrote this" is not the same fact as "this says linear".
	Subharness string `json:"subharness,omitempty"`

	// Spec is the planner's task object for this node, carried as opaque bytes.
	//
	// The store learns nothing about what a spec is, for the same reason it
	// learns nothing about what a plan is: the planner is a consumer of the
	// store, and decoding its object here would make the plan package a
	// dependency of the journal. What the store guarantees is that the bytes
	// arrive, land on the node, and come back out unchanged — which is all a
	// retry needs to inherit a criterion instead of inventing one.
	//
	// Empty is legal and is what every node admitted before this field existed
	// carries. Brief remains the read; this is the object beside it.
	Spec json.RawMessage `json:"spec,omitempty"`
}

type NodeSurprise struct {
	NodeID         string  `json:"node_id"`
	ActualTokens   int     `json:"actual_tokens"`
	ExpectedTokens int     `json:"expected_tokens"`
	Surprise       float64 `json:"surprise"`
}

type NodeUsage struct {
	NodeID           string  `json:"node_id"`
	PromptTokens     int     `json:"prompt_tokens"`
	CompletionTokens int     `json:"completion_tokens"`
	CachedTokens     int     `json:"cached_tokens,omitempty"`
	Cost             float64 `json:"cost"`
	Model            string  `json:"model,omitempty"`
}

type Origin string

type OverrunEvidence struct {
	Seq int64 `json:"-"`
	// NodeID is the leaf this is about.
	NodeID string `json:"-"`
	// Spent is what the leaf had cost when the comparison was made, and Turns is
	// how many rounds it took to spend it.
	Spent int `json:"spent"`
	Turns int `json:"turns,omitempty"`
	// Anchor is the measured median, Threshold the point that was crossed,
	// Multiple how many anchors that is, and Samples how many measured leaves
	// the pair was derived from.
	Anchor    int     `json:"anchor"`
	Threshold int     `json:"threshold"`
	Multiple  float64 `json:"multiple,omitempty"`
	Samples   int     `json:"samples,omitempty"`
	// Verdict is what was decided, in whatever words the deciding party used.
	Verdict string `json:"verdict,omitempty"`
}

type ParameterChange struct {
	Name      string            `json:"name"`
	Old       float64           `json:"old"`
	New       float64           `json:"new"`
	Evidence  ParameterEvidence `json:"evidence"`
	Direction string            `json:"direction"`
	Phrase    string            `json:"phrase"`
	Seq       int64             `json:"-"`
}

type ParameterEvidence struct {
	Reversals int     `json:"reversals"`
	Total     int     `json:"total"`
	Rate      float64 `json:"rate"`
}

type PartKind string

type PlanGraph struct {
	Root  string          `json:"root"`
	Model string          `json:"model,omitempty"`
	Graph json.RawMessage `json:"graph"`
}

type PollWatch struct {
	Condition string        `json:"condition"`
	Cadence   time.Duration `json:"cadence"`
}

type ProgressPart struct {
	NodeID string `json:"node_id,omitempty"`
	Phase  string `json:"phase"`
	Done   int    `json:"done,omitempty"`
	Total  int    `json:"total,omitempty"`
	Latest string `json:"latest,omitempty"`
}

type ProposalAppetiteValue struct {
	Acceptance float64 `json:"acceptance"`
}

type Provenance struct {
	Origin    Origin `json:"origin"`
	SessionID string `json:"session_id,omitempty"`
	Intent    string `json:"intent"`
	// CharterID points work back to the standing responsibility whose firing or
	// self-maintenance inquiry admitted it. It is empty for ordinary user work.
	CharterID string `json:"charter_id,omitempty"`
	// Attachments are user-supplied image paths kept separate from visible
	// intent text so every leaf can receive them as multimodal content.
	Attachments []string `json:"attachments,omitempty"`
	// TrialOf is the fact sequence of the unsettled pair this subtree tests.
	// Zero means the splice is ordinary work.
	TrialOf int64 `json:"trial_of,omitempty"`
	// RetryOf links a freshly spliced retry to the failed/cancelled node it
	// supersedes. The predecessor stays immutable and fully inspectable.
	RetryOf string `json:"retry_of,omitempty"`
	// ServiceIntent records the compiler's deterministic recognition that the
	// user asked for a running thing. It is consent provenance, not a display
	// hint, and therefore travels through the splice event and Rebuild.
	ServiceIntent bool `json:"service_intent,omitempty"`
	// WorkModel is the model the user named for this job in their own words
	// ("with the better model", "use gemini"). Empty means the surface's
	// current work model serves, as always. It is provenance rather than
	// configuration: the leaf that ran is inseparable from the model asked for.
	WorkModel string `json:"work_model,omitempty"`
	// PlanModel is the model that actually structured this job, recorded only
	// when it was not the model the job's work runs on. Empty — which is nearly
	// every job — means the plan slot followed the work slot, the default the
	// whole product is built around, and a surface that shows it says nothing.
	// It is provenance for the same reason WorkModel is: a graph's shape is
	// inseparable from the model that drew it, and a slot moved an hour later
	// must not be able to rewrite the answer to "who planned this".
	PlanModel string `json:"plan_model,omitempty"`
	// RunModel is the model this job's leaves were handed to work on, recorded
	// only in the same breath as PlanModel — when the plan slot split from the
	// work slot. It is what makes "planned by <model>" legible instead of
	// alarming: a reader who is told who structured the job and never told who
	// worked it concludes the wrong thing about both. It is deliberately not
	// WorkModel: "the model you named" and "the model the work ran on" are two
	// different claims, and only one of them is ever the user's.
	RunModel string `json:"run_model,omitempty"`
	// Craft names the learned workflow this subtree compiled from, as
	// "name@commit". Empty is ordinary planned work. Every node of a craft run
	// carries it: survival is measured per workflow version, so the version a
	// leaf actually ran under must be as durable as the leaf itself.
	Craft string `json:"craft,omitempty"`
	// Subharness names the worker chosen for this whole subtree by a build that
	// had more than one to choose from. NOTHING WRITES IT: it is kept so that a
	// graph written by such a build still replays and still reads back what it
	// recorded, which is the same reason the hand-over event above is kept.
	Subharness string `json:"subharness,omitempty"`
}

type QuestionCategory string

type QuestionClass string

type QuestionConfig struct {
	Kind      QuestionKind
	Default   string
	Category  QuestionCategory
	AllowFree *bool
}

type QuestionKind string

type QuestionOption struct {
	Label string `json:"label"`
	Value string `json:"value,omitempty"`
	Hint  string `json:"hint,omitempty"`
}

type QuestionPart struct {
	Seq int64 `json:"seq"`
	// Kind is how the question is drawn: a numbered list, an inline yes/no
	// strip, or a plain prompt. It was previously recoverable only by parsing
	// the body, which is why a confirm question and a choose question were
	// indistinguishable to anything that did not brace-scan.
	Kind QuestionKind `json:"kind,omitempty"`
	// Class is the consent axis (9.4). It rides on the part because the surface
	// that draws the question is the surface that must not offer to answer a
	// consent question on the person's behalf, and it should not have to open a
	// second table to find out which kind it is holding.
	Class QuestionClass `json:"class,omitempty"`
	// Category is the gate this question is asked under, which is what a
	// "don't ask me this again" affordance acts on.
	Category QuestionCategory `json:"category,omitempty"`
	// Default is the option key that stands if the person says nothing. It is a
	// key rather than a label because the label is the option's to change.
	Default string `json:"default,omitempty"`
	// AllowFree says whether an answer outside the options is accepted. It is
	// spelled positively and defaults to false, so a part written by a producer
	// that forgot the field offers the narrower affordance rather than the wider
	// one — the same direction Class defaults in, and for the same reason.
	AllowFree bool `json:"allow_free,omitempty"`
	// NodeID and CharterID are what the question is about, when it is about
	// something. Both are references; neither carries a title, a status or a
	// spend, because those are the referent's to answer.
	NodeID    string `json:"node_id,omitempty"`
	CharterID string `json:"charter_id,omitempty"`
}

type QuestionPractice struct {
	StartSeq         int64
	QuestionSeq      int64
	JobID            string
	BaselineSurprise float64
	ExpectedTokens   int
	ResultSurprise   *float64
	Reduced          *bool
	CompletionSeq    int64
	Reason           string
}

type QuestionPracticeStarted struct {
	QuestionSeq      int64   `json:"question_seq"`
	JobID            string  `json:"job_id"`
	BaselineSurprise float64 `json:"baseline_surprise"`
	ExpectedTokens   int     `json:"expected_tokens"`
}

type QuestionUrgency string

type RailAdjustment struct {
	Amount    float64 `json:"amount"`
	Origin    string  `json:"origin"`
	Unlimited bool    `json:"unlimited,omitempty"`
}

type Ratification struct {
	Origin    Origin `json:"origin"`
	SessionID string `json:"session_id,omitempty"`
	Evidence  string `json:"evidence"`
}

type RecallHit struct {
	NodeID   string   `json:"node_id"`
	Intent   string   `json:"intent"`
	Digest   string   `json:"digest"`
	Pointers []string `json:"pointers"`
	Age      string   `json:"age"`
	Score    float64  `json:"score"`
}

type ResidentLane string

type ResidentWatermark struct {
	Lane   ResidentLane
	Seq    int64
	At     time.Time
	Cursor int64
}

type ResolvedRole struct {
	Role   ModelRole
	Model  string
	Source RoleSource
	// Scope is the scope that answered, empty for a pin, a default, and an
	// unbound role.
	Scope BindingScope
}

type RetrospectiveWatermark struct {
	Seq         int64
	At          time.Time
	SettledJobs int
}

type ReversalRate struct {
	Class     string
	Reversals int
	Total     int
	Rate      float64
}

type Role string

type RoleBinding struct {
	Role    ModelRole    `json:"role"`
	Scope   BindingScope `json:"scope"`
	Value   string       `json:"value,omitempty"`
	Origin  string       `json:"origin,omitempty"`
	Cleared bool         `json:"cleared,omitempty"`
	Seq     int64        `json:"-"`
}

type RoleDefaults map[ModelRole]string

type RoleSource string

type RoomSpend struct {
	SessionID string
	// SinceSeq and Since are the journal row the window opens at: the room's
	// first message for a whole-room read, the room's newest user message for
	// a turn. Zero means there was nothing to open at.
	SinceSeq int64
	Since    time.Time
	// Last is the newest usage row inside the window, or the zero time when
	// there is none. It is the journal's own timestamp rather than a clock
	// read here, so two lenses asking the same question agree.
	Last time.Time

	Work  SpendSlice
	Spine SpendSlice

	// Shared says another room was live inside this window — it spent against
	// its own nodes, or it was spoken in. Spine is then a ceiling on this
	// room's conversational cost and not its bill.
	Shared bool

	// SpinePromptHighWater is the largest prompt_tokens on any single spine row
	// inside the window. It is named for what it measures rather than for what
	// it is wanted for, because those are not quite the same thing and the gap
	// is the whole of what 5.9 still owes.
	//
	// What it is wanted for: the head's context occupancy, the numerator of
	// ctx%. Most spine rows are written one per provider call by
	// pool.recordStructuringSpend, so such a row's prompt_tokens IS that call's
	// whole context — and the answering call's prompt dominates the routing and
	// compiling calls beside it, which see one instruction rather than the
	// thread. For a turn that was pure conversation, this is the head's window,
	// exactly.
	//
	// Where it stops being exact: three call sites journal ONE spine row for
	// MANY calls, summing their prompts — the planner's passes
	// (journalPlanSpend) and headless preparation and run totals. A summed
	// prompt is not a context occupancy, so a window containing one of those
	// makes this an upper bound. That is the safe direction for a health signal
	// — a context gauge that errs toward alarm sends a person to look, while
	// one that errs toward calm is why nobody could answer "why did it get
	// dumber" — but it is an error and it is written down here rather than
	// dressed up at the seam.
	//
	// It is deliberately measured over Spine alone. A leaf's row is a whole
	// tool loop summed by construction, so the same maximum over Work rows
	// would be a number with no referent at all.
	//
	// It is NOT 5.9's durable context figure and must never be labelled as one.
	// That one needs executors to journal window-size high-water marks — the
	// window a call actually occupied, per call, as its own fact — which no
	// executor does yet. Until they do, this is what the journal can say, it
	// can only say it about the conversation, and it says nothing at all when
	// Shared is true.
	SpinePromptHighWater int
}

type ScaleGate struct {
	Goal      string `json:"goal,omitempty"`
	Structure string `json:"structure,omitempty"`
	Scale     string `json:"scale,omitempty"`
	Route     string `json:"route"`
	Leaves    int    `json:"leaves"`
	// Parts is how many separable requests the compiler read in the ask. Zero
	// is the ordinary ask; two or more once meant a second route out of this
	// gate — a flat layout with no planner in it — and now means only that the
	// planner was handed the person's own division as evidence. It is kept
	// because it is the one number that says whether a wide plan followed a
	// wide ask or was found by the planner in a single one.
	Parts int `json:"parts,omitempty"`
}

type ScopeAlias struct {
	From string
	To   string
	Seq  int64
}

type ScopeCompetence struct {
	Scope           string          `json:"scope"`
	Kind            ScopeKind       `json:"kind"`
	Class           CompetenceClass `json:"class"`
	Samples         int             `json:"samples"`
	Successes       int             `json:"successes"`
	Failures        int             `json:"failures"`
	SuccessRate     float64         `json:"success_rate"`
	FailureRate     float64         `json:"failure_rate"`
	SurpriseSamples int             `json:"surprise_samples"`
	Surprise        float64         `json:"surprise"`
	SurpriseTrend   SurpriseTrend   `json:"surprise_trend"`
	InstalledSkills []string        `json:"installed_skills,omitempty"`
	LastTouched     time.Time       `json:"last_touched,omitempty"`
}

type ScopeKind string

type ScopeSurprise struct {
	Scope            string
	Samples          int
	SettledJobs      int
	Territories      int
	AverageSurprise  float64
	ExpectedTokens   int
	Evidence         string
	RecentSurprise   float64
	PriorSurprise    float64
	LearningProgress float64
	ColdStart        bool
	Allocation       float64
}

type Seen struct {
	Seq       int64
	Time      time.Time
	Surface   string
	SessionID string
	State     SeenState
}

type SeenState string

type SelfInquiryRetirement struct {
	Scope      string `json:"scope"`
	Origin     string `json:"origin"`
	TargetKind string `json:"target_kind,omitempty"`
	TargetID   string `json:"target_id,omitempty"`
	Action     string `json:"action"`
	Reason     string `json:"reason"`
}

type SelfReceipt struct {
	Seq           int64     `json:"-"`
	Time          time.Time `json:"-"`
	NodeID        string    `json:"node_id"`
	Origin        string    `json:"origin"`
	Scope         string    `json:"scope"`
	Cost          float64   `json:"cost"`
	FactIDs       []int64   `json:"fact_ids"`
	SkillIDs      []int64   `json:"skill_ids"`
	Surprise      *float64  `json:"surprise,omitempty"`
	SurpriseDelta *float64  `json:"surprise_delta,omitempty"`
	Nothing       bool      `json:"nothing"`

	TargetKind string `json:"target_kind,omitempty"`
	TargetID   string `json:"target_id,omitempty"`
}

type SentinelCheck struct {
	WakeSeq int64  `json:"wake_seq"`
	Yes     bool   `json:"yes"`
	Line    string `json:"line,omitempty"`
	Error   string `json:"error,omitempty"`
}

type SentinelJudgment struct {
	Yes  bool
	Line string
	// Outcome is what happened after the judgment — the firing it caused, or
	// the user's refusal of that firing. Empty means nothing followed, which is
	// itself worth reading: a yes that led nowhere.
	Outcome string
	Error   string
}

type Service struct {
	ID           string            `json:"id"`
	Name         string            `json:"name"`
	Command      string            `json:"command"`
	Dir          string            `json:"dir"`
	Health       ServiceHealth     `json:"health"`
	LogPath      string            `json:"log_path"`
	Provenance   ServiceProvenance `json:"provenance"`
	PID          int               `json:"pid"`
	StartedAt    time.Time         `json:"started_at"`
	Status       ServiceStatus     `json:"status"`
	AutoRestart  bool              `json:"auto_restart"`
	RestartCount int               `json:"restart_count"`
	CreatedSeq   int64             `json:"created_seq"`
	UpdatedSeq   int64             `json:"updated_seq"`
}

type ServiceHealth struct {
	Kind  ServiceHealthKind `json:"kind"`
	Value string            `json:"value"`
}

type ServiceHealthKind string

type ServiceProvenance struct {
	OriginJobID int    `json:"origin_job_id"`
	LeafNodeID  string `json:"leaf_node_id"`
}

type ServiceStatus string

type Session struct {
	ID    string
	Title string
	// Tags are the subject words the naming pass filed this room under. They
	// are a FINDING aid and not a second title: nothing draws them as chips,
	// and the one place they earn their keep is a switcher's filter, where a
	// person who remembers what a conversation was ABOUT but not what it ended
	// up called can still type their way back into it.
	//
	// They are written by the same pass that names the room and by nothing
	// else. A person renaming a tab states a new NAME; they are not restating
	// what the conversation is about, so [Store.RenameSession] leaves whatever
	// is here exactly as it stands.
	Tags    []string
	Surface string
	// Created is the first message that named this session; LastActive is the
	// newest one. Both are message times rather than wall-clock times taken
	// here, so a rebuild reproduces them exactly.
	Created    time.Time
	LastActive time.Time
}

type SilentClaim struct {
	// ID is the node the claim is on.
	ID string
	// Owner and Token are the claim itself, so a caller that decides to take it
	// back can do so through the ordinary CAS without reading the node again.
	Owner string
	Token uint64
	// CancelRequested carries the surgery flag through, because a claim the user
	// had already asked to stop is finished as a cancellation once it is back.
	CancelRequested bool
	// Quiet is how long it had been since the node last showed a sign of life.
	Quiet time.Duration
	// LastSign is when that sign was. It is the claim's own start when the
	// worker never wrote anything at all, which is the honest reading: the
	// claim was granted and nothing has happened since.
	LastSign time.Time
	// Reason is the release sentence, journaled on the release event.
	Reason string
}

type Snapshot struct {
	Nodes []Node
	Edges []Edge
}

type SpecGranularityValue struct {
	MedianBriefBytes  int     `json:"median_brief_bytes"`
	CorrectionDensity float64 `json:"correction_density"`
}

type SpendSlice struct {
	Runs             int
	Cost             float64
	PromptTokens     int
	CompletionTokens int
	CachedTokens     int
}