engine

type AbandonDispatchOptions struct {
	Reason string
	Token  string
	NowMS  int64
}

type AbandonIssueOptions struct {
	RunID   int
	IssueID int
	// Reason is `--reason`, required.
	Reason string
	// Token is the run's conductor capability (DKT-2465, conductor.go):
	// required on a bound run, ignored on an unbound one.
	Token string
	NowMS int64
}

type AbandonIssueOutcome struct {
	Run   string `json:"run"`
	Issue string `json:"issue"`
	// Steps lists the instances moved to `failed-routed`, in id order.
	Steps []string `json:"steps"`
	// RunStatus is the run's status AFTER the rollup — the abandoned issue may
	// have been the last unfinished work, in which case the run is now done.
	RunStatus string `json:"run_status"`
	// Worktrees is the issue's recorded worktrees (DKT-116) — what its steps
	// declared at record time and no close will ever sweep now. Excluded from
	// the frozen v1 payload; the CLI's v2 wrapper and the event carry it.
	Worktrees []string `json:"-"`
}

type ActionResult struct {
	// Kind is the produced artifact's kind — `params.output`.
	Kind string
	// Body is the artifact body.
	Body string
	// Payload is the structured half, as JSON text — the PLAIN ARRAY.
	// The old `{"stub":true,…}` wrapper is history and is never written again;
	// the marker now rides in `artifacts.stub`, which a result this stage
	// produces leaves at 0.
	Payload string

	// Held indexes the output payload's elements whose spread tripped
	// `hold_spread`. A non-empty list defers the step's routing into the saga's
	// `held` stage.
	Held []int

	// Results are the per-attempt records to write into `action_results`.
	// A builtin produces exactly one, with NULL argv and exit; a trusted
	// command produces one per flaky attempt.
	Results []ActionResultRow

	// Failed reports that the computation did not succeed. The step routes per
	// its effective `on_fail` and NO ARTIFACT IS WRITTEN — a computation that
	// could not run has not produced a result to record. This is a STEP
	// failure rather than an engine error: a workflow authoring mistake must
	// not wedge a run.
	Failed bool
	// Reason explains a failure, for the routing record and the operator.
	Reason string
}

type ActionResultRow struct {
	Action     string
	Ordinal    int
	Argv       []string
	Exit       *int
	DurationMS int64
	Output     string
	Truncated  bool
	Verdict    string
	Reason     string
	// Builtin marks a result core computed itself — the field that tells an
	// `aggregate` apart from a trusted command that happened to succeed.
	Builtin bool
	// TrustEntry names the entry that authorized this, for the audit record.
	TrustEntry string
	// ArgvSHA256 is the canonical hash of the candidate argv, for trust_cache.
	ArgvSHA256 string
	// Prefix records that a prefix entry authorized it.
	Prefix bool
}

type ActionRunner interface {
	Run(ctx context.Context, a ActionSpec, sc StepContext) (ActionResult, error)
}

type ActionSpec struct {
	// Name is the `action` value. Core carries it opaquely: it is either a
	// builtin's name or a trust entry's name, and nothing else about it is read.
	Name string
	// Params is the opaque KV bag, verbatim. CORE NEVER READS A KEY INSIDE IT
	// for a non-builtin action — a trusted command's params are its author's
	// business. The builtin reads exactly six keys (field, method, hold_spread,
	// output, route_at, source_field), and register time refuses any other.
	Params map[string]any
	// Output is `params.output`: the artifact kind this step produces.
	// It is lifted out of Params so the saga never reaches into the bag.
	Output string

	// Inputs is the payload set the computation reduces: THE CONCATENATED
	// PAYLOADS OF THE STEP'S DECLARED `inputs` ARTIFACTS, resolved and already
	// shape-validated.
	//
	// It is NOT the step's own recorded payload. An action step that has never
	// run has none, so reading one would make every aggregate reduce over nil in
	// production and leave the flow producible only by a dispatcher that claimed
	// the step and wrote its input by hand — reconcile.py reborn as a
	// claim+complete shim, which `claim` now refuses outright for an action
	// step.
	//
	// The ORDER source is untouched by this: the register-time check rejects the
	// predecessor's SCHEMA as the ORDER source, which stays the step's own
	// declared `payload`. The ORDER and the
	// DATA are two questions, and `inputs` is the declaration that answers the
	// second — ordinal-aware, `done`-only, and in the author's declared order.
	Inputs []map[string]any
	// Order is the step's PINNED payload schema's ordered index, or nil when the
	// step declares none. The builtin refuses to reduce without it (the runtime
	// half of the register-time ordered-field check); a trusted command never
	// sees it.
	Order OrderResolver
	// Validate validates a produced payload against the step's declared schema,
	// or is nil when the step declares none. It is a function rather than a
	// compiled document so the seam does not drag the schema package into every
	// test that builds a spec.
	Validate func(payload []byte) error
	// Context is the context object as `docket step context --json` emits it —
	// the bytes a trusted command receives on stdin. It is
	// assembled by the saga BEFORE the runner is invoked, because assembling it
	// needs a transaction and a subprocess may never run inside one.
	Context []byte
}

type ActivateOptions struct {
	// FilePins are `--pin PATH` (repeatable): arbitrary operator-supplied
	// files pinned by path and content hash. This is how the reference
	// instance pins its contracts, fragments, and policy without core knowing
	// what they are — so core reads bytes, hashes
	// them, stores the path, and never opens the content again except to serve
	// `context.pins`.
	FilePins []string
	// NowMS is the activation timestamp, injected so a test can pin it and
	// two activations of the same inputs produce comparable rows.
	NowMS int64
	// DryRun computes the whole activation and DISCARDS it, so an
	// operator sees what a run would bind and invoke before committing.
	DryRun bool
	// Reason is the operator's optional stated reason for activating, recorded
	// on the run-activated event's data when non-empty — matching `run budget
	// --set --reason`, `run abandon --reason`, and `step reap --reason`.
	Reason string
	// HeadBranch and HeadCommit are the activating checkout's HEAD, read by
	// the verb through config.GitHead on the configured exec root and
	// recorded on the run-activated event's data (DKT-3263), so a close
	// report can range `git log <head_commit>..HEAD` even after the shared
	// branch is rewritten. Each is omitted when empty: outside a checkout
	// the head is unknown, never invented.
	HeadBranch string
	HeadCommit string
}

type ActivateResult struct {
	Run *model.Run
	// IssuesBound is every issue in the run, bound and snapshotted.
	IssuesBound int
	// IssuesExpanded is the subset whose phase expanded THIS activation —
	// phase-1 issues at first activation, newly-unblocked phases at a
	// re-activation.
	IssuesExpanded int
	StepsCreated   int
	// ExpectedCostTotal is the run-wide SUM of the steps' expected_cost as
	// this activation leaves it — every step the run holds, including any a
	// PRIOR activation already created, computed inside the SAME transaction
	// so a --dry-run projects the steps it provisionally created (DKT-54's
	// activation half: cap-vs-cost in front of a panel before any step
	// exists for `step list` to enumerate). This is the whole roster, NOT
	// this activation's delta — see ExpectedCostAdded for that (DKT-517: a
	// conductor read this total as a 5-step increment when the real
	// increment, ExpectedCostAdded, was a fifth of it).
	//
	// A skipped step (workflow.StatusSkipped) is still an inserted row with
	// its own expected_cost, so it counts toward this sum exactly as an
	// un-skipped step does — the sum reads the `steps` table, not step
	// status.
	ExpectedCostTotal float64
	// ExpectedCostAdded is the SUM of expected_cost across only the steps
	// THIS activation created — ExpectedCostTotal's increment, named
	// distinctly so a conductor cannot mistake the whole roster for the
	// delta (DKT-517). On a first activation the run holds no prior steps,
	// so this equals ExpectedCostTotal; on a re-activation it is the newly
	// expanded phase's cost alone. Same skipped-step accounting as
	// ExpectedCostTotal.
	ExpectedCostAdded float64
	PinsRecorded      int
	FencesHarvested   int
	// PromotedIssues names, by display id, every issue stage 7 moved
	// `backlog -> todo` this activation (DKT-102/DKT-94: a count alone
	// answers "how many" and not "which ones" — an operator approving a
	// `--dry-run`'s roster needs the ids, the same way `issues_bound`'s
	// count-only shape was already the DKT-94 complaint elsewhere). Populated
	// identically on a dry run and a real activation, since promotion is
	// computed the same way on both — only a real activation commits it.
	PromotedIssues []string
	// BoundIssues names, by display id, every issue bound this activation, paired
	// with the exact workflow@version it bound to (DKT-94). This is the roster
	// `IssuesBound`'s count was missing — an operator approving a `--dry-run`
	// needs to know WHAT was bound, not just how many.
	BoundIssues []BoundIssue
	// BlockedIssues names, by display id, every bound issue this activation
	// left UNEXPANDED, each with the in-run depends_on predecessors still
	// holding it and their status as this activation leaves it (DKT-1180: a
	// re-activation that expanded nothing carried no field saying why, and the
	// cause — a predecessor check gating on issues the blocked one had no edge
	// into — took a source audit to find). Populated identically on a dry run
	// and a real activation. Nil when every bound issue is expanded, so the
	// ordinary run carries no key at all rather than an empty one.
	BlockedIssues []BlockedIssue
	// ConductorToken is the run's conductor capability, minted by a FIRST
	// activation and returned here and nowhere else (DKT-2465): only its hash
	// is stored. Empty on a re-activation, a dry run, and a run conducted
	// before it activated (the seat's holder already has the token).
	ConductorToken string
	// Reactivation reports whether this was a re-activation of an already
	// `active` run, so the verb can say "expanded 2 new phases" rather than
	// implying a first activation.
	Reactivation bool
	// ContextWarnings names every step whose closure exceeded
	// `context.warn_bytes`. The WARN cap does not refuse — only the
	// ERROR cap does — so these ride out on the result rather than as an
	// error, and the verb chooses the channel: stderr in human mode, a flag on
	// the row in JSON mode. Returning them rather than printing them here
	// keeps the engine free of an output dependency it has no other use for.
	ContextWarnings []ContextWarning
	// SourceWarnings names every BOUND workflow whose registered source file
	// could not be verified against `source_sha256` — and that activation did
	// not refuse over (DKT-590). Drift on a binding this activation MADE is a
	// refusal, so it appears here only in the three cases refusing would be
	// wrong: an unreadable source (the registered bytes still reproduce; only
	// their provenance is gone), drift under a binding inherited from an
	// earlier activation (a mid-run edit stays a non-event), and drift
	// under `registration.auto = false`, where a registry lagging the corpus is
	// the operator's own standing decision.
	//
	// It travels here for ContextWarnings' reason and takes the same stance:
	// the engine holds no output dependency, and the verb picks the channel —
	// stderr in human mode, an array in JSON.
	SourceWarnings []SourceWarning
	// ScopeWarnings names every issue that declared no scope at all while
	// binding a workflow whose steps occupy the tree (lintUnscopedHolders).
	//
	// It travels here for ContextWarnings' reason and takes the same stance: the
	// condition is a planning omission rather than an illegal state, so it warns
	// and proceeds, and the verb picks the channel — stderr in human mode, an
	// array in JSON.
	ScopeWarnings []ScopeWarning
	// BindingWarnings names every issue that bound one workflow while its
	// declared scope lies entirely inside ANOTHER registered workflow's declared
	// `[match] domain_paths`, and lacks only the labels that other workflow
	// requires (lintDomainScopeMismatch, DKT-1182).
	//
	// It is the exactly-one-WRONG-match signal. Activation refuses zero matches
	// and refuses several, but a mis-labelled issue matches its wrong workflow
	// exactly once, which is the one shape the binding rule cannot see — so it
	// bound, ran, and lost the other pipeline's gates with no output saying so.
	//
	// It travels here for ContextWarnings' reason and takes the same stance:
	// binding on the labels the operator applied is legal and sometimes
	// deliberate, so this reports and proceeds, and the verb picks the channel.
	BindingWarnings []BindingWarning
	// Registered is what auto-registration acted on, in registration order —
	// schemas first, then workflows.
	//
	// An activation that registered nothing leaves this NIL and the verb
	// prints no `Registered` block — not an empty one — so a repo with no
	// config directory is VISIBLY DORMANT IN THE OUTPUT rather than merely
	// dormant underneath it.
	Registered []Registration
	// PinsFromConfig counts the files under `.docket/config/` that were pinned
	// rather than registered — since DKT-581, only the PACKET CLOSURE the
	// bound workflows reach (packet entries, their `packet_includes`, and
	// policy.toml), not every file the scan walked. They are counted, not
	// listed: a closure can hold dozens of files and none of them is a
	// decision an operator needs to read before approving.
	PinsFromConfig int
	// NewPolicyPin names the policy.toml a RE-ACTIVATION pinned because the
	// run's pin set held none. Waiting rows resolve model, effort, and variant
	// against the pinned policy, so from this activation on they adopt a
	// policy the run did not start under. Nil on a first activation and on a
	// re-activation that pinned no new policy.toml; an inherited policy pin
	// keeps its original hash and is never reported here.
	NewPolicyPin *PolicyPin

	// Fences is the trust report: every harvested fenced command and whether
	// a trust entry authorizes it.
	//
	// Activation must surface what it will bind, including every harvested
	// fenced command, verbatim. Harvesting stores the commands; this report
	// adds the TRUST STATUS, because a verbatim list an
	// operator cannot act on is only half the mechanism: they need to see which
	// commands will actually run before the run, not after.
	Fences []FenceReport
	// GatePreflight is DKT-255's static check: every gate the bound workflows
	// DECLARE, resolved against this repo's trust store before the run.
	//
	// The fence report above answers the same question for a HARVESTED command
	// and nothing asked it of a declared gate, so the gap was discovered
	// mid-run, one gate at a time, when the gate fired and found nothing to
	// run. All 34 gate-unmatched events of the epoch were missing entries, and
	// every one was knowable here.
	//
	// It WARNS, on the same footing as ScopeWarnings and the fence report: some
	// gates are legitimately absent on some machines, and activation is not the
	// place to make that a hard stop.
	GatePreflight []GatePreflight
	// RoutingWarnings is DKT-4275's dry-run-only array: bound issues without the
	// security label that look security-shaped. It warns; it routes nothing.
	RoutingWarnings []RoutingWarning
	// RoutingLint states what that lint could check, on a dry run only (nil on
	// a real activation, which never runs it). An empty RoutingWarnings is read
	// against it: a lint with no lexicon and no labelled issue found nothing
	// because it had nothing to compare against.
	RoutingLint *RoutingLintReport
	// HoldPolicy is who will answer a hold this run mints (DKT-266) — a panel
	// when both `vote.hold.*` keys are set, one operator otherwise.
	//
	// It is reported because a configured governance surface that does nothing
	// and a broken one look identical from outside, and telling them apart took
	// a source audit. The engine was doing exactly what it was told.
	HoldPolicy HoldPolicy `json:"hold_policy"`
	// DryRun reports that nothing was written, so a caller cannot mistake a
	// discarded activation for a real one.
	DryRun bool
	// ProjectedStatus and ProjectedActivatedAtMS are set ONLY on a dry run
	// (DKT-96/DKT-100/DKT-109): what `Run.Status`/`Run.ActivatedAtMS` would
	// become if this activation committed. `Run` itself renders the run AS IT
	// ACTUALLY IS — the still-committed row, read before activateTx's stage 7
	// mutated it in the discarded transaction — so a dry run can never be
	// mistaken, field-for-field, for a real activation. On a real activation
	// both are zero/nil: `Run` already carries the committed projected state,
	// so a second copy would be redundant.
	ProjectedStatus        model.RunStatus
	ProjectedActivatedAtMS *int64
	// contains filtered or unexported fields
}

type ActivationHead struct {
	Branch string `json:"branch,omitempty"`
	Commit string `json:"commit"`
}

type Actor string

type ActorCount struct {
	Actor string `json:"actor"`
	Count int    `json:"count"`
}

type AggregateOutcome struct {
	// Payload is the output payload, one element per emitted cluster.
	// Without `route_at` that is one element per input element; with it, only
	// the clusters whose reduced value's position reached the floor.
	Payload []map[string]any
	// Held indexes the PAYLOAD elements whose spread tripped `hold_spread`. It
	// is a list rather than a count because held materialization has to be
	// able to say WHICH clusters are open, and a count cannot. The indices are
	// positions in Payload — the payload the artifact records and held
	// resolution re-reads — which coincide with input positions whenever
	// `route_at` is absent.
	Held []int
	// Recorded holds the clusters `route_at` routed below the floor (DKT-593):
	// fully reduced — value, members, demotion trail — but destined for the
	// record rather than the loop output. The caller writes them into the
	// action's own audit row; they never enter the artifact payload, so the
	// threshold and every downstream `inputs` reader see only the emitted set.
	// Nil whenever `route_at` is absent, which is what keeps the absent case
	// byte-identical to the pre-`route_at` builtin.
	Recorded []map[string]any
}

type AggregateParams struct {
	Field      string
	Method     string
	HoldSpread int
	Output     string
	// RouteAt is the routing floor, or "" when the step declares none — the
	// absent case, in which Aggregate emits every cluster exactly as it always
	// has.
	RouteAt string
	// SourceField is the property name the run report groups clusters by, or
	// "" when the step declares none. Aggregate itself never reads it — the
	// verbatim carry-through already moves whatever key this names — it rides
	// on AggregateParams purely so complementarityRollup can find it without
	// re-parsing the step's raw params.
	SourceField string
}

type ArtifactIndexEntry struct {
	Artifact string `json:"artifact"`
	Kind     string `json:"kind"`
	Producer string `json:"producer,omitempty"`
	Executor string `json:"executor,omitempty"`
	Issue    string `json:"issue,omitempty"`
	SHA256   string `json:"sha256"`
	Bytes    int    `json:"bytes"`
	// Supersedes names the artifact this one REVISES, e.g. `ARTIFACT-71`
	// (DKT-70). A held cluster's resolution records a new artifact rather than
	// annotating the old one, and the two share a kind and a sha256 — so this
	// index showed one operator decision as a second unit of work, and ledger
	// mining, which counts artifacts as evidence of work, counted it twice.
	// A rollup counting work should skip entries that carry it.
	Supersedes string `json:"supersedes,omitempty"`
}

type Attribution struct {
	Actor string
	Cwd   string
}

type Authority struct {
	// Kind is one of the three constants above.
	Kind string
	// Ref names the standing authorization, on AuthorityStandingGrant only.
	Ref string
}

type AuthorityCount struct {
	Authority string `json:"authority"`
	Count     int    `json:"count"`
}

type BackfillOutcome struct {
	Written int `json:"written"`
	Steps   int `json:"steps"`
	// MetadataMerged counts the steps whose record took a back-fill metadata
	// bag. Zero when no row carried one.
	MetadataMerged int          `json:"metadata_merged"`
	Source         string       `json:"source"`
	Skipped        []SkippedRow `json:"skipped,omitempty"`
	// Unclaimed names the targets no worker ever held. The rows for them ARE
	// written — see BackfillUsage — so this is an advisory, not a refusal, and
	// it is on the payload because `Warn` is suppressed in JSON mode and a
	// conductor runs with `--json`.
	Unclaimed []UnclaimedTarget `json:"unclaimed,omitempty"`
	// MetadataDropped names the steps whose bag was dropped. As with Unclaimed,
	// the usage rows for them are written and this is an advisory, not a
	// refusal. A step that was reaped for retry lands here and not in
	// Unclaimed, because a worker did claim it.
	MetadataDropped []DroppedMetadataTarget `json:"metadata_dropped,omitempty"`
}

type BackfillRow struct {
	Step     int
	Unit     string
	Quantity float64
	// Metadata is an optional opaque KV bag merged onto the step's record in the
	// same transaction as the usage row. Core stores it verbatim and reads no
	// key in it. On a step that has not reached a terminal status its usage row
	// still lands, but the bag is dropped and the step is named on the outcome:
	// a live step's record is written under its holder's token, and a back-fill
	// has none. A bag that is not a JSON object refuses the batch whatever the
	// step's status.
	Metadata string
}

type BindingWarning struct {
	IssueID string `json:"issue"`
	// BoundWorkflow is what activation actually bound, as `name@version` —
	// named because it is the pipeline that will really run, and an operator
	// reading only the domain half would not know what they are getting.
	BoundWorkflow string `json:"bound_workflow"`
	// DomainWorkflow is the workflow whose `domain_paths` contain the issue's
	// scope, as `name@version` — the pipeline the paths say should own it.
	DomainWorkflow string `json:"domain_workflow"`
	// Scope is the issue's declared scope, verbatim and in declared order, so
	// the warning carries the evidence rather than asking the reader to go find
	// what the issue claims to touch.
	Scope []string `json:"scope"`
	// MissingLabels names what would move the binding: every `labels_all` entry
	// the issue lacks, plus the `labels_any` list when it holds none of it.
	// Never empty — an issue missing nothing already bound the other workflow,
	// or hit the exactly-one-match refusal.
	MissingLabels []string `json:"missing_labels"`
	Reason        string   `json:"reason"`
}

type BlockedIssue struct {
	IssueID   string          `json:"issue"`
	BlockedBy []BlockingIssue `json:"blocked_by"`
}

type BlockerHop struct {
	Issue  string `json:"issue"`
	Status string `json:"status"`
}

type BlockingIssue struct {
	IssueID string `json:"issue"`
	Status  string `json:"status"`
}

type BoundIssue struct {
	IssueID  string `json:"issue"`
	Workflow string `json:"workflow"`
}

type BudgetSource string

type CastFinding struct {
	Proposal string `json:"proposal"`
	Voter    string `json:"voter"`
	Role     string `json:"role,omitempty"`
	// Kind is which list the entry came from: blocker, concern, or suggestion.
	Kind string `json:"kind"`
	Text string `json:"text"`
	// Evidence is the references the engine resolved when the cast recorded,
	// in the caster's order and canonical spelling.
	Evidence []string `json:"evidence,omitempty"`
	// Unsupported marks an entry that cited nothing. A flag rather than the
	// absence of Evidence, so a consumer never reads an omitted key as "not
	// applicable" — the same discipline VoteUsageCoverage states for silence.
	Unsupported bool `json:"unsupported,omitempty"`
}

type CheckedIntegration struct {
	Step     string `json:"step"`
	Instance string `json:"instance"`
	SHA      string `json:"sha"`
	// How is "ancestor" or "patch-equivalent" when this pass asked git,
	// "resolved" when the recorded head is one `step annotate
	// --integrated-sha` verified and re-recorded (annotate_integration.go) and
	// git confirmed its ancestry again here, "skipped" when this close's
	// --skip-integration-check reason vouched for the commit instead — or,
	// with Prior set, the verdict the prior close recorded, carried forward
	// unchanged.
	How string `json:"how"`
	// Prior names the earlier close of this run that accepted this sha —
	// "DISPATCH-N", or "run" for an acceptance recorded with no manifest open
	// — present only when this pass honored that record rather than asking
	// git again. A writer sha that a conflicting cherry-pick was resolved by
	// hand is NEVER an ancestor and never patch-equivalent, so without this
	// every close after the one that accepted it would refuse on it again
	// (RUN-90, four steps, every close for the rest of the run).
	Prior string `json:"prior,omitempty"`
	// BaseDiverged is DKT-3288's advisory: inherited commits under the step's
	// recorded base that the shared branch no longer carries by patch (a
	// mid-run rebase rewrote them). The step's own commits were judged
	// patch-equivalent; these are named, never refused on.
	BaseDiverged []string `json:"base_diverged,omitempty"`
}

type ClaimOptions struct {
	Owner string
	// TTLOverride is an explicit `--ttl`. Zero means resolve from the
	// workflow's [limits], then config.
	TTLOverride int64
	// Metadata is `--metadata`, the opaque KV bag the DISPATCHER knows at
	// claim time, merged onto the step's own in the claim's own transaction
	// (DKT-592).
	//
	// It exists because the facts a dispatcher knows when it hands a step out
	// are exactly the facts a step that never completes would otherwise never
	// record. Deferring them to `complete` means the steps that failed or
	// crashed — the ones an operator most wants to characterize — are the only
	// steps with no bag at all, and a rollup over those keys goes blind at
	// precisely the rows that motivated it.
	//
	// Core reads no key here, as everywhere: the bag is stored and never
	// interpreted.
	Metadata string
	// CostMultiplier is `--cost-multiplier`: the DISPATCHER's declaration that
	// this claim will cost this many times the step's declared `expected_cost`
	// (DKT-867). Zero means unset — the claim accrues the declared cost,
	// byte-for-byte the pre-DKT-867 behavior.
	//
	// It exists because `expected_cost` is variant-blind: the definition
	// declares one number per step template, and the party that resolves a
	// step to an executor variant — routing an escalated retry to something
	// far pricier — is the dispatcher, at claim time. The multiplier is that
	// resolution priced in the cap's own currency, declared by the only party
	// in a position to know it. Core stores, sums, and reserves the number and
	// never interprets it (the genericity rule): what varied and by how much is the
	// dispatcher's business, exactly as `--usage`'s units are the claimant's.
	//
	// The scaled cost participates in the SAME facts the declared cost always
	// has: it is checked against the cap in the claim's own transaction and
	// recorded in the claim's `step-claimed` event, so each attempt of a step
	// accrues what ITS claim declared — an escalated re-claim accrues more
	// than the cheap first attempt did (retry re-accrual, made
	// variant-aware).
	CostMultiplier float64
	// RecoverySecret is the claimant's proof for a later same-owner re-claim.
	// The first claim stores only its hash; a re-claim of a lease that stored
	// one re-mints only when it presents the same secret (reMintOwnClaim).
	RecoverySecret string
	NowMS          int64
}

type ClaimResult struct {
	Step           string   `json:"step"`
	Token          string   `json:"token"`
	LeaseExpiresMS int64    `json:"lease_expires_ms"`
	Context        *Context `json:"context"`

	// Attempt and RowVersion surface under --json=v2 only: a claim is a
	// mutation and advances the version.
	Attempt    int `json:"-"`
	RowVersion int `json:"-"`

	// ReMinted marks a response that re-keyed the caller's OWN standing lease
	// rather than taking a new one (DKT-1564). Nothing about the claim changed
	// — same attempt, same accrual, same recorded bundle — but the caller asked
	// twice, and the honest answer says which of the two it got.
	ReMinted bool `json:"-"`
}

type ClassCap struct {
	Max    int
	Source ClassCapSource
}

type ClassCapSource string

type CloseOutcome struct {
	Dispatch string `json:"dispatch"`
	Run      string `json:"run"`
	Status   string `json:"status"`
	Reason   string `json:"close_reason"`
	// Accepted lists the steps closed over under `--accept-missing-usage`
	// as "STEP-N instance". It is part of the RECORD rather than of the
	// message: the flag "records the acceptance", and a list only
	// stderr carried would be gone by the time anyone audited. It names ids
	// because instances repeat across issues (DKT-315).
	Accepted []string `json:"accepted,omitempty"`
	// Integration is DKT-1284's verdict: every write-class step's recorded
	// commit was found integrated into the shared branch ("verified", with
	// the checked shas), or the operator named a reason to skip asking
	// ("skipped"). It is never nil — a close that reached this far always
	// ran one of the two.
	Integration *IntegrationCheck `json:"integration,omitempty"`
	// ConditionsWaived lists the sealed votes whose unfiled approve-with-concerns
	// conditions `--no-conditions` closed over (DKT-4263).
	ConditionsWaived []UnfiledCondition `json:"conditions_waived,omitempty"`
}

type ClusterComplementarity struct {
	Step     string `json:"step"`
	Instance string `json:"instance"`
	Issue    string `json:"issue"`
	// Unique counts clusters with exactly one member: the field's declared
	// order had one voice on that value, corroborated by nothing.
	Unique int `json:"unique"`
	// Corroborated counts clusters with more than one member: the SAME
	// measurement Anthropic's fanout-width case made ("only 12 vulnerabilities
	// in common") — how much of the round agreed rather than merely occurred.
	Corroborated int `json:"corroborated"`
	// ByMemberCount is Unique and Corroborated's own detail, ordered by
	// member count ascending (a total key): every cluster this round
	// reduced, grouped by how many members it had.
	ByMemberCount []MemberCount `json:"by_member_count,omitempty"`
	// InputArtifacts is how many artifacts fed the step whose output this
	// round reduced — `step_inputs` on that PRODUCER step, not on the
	// aggregate step itself (an action step is never claimed and so never
	// gets a `step_inputs` row of its own, per DKT-1054). Summed over every
	// run step sharing the producer's declared name, so a fanned-out producer
	// (`review@0#0..3`) counts every sibling's artifact once. Zero when the
	// producer step cannot be resolved — an aggregate step with no
	// `<step>.<kind>` input, which V3/V29 already make unregisterable, but a
	// restored database is not required to have run today's validation.
	InputArtifacts int `json:"input_artifacts"`
	// PayloadUnreadable marks a step whose aggregate output does not decode
	// as the array of objects `aggregate` promises, so an absent row is never read
	// as "this round produced nothing" (the same discipline MetadataUnreadable
	// states). The bag is not re-validated here: a read verb that
	// refused over one odd artifact would be useless during exactly the run
	// an operator wants to inspect.
	PayloadUnreadable bool `json:"payload_unreadable,omitempty"`
}

type ClusterSourceAttribution struct {
	Step     string `json:"step"`
	Instance string `json:"instance"`
	Issue    string `json:"issue"`
	// Source is the opaque value itself — a step ref such as `review@0#0` in
	// this corpus's convention, but core treats it as a string it groups,
	// never as content it parses.
	Source string `json:"source"`
	// Executor is the hint the named step declared, when Source resolves to a
	// step instance in this run. Empty when it does not resolve — a source
	// naming a step outside this run, or a value that is not a step ref at
	// all — kept rather than dropped, since an unresolved source is
	// still a fact about the round.
	Executor string `json:"executor,omitempty"`
	// Clusters is how many of the round's clusters this source contributed a
	// member to.
	Clusters int `json:"clusters"`
}

type CompleteOptions struct {
	Token string
	// WorkDir is `--worktree`: the checkout the work actually happened in.
	// Persisted on the step at stage 0 and read by the diff stage, so a
	// conductor recording on behalf of an executor in another worktree
	// captures THAT tree rather than its own. Empty means "the
	// invoking checkout", resolved at diff time.
	WorkDir string
	// Artifact is the body from --artifact-file.
	Artifact []byte
	// Payload is the JSON from --payload-file, or nil.
	Payload []byte
	// Usage is `--usage`. It is STORED and ENFORCES NOTHING here — the same
	// reasoning as `--budget`: the wire shape lands whole, so enforcement is
	// added later rather than a flag.
	Usage string
	// Metadata is `--metadata`, opaque KV merged onto the step's own.
	Metadata string
	// Gaps are `--gap-file` bodies (repeatable): out-of-scope problems the
	// worker surfaced. Each records an auxiliary artifact of GapArtifactKind
	// beside the declared emit AND materializes a backlog issue related to the
	// step's own, in the same transaction (DKT-72).
	Gaps [][]byte
	// GapIssues, when non-nil, receives the refs of the issues materialized
	// from Gaps — the caller's channel for telling the operator where the
	// residue landed.
	GapIssues *[]string
	// Comments are `--comment-file` bodies (repeatable): issue comments the
	// step's acceptance criterion requires. Each records an auxiliary artifact
	// of IssueCommentArtifactKind and posts as a comment on the step's own issue
	// in the same transaction (DKT-4272).
	Comments [][]byte
	// Pending, when non-nil, is set true when the gates and routing were
	// handed to a detached run instead of running inside this call.
	Pending *bool
	NowMS   int64
}

type ConditionsWaiver struct {
	Reason string
	Token  string
	By     Attribution
}

type ConductOptions struct {
	// By is who is taking the seat and from where. REQUIRED, exactly as on a
	// ruling: the event is the whole audit trail of a token-free verb that
	// mints authority, so an unattributed one must not be written.
	By    Attribution
	NowMS int64
}

type ConductResult struct {
	Run *model.Run
	// Token is the freshly minted capability. It is never stored; only its
	// hash is.
	Token string
	// Rotated reports that a capability already stood and was retired by this
	// mint — the fact the standing conductor will discover at its next ruling,
	// stated up front to whoever just took the seat.
	Rotated bool
}

type Context struct {
	Step   model.StepRow  `json:"step"`
	Issue  ContextIssue   `json:"issue"`
	Inputs []ContextInput `json:"inputs"`
	Pins   []ContextPin   `json:"pins"`
	// LoopEntry is the ordinal k and the routing that entered it, NULL at k=0.
	// It is a pointer so the wire shape carries `null` rather than a
	// zero-valued object, which a consumer would have to know to ignore.
	LoopEntry *LoopEntry `json:"loop_entry"`
	// Metadata is the definition's opaque KV, verbatim. Core never reads a key
	// inside it.
	Metadata map[string]any `json:"metadata,omitempty"`
	// PreGates carries the results of the step's `pre = true` gates, in
	// declared order, so the results are included in the context bundle.
	//
	// PRESENT ONLY WHEN THE STEP DECLARES PRE-GATES — absent, not empty,
	// otherwise, which is the rule the v6 `lease` object established.
	PreGates []PreGateResult `json:"pre_gates,omitempty"`
	// TargetSHA and TargetWorktree are the machine-readable target ref
	// (DKT-24): the commit the step's resolved `issue.diff` tree stood at, and
	// the producing record's declared worktree path — good while that checkout
	// is still on disk (it is swept at integration). Lifted from the diff
	// artifact's own round-record payload, so they are exactly as reproducible
	// as the input they describe.
	//
	// Before these, the target commit rode a PROSE convention ("the
	// change-summary's first line carries the sha") and every reviewing
	// consumer re-derived the tree via `git archive | tar -x` — or burned
	// reasoning proving tree-equivalence when integration had already minted a
	// new sha. Both absent when the resolved diff carries no round record.
	TargetSHA      string `json:"target_sha,omitempty"`
	TargetWorktree string `json:"target_worktree,omitempty"`
	// DiffBase is the commit the resolved `issue.diff` was computed from, read
	// from the same round record (DKT-3307), so a judge reviewing it knows
	// the range without rebuilding the diff. Absent for a record that
	// predates the field.
	DiffBase string `json:"diff_base,omitempty"`
	// Resolution is the ruling recorded on THIS STEP that sent it back for
	// rework — the routing, and the note whoever decided it wrote (DKT-247).
	//
	// A resolve/approve note was audit-trail only: the packet rendered header,
	// frozen body, inputs, pins, and output spec, and nothing else. So a
	// ruling issued BETWEEN rounds — the operator's answer to the very
	// question that parked the step — could not reach the retry it authorized,
	// and a conductor applied rulings as its own repo commits instead (agw:
	// 3df53c4, b9182fa — both worked, neither sanctioned).
	//
	// SCOPED TO THIS STEP'S OWN ROW. A note on another step is a fact about
	// that step, and rendering it here would put one instance's ruling in
	// another's packet — the collision the instance-label ambiguity already
	// makes easy. Read from `steps.routing`, which holds the CURRENT routing
	// record for this step alone.
	//
	// TWO WRITERS PUT A RULING HERE, and together they are the ONLY reliable
	// operator-steering channels into a packet (DKT-725): `step resolve --as
	// retry|rerun-gates -m` leaves the note on the SAME row it re-executes,
	// and `step resolve --as fix-round -m` stamps it onto the NEW round's
	// instantiated rows (stampEntryRouting), because the parked row it was
	// issued against is superseded and renders nothing again. Issue COMMENTS
	// are not a context source at all — the source rule, by design — and a
	// mid-run `description` edit never renders either, because
	// `body_snapshot` froze at activation. `run refresh-body`
	// (DKT-2291) is that freeze's one explicit exception, and it is a separate
	// operator act rather than a consequence of the edit.
	//
	// nil when the step carries no routing record, so a first-round packet is
	// byte-identical to what it always was.
	Resolution *ContextResolution `json:"resolution,omitempty"`
	// Notes are the run's standing statements (DKT-1079): every `run note
	// add` recorded against THIS RUN, in insertion order, whichever issue or
	// step the bundle is for.
	//
	// It is the one steering channel that is run-wide rather than
	// step-scoped. `Resolution` reaches the step a ruling was issued against
	// (and the round it authorizes), which is right for a ruling about one
	// step's work and useless for a fact about the whole run — RUN-70's
	// conductor learned BEFORE DISPATCH that a required gate fails on clean
	// HEAD, got the operator's disposition, filed the tracking issue, and had
	// nowhere to put any of it that a packet reads: issue comments are an
	// audit surface (the source rule, by design), the body froze at
	// activation, and no step had a routing record yet. The executor
	// re-derived the failure and filed a duplicate.
	//
	// omitempty, so a run with no notes renders every bundle byte-identically
	// to what it always was.
	Notes []RunNote `json:"notes,omitempty"`
}

type ContextGateOutcome struct {
	Gate string `json:"gate"`
	// Verdict is `fail`, `unmatched`, or `skipped` — never `pass`, since a
	// passing gate is not why the step came back.
	Verdict string `json:"verdict"`
	// Reason is the recorded diagnosis, verbatim. It is what separates "the
	// trust entry is missing" from "the tree was gone" from a real failure,
	// and it is the field a classifier reads after the verdict.
	Reason string `json:"reason,omitempty"`
}

type ContextInput struct {
	Artifact string `json:"artifact"`
	Kind     string `json:"kind"`
	// ProducerStep is the rendered instance identity of the step that produced
	// it, or "" for an engine-produced artifact (`issue.diff` at activation).
	ProducerStep string `json:"producer_step"`
	Body         string `json:"body"`
	// Payload is the artifact's STRUCTURED half as stored — JSON text, or ""
	// when the producing step declared none.
	//
	// CARRIED VERBATIM: no re-encoding, no re-validation, no key inspection.
	// Core validated the shape once, at completion, against the schema
	// register. Re-parsing here would let assembly reject an
	// artifact the engine already accepted — a packet that fails on data the
	// ledger holds is a worse failure than the one this field fixes.
	//
	// It is `omitempty` so a payload-less input serializes exactly as it did
	// before this field existed: every workflow that does not use payloads sees
	// byte-identical bundles and byte-identical packets.
	//
	// Without it, a step whose contract requires its inputs' structure had only
	// the prose — and recovering the rest meant reading engine storage directly,
	// which voids the pinning, the reproducibility, and the no-live-state rule
	// that the packet exists to provide.
	Payload string `json:"payload,omitempty"`
}

type ContextIssue struct {
	ID           string   `json:"id"`
	Title        string   `json:"title"`
	BodySnapshot string   `json:"body_snapshot"`
	Kind         string   `json:"kind"`
	Labels       []string `json:"labels"`
	Scope        []string `json:"scope"`
}

type ContextMeta struct {
	IssueBytes    int `json:"issue_bytes"`
	InputsBytes   int `json:"inputs_bytes"`
	PinsBytes     int `json:"pins_bytes"`
	MetadataBytes int `json:"metadata_bytes"`
	// NotesBytes is the run notes' share (DKT-1079). Counted, because a note
	// rides EVERY packet of the run: a cap computed without it would let a
	// bundle exceed its declared limit by exactly the words a dispatcher
	// added to all of them.
	NotesBytes int `json:"notes_bytes"`
	TotalBytes int `json:"total_bytes"`
	// TemplatePinned reports whether the template a render would use is pinned.
	// An UNPINNED template is reported so the reproducibility gap is visible
	// rather than assumed — a packet rendered through an unpinned
	// file is reproducible only to the extent the operator chose.
	TemplatePinned bool `json:"template_pinned"`
}

type ContextPin struct {
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
}

type ContextResolution struct {
	// Routing is the recorded routing — `retry`, `fix-loop`, `waiting-human`,
	// and so on. It is carried beside the note because "do X" reads very
	// differently under a retry than under an override.
	Routing string `json:"routing"`
	// Note is what the decider wrote, verbatim. Empty when the routing was
	// recorded without one — the routing alone is still worth rendering,
	// since it says why the step is being asked again.
	Note string `json:"note,omitempty"`
	// Gates names the gates that did NOT pass on the attempt this routing
	// ended, with their verdicts and reasons (DKT-261).
	//
	// It exists so a relay can tell an ENVIRONMENTAL failure from a CAPABILITY
	// one without a second query. That distinction is the hard and valuable
	// part of an escalation ladder: all three genuine capability-suspect
	// retries of the RUN-25/26 epoch were in fact environmental, so a naive
	// "gate failed twice, escalate" rule would have escalated three times and
	// helped zero times.
	//
	// DKT-254 is what makes the distinction readable rather than a guess. A
	// gate that COULD NOT MEASURE now records `skipped` and parks the step for
	// an operator instead of routing `on_fail`, so it never reaches a retry at
	// all; `unmatched` says the command was never trusted here; only `fail`
	// means a measurement was taken and the work did not pass it. A ladder that
	// escalates on `fail` alone is the rule the epoch's evidence supports.
	//
	// Empty on a step whose routing had nothing to do with gates, which is most
	// of them.
	Gates []ContextGateOutcome `json:"gates,omitempty"`
}

type ContextWarning struct {
	Instance string `json:"instance"`
	IssueID  string `json:"issue"`
	Bytes    int    `json:"context_bytes"`
	Cap      int    `json:"warn_bytes"`
}

type CorpusEntry struct {
	// Kind is RegistrationKindWorkflow or RegistrationKindSchema.
	Kind    string `json:"kind"`
	Name    string `json:"name"`
	Version int    `json:"version"`
	Path    string `json:"path"`
}

type CorpusIndex struct {
	// contains filtered or unexported fields
}

type DecideOptions struct {
	// Approve is the verb: true for `approve`, false for `reject`.
	Approve bool
	// Note is `--note`.
	Note string
	// Value is `--value` (DKT-42): an operator's corrected value for a held
	// cluster's aggregated field, validated against the pinned schema's
	// declared enum and applied only on approve of a materialized held step.
	// Every other decision passes "".
	Value string
	// By is who is ruling and from where. REQUIRED: an empty field refuses the
	// decision before anything is written (see Attribution).
	By Attribution
	// Under is the authority the decision is made under (DKT-1899). REQUIRED:
	// the zero value refuses the decision before anything is written.
	Under Authority
	// Token is the run's conductor capability (DKT-2465, conductor.go). It is
	// REQUIRED on a bound run and ignored on an unbound one; the empty string
	// authorizes nothing.
	Token string
	NowMS int64
}

type DetachedPreGateRun struct {
	Step      string `json:"step"`
	TargetSHA string `json:"target_sha"`
	Outcome   string `json:"outcome"`
	// Gates are the rows this run recorded, or the recorded rows it found
	// complete — empty for every other outcome.
	Gates []PreGateResult `json:"gates,omitempty"`
}

type DetachedSagaRun struct {
	Step    string `json:"step"`
	Outcome string `json:"outcome"`
}

type DiffFacts struct {
	// Lines is added plus removed content lines.
	Lines int
	// Files is the number of files the diff touches.
	Files int
	// Empty reports that no content line changed.
	Empty bool
}

type Discrepancy struct {
	Kind     DiscrepancyKind `json:"kind"`
	Step     string          `json:"step"`
	Instance string          `json:"instance"`
	// Resolution is the enumerated way out, rendered for this specific row.
	// The resolutions are enumerated precisely so reconciliation is
	// an operator's act rather than a guess the engine makes.
	Resolution string `json:"resolution"`
}

type DiscrepancyKind string

type DoctorCheck struct {
	Check   string
	Verdict DoctorVerdict
	Detail  string
}

type DoctorOptions struct {
	// Cwd is the invoking process's working directory, canonicalized.
	Cwd string
	// DBPath is the store's database file — the same path the current seat
	// already opened read-write to reach this verb, re-verified directly.
	DBPath string
	// ProjectID is the project the invocation resolved to, as the root hook
	// decided it: a registered row's id, db.DefaultProjectID on a
	// single-tenant store, or db.UnregisteredProjectID when Identity has no
	// row. Doctor reports it and never changes it.
	ProjectID int
	// Identity is the invocation's project identity as config resolved it,
	// or "" on a single-tenant store — named in the detail so an unbound
	// report says which path has no project.
	Identity string
	// RunID is `--run`'s target, or 0 when absent — AC2's SKIP case.
	RunID int
	// SourceRoot is `--source PATH`, or "" when absent — install-drift's own
	// SKIP case.
	SourceRoot string
	NowMS      int64
}

type DoctorReport struct {
	Clean   bool
	Skipped bool
	Checks  []DoctorCheck
}

type DoctorVerdict string

type DroppedMetadataTarget struct {
	Step     string `json:"step"`
	Instance string `json:"instance"`
	Status   string `json:"status"`
}

type ElidedFile struct {
	Path string
	Blob string
	Adds int
	Dels int
}

type Engine struct {
	Gates   GateRunner
	Actions ActionRunner
	// DiffFn computes an issue's VCS diff over its snapshotted scope. It is a
	// field so a test can supply a deterministic one: the real implementation
	// shells out to git, which is THE ONE declared VCS coupling, and a test
	// that invoked it would depend on the working
	// tree it is supposed to prove immunity from.
	DiffFn func(dir, base string, scope []string) (string, error)
	// HeadFn resolves a checkout's current HEAD commit, for the round-delta
	// record (DKT-106). A field for DiffFn's reason exactly: the real one
	// shells out to git. "" means "could not resolve", and every consumer
	// treats that as "record no head, compute no delta".
	HeadFn func(dir string) string
	// IsAncestorFn reports whether `sha` is an ancestor of (or equal to)
	// execRoot's HEAD, and whether the question could be answered at all
	// (DKT-193). A field for DiffFn's reason: the real one shells out to git.
	// `known = false` means every consumer stays silent — an unanswerable
	// question is not evidence of staleness.
	IsAncestorFn func(execRoot, sha string) (ancestor, known bool)
	// PatchContainedFn reports whether execRoot's HEAD carries `sha`'s PATCH —
	// whether some commit on HEAD's side of their merge base is patch-id
	// equivalent to each commit on `sha`'s side (DKT-1033) — and whether that
	// question could be answered at all. A field for DiffFn's reason: the real
	// one shells out to git.
	//
	// It is the FIRST question a disproved ancestry opens, ahead of
	// TreeMatchFn, because it asks about the work rather than the tip: a
	// sibling issue's integration or a conductor's follow-up patch on the same
	// file moves HEAD's tree without touching this patch, and RUN-67 warned on
	// all nine review rows for exactly that. Like TreeMatchFn it may only
	// ACQUIT a sha ancestry already disproved; unlike TreeMatchFn, a
	// definitive `contained = false` is the ONE measurement that lets the
	// advisory call an integration diverged, because it is the one that
	// actually measured the patch.
	PatchContainedFn func(execRoot, sha string) (contained, known bool)
	// StepPatchContainedFn is PatchContainedFn for a write-class step's own
	// commit at dispatch close (DKT-3288), bounded below by the step's recorded
	// base so only base..sha is judged; `diverged` names inherited base
	// commits the shared branch no longer carries, for the close's advisory.
	// An empty base asks the unbounded question. A field for DiffFn's reason.
	StepPatchContainedFn func(execRoot, sha, base string) (contained, known bool, diverged []string)
	// TreeMatchFn reports whether execRoot's HEAD still carries `sha`'s TREE
	// on the paths `sha`'s work touched — or, where that question has no
	// evidence to answer with, whether the two carry the same root tree
	// outright (DKT-424, DKT-451) — and whether either could be answered at
	// all. A field for DiffFn's reason: the real one shells out to git.
	//
	// It is IsAncestorFn's ACQUITTAL, never its accuser: staleTargets asks it
	// only about a sha ancestry already disproved, and only a `match = true`
	// changes the outcome. `known = false` therefore leaves DKT-193's verdict
	// exactly as it stood — a probe that cannot answer must not silence a
	// warning it did not disprove, which is the opposite direction from
	// IsAncestorFn's own fail-open and deliberately so.
	//
	// Since DKT-1033 it is PatchContainedFn's FALLBACK: a tree comparison
	// reads any later commit on the same paths as a difference, so its
	// `match = false` is no longer allowed to word the advisory as a
	// divergence — only as content that could not be matched.
	TreeMatchFn func(execRoot, sha string) (match, known bool)
	// ObjectExistsFn reports whether `sha` resolves as a COMMIT OBJECT from
	// execRoot at all — `git cat-file -e <sha>^{commit}` — and whether that
	// question could be answered (DKT-742). A field for DiffFn's reason: the
	// real one shells out to git.
	//
	// It exists because IsAncestorFn's `known = false` conflates two states
	// that read very differently to a packet consumer: "git could not answer"
	// (git absent, not a repository — nothing to warn about) and "the object
	// is not in the shared store at all" (a separate-clone worktree whose
	// objects never reached the shared store, or a pruned+GC'd one). RUN-52's
	// DKT-V253 was the second: all three vote seats ran `git cat-file -t` on
	// the packet's target, found no object anywhere, and burned an
	// investigation each — while the engine, which had asked git about that
	// exact sha at dispatch open, had silently skipped it as unanswerable.
	//
	// staleTargets consults it only where ancestry was UNANSWERABLE, and only
	// a definitive `exists = false, known = true` produces a warning — so the
	// "absence of evidence is not staleness" posture holds for every state
	// where git genuinely could not answer.
	ObjectExistsFn func(execRoot, sha string) (exists, known bool)
	// CommitPatchFn renders ONE commit's own patch — `sha` against its parent,
	// read from execRoot and scoped like every `issue.diff` — for the verified
	// integration annotation (annotate_integration.go), which re-records a
	// step's diff from the commit the shared branch carries rather than from
	// a working tree. A field for DiffFn's reason: the real one shells out to
	// git, and a test injects a body. nil records an empty body.
	CommitPatchFn func(execRoot, sha string, scope []string) (string, error)
	// IntegrationRangeFn establishes, for the verified integration annotation,
	// whether `tip` (the annotated sha) carries the writer's chain base..head by
	// patch, and where the integrated range starts (DKT-4269). nil skips the
	// check and records the commit's own patch, as before it existed. A field
	// for DiffFn's reason: the real one shells out to git.
	IntegrationRangeFn func(execRoot, tip, head, base string) IntegratedRange
	// RangePatchFn renders the combined patch of from..to, scoped like
	// CommitPatchFn, for the annotation's full-range re-pin. nil falls back to
	// CommitPatchFn on the tip.
	RangePatchFn func(execRoot, from, to string, scope []string) (string, error)
	// IntegrationChainFn answers, read-only, whether a writer's base..head is a
	// chain `step integrate` will pick, and lists its commits oldest first
	// (DKT-4268). nil refuses the verb.
	IntegrationChainFn func(execRoot, base, head string) ([]string, error)
	// CherryPickFn is the engine's only git WRITE: it cherry-picks base..head
	// onto the shared checkout with -x, all or nothing (integrate_git.go). nil
	// refuses the verb, so an engine built without it, every test engine
	// included, can never write the shared branch.
	CherryPickFn func(execRoot, base, head string) (GitPick, error)
	// contains filtered or unexported fields
}

type Error struct {
	Code    ErrorCode
	Message string
	// Err is the underlying cause when there is one, so errors.Is still
	// reaches a db sentinel through this wrapper.
	Err error
	// Holders names the steps that made a claim refusal (DKT-4264). Empty for
	// every error that is not a scope or headroom refusal.
	Holders []Holder
}

type ErrorCode string

type Event struct {
	Seq  int64  `json:"seq"`
	AtMS int64  `json:"at_ms"`
	Kind string `json:"kind"`
	// Run is `RUN-N`, OMITTED WHEN NULL per the `?` in the shape. A trust
	// event has no run and attributing it to one would be a fabrication.
	Run string `json:"run,omitempty"`
	// Step is the RENDERED INSTANCE IDENTITY (`name@k#i`) — matching every other
	// wire shape's step rendering — and omitted when NULL.
	Step string `json:"step,omitempty"`
	// StepID is `STEP-N`: the joinable id, the addition to the shape.
	StepID string `json:"step_id,omitempty"`
	// Issue is `DKT-N`, omitted when the event has none (DKT-74). Instance
	// labels COLLIDE across issues in one run — two issues on the same
	// workflow both have a `fix@1` — and a feed filtered by instance once
	// misattributed a pass-route to a reaped step over exactly that collision.
	// The column was always stored; the wire now carries it.
	Issue string `json:"issue,omitempty"`
	// Project is the NAME of the project the event belongs to — the run's, else
	// the issue's — and is empty for a store-level event (DKT-67).
	//
	// It exists because `--all-projects` had no project discriminator at all
	// once the prefix stopped being one: two projects can hold a `fix@1` step
	// and a `RUN-6`, and the ids alone do not say whose. Omitted when empty so a
	// single-project feed carries no redundant column.
	Project string `json:"project,omitempty"`
	// Data is the stored JSON object, VERBATIM. Core never reshapes it; the
	// writer already normalized it to an object on the way in.
	//
	// It is json.RawMessage rather than a map so the bytes reach `--json`
	// unaltered: re-marshaling a decoded map would reorder keys and re-escape
	// strings, which for a consumer diffing two feeds is a change with no cause.
	Data json.RawMessage `json:"data"`
}

type EventPage struct {
	Events []Event
	// Total counts MATCHING events before the slice, so `truncated` is
	// computable rather than guessed.
	Total int
}

type EventQuery struct {
	// Since returns events with `seq > Since` — STRICTLY GREATER, so a
	// consumer stores the last seq it saw and passes it back without re-reading
	// it. Zero is the default and returns from the beginning.
	Since int64
	// RunID filters to one run using `idx_events_run_seq`. Zero is the
	// repo-wide feed, which is the only place a trust event is visible.
	RunID int
	// Limit applies AFTER ordering. Zero means the caller's default.
	Limit int
	// Tail selects the NEWEST N matching events instead of the oldest N.
	// Zero is off.
	//
	// This is a SELECTION change, not an ordering one. The returned page is
	// still `seq ASC` — the newest N rows, handed back oldest-first — so a
	// reader consumes them in the same direction as every other answer and the
	// last seq is still the cursor to store. "No reverse mode" stands:
	// what varies is WHICH window of the feed is returned, never its direction.
	//
	// Tail is for the mid-incident question ("what just happened"), which the
	// cursor cannot answer without first paging through the entire history to
	// reach the end.
	Tail int
	// Kind filters to one event kind; empty is every kind. StepID filters to
	// one step's events by its joinable id; zero is every step. Both are
	// predicates in the WHERE clause, so they apply BEFORE Limit and Tail and
	// Total counts only the matches (DKT-3293): a lookup by kind or step
	// covers the whole trail instead of searching the oldest page.
	Kind   string
	StepID int
	// ProjectID scopes the feed to one project (v12); 0 is the whole store.
	//
	// An event's project is its RUN's when it has one, else its ISSUE's, else
	// the REPOSITORY ITS PAYLOAD NAMES (DKT-68) — `repo` for a trust change,
	// `identity` for a registration. A store-level event that names no
	// repository at all is a fact about the store and appears in every scoped
	// view, because a scoped feed that hid it would be an audit trail with a
	// blind spot; one that names another repository belongs to that
	// repository's trail, not to this one's. See eventFilter.
	//
	// IT IS IGNORED WHEN RunID IS SET (DKT-583). A run belongs to exactly ONE
	// project, so `--run` is ALREADY a project scope — a narrower one. Anding
	// the invoking project's scope onto it cannot select a meaningful subset:
	// it either changes nothing (the run is this project's) or empties the page
	// entirely (the run is a neighbor's), and the second case answered
	// `{"ok":true,"events":null,"total":0}` for a run with hundreds of events.
	// A successful empty feed is the WORST available answer — a consumer
	// polling it waits forever on a run it can see in `run report`, which
	// resolves a run's project independent of the cwd. `--run` now does the
	// same, which is the disposition DKT-583 prefers.
	ProjectID int
}

type ExecActionRunner struct {
	// RepoRoot is the working-tree root — the cwd every action runs in and the
	// containment boundary.
	RepoRoot string
	// Identity is the project identity trust entries bind to. It
	// equals RepoRoot for env/local stores; under the global store it is the
	// worktree-stable project path.
	Identity string
	// LockPath is the tree lockfile serializing this project's tree-declaring
	// commands.
	LockPath string
	// LoadStore reads the trust store. It is a FIELD so a test can supply a
	// sandbox store without the package growing a path-taking constructor,
	// which is forbidden because every additional way to point
	// docket at a trust file is another way for repo content to point it
	// somewhere.
	LoadStore func() (*trust.Store, error)
}

type ExecRunner struct {
	// RepoRoot is the working-tree root — the cwd every gate runs in — and
	// the containment boundary.
	RepoRoot string
	// Identity is the project identity trust entries bind to. It
	// equals RepoRoot for env/local stores; under the global store it is the
	// worktree-stable project path, which is what lets two checkouts of one
	// repository match the same entries.
	Identity string
	// LockPath is the tree lockfile serializing this project's tree gates.
	LockPath string
	// LoadStore reads the trust store. It is a FIELD so a test can supply a
	// sandbox store without the package growing a path-taking constructor —
	// one is forbidden, because every additional way to point docket at a
	// trust file is another way for repo content to point it somewhere.
	LoadStore func() (*trust.Store, error)
	// NowMS stamps results. Injected so a test is not at the mercy of a clock.
	NowMS func() int64
}

type ExecutorLedger struct {
	Runs      int                 `json:"runs"`
	Executors []ExecutorLedgerRow `json:"executors"`
	Voters    []VoterLedgerRow    `json:"voters"`
}

type ExecutorLedgerOptions struct {
	// ProjectID scopes the runs to one project; 0 reads every project in the
	// store, the way `events list --all-projects` does.
	ProjectID int
	// SinceRun admits runs whose id is at least this; 0 sets no floor.
	SinceRun int
	// SinceMS admits runs created at or after this instant; 0 sets no floor.
	SinceMS int64
}

type ExecutorLedgerRow struct {
	Executor string `json:"executor"`
	// Runs is how many runs in the window expanded a step carrying the hint.
	Runs  int `json:"runs"`
	Steps int `json:"steps"`
	// FixLoopRoutes counts steps carrying the hint whose recorded routing is
	// `fix-loop` — the step's own threshold or on_fail sent the issue into a
	// fix round.
	FixLoopRoutes int `json:"fix_loop_routes"`
	// OverridePasses counts `step resolve --as override-pass` rulings on steps
	// carrying the hint: the times an operator passed what the step's own
	// gates would not.
	OverridePasses int `json:"override_passes"`
	// Reaps counts the `lease-reaped` events on the hint's steps; ForcedReaps
	// is the subset a relay declared dead with `step reap`.
	Reaps       int `json:"reaps"`
	ForcedReaps int `json:"forced_reaps"`
	// UniqueClusters and CorroboratedClusters count, over every `aggregate`
	// round whose step declares `source_field`, the clusters a step carrying
	// the hint contributed a member to: unique when the cluster had one
	// member, corroborated when it had more. HeldClusters is the subset whose
	// spread tripped `hold_spread`.
	UniqueClusters       int `json:"unique_clusters"`
	CorroboratedClusters int `json:"corroborated_clusters"`
	HeldClusters         int `json:"held_clusters"`
}

type Extension struct {
	Dispatch string `json:"dispatch"`
	Run      string `json:"run"`
	// ExtendedSeq is the event seq the appended rows were computed at — the
	// same fact `opened_seq` records for the open, read before this call's own
	// event so it names the log position rather than the append.
	ExtendedSeq int64 `json:"extended_seq"`
	// ExpiresMS is the manifest's expiry AFTER the extension, grown by the
	// appended rows' own staged lease sum.
	ExpiresMS int64           `json:"expires_ms"`
	Rows      []model.StepRow `json:"rows"`
	// Reaped names the step instances whose leases this extend reaped, the
	// same channel OpenDispatch reports its own reaps on.
	Reaped []string `json:"reaped,omitempty"`
	// ReapHold is the guidance for the hold THIS EXTEND left behind, carried
	// for OpenDispatch.ReapHold's reason: an extend runs the same shared reap,
	// and reaping a BOUNDED class inserts an unacknowledged `reap_acks` row
	// that denies the next `guard spawn --active`. A relay that extends and
	// then launches the appended rows would meet that denial with no warning
	// from the verb that created it, and the engine's own advice names
	// `dispatch open --ack-reap` — a verb this relay cannot reach without the
	// dispatch boundary the extend exists to avoid.
	ReapHold string `json:"reap_hold,omitempty"`
}

type FailedGate struct {
	Gate    string `json:"gate"`
	Verdict string `json:"verdict"`
	Exit    *int   `json:"exit"`
	// Reason explains an `unmatched` verdict or a timeout, verbatim from the
	// recorded row.
	Reason string `json:"reason,omitempty"`
}

type FenceReport struct {
	Issue string `json:"issue"`
	Gate  string `json:"gate"`
	Tag   string `json:"tag"`
	// Ordinal is the command's position in body order, which is the order an
	// operator read it in and the order it will run in.
	Ordinal int `json:"ordinal"`
	// Command is the RAW STORED BYTES: JSON escaping is
	// encoding/json's job and the consumer is a program. Human-mode rendering
	// escapes at the print boundary instead, so the stored bytes stay exactly
	// what was harvested and hashed.
	Command string `json:"command"`
	Matched bool   `json:"matched"`
	// Entry names the trust entry that authorized it, when one did.
	Entry  string `json:"entry,omitempty"`
	Reason string `json:"reason,omitempty"`
}

type ForceReapOptions struct {
	// Reason is `--reason`, REQUIRED: the assertion that the holder is gone.
	Reason string
	// By is who asserted it and from where. REQUIRED: an empty field refuses
	// the reap before anything is written (see Attribution).
	By Attribution
	// Token is the run's conductor capability (DKT-2465, conductor.go):
	// required on a bound run, ignored on an unbound one.
	Token string
	NowMS int64
}

type GateExecution struct {
	// Results are the rows to record, in execution order.
	Results []GateResultRow
	// Verdict is the gate's routing verdict, conjunctive over Results.
	Verdict string
}

type GateOutcome string

type GatePreflight struct {
	// Gate is the gate name as the workflow declares it.
	Gate string `json:"gate"`
	// Workflows names every bound workflow declaring this gate, so an operator
	// adding one entry knows what it unblocks. Sorted, so two activations of
	// the same run render identically.
	Workflows []string `json:"workflows"`
	// Matched reports that a trust entry of this name resolves for this repo.
	Matched bool `json:"matched"`
	// Entry names the resolving entry, when one did.
	Entry string `json:"entry,omitempty"`
	// Stub reports that the resolving entry declared itself a placeholder
	// (DKT-265). A gate that WILL run and will measure nothing is a different
	// answer from one that will not run, and both are different from a real
	// check — an operator reading a green preflight should not have to open the
	// trust store to learn which they have.
	Stub bool `json:"stub,omitempty"`
	// StubReason is the resolving entry's recorded reason for being a stub —
	// why the decision was made and which issue tracks replacing it (DKT-607).
	// It rides here so the documented decision is discoverable from the
	// preflight itself, not only from a tribunal transcript or the trust file.
	// Empty when the entry recorded none, which the renderer calls out.
	StubReason string `json:"stub_reason,omitempty"`
	// Reason explains an unmatched gate, verbatim from the matcher, so the
	// preflight and the mid-run diagnostic say the same thing.
	Reason string `json:"reason,omitempty"`
	// Warning is the matcher's warning for a matched gate, verbatim: today an
	// entry with an absolute argv[0] and no content pin, which runs whatever
	// that file holds when the gate fires.
	Warning string `json:"warning,omitempty"`
}

type GateResult struct {
	Gate       string   `json:"gate"`
	Argv       []string `json:"argv"`
	Exit       int      `json:"exit"`
	DurationMS int64    `json:"duration_ms"`
	Output     string   `json:"output"`
	Truncated  bool     `json:"truncated"`
	Verdict    string   `json:"verdict"`
	Stub       bool     `json:"stub,omitempty"`
}

type GateResultRow struct {
	Gate       string
	Ordinal    int
	Argv       []string
	Exit       *int
	DurationMS int64
	Output     string
	Truncated  bool
	Verdict    string
	Reason     string
	// TrustEntry names the entry that authorized this, for the audit record.
	TrustEntry string
	// ArgvSHA256 is the canonical hash of the candidate argv, for trust_cache.
	ArgvSHA256 string
	// Prefix records that a prefix entry authorized it.
	Prefix bool
	// Pre marks a pre-gate result: an input to the step rather than a
	// judgment of it, and excluded from the saga's verdict.
	Pre bool
	// Stub is 1 ONLY for results the pass-through produced. NOTHING THIS
	// RUNNER PRODUCES SETS IT — the field survives so a migrated pass-through
	// row stays distinguishable forever, and so the fakes tests build on the
	// old seam keep recording honestly.
	Stub bool
	// StubEntry carries the matched entry's own `stub` declaration (DKT-265):
	// the command that ran was a placeholder, not the check its name implies.
	//
	// It is set on EVERY row that names a TrustEntry, including the ones whose
	// verdict is unmatched, skipped, or fail. The field describes the ENTRY,
	// not the outcome, and a reader diffing a gate's rows should not have to
	// wonder whether its absence on a failing row means "not a stub" or "we
	// only bother recording this when it passes".
	//
	// Distinct from Stub above, which is about which era of this codebase
	// produced the row. A row can be either, both, or neither.
	StubEntry bool
	// TargetSHA keys a PRE-gate row measured by a detached run to the commit
	// it measured, so a claim reuses it for that target only. The
	// runner never sets it: the detached phase stamps its rows after the
	// measurement, exactly as the claim path stamps Pre. Empty everywhere
	// else.
	TargetSHA string
}

type GateRunner interface {
	Run(ctx context.Context, g GateSpec, sc StepContext) (GateResult, error)
}

type GateSeat struct {
	Voter   string
	Cast    bool
	Verdict string
}

type GateSpec struct {
	// Name is the trusted gate name.
	Name string
	// Source is `fence:<tag>` when the gate's commands come from an issue
	// body's fenced block, or "" for a trusted gate resolved from the trust
	// file. Core reads the tag; what the commands mean is never its business.
	Source string
	// Pre marks a gate that runs at claim, with its results included in the
	// context bundle, rather than in order inside `complete`.
	Pre bool
	// Commands are the harvested fence lines, verbatim, for a `fence:` gate.
	// They are carried rather than re-read so what runs is what was hashed at
	// activation — a post-activation edit cannot inject.
	Commands []string
	// CommandHashes are the SHA-256s activation stored alongside each command,
	// positionally aligned with Commands.
	//
	// The real runner re-verifies each one against its stored command BEFORE
	// spawning. The activation snapshot already closes "the issue body cannot
	// inject"; this closes the narrower "the stored row cannot be swapped". A
	// direct database write is outside the trust boundary, but it costs one
	// hash to detect and a mismatch is refused rather than run.
	CommandHashes []string
}

type GateStatusResult struct {
	StepStatus string
	// Proposal is the display id of the vote this gate opened, empty on a
	// human gate and on a vote gate whose proposal has not opened yet.
	Proposal     string
	Outcome      GateOutcome
	Tally        *GateTally
	Seats        []GateSeat
	MissingSeats []string
	Target       *GateTarget
}

type GateTally struct {
	WeightedScore *float64
	Threshold     float64
}

type GateTarget struct {
	SHA      string
	Worktree string
}

type GateVerdict struct {
	Gate   string `json:"gate"`
	Status string `json:"status"`
	// Reason says why, naming the paths and steps involved, so an operator can
	// tell a `make` entry (retarget it to name the script) from a pin that was
	// never recorded (the run activated before gate scripts were pinned), or
	// an edited copy from a swept work root.
	Reason string `json:"reason"`
}

type GitPick struct {
	// Before is the checkout's HEAD ahead of the pick.
	Before string
	// Tip is its HEAD after, the commit a `step annotate --integrated-sha`
	// names.
	Tip string
	// Picked lists the commits the pick added, oldest first.
	Picked []string
}

type GuardVerdict struct {
	// Allowed is exit 0 when true, exit 2 when false.
	Allowed bool
	// Reason explains a denial. It goes to stderr in human mode and into the
	// JSON envelope's `error` under --json.
	Reason string
}

type HeldClusterLink struct {
	// Cluster is the element's POSITION in the routing step's payload array,
	// zero-based — the number the instance's `#N` suffix carries. Named
	// `cluster_index`, not `cluster`, precisely because it is not an id.
	Cluster int `json:"cluster_index"`
	// Clusters is how many the payload holds, which is what makes the index
	// legible: `#3` alone says nothing about whether that is the last one.
	Clusters int `json:"cluster_count"`
	// Artifact is the ARTIFACT-N the cluster's payload lives in — the answer
	// `step artifacts` on the held row cannot give, because the held row
	// produced nothing.
	Artifact string `json:"artifact"`
	// ProducerStep is the routing step instance that recorded it.
	ProducerStep string `json:"producer_step"`
	// contains filtered or unexported fields
}

type HeldStep struct {
	Step     string `json:"step"`
	Instance string `json:"instance"`
	Issue    string `json:"issue"`
	Reason   string `json:"reason"`
}

type HoldOptions struct {
	// Reason is `--reason`, REQUIRED: it becomes the step's park reason.
	Reason string
	// By is who held it and from where (see Attribution).
	By Attribution
	// Token is the run's conductor capability; required on a bound run.
	Token string
	NowMS int64
}

type HoldPolicy struct {
	// Rule is the configured `vote.hold.rule`, empty when unset.
	Rule string `json:"rule,omitempty"`
	// Voters is the configured `vote.hold.voters`, empty when unset.
	Voters []string `json:"voters,omitempty"`
	// Panel reports the effective answer: true when a hold this run mints will
	// be decided by a tally, false when it goes to one operator.
	//
	// It is a DERIVED field rather than something a reader recomputes from the
	// two above, because the derivation is the thing that was invisible: both
	// keys must be non-empty, and a half-configured pair silently means "one
	// operator" — which is the state an operator who set only one of them would
	// least expect and least easily notice.
	Panel bool `json:"panel"`
}

type Holder struct {
	Step   string `json:"step"`
	Status string `json:"status"`
}

type IncompleteClaimError struct {
	// Result is the claim as transaction A committed it. Context carries the
	// bundle that transaction recorded, which is what the step's inputs are
	// bound to; it lacks only what the failed stage would have added.
	Result *ClaimResult
	Err    error
}

type IntegratedRange struct {
	// Known is false when git could not answer; the caller refuses rather than
	// record an integration nobody verified.
	Known bool
	// Carried reports that the tip holds a patch-equivalent of every commit of
	// the writer's chain, or holds the chain itself.
	Carried bool
	// From is the commit the integrated range starts after: the first parent of
	// the earliest integrated commit. The re-pinned diff runs From..tip, so a
	// multi-commit writer's diff covers every integrated commit, not the last.
	From string
	// Missing names the writer commits (short ids) the tip carries no
	// equivalent of, when Carried is false.
	Missing []string
}

type IntegrationAnnotation struct {
	// IntegratedSHA is the verified commit, as recorded.
	IntegratedSHA string `json:"integrated_sha"`
	// ResolvedFrom is the head the step's previous `issue.diff` record named —
	// the commit the landed content diverged from.
	ResolvedFrom string `json:"resolved_from,omitempty"`
	// Repin is the `issue.diff` re-record this annotation performed, in the
	// shape the `--worktree` re-pin reports; Unchanged when the step's record
	// already named this sha at this body.
	Repin *IssueDiffRepin `json:"issue_diff_repin,omitempty"`
}

type IntegrationCheck struct {
	// Status is "verified" (every write-class step's commit reached the
	// shared branch) or "skipped" (--skip-integration-check named a reason).
	Status string `json:"status"`
	// Reason is the operator's stated reason for skipping, present only when
	// Status is "skipped".
	Reason string `json:"reason,omitempty"`
	// Checked names every write-class commit this close accepted and how:
	// asked of git this pass, honored from a prior close, or vouched for by
	// this close's skip reason. A skipped close asks git nothing, but still
	// records what its reason covered — that record is what lets the next
	// close honor it (integrationCandidatesTx).
	Checked []CheckedIntegration `json:"checked,omitempty"`
}

type IntegrationSkip struct {
	// Conditions is `--no-conditions`, the waiver for unfiled seat conditions
	// (DKT-4263). It rides here because both are close-time overrides that the
	// same conductor token authorizes.
	Conditions ConditionsWaiver
	Reason     string
	Token      string
}

type IssueDiffRepin struct {
	// Worktree is the checkout the diff and target were recomputed from.
	Worktree string `json:"worktree"`
	// FromSHA is the target the step's previous issue.diff record named — the
	// stale one — or "" when the step had recorded no diff at all.
	FromSHA string `json:"from_sha,omitempty"`
	// ToSHA is the re-pinned target: Worktree's HEAD at re-pin time.
	ToSHA string `json:"to_sha"`
	// Artifact is the `ARTIFACT-N` the re-pin recorded, and Supersedes the
	// step's previous issue.diff artifact it revises. Both empty on an
	// Unchanged re-pin, which records nothing.
	Artifact   string `json:"artifact,omitempty"`
	Supersedes string `json:"supersedes,omitempty"`
	// Unchanged reports that the step's newest issue.diff already describes
	// Worktree's tree byte for byte, at the same head, so nothing was recorded
	// and no event was written: the resolution proceeds and the caller says
	// so, rather than refusing a resolution whose only fault is redundancy.
	Unchanged bool `json:"unchanged,omitempty"`
	// contains filtered or unexported fields
}

type IssueDisposition struct {
	Issue string `json:"issue"`
	// Disposition is the ruling. One value today — the constant above — and a
	// field rather than a bare presence flag, so a second issue-level ruling
	// can land here instead of forcing a second section.
	Disposition string `json:"disposition"`
	// By is the step instance whose routing abandoned the issue, or empty when
	// an operator abandoned it from OUTSIDE the graph with `run abandon
	// --issue` — where no step decided anything and naming one would be a
	// fabrication.
	By string `json:"by,omitempty"`
	// Reason is the recorded ruling, VERBATIM and unabridged. Both abandon
	// paths capture it and neither published it: `run abandon --issue` puts it
	// in the event payload, the routing path in the deciding step's own
	// routing note. A renderer may show a head; this carries the whole thing.
	Reason string `json:"reason,omitempty"`
}

type LoopEntry struct {
	Ordinal int    `json:"ordinal"`
	Routing string `json:"routing"`
}

type LoopOutcome struct {
	// Entered reports whether the loop was actually entered. False means the
	// bound was hit and the routing became `waiting-human` (clause 1).
	Entered bool
	// Ordinal is the new loop ordinal when Entered, i.e. the issue's new
	// loop_count. Instances created by this entry carry it.
	Ordinal int
	// Routing is the routing that ACTUALLY applies after the bound is
	// considered: `fix-loop` on entry, `waiting-human` when bounded.
	Routing string
	// Reason explains a bound, for the operator resolving the parked step.
	Reason string
	// Stalled reports that the refusal was non-convergence rather than the
	// `max_fix_loops` bound: budget remained, but the loop was not moving.
	Stalled bool
	// Superseded lists the instances the sweep terminated (clause 2).
	Superseded []string
	// Instantiated lists the instances this entry created — the loop bodies of
	// clause 3 and the re-instantiated chain of clause 4.
	Instantiated []string
}

type Manifest struct {
	Dispatch string `json:"dispatch"`
	Run      string `json:"run"`
	// OpenedSeq is the event seq at open time — the manifest's place in the log
	// and the boundary for "reaps this relay has not yet seen".
	OpenedSeq int64 `json:"opened_seq"`
	// ExpiresMS is not in the wire shape and is emitted alongside it, because
	// both open refusals must NAME the expiry: a relay told only
	// that a dispatch is open cannot tell whether waiting is a strategy.
	ExpiresMS int64           `json:"expires_ms"`
	Rows      []model.StepRow `json:"rows"`
	// Total is the ready set's size BEFORE `--limit` cut it, and Truncated
	// says whether the cut dropped anything. They ride BESIDE the wire shape
	// for StaleTargets' reason: a relay reading only `rows` cannot tell a run
	// whose remaining work fits from one the cap is metering out, and RUN-95's
	// conductor read a post-cut count as the run's whole offer twice against a
	// 930-row ready set. Rows are untouched, so hashing and `dispatch verify`
	// are unchanged.
	Total     int  `json:"total"`
	Truncated bool `json:"truncated"`
	// Limits is the effective per-class `[limits] max` from the scheduler's
	// merged limits, for every class present in the manifest's rows. Without
	// it a relay inferred each class's concurrency from the largest same-stage
	// count in the manifest, which a chain-deep manifest carrying few issues
	// per stage under-certifies.
	Limits map[string]int `json:"limits,omitempty"`
	// LimitSources names what set each Limits entry, keyed by the same
	// classes: "workflow", "override", or "auto" (ClassCapSource).
	LimitSources map[string]string `json:"limit_sources,omitempty"`
	// StaleTargets rides BESIDE the wire shape for ExpiresMS's reason: a
	// conductor about to spend review budget on these rows needs the staleness
	// named (DKT-193). Never a row field — rows are hashed at open and
	// byte-compared at verify, and a live-derived fact would either freeze an
	// open-time answer into row_json or need normalizing away.
	StaleTargets []StaleTarget `json:"stale_targets,omitempty"`
	// BudgetHeld names the ready rows this manifest withheld for lack of
	// budget headroom, with the numbers (DKT-242). It rides BESIDE the wire
	// shape for StaleTargets' reason, and is `omitempty` for the same reason
	// `next`'s equivalent is empty by default: a run with no cap says nothing
	// new.
	//
	// Measured cost of its absence: with 0.9 headroom the engine offered 1 of
	// 5 ready judges and named no reason, and the round serialized around an
	// invisible wall for ~10 minutes and an extra wave cycle. `run budget`
	// already states the numbers honestly; the verb that DECIDES on them did
	// not.
	BudgetHeld string `json:"budget_held,omitempty"`
	// PinDrift is the run's unsound pins, when any (DKT-408) — the same
	// advisory channel StaleTargets rides, for the same reader at the same
	// moment: the conductor deciding whether to spend a wave on these rows.
	// Harness RUN-14 dispatched 3.5M tokens against a drifted pin set and
	// every step reading the drifted contract refused at render; the refusals
	// were correct and the spend was not. Advisory rather than a refusal
	// because drift blocks only the steps that READ a drifted ref — the
	// per-step CONFLICT at claim/render stays the enforcement — but the
	// conductor must get to decide before the wave, not discover it from
	// exit codes inside one.
	PinDrift []PinVerdict `json:"pin_drift,omitempty"`
	// Reaped names the step instances whose leases THIS open reaped — the
	// same fact `next` reports in ReadySteps.Reaped, on the wire because a
	// relay that only ever opens dispatches never calls `next`. OpenedSeq is
	// the boundary for reaps the relay has not yet seen; a reap the open
	// itself performs lands AFTER that boundary, and --ack-reap applied to the
	// same open cannot cover it. Without this a relay learned of its own
	// open's reap only when `guard spawn --active` denied the launch it had
	// just composed (RUN-95: two of four launches, about nine minutes each to
	// convene the panel, join its usage, and relaunch).
	Reaped []string `json:"reaped,omitempty"`
	// ReapHold is the guidance for every unacknowledged bounded-class reap
	// still holding this run's headroom once the open committed — the reaps
	// above included — with each seq and the flag that clears it. It is the
	// text `guard spawn` will deny the next launch with, handed to the relay
	// BEFORE it composes that launch, so the panel or the acknowledgment can
	// come first. Empty whenever nothing is held.
	ReapHold string `json:"reap_hold,omitempty"`
	// RetryEligible lists the gap-only parks whose issue's depends_on or blocks
	// prerequisites are all done and one moved after the park (DKT-4257), so the conductor settles them
	// advisor-first in this loop pass instead of waiting for an operator to ask.
	// Beside the wire shape for StaleTargets' reason: it is a live-derived fact,
	// never a row field. The open also records one park-retry-eligible event
	// per park.
	RetryEligible []RetryEligible `json:"retry_eligible,omitempty"`
	// Held lists the run's held steps with the holder's reason (DKT-4273). A
	// held step is parked, so it is never a row; this says that a withheld row is
	// held on purpose, ready or staged, so the conductor keeps no exclusion list
	// of its own. Live-derived like RetryEligible.
	Held []HeldStep `json:"held,omitempty"`
}

type MemberCount struct {
	Members  int `json:"members"`
	Clusters int `json:"clusters"`
}

type MoveRunOptions struct {
	RunID int
	// Verb names the CLI verb for the refusal message: pause, resume, abandon.
	Verb string
	// To is the target status; From is the closed set of statuses the
	// transition may leave.
	To   model.RunStatus
	From []model.RunStatus
	// Reason is `--reason`, required by the CLI on an abandon.
	Reason string
	// Under is the authority a PAUSE or an ABANDON is exercised under
	// (DKT-1899), required on exactly those two. A RESUME carries none: it
	// returns a run to work rather than disposing of anything, so there is no
	// resolution for an authority to answer for.
	Under Authority
	// Token is the run's conductor capability (DKT-2465, conductor.go):
	// required on a bound run, ignored on an unbound one.
	Token string
	NowMS int64
}

type OrderResolver interface {
	// Position reports a value's index in the field's declared order, and
	// whether the field is ordered AND the value is in that order (I4).
	Position(field, value string) (int, bool)
	// Ordered reports whether the field declares an order at all.
	Ordered(field string) bool
	// FieldType is the field's declared JSON `type`, or "" when the field
	// declares none or is not declared at all. Both fall back to the string
	// comparison, which is correct: a schema that constrains nothing has said
	// the value may be anything.
	FieldType(field string) string
	// Conservative is the field's declared `conservative_end` — which END of
	// the declared order the author considers the cautious one — or "" when
	// none was declared.
	//
	// It reports a DIRECTION, never a rank and never a value, so it cannot
	// become the second ordering API Position exists to be the only one of. Its
	// single reader is the aggregate's even-count median tie-break (DKT-267):
	// core still does not know which end of an order is bad, it asks the order.
	Conservative(field string) string
}

type PacketFile struct {
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
	Body   string `json:"body"`
}

type PacketGate struct {
	Name string
	// Pre marks a gate that runs at claim rather than at record.
	Pre bool
	// Source is a fence gate's source; its commands are the fenced lines,
	// each matched when the gate runs, so no single argv is rendered.
	Source string
	// Matched and Argv are the trust store's answer for a named gate.
	Matched bool
	Argv    []string
	// Reason is why a named gate is unmatched.
	Reason string
}

type PassThroughRunner struct{}

type PinEpoch struct {
	// Epoch numbers from 1, so a zero on a step means "no epoch", never
	// "the first one".
	Epoch int `json:"epoch"`
	// FromSeq is the event seq this agreement took effect at — the
	// `run-activated` event for epoch 1, the repin's first event for the rest.
	// Zero for epoch 1 on a run whose activation event has been pruned away.
	FromSeq int64 `json:"from_seq"`
	AtMS    int64 `json:"at_ms,omitempty"`
	// Origin is `activation` or `repin`.
	Origin string `json:"origin"`
	// Reason is the operator's `--reason`, verbatim, on a repin epoch.
	Reason string `json:"reason,omitempty"`
	// Changes is what MOVED entering this epoch, one entry per changed ref,
	// carrying both hashes exactly as the event recorded them. Empty on epoch 1:
	// nothing moved, the run froze.
	Changes []RepinChange `json:"changes,omitempty"`
}

type PinReport struct {
	Run string `json:"run"`
	// Pins is every pin the run holds, in a total order (kind, then ref), so
	// two checks of one unchanged run produce identical output.
	Pins []PinVerdict `json:"pins"`
	// References is the CLOSURE check, kept beside the per-pin check rather
	// than mixed into it: a conductor reading this needs to know which of the
	// two failed, because they have different remedies and only one of them is
	// about the filesystem. Empty (never nil), in ref order.
	References []ReferenceVerdict `json:"references"`
	// Changed, Missing and Unpinned are the counts a caller branches on without
	// re-walking the lists.
	Changed  int `json:"changed"`
	Missing  int `json:"missing"`
	Unpinned int `json:"unpinned"`
	// Gates lists the declared gates whose script this run does not pin
	// (GateUnpinned) or could not check (GateUnchecked), those whose copy
	// under the invoking exec root differs from the pin
	// (GateExecutedCopyChanged) or is absent (GateExecutedCopyAbsent), and
	// those whose copy under a work root a step recorded differs from the pin
	// (GateStepCopyChanged) or is absent, or whose work root is gone
	// (GateStepCopyAbsent), by gate name. Sound() reads only
	// GateExecutedCopyChanged: a `make <target>` entry names no script file,
	// an absent copy cannot run, and a step may legitimately edit a gate
	// script, so Sound() does not read GateStepCopyChanged or
	// GateStepCopyAbsent. Empty (never nil) only when every declared gate was
	// checked, found pinned, and found matching where it would execute, in
	// gate-name order.
	Gates []GateVerdict `json:"gates"`
	// UnpinnedGates counts only the GateUnpinned rows.
	UnpinnedGates int `json:"unpinned_gates"`
	// ExecutedCopyChanged counts the GateExecutedCopyChanged rows, the one
	// gate status Sound() reads.
	ExecutedCopyChanged int `json:"executed_copy_changed"`
}

type PinVerdict struct {
	Kind   string `json:"kind"`
	Ref    string `json:"ref"`
	Status string `json:"status"`
	// Pinned is the hash the run recorded at activation.
	Pinned string `json:"pinned"`
	// Found is the hash the ref resolves to now — empty when it does not
	// resolve at all.
	Found string `json:"found,omitempty"`
	// Path is where a file pin actually resolved, so an operator restoring a
	// file does not have to guess which config root won.
	Path string `json:"path,omitempty"`
}

type PinnedWorkflowStaleness struct {
	// Ref is the pin's ref verbatim — `name@version`, what the run froze.
	Ref  string `json:"ref"`
	Name string `json:"name"`
	// PinnedVersion is the version this run is expanded from.
	PinnedVersion int `json:"pinned_version"`
	// CurrentVersion is the highest registered version of this name that STILL
	// BINDS — the version a run activated now would pin. Zero when no version
	// of the name binds any more (every one retired, or the name is gone from
	// this project's registry), which is a fact worth publishing rather than
	// rounding to the pinned version.
	CurrentVersion int `json:"current_version"`
	// Behind is THE STALENESS COUNT: how many binding versions are registered
	// STRICTLY ABOVE the pinned one.
	//
	// A count of rows rather than `current - pinned`, and never negative. The
	// subtraction would go negative the moment a higher version is retired
	// while a run holds it, and would over-count where a name's versions are
	// not contiguous — a registry with @1 and @8 and nothing between is one
	// version of advance, not seven.
	Behind int `json:"behind"`
}

type PolicyAssignment struct {
	Model   string `json:"model,omitempty"`
	Effort  string `json:"effort,omitempty"`
	Variant string `json:"variant,omitempty"`
}

type PolicyPin struct {
	Ref    string `json:"ref"`
	SHA256 string `json:"sha256"`
}

type PreGateResult struct {
	Gate       string   `json:"gate"`
	Argv       []string `json:"argv"`
	Exit       *int     `json:"exit"`
	DurationMS int64    `json:"duration_ms"`
	Output     string   `json:"output"`
	Truncated  bool     `json:"truncated"`
	Verdict    string   `json:"verdict"`
	// Stub and StubEntry are the flags `docket step gates` carries, so a
	// consumer judging from a `pass` here can tell a placeholder or migrated
	// row from a measurement. StubEntry describes the authorizing trust entry:
	// it is false on a row no entry authorized, so read the verdict first.
	Stub bool `json:"s3_migrated,omitempty"`
	// StubEntry is never omitted: an absent key would read the same as a
	// docket too old to carry the flag.
	StubEntry bool   `json:"stub"`
	Reason    string `json:"reason,omitempty"`
}

type ProjectRegistration struct {
	// ID is the project row that came into being.
	ID int
	// Name is the row's display name.
	Name string
	// Identity is the path the row is keyed by.
	Identity string
	// Cwd is the working directory the invocation ran from.
	Cwd string
	// Verb is the full command path (`step complete`, `issue create`) that
	// triggered the registration.
	Verb string
	// Prefix is the display prefix the row was given.
	Prefix string
}

type ProjectRegistryAudit struct {
	ProjectID int    `json:"project_id"`
	Project   string `json:"project"`
	Prefix    string `json:"prefix,omitempty"`
	Identity  string `json:"identity,omitempty"`
	// Compared is how many distinct registered names were classified. It is
	// carried so "no findings" is distinguishable from "nothing registered
	// here" — two clean-looking results with nothing in common.
	Compared int              `json:"compared"`
	Behind   []RegistryLag    `json:"behind"`
	Orphaned []RegistryOrphan `json:"orphaned"`
}

type PruneQuery struct {
	// Before deletes events with `seq < Before` — STRICTLY LESS, so
	// `--before N` and a cursor at `N-1` name the same boundary, which is the
	// convention every other seq comparison in this feed already follows.
	Before int64
	// BeforeRun deletes every event of one run, whatever its seq. It is the
	// preferred form — trim whole runs that reached a terminal status, rather
	// than the oldest N events across all of them, so the report stays honest
	// for every run still covered.
	BeforeRun int
	// RunID narrows Before to one run. Zero is every run.
	RunID int
	// DryRun computes the answer and deletes nothing.
	DryRun bool
	// NowMS is the transaction's clock, used for the retention boundary and for
	// the `events-pruned` event's timestamp. It is passed IN rather than read
	// here so the boundary and the event agree, and so a test can place the
	// window without waiting for wall-clock time to pass.
	NowMS int64
}

type PruneResult struct {
	Pruned          int   `json:"pruned"`
	RetainedMinimum int64 `json:"retained_minimum"`
	DryRun          bool  `json:"dry_run,omitempty"`
	// HeldByRetention counts rows the boundary protected. It is reported
	// rather than silently subtracted: an operator who asked to prune 900 events
	// and pruned 200 must be told a policy held back the other 700, or they will
	// conclude the verb is broken.
	HeldByRetention int `json:"held_by_retention,omitempty"`
	// LiveRuns names the non-terminal runs that blocked the prune, for the
	// refusal message.
	LiveRuns []string `json:"-"`
}

type ReadyCondition string