dispatch

type ContextEnterRequest struct {
	// Enter is the enter script path, relative to Dir.
	Enter string

	// Event is the fired `on` trigger — a ContextEventKind (a Post variant is
	// legal, unlike a gate). Carried into the payload flat, as `event`.
	Event event.Event

	// TranscriptPath names the session record enter reads to recognise "now it's
	// the time" and extract the payload. May be "".
	TranscriptPath string

	// Gates is every declared gate's most recent verdict, by name — what enter
	// reads as `gates[<name>].status` to gate its own activation.
	Gates map[string]natures.GateState

	// CurrentContext is this context's own last {active, payload}, so enter sees
	// what was there before deciding whether to grow, replace, or leave it.
	CurrentContext natures.ContextState

	// Dir is the context's own folder — enter resolves relative to it, and its
	// scripts find their siblings there.
	Dir string

	// Name is the context's name, for the script's SR_GUARDRAIL and for
	// diagnostics.
	Name string

	// Workspace and SessionID are the session facts enter's environment carries —
	// SR_WORKSPACE (to resolve a workspace-relative path and key its own state) and
	// SR_SESSION_ID — the same as a check's. Empty leaves them unset.
	Workspace string
	SessionID string

	// AgentID is the sub-agent the hook fired inside, emitted as SR_AGENT_ID —
	// see Request.AgentID.
	AgentID string

	// LaunchedBy is the re-entry provenance emitted as SLOPRAIL_LAUNCHED_BY, so a
	// context whose enter spawns sr-agent does not re-enter itself on the launched
	// agent's writes. The caller computes it (appendLaunchedBy) and threads it
	// through; the runner forwards it onto the scriptCall. See scriptCall.LaunchedBy.
	LaunchedBy string
}

type ContextExitRequest struct {
	// Exit is the exit script path, relative to Dir.
	Exit string

	// Event is the Stop that triggered the exit check.
	Event event.Event

	// TranscriptPath names the session record exit reads. May be "".
	TranscriptPath string

	// Gates is every declared gate's most recent verdict, by name — how the
	// paired context reads a gate's own verdict back to decide active/inactive.
	Gates map[string]natures.GateState

	// CurrentContext is this context's own entry from the context[] map.
	CurrentContext natures.ContextState

	// Dir is the context's own folder.
	Dir string

	// Name is the context's name.
	Name string

	// Workspace and SessionID are the session facts exit's environment carries —
	// see ContextEnterRequest. Empty leaves them unset.
	Workspace string
	SessionID string

	// AgentID is the sub-agent the hook fired inside, emitted as SR_AGENT_ID —
	// see Request.AgentID.
	AgentID string

	// LaunchedBy is the re-entry provenance emitted as SLOPRAIL_LAUNCHED_BY — see
	// ContextEnterRequest.LaunchedBy. The caller threads it through so an exit that
	// spawns sr-agent does not re-enter this context on the launched agent's writes.
	LaunchedBy string
}

type FileHistory struct {
	Baseline, Current HistoryState
	Points            []HistoryPoint

	// Content returns the content a hash names, and whether it is known.
	Content func(hash string) (string, bool)
}

type HistoryPoint struct {
	// Foreign marks a change the agent did not make: the file as it stood at
	// the start of one of the agent's cycles, when that differs from how the
	// agent left it (or, at the session's first hook, from the baseline). Such
	// a change is never charged to the agent. From is where it started; nil
	// when that is not known (the session's first hook), which charges nothing
	// before it either.
	Foreign bool
	From    *HistoryState

	// FromAt is when the file stood at From (the agent's last Stop). A cited
	// change of another session landing after it — a background sub-agent's,
	// say — explains a difference from From that is not the agent's either.
	FromAt int64

	// BetweenTurns marks a change that landed between the agent's Stop and its
	// next hook while work it had started may still have been running (By
	// names that work): charged like the agent's own, from From to After, and
	// the refusal says why.
	BetweenTurns bool
	By           string

	// Pools are the pools the citations of a cited change resolved in. A cited
	// change grounds a requirement only when one of them is one it accepts:
	// a change cited in the wrong pool is, to that requirement, uncited.
	Pools []transcript.SourceType

	// Whole marks a cited change that stated the file's entire content (an
	// sr-file write): it grounds the file as it left it, so nothing before it
	// is left ungrounded.
	Whole bool

	Before, After HistoryState

	// At orders points across the stores a Stop merges (the session's own and
	// its sub-agents' or dispatcher's).
	At int64
}

type HistoryState struct {
	Exists bool
	Hash   string
}

type Nature string

type Prepared struct {
	// Skip: prepare asked not to run the judge; the check abstains.
	Skip bool
	// Context is prepare's additionalContext, folded into the judge's input.
	Context declaration.PreparedContext
}

type Request struct {
	// Nature is which payload/judge-input shape the checks are handed.
	Nature Nature

	// Require are the preconditions that must hold before any check runs, in
	// order. A failed prerequisite refuses before a check is paid for.
	Require []declaration.Prerequisite

	// Checks are the checks to run, in order, first-refusal-ends-it.
	Checks []declaration.Check

	// Event is the fired event the checks decide about — a pre-action GateEventKind
	// for a gate, a file event for a file-guard. Carried into the payload as-is.
	Event event.Event

	// TranscriptPath names the session record a check (or the native `{skill}`
	// prerequisite) reads for what the event does not carry. May be "" when the
	// session's record could not be resolved; a `{skill}` prerequisite then
	// refuses, because a precondition it cannot check has not passed.
	TranscriptPath string

	// Subagent is true when the agent being judged is a sub-agent — decided by
	// the hook that fired (SubagentStop), never read from a record. A refusal for
	// want of the user's words then tells it to hand the change back to its
	// parent, which can ask the user, rather than to ask the user itself.
	Subagent bool

	// Context is every declared context by name, at parity with the nature's match
	// scope — what a check reads as `context[<name>]`, and what a `{context}`
	// prerequisite consults. Nil is an empty map.
	Context map[string]natures.ContextState

	// Gates is every declared gate's most recent verdict by name. Carried for the
	// payloads that expose it (a context's enter/exit; not a gate/file-guard check,
	// which the spec gives no `gates`) and threaded through for the next slice. Nil
	// is an empty map.
	Gates map[string]natures.GateState

	// Dir is the rule's own folder, against which a check's `script`, `judge` and
	// `prepare` paths resolve — the same relative-to-the-guard rule the spec states
	// and the old format's guardrailDir provides.
	Dir string

	// GuardName is the rule's name, used only for diagnostics and for the judge's
	// isolation. Not load-bearing for the verdict.
	GuardName string

	// Qualified is the rule's `<plugin>/<nature>/<name>` (`<nature>/<name>` in-repo): what a
	// judge is identified by under SR_CHECKS_JUDGE_MOCKS. Empty falls back to the nature and GuardName.
	Qualified string

	// Workspace is the tree being guarded, passed into a check's environment as
	// SR_WORKSPACE so a script can resolve a workspace-relative path (a goal's
	// verify.sh under <workspace>/goal/…) and key its own `sr-session state`. The
	// caller resolves it (the payload's cwd, git-rooted); the runner only forwards
	// it. Empty leaves SR_WORKSPACE unset.
	Workspace string

	// ProjectRoot is the tree a JUDGE reads as the project, when it differs from
	// Workspace: a changeset's read-only snapshot of the tip being judged (SR_TREE).
	// A file-guard judges commits, so the judge must see the committed tree of that
	// tip, never the folder's checked-out working tree (another branch, or
	// uncommitted edits). Empty falls back to Workspace.
	ProjectRoot string

	// SessionID is the conversation's identity, passed as SR_SESSION_ID so a
	// check's own `sr-session state` lands in this session's keyspace. Empty leaves
	// it unset (diagnosable). Not load-bearing for the verdict.
	SessionID string

	// AgentID is the sub-agent the hook fired inside, as the harness reported it,
	// passed as SR_AGENT_ID (empty, but set, in the main session) so a rule can
	// tell a sub-agent's action from the main session's. Not load-bearing for the
	// verdict.
	AgentID string

	// LaunchedBy is the re-entry provenance — the colon-separated list of guards
	// whose checks are on the current call stack — passed into every check's
	// environment as SLOPRAIL_LAUNCHED_BY. A check that spawns sr-agent (a judge,
	// or a script that shells it) carries this across the exec into the launched
	// agent, whose own hooks read it and decline to re-fire THOSE guards on the
	// agent's writes. Without it a judging guard re-fires on itself and recurses.
	//
	// The caller computes it with services/sr-session's appendLaunchedBy (this
	// guard appended to any inherited value, deduped) because this package sits
	// below that one and cannot import its provenance logic. The runner only
	// forwards it onto the scriptCall / judgeCall. Empty leaves the variable unset
	// — correct for a check that cannot launch an agent, harmless for one whose own
	// name is the only entry. Not load-bearing for THIS request's verdict; it
	// governs the verdict of the dispatch one exec down.
	LaunchedBy string

	// History is, for a Post file event at Stop whose path had cited changes
	// this session, the file's history from the session baseline (see
	// FileHistory). A citation grounds only the change it rode on, so a
	// `citation` prerequisite holds only when its `when` waives every part of
	// the change the agent made that no cited change in its pools made (with no
	// `when`, no such part may exist). Nil for every other event — a Pre event
	// IS one change, and its citations ride on it.
	History *FileHistory

	// Changeset, when set, is what a file-guard's checks are handed instead of a
	// file event: a script's stdin and a judge's template variables are this
	// payload (`event: {kind: "Changeset"}`, `changeset`, `subject`, ...), and a
	// judge additionally gets `change`, the combined diff of the selected files.
	// Event still carries the changeset's citations (under `citations`), which is
	// what a `require: citation` prerequisite reads.
	Changeset *changeset.Payload

	// Env is extra environment for every script and judge this request runs,
	// appended after the inherited one so it wins — SR_TREE, SR_BASE and SR_HEAD for
	// a changeset: the read-only snapshot of head the checks read, and the range.
	Env []string
}

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

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

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

type UncitedChange struct {
	FromExists bool
	From       string
	ToExists   bool
	To         string
	// ToKnown is false when To could not be read (the settled file, unreadable).
	ToKnown bool

	// BetweenTurns: the change landed after the agent's last Stop, while work
	// it had started (By) may still have been running.
	BetweenTurns bool
	By           string
}

type Verdict struct {
	// Refused reports whether the action must not proceed. When true, Reason is
	// non-empty.
	Refused bool

	// Reason is what to tell the agent on a refusal — the prerequisite's remedy,
	// or the check's own words. Never empty when Refused.
	Reason string

	// Abstained reports that this ONE check reached no verdict and drops out of the
	// chain — the other checks decide. Never true together with Refused. Set only by
	// a judge check whose prepare asked to skip; the loop treats it as "continue,
	// count nothing", and Run never surfaces it (an all-abstain chain permits, the
	// same as reaching the end with no refusal).
	Abstained bool

	// NoVerdict reports that a check refused for want of an answer, not as a verdict on the
	// content. For a judge: it produced nothing the verifier could read, timed out, could not
	// start, or the model's transport failed. For a script or a prepare: it could not be run
	// at all, or said {"error": true} on stdout.
	// Only with Refused. Set by the check call itself (askJudge, runScriptCheck, runPrepare),
	// so callers need not read the Reason text.
	NoVerdict bool

	// Unavailable is, for a judge whose substrate (the harness behind sr-agent) died, the cause
	// sr-agent named: "usage limit", "authentication", "version skew" or "other". Only with
	// NoVerdict. It lets a run report one "judges unavailable" outage instead of a refusal per check.
	Unavailable string
}