declaration

type Check struct {
	// Script is a deterministic executable, resolved relative to the rule's
	// folder. Receives the payload on stdin and exits with a pass/fail code.
	// Exactly one of Script / Judge is set.
	Script string `yaml:"script"`

	// Judge is a model judgement, a Jinja2 prompt template (`.md.j2`) resolved
	// relative to the rule's folder. Exactly one of Script / Judge is set.
	Judge string `yaml:"judge"`

	// Prepare is an optional deterministic executable that runs before the check
	// (a Judge or a Script). What it returns under `additionalContext` is added to
	// the judge's prompt variables, or to the script's payload. It only builds context:
	// it names no fingerprint, and neither its output nor the rendered prompt is part of
	// the verdict's cache key (a `subjects:` script supplies a fingerprint).
	Prepare string `yaml:"prepare"`

	// Model is which model a Judge asks, in the same modelset format sr-agent's
	// `--model` takes (a `size-xs`..`size-xxl` alias, a concrete harness model
	// name, or a comma-separated preference list). Empty means the engine's
	// default (size-md). Only meaningful alongside a Judge — a script has no
	// model to choose — so Model set on a script-only check is a load error the
	// validator refuses. See
	// dot-dir-file-store/main.tsp Check.model.
	Model string `yaml:"model"`

	// Timeout is how long a Judge may take before it is killed and read as a
	// refusal, overriding the engine's default (defaultCheckTimeout, 600s). A Go duration string
	// (`45s`, `2m`, `1m30s`) parsed with time.ParseDuration; the validator
	// refuses one that does not parse or is <= 0. Only meaningful alongside a
	// Judge — a script's own runtime is the author's to bound — so Timeout set
	// on a script-only check is a load error. See
	// dot-dir-file-store/main.tsp Check.timeout.
	Timeout string `yaml:"timeout"`

	// AllowedTools are the tools a Judge's agent is permitted to use, threaded to
	// sr-agent's `--allowed-tools` (which maps to claude's own `--allowed-tools`).
	// A judge that must Read the file it judges, or WebFetch a URL it verifies
	// against, names those here; the engine's judge substrate already grants the
	// Write the verdict file needs, so this is only the tools the RUBRIC's own
	// work requires. Only meaningful alongside a Judge — a script names its own
	// tools by being an executable — so AllowedTools set on a script-only check is
	// a load error, mirroring the stray-model/timeout rule. See
	// dot-dir-file-store/main.tsp Check.allowed_tools.
	AllowedTools []string `yaml:"allowed_tools"`

	// DisallowedTools are harness permission rules the Judge's agent is DENIED,
	// threaded to sr-agent's `--disallowed-tools` (claude's own
	// `--disallowed-tools`). A deny beats every allow, so this is how a rule that
	// grants a command family — `Bash(curl:*)` — takes back the forms of it the
	// judge must not use (`Bash(curl * -o *)`). Each entry is one rule in the
	// harness's own syntax, parentheses and spaces included. Judge-only, like
	// AllowedTools.
	DisallowedTools []string `yaml:"disallowed_tools"`
}

type CheckPayload struct {
	// Event is the file event — a FileEvent variant (always a Post*: a file-guard
	// judges the settled file at Stop and never sees a Pre*). A FlatEvent, so its `kind` and fields are
	// read FLAT under `event` (`.event.path`, `.event.newContent`,
	// `.event.newMarkers`) the way the spec models it and every example reads it —
	// not through the nested `{kind, fields}` envelope the old format used.
	Event FlatEvent `json:"event"`

	// TranscriptPath names the session record a check reads for what the event
	// does not carry.
	TranscriptPath string `json:"transcriptPath"`
}

type CitationPrerequisite struct {
	// SourceTypes are the pools a citation may have resolved in — cite's
	// --source-types vocabulary. Required and non-empty.
	SourceTypes []string `yaml:"source_types"`
}

type Context struct {
	// Name is the context's name, its folder's name, and its key in the `context`
	// map. Not a YAML field.
	Name string `yaml:"-"`

	// On are the events that can (re-)run `enter` — the cheap first stage. Wider
	// than a gate's (ContextEventKind): a context may wake on the Post file
	// events and PostTagWrite, because it sometimes must recognise itself from a
	// file's SETTLED content. A trigger's `event` may be the alias `PreFileWrite`
	// or `PostFileWrite`, expanded to the matching Create + Update pair.
	On []ContextTrigger `yaml:"on"`

	// Require are preconditions that must hold before `enter` runs — see
	// Prerequisite. Optional.
	Require []Prerequisite `yaml:"require"`

	// Enter is the script that decides whether to (re-)activate and what the
	// context's payload should be. Runs on EVERY `on` trigger, active or not.
	// Required and non-empty.
	Enter string `yaml:"enter"`

	// Exit is the script that decides whether the context is done, consulted on a
	// Stop while active. Its verdict only flips this context's own `active`; it
	// does not refuse the Stop. Required and non-empty.
	Exit string `yaml:"exit"`

	// Dir is the context's own folder. Not a YAML field.
	Dir string `yaml:"-"`

	// Origin is where this context was found — the project's own `.sloprail`, or a
	// plugin that ships it. Not a YAML field; the loader fills it. The zero value
	// is a project's own context.
	Origin Origin `yaml:"-"`
}

type ContextEnterPayload struct {
	// Event is the trigger that fired — a ContextEventKind variant. A FlatEvent,
	// read FLAT under `event` (`.event.newContent`, `.event.path`, `.event.kind`,
	// `.event.tags`) the way the context example scripts read it.
	Event FlatEvent `json:"event"`

	// TranscriptPath names the session record enter reads.
	TranscriptPath string `json:"transcriptPath"`

	// Gates is every declared gate's most recent verdict, by name.
	Gates map[string]natures.GateState `json:"gates"`

	// CurrentContext is this context's own last state — enter runs on every
	// trigger, active or not, so it needs to see what was there.
	CurrentContext natures.ContextState `json:"currentContext"`
}

type ContextExitPayload struct {
	// Event is always the Stop that triggered the exit check. A FlatEvent, read
	// FLAT under `event` — a Stop carries only `.event.kind`, but the shape is the
	// same flat one every other payload uses so a script reads it uniformly.
	Event FlatEvent `json:"event"`

	// TranscriptPath names the session record exit reads.
	TranscriptPath string `json:"transcriptPath"`

	// CurrentContext is this context's own entry from the `context` map.
	CurrentContext natures.ContextState `json:"currentContext"`

	// Gates is every declared gate's most recent verdict, by name.
	Gates map[string]natures.GateState `json:"gates"`
}

type ContextTrigger struct {
	// Event is the event kind. May be the config-level alias `PreFileWrite` or
	// `PostFileWrite`, each expanded to the matching Create + Update pair on load.
	Event string `yaml:"event"`

	// Match is an optional expression over the event's fields; absent means every
	// occurrence. Scoped to the context scope for whichever kind Event names — the
	// event's fields under `event` (`any(event.tags, …)`, `event.path startsWith …`).
	Match string `yaml:"match"`
}

type Deletions string

type Env struct {
	// Registry is the module registry, for the field declarations a trigger's
	// `match` is compiled against. A gate/context trigger's `match` reads the
	// fired event's fields under `event`, and those fields are the kind's — so the
	// scope must be built from the kind's KindDecl, which the registry holds.
	Registry *module.Registry

	// Contexts is the set of declared context names, for resolving a
	// `require: [{context: X}]`. Built by the loader from the context folder
	// before any declaration is validated, because a prerequisite may name a
	// context declared in a different folder than the rule that requires it.
	Contexts map[string]bool
}

type Fault int

type FileGuard struct {
	// Name is the guard's name and its folder's name. Taken from the folder
	// rather than the file, the same reasoning the old loader records: a name
	// recorded twice is a name that can disagree with itself. Not a YAML field.
	Name string `yaml:"-"`

	// Match is which files this guard covers, and under which contexts. A
	// FileMatchExpression: either a bare glob (the common "this path" case) or a
	// full expression over a file's own facts — its path, the markers it carries,
	// and `context[<name>]`. Compiled against the file scope at load, so a bad
	// expression is refused with a diagnostic naming it rather than silently
	// never matching.
	Match string `yaml:"match"`

	// HadPreventiveKey records that the RETIRED `preventive:` key was present,
	// whatever its value. A file-guard judges only the settled result at Stop;
	// preventing a write is a gate's job (a PreFileWrite or PreFileDelete gate).
	// The field exists only so the loader can SEE the key and refuse the
	// declaration by name (ValidateFileGuard, ErrRetiredKey) — unknown keys are
	// otherwise tolerated, and a `preventive: true` quietly ignored would leave
	// the write it was written to stop unguarded. Nothing else reads it.
	HadPreventiveKey bool `yaml:"-"`

	// Deletions says whether a DELETED file is this guard's business: `skip`
	// (the default, and what an absent key means), `include`, or `only`. See
	// Deletions for the three values.
	//
	// One axis with three values, NOT a list of events — the same reasoning that
	// keeps a file-guard's other axes small. A file-guard binds to a
	// file's STATE, not to events; the one place the state question genuinely
	// forks is a file that no longer exists, which has no end state, no
	// newContent and no newMarkers. Most guards validate content and have nothing
	// to say about a file that is gone (so they skip it); a few exist precisely
	// to catch the loss (so they include it, or look at nothing else). An `on:`
	// list would reopen every create/update/delete combination a state rule has
	// no use for, so it is deliberately not offered.
	Deletions Deletions `yaml:"deletions"`

	// Require are preconditions that must hold before a guarded write is
	// permitted — see Prerequisite. Optional.
	Require []Prerequisite `yaml:"require"`

	// Subjects is an optional script, resolved from the rule's folder, that splits the
	// selected files into the units the rule is judged on, each cached on its own. Run with
	// the changeset payload on stdin and no session; prints a JSON array of
	// {"id", "files", "fingerprint"} (fingerprint optional: what that subject's verdict depends
	// on beyond its files' content). Absent: one subject made of every selected file.
	Subjects string `yaml:"subjects"`

	// Checks are the checks a guarded file must pass, in order. Each is a script
	// or a judge (both may appear across the list), and order is significant: a
	// cheap deterministic script runs first and can settle the matter before a
	// judge is paid for. The first check that refuses ends it.
	Checks []Check `yaml:"checks"`

	// Dir is the guard's own folder, so its scripts and judge prompts resolve
	// relative to it. Not a YAML field — the loader fills it from where the file
	// was found.
	Dir string `yaml:"-"`

	// Origin is where this guard was found — the project's own `.sloprail`, or a
	// plugin that ships it. Not a YAML field; the loader fills it from which root it
	// read the guard from, so a refusal can name the plugin a shipped guard came
	// from (see Origin). The zero value is a project's own guard.
	Origin Origin `yaml:"-"`
}

type FileJudgeInput struct {
	// CheckPayload's fields render unprefixed at the template's top level
	// (`{{ event.newContent }}`, `{{ transcriptPath }}`, `{{ context }}`).
	CheckPayload `json:",inline"`

	// Change is the unified diff from the event's oldContent to its newContent
	// (`{{ change }}`): what THIS change does to the file — at pre-tool the
	// pending write, at Stop everything since the session baseline. A judge of a
	// grounded change rules on it, not the whole file: a citation grounds the
	// change it was made with, and lines the change leaves alone were grounded,
	// or not, when they were written. Empty when the event carries no content.
	Change string `json:"change"`

	// AdditionalContext is present only when the check's own prepare returned one.
	AdditionalContext PreparedContext `json:"additionalContext,omitempty"`
}

type FlatEvent event.Event

type Gate struct {
	// Name is the gate's name and its folder's name. Not a YAML field.
	Name string `yaml:"-"`

	// On are the events this gate wakes on — pre-action only (GateEventKind). A
	// trigger's `event` may be the alias `PreFileWrite`, which the loader expands
	// to PreFileCreate + PreFileUpdate. Each trigger's optional `match` is
	// compiled against the gate scope for the kind it names.
	On []GateTrigger `yaml:"on"`

	// Require are preconditions that must hold before the gated action is
	// permitted — the same Prerequisite a file-guard uses. Optional, BUT a gate
	// must carry at least one of Require / Checks (a gate with neither would wake
	// and do nothing).
	Require []Prerequisite `yaml:"require"`

	// Checks are the checks the gated action must pass, in order — the same Check
	// shape a file-guard uses. Optional, subject to the same at-least-one rule as
	// Require.
	Checks []Check `yaml:"checks"`

	// Enabled, when false, ships the gate OFF: it is inert until the project lists its
	// qualified name under `enabled:` in `.sloprail/config.yaml`. Absent means on.
	Enabled *bool `yaml:"enabled"`

	// Dir is the gate's own folder. Not a YAML field.
	Dir string `yaml:"-"`

	// Origin is where this gate was found — the project's own `.sloprail`, or a
	// plugin that ships it. Not a YAML field; the loader fills it. The zero value
	// is a project's own gate.
	Origin Origin `yaml:"-"`
}

type GateCheckPayload struct {
	// Event is the fired pre-action event — a GateEventKind variant. A FlatEvent,
	// read FLAT under `event` (`.event.path`, `.event.invocations`) the way the
	// spec models it — see CheckPayload.Event.
	Event FlatEvent `json:"event"`

	// TranscriptPath names the session record for the trajectory-reading a gate's
	// checks usually do.
	TranscriptPath string `json:"transcriptPath"`

	// Context is every declared context, by name.
	Context map[string]natures.ContextState `json:"context"`
}

type GateJudgeInput struct {
	// GateCheckPayload's fields render unprefixed at the template's top level.
	GateCheckPayload `json:",inline"`

	// AdditionalContext is present only when the check's own prepare returned one.
	AdditionalContext PreparedContext `json:"additionalContext,omitempty"`
}

type GateTrigger struct {
	// Event is the event kind. May be the config-level alias `PreFileWrite`,
	// which the loader expands to PreFileCreate + PreFileUpdate. No `PostFileWrite`
	// alias here — a gate does not wake on settled content.
	Event string `yaml:"event"`

	// Match is an optional expression over the event's fields; absent means every
	// occurrence of the kind. Scoped to the gate scope for whichever kind Event
	// names, so the event's fields are read under `event` (`event.path`,
	// `any(event.invocations, …)`).
	Match string `yaml:"match"`
}

type Invalid struct {
	// Nature says which of the formats this was — so a diagnostic can say
	// "gate X" rather than a bare name that collides across natures (a gate and a
	// context may both be named `people-linked`).
	Nature Nature

	// Name is the declaration's name, from its folder. Empty for a structure gate,
	// which has no per-name folder.
	Name string

	// Origin says where this unloadable declaration was found. A broken rule needs
	// attribution more than a working one does, not less: the refusal it causes
	// tells an author to go and fix a file, and for a plugin's rule that file is not
	// in their project and not theirs to fix. The zero value is a project's own.
	// Mirrors guardrail.Invalid.Origin.
	Origin Origin

	// Path is where the unloadable declaration was found, so an author can open
	// the exact file.
	Path string

	// Problems is every fault found, each carrying a Kind a caller can branch on
	// with errors.Is.
	Problems []Problem

	// Reasons is Problems rendered one line each, and Reason is those joined —
	// derived at construction so they cannot drift from the list they summarise.
	Reasons []string
	Reason  string
}

type Loaded struct {
	// FileGuards are the loaded file-guard declarations, sorted by name.
	FileGuards []FileGuard

	// Gates are the loaded gate declarations, sorted by name.
	Gates []Gate

	// Contexts are the loaded context declarations, sorted by name.
	Contexts []Context

	// Structures are the loaded structure gates — the project's own first (when
	// it declares one), then each enabled plugin's in precedence order. They are
	// COMBINED, not resolved: none shadows another. The project's covers the
	// whole tree; each plugin's covers only its declared `scope`. How they combine
	// on a written path is internal/dispatch's StructureSet.Decide.
	Structures []StructureGate

	// ScopeOverlaps are pairs of loaded plugin structures whose LITERAL scopes
	// overlap. Both stay loaded (a write in the overlap is refused at write time
	// as an ownership conflict); the overlap is reported so it is seen before an
	// agent meets it.
	ScopeOverlaps []ScopeOverlap

	// Degraded are declarations that ARE loaded and enforced but carry an environment
	// fault (a declared script that lost its shebang or execute bit): reported where
	// Invalid is, never dropped, because a rule that stopped loading would stop
	// refusing. At run time the exec path refuses what such a rule guards until the
	// file is fixed. Only declarations that are in force: one displaced (Shadowed) or
	// disabled is neither loaded nor enforced, so it is not reported here. Sorted by
	// qualified name.
	Degraded []Invalid

	// Invalid are the declarations that could not be loaded, across every nature,
	// sorted by their qualified name. Reported rather than fatal: the engine loads
	// every sound declaration and refuses only the ones that are not.
	Invalid []Invalid

	// Shadowed are plugin declarations a declaration of the same (nature, name)
	// displaced (never a structure gate — those combine rather than shadow) — the project's own, or an earlier-listed plugin's. Returned rather
	// than applied silently, for the reason guardrail.Resolution.Shadowed is: a
	// project that believes it has two protections and has one is the failure this
	// product exists to prevent. The precedence IS applied (the winner is what
	// loads); the consumer is merely told which rule they displaced and where it
	// lives, so overriding stays a choice rather than an accident. See Shadow.
	Shadowed []Shadow
}

type Nature string

type Origin struct {
	// Plugin is the name of the plugin this declaration shipped inside, or "" for
	// a declaration the project declared itself.
	//
	// Supplied by the resolver, which read it out of the settings key that enabled
	// the plugin, rather than derived here from the directory name. The settings
	// key is what the USER wrote and what they will search for; a cache directory's
	// name is an artefact they never see, and the two can differ. (This is the
	// exact reasoning guardrail.Origin.Plugin records.)
	Plugin string

	// Root is the plugin installation directory this declaration was found under,
	// empty for a project's own. Kept so a diagnostic can name the actual path,
	// which is what an author needs when the rule is not where they would look.
	Root string
}

type PreparedContext map[string]any

type PreparedOutcome struct {
	// AdditionalContext is the freeform template context, present only when the
	// prepare emitted one AND the judge is going to run. Ignored when Skip.
	AdditionalContext PreparedContext `json:"additionalContext"`

	// Skip, when true, is prepare asking this judge check to ABSTAIN: the judge is
	// not invoked and the check reaches no verdict of its own — other checks decide
	// (see the four-outcome contract above). Absent/false is the unchanged "run the
	// judge" default.
	Skip bool `json:"skip"`
}

type Prerequisite struct {
	// Skill is the name of a skill that must have been loaded (a real Skill
	// tool_use in the trajectory, not a claim) before the write. Optional.
	Skill string `yaml:"skill"`

	// Files, optional and meaningful only alongside Skill, names one or more
	// files INSIDE that skill (relative to its own directory — the one holding
	// its SKILL.md, e.g. "script-checks.md", "file-guard.md") that must ALSO
	// have been read (a Read tool_use, or a file-reading Bash command) before
	// the write — the same evidence a bare `{skill}` already accepts for the
	// skill's own SKILL.md, extended to its subpages.
	//
	// This exists because loading a skill only guarantees its SKILL.md was
	// read; a skill's detail — a per-event-kind script skeleton, a judge
	// contract — often lives in a page SKILL.md merely links to, and an agent
	// that loaded the skill has no guarantee of ever opening it. Measured
	// against a real onboarding run: every agent loaded authoring-guardrails
	// yet none read file-guard.md, so every check script was written from
	// memory and refused several times before it was right.
	//
	// A relative path with no `..` and no leading `/` — it names a file inside
	// the skill's own directory, never an escape from it. Load error otherwise.
	Files []string `yaml:"files"`

	// Context is the name of a context declaration that must run first, when both
	// this rule and that context wake on the same event in the same cycle.
	// Optional. Validated to resolve against the loaded contexts.
	Context string `yaml:"context"`

	// Citation requires the action to carry a resolved citation. Optional.
	Citation *CitationPrerequisite `yaml:"citation"`

	// When, optional, is a script that decides whether this prerequisite
	// applies to the action at all — for a requirement that is conditional on
	// the change ("a citation, but only when the body changes"). Resolved
	// relative to the rule's folder and handed the same payload on stdin as a
	// script check. Exit 0: the prerequisite applies. Exit 1: it does not, and
	// is skipped. Any other outcome — another exit code, a script that cannot
	// run, a timeout — applies it: a condition that could not be decided must
	// not waive a requirement.
	When string `yaml:"when"`
}

type Problem struct {
	// Kind is which sentinel this problem is an instance of. Compare with
	// errors.Is rather than by reading Detail.
	Kind error

	// Fault says whether this disables the rule or only warns about it.
	Fault Fault

	// Where locates the fault within the declaration for a person — "trigger 0",
	// "check 1", "require 0", or "" for a fault about the whole declaration. A
	// free-form breadcrumb rather than the old loader's fixed event/binding/hook
	// triple, because the new formats have several different nested shapes
	// (triggers, checks, prerequisites, structure entries) and one breadcrumb
	// string describes them all without a struct field per nesting.
	Where string

	// Detail is the specific complaint, without the location. Message joins the
	// two.
	Detail string
}

type ScopeOverlap struct {
	// A and B are the two plugins, in load (precedence) order.
	A, B Origin

	// ScopeA and ScopeB are the overlapping scope globs as each plugin wrote them.
	ScopeA, ScopeB string
}

type Shadow struct {
	// Nature and Name are the (nature, name) both declarations share.
	Nature Nature
	Name   string

	// Plugin is the plugin whose declaration was displaced, and PluginDir is where
	// that displaced declaration sits — the path an author needs to read the rule
	// they have overridden.
	Plugin    string
	PluginDir string

	// WinnerDir is the folder that took precedence — the project's own, or an
	// earlier-listed plugin's.
	WinnerDir string

	// WinnerPlugin is the plugin the winning declaration came from, empty when the
	// project's own won. What distinguishes "you overrode this" from "one of your
	// two plugins is quietly not enforcing", which need different remedies.
	WinnerPlugin string
}

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

type StructureEntry struct {
	// Glob is a bare glob pattern. Exactly one of Glob / Regex is set.
	Glob string `yaml:"glob"`

	// Regex is a full regex pattern, for the cases a glob cannot express (a
	// dated-folder shape, say). Exactly one of Glob / Regex is set.
	Regex string `yaml:"regex"`
}

type StructureGate struct {
	// Scope is the part of the tree a PLUGIN's structure gate owns: a list of
	// folders, each a `glob` ending in `/` (".mdmap/", "**/.adr/"). Required for a
	// plugin's structure.yaml and forbidden in a project's (the project's covers
	// the whole tree implicitly). Glob-only for now; the object shape leaves room
	// for `regex` later. A scope may not cover the whole tree (`**/`, `*/`, `/`).
	Scope []StructureEntry `yaml:"scope"`

	// Allow is the allowlist. Each entry is a glob or a regex (exactly one set).
	// In a plugin's structure every entry must lie inside its scope when the
	// scope is a literal folder.
	Allow []StructureEntry `yaml:"allow"`

	// Deny carves exceptions out of Allow. Optional. Each entry is a glob or a
	// regex (exactly one set). A PROJECT deny also vetoes writes inside a
	// plugin's scope.
	Deny []StructureEntry `yaml:"deny"`

	// Dir is the folder the structure.yaml sits in — `.sloprail/file-guard`. Not
	// a YAML field.
	Dir string `yaml:"-"`

	// Origin is where this structure gate was found — the project's own
	// `.sloprail`, or a plugin that ships it. Not a YAML field; the loader fills it.
	// The zero value is a project's own structure gate. It decides which rules
	// apply: a plugin's must carry a scope, a project's must not.
	Origin Origin `yaml:"-"`
}