standing

type Action struct {
	// Isolate runs a task in a separate Git worktree, as shown on its approval
	// card. Permission prose never selects an execution directory.
	Isolate    bool       `json:"isolate,omitempty"`
	Kind       ActionKind `json:"kind"`
	Say        string     `json:"say,omitempty"`
	Brief      string     `json:"brief,omitempty"`
	Acceptance string     `json:"acceptance,omitempty"`
	Model      string     `json:"model,omitempty"`

	// Effort is the rung on the effort ladder this item's firings and its checks
	// ask for (internal/effort), and empty on almost every item.
	//
	// EMPTY IS NOT THE CHEAPEST RUNG, IT IS "NOBODY SAID". An item that says
	// nothing runs at the standing role's own floor — low — because a firing is
	// unattended and repeats forever, and an install dialled deep must not turn
	// every check on the machine into a deep pass. This field is how the one
	// item that genuinely needs thinking says so once and gets it every time.
	Effort string `json:"effort,omitempty"`

	MaxSteps int `json:"maxSteps,omitempty"`
}

type ActionKind string

type Altitude string

type Brief struct {
	Title  string `json:"title,omitempty"`
	Prompt string `json:"prompt,omitempty"`
}

type CardKind string

type Deliverer interface {
	// Deliver carries out a pending delivery whose identity was already
	// written to the item. It answers the same [Outcome] Runner.Say does.
	Deliver(ctx context.Context, item Item, pending Pending) (Outcome, error)
}

type DrainFile struct {
	// Notes are the notes read whole from this file, oldest first, EXCLUDING any
	// identity already in the drained-identity record: an identity there was
	// handed over and acknowledged on an earlier drain, so it is retired without
	// being shown again. A READ FAILURE in this very file yields no DrainFile at
	// all (it is kept and reported instead).
	Notes []Note
	// contains filtered or unexported fields
}

type Entry struct {
	At     time.Time `json:"at"`
	ItemID string    `json:"item"`
	// Kind is "check" (a probe + sentinel), "say", or "task".
	Kind string  `json:"kind"`
	USD  float64 `json:"usd"`
	// Run is the run folder, for a firing.
	Run string `json:"run,omitempty"`
	// Pending is the delivery identity this firing settled, when it settled
	// one: the identity of the [Pending] intent the line was carried out
	// under. The line is written only AFTER the delivery succeeded, so its
	// presence in the append-only ledger is NATIVE DURABLE FIRING EVIDENCE.
	// [Ticker.settleItem] reads it to settle an intent whose item write was
	// lost — a one-shot whose line already reached the person retires from
	// this evidence instead of being delivered a second time.
	Pending string `json:"pending,omitempty"`
	// Outcome is what the firing came to ([Outcome.Kind]: said, landed,
	// needs-you, failed or nothing). [Item.LastOutcome] is overwritten by the
	// next firing, so this field is the only durable record of what this one
	// outcome was; a settlement reads it back rather than inventing one.
	Outcome string `json:"outcome,omitempty"`
	// Line is the one sentence the firing carried (the sighting line
	// [Ticker.fire] recorded as its check line), which is what the firing wrote
	// into [Item.LastCheckLine] and [Item.Previous]. It is kept here so a
	// settlement of this firing can restore both from the record it left behind
	// rather than from a fresh clock.
	Line string `json:"line,omitempty"`
	// Needs is the one line the firing left waiting for the person
	// ([Item.NeedsPerson]), empty when it left none. A firing that stopped on a
	// question is a REACHED outcome and not a clean success, so the record
	// carries the question itself: a settlement restores it, and derives the
	// clean-run counter from it, rather than reading any line on the ledger as
	// a clean success.
	Needs string `json:"needs,omitempty"`
}

type Exception struct {
	Workspace string    `json:"workspace,omitempty"`
	SessionID string    `json:"sessionId,omitempty"`
	At        time.Time `json:"at"`
}

type Idle func(for_ time.Duration) bool

type Item struct {
	Schema int    `json:"schema"`
	ID     string `json:"id"`
	// Words are the person's verbatim sentence. Permanent anchor; every
	// surface leads with it.
	Words string `json:"words"`
	// Workspace is the REAL project root the item belongs to — the resolved git
	// root, an owned work/ directory, or the person's home for a machine-wide
	// item. It is what home groups by and where a task firing runs.
	Workspace string `json:"workspace"`
	Origin    Origin `json:"origin"`
	When      When   `json:"when"`
	Does      Action `json:"does"`
	Rails     Rails  `json:"rails"`
	// Altitude is the item's reach (see [Altitude]); empty reads as project.
	Altitude Altitude `json:"altitude,omitempty"`
	// Brief is the working title and compiled prompt; empty reads as Words.
	Brief Brief `json:"brief,omitempty"`
	// Grant is one sentence of what acting on this item may do without asking,
	// quoted on the card that ratified it. Empty means say-only, which is what
	// every item made before grants were spelled could do.
	Grant string `json:"grant,omitempty"`
	// Exceptions are the places this item deliberately does not reach.
	Exceptions []Exception `json:"exceptions,omitempty"`

	Status  Status    `json:"status"`
	Created time.Time `json:"created"`
	Updated time.Time `json:"updated"`
	// Revision counts this document's writes. It is the generation a pass that
	// has been holding a copy for minutes compares against before it writes:
	// if the number moved, somebody edited, paused or resumed the item while the
	// pass was looking, and THEIR ACT IS NEWER THAN THE PASS'S STALE COPY. A
	// status-only check is not enough — a pause and a resume both leave the
	// status active — so the count is what the guard actually reads.
	Revision int64 `json:"revision,omitempty"`
	// RetiredWhy says why a retired item retired: "fired", "expired",
	// "stopped by you", or the sentence the last failure left.
	RetiredWhy string `json:"retiredWhy,omitempty"`

	// The quiet half. LastChecked and LastCheckLine are what let a watch that
	// checked faithfully for thirty mornings and found nothing read differently
	// from one that never ran.
	LastChecked   time.Time `json:"lastChecked,omitempty"`
	LastCheckLine string    `json:"lastCheckLine,omitempty"`
	NextDue       time.Time `json:"nextDue,omitempty"`
	// Fingerprint is a WhenFile's last reading.
	Fingerprint string `json:"fingerprint,omitempty"`
	// Positive is a WhenProbe's last AFFIRMATIVE reading, as an identity: a
	// bounded digest of the exact evidence the check observed when the sentinel
	// last said yes. It is what bounds an UNCHANGED continuous positive from
	// being reported again, independently of the words the sentinel happens to
	// use on a later check: while the observed reading is byte-for-byte the one
	// already reported, the watch is quiet, and a decided no clears it so a
	// later true is a fresh edge again.
	//
	// IT IS AN IDENTITY AND NOT A REASON. Nothing here reads the model's line,
	// because a model that says "same state already reported" and answers yes in
	// the same breath is exactly the failure this field exists to bound. It is
	// also not the evidence: only the digest is kept, so no probe output and no
	// secret it carried is retained.
	//
	// IT IS EMPTY WHEN THE READING CANNOT CERTIFY ANYTHING. A reading the clip
	// cut short ([ProbeClip]) is a partial view, so a repeated look at it must
	// not be passed off as "the same state"; the identity stays empty and the
	// sentinel keeps deciding. An empty identity is never a suppression.
	Positive string `json:"positive,omitempty"`
	// Previous are the last [Previous] sentinel lines, newest first, each with
	// what came of it.
	Previous []string `json:"previous,omitempty"`
	// Pending are deliveries this item means to make but has not confirmed. A
	// delivery record is written BEFORE the line is carried out and cleared only
	// when the delivery is acknowledged, so a crash between the two leaves the
	// intent on disk and a later pass reconciles it BY IDENTITY instead of
	// guessing. It is bounded by [PendingKeep] and empty on almost every item.
	// A later pass settles it at the top of the walk, before any fresh look, so
	// an advanced prerequisite can never strand it.
	Pending []Pending `json:"pending,omitempty"`
	// TaskInflight, when set, is the durable marker of a task attempt that began
	// but whose outcome is not known: written BEFORE [Runner.Run] and cleared
	// only on a terminal outcome. A later pass refuses to run the task again
	// while it is set and reconciles it as [Item.NeedsPerson] rather than
	// replaying arbitrary edits. It makes NO exactly-once promise about what a
	// task did; it makes replay STOP.
	TaskInflight *TaskInflight `json:"taskInflight,omitempty"`

	// The ledger half, kept on the item for the card; the daily ledger is the
	// truth for the rails.
	Runs        int       `json:"runs"`
	LastFired   time.Time `json:"lastFired,omitempty"`
	LastOutcome string    `json:"lastOutcome,omitempty"`
	LastRun     string    `json:"lastRun,omitempty"`
	SpentUSD    float64   `json:"spentUsd"`
	// NeedsPerson is set while the latest run is stopped waiting on the person,
	// with the one line it is stopped on. Home sorts on it.
	//
	// IT CARRIES TWO DIFFERENT THINGS, and a reader has to know which. One is a
	// QUESTION the firing put to the person, in its own words. The other is the
	// line written when a call was refused for want of somebody to allow it,
	// which opens with [NeedsPermissionLead].
	//
	// The pass writes this field whole on the next firing. The PERSON can put
	// down the permission line by changing the item ([Item.ClearNeedsPerson]),
	// and can never lose a question that way. With only the pass, an item that
	// could not fire again — one that had spent its allowance for the day — kept
	// a row on home saying it needed somebody for as long as that stayed true,
	// with no act of theirs able to put it down.
	NeedsPerson string `json:"needsPerson,omitempty"`
	// CleanRuns is HOW MANY FIRINGS IN A ROW CAME BACK CLEAN — fired with
	// nothing waiting for the person and no failure. It is the count the rope
	// column's middle rung is drawn from ([RopeWord]), and a firing that stops
	// on a question or fails puts it back to nothing.
	//
	// IT IS RECORDED AND NOT DERIVED, and that is a deliberate loss of
	// elegance. Everything else this struct keeps about a firing is the LATEST
	// one — LastOutcome is overwritten every time — so a streak simply is not in
	// the record. The one field that looks like it might do is [Item.Previous],
	// which holds the last few sentinel judgments with `" → " + outcome.Kind`
	// glued on the end; reading a streak out of that would mean splitting
	// model-authored prose on an arrow, and it would silently tie a product
	// threshold to [Previous], whose size exists to bound a PROMPT. Somebody
	// trimming that prompt by two lines would quietly make trust unreachable.
	// So the count is kept at the one site that records a firing
	// ([Ticker.fire]), which is the same place [Item.Runs] is kept.
	//
	// AN ITEM WRITTEN BEFORE THIS FIELD EXISTED DECODES AS ZERO and starts
	// earning trust again. That is the conservative direction and the only
	// honest one: nothing on disk says those firings were clean, and a column
	// that assumed they were would be granting rope nobody measured.
	CleanRuns int `json:"cleanRuns,omitempty"`
}

type Judgment struct {
	Item     Item
	Evidence string
	Previous []string
}

type Note struct {
	At     time.Time `json:"at"`
	ItemID string    `json:"item"`
	Words  string    `json:"words"`
	// Kind is "said", "landed", "needs-you", or "failed".
	Kind string `json:"kind"`
	Text string `json:"text"`
	// Run is the run folder a person can open for the whole story.
	Run string `json:"run,omitempty"`
	// ID is the delivery identity, when the writer had one: the identity of
	// the [Pending] record the core wrote before the line was carried out.
	// Drain and Peek dedup on it, so a line appended twice across a restart or
	// a torn write reaches the person once. Empty notes — every note written
	// before this field existed, and every writer that has no identity — are
	// passed through untouched.
	ID string `json:"id,omitempty"`
}

type Origin struct {
	// SessionID and Transcript name the conversation the card was answered in.
	SessionID  string `json:"sessionId,omitempty"`
	Transcript string `json:"transcript,omitempty"`
	// Exchange is set instead when the item was made from home's own box: the
	// short exchange that produced it is kept under the item's folder
	// ([Store.ExchangeDir]) and not as a project session. Promoting it to a
	// conversation moves the folder and fills SessionID.
	Exchange string `json:"exchange,omitempty"`
	// TaskID is set when a finishing task proposed the item itself.
	TaskID int `json:"taskId,omitempty"`
	// TurnIDs are the turns of the origin session that were about making or
	// changing this item. Home uses them to tell a conversation that was only
	// ever about this item from one that merely contains it.
	TurnIDs []string `json:"turnIds,omitempty"`
	// PinnedModel and OneModel are the RATIFYING CONVERSATION'S MODEL POLICY,
	// frozen at the moment the person said yes. They are on the origin because
	// a firing is that conversation's work done later: a background pass
	// reloads a keyless posture whose tiers, role pins and fallback ladder are
	// the profile's, and without the pin an item made under `--one-model` would
	// quietly route its sentinel and its child work through a different model
	// the person had already promised away. OneModel is whether the promise was
	// in force; PinnedModel is the model it named (the conversation's own), and
	// is the model every TEXT seat of this item must use when it is set.
	//
	// IT IS WRITTEN AT SCHEMA 3 WHEN SET (see [SchemaOf]): a build that predates
	// these fields decodes the document without them and would re-marshal the
	// silent re-routing back, so such an item is fenced rather than left to be
	// read as an ordinary unpinned order.
	PinnedModel string `json:"pinnedModel,omitempty"`
	OneModel    bool   `json:"oneModel,omitempty"`
}

type Outcome struct {
	// Kind is "said", "landed", "needs-you", "failed", or [OutcomeNothing].
	Kind string
	Text string
	USD  float64
	// NeedsPerson is the one line the run stopped on, when Kind is needs-you.
	NeedsPerson string
}

type Pass struct {
	At       time.Time
	Examined int
	Checked  int
	Fired    int
	Said     int
	NeedsYou int
	Skipped  int
	Errors   int
	// Tidied is how many remembered lines the consolidation pass moved, which
	// is zero on all but a handful of passes a day (see [Tidy]).
	Tidied int
	// Unread is how many standing documents [Store.List] skipped because they
	// could not be read — a newer schema, a damaged file, a dangling link.
	// UnreadWhy says which and why in ONE bounded line. A pass that skipped a
	// document says so; absence of evidence is not success.
	Unread    int
	UnreadWhy string
	// Notes are one sentence per thing worth saying, for the log.
	Notes []string
}

type Pending struct {
	// ID is the delivery identity, stable across restart, and the thing an
	// inbox dedups on.
	ID string `json:"id"`
	// Kind is [ActionSay] today; it names what was being delivered.
	Kind ActionKind `json:"kind"`
	// Text is the line, already templated, that was meant to be said.
	Text string `json:"text,omitempty"`
	// At is when the intent was written.
	At time.Time `json:"at"`
	// Attempts counts how many passes have tried to settle this intent and
	// failed, so a line that cannot be delivered becomes an explicit
	// [Item.NeedsPerson] rather than retrying forever in silence.
	Attempts int `json:"attempts,omitempty"`
}

type Probe struct {
	Command string          `json:"command,omitempty"`
	Tool    string          `json:"tool,omitempty"`
	Args    json.RawMessage `json:"args,omitempty"`
}

type ProbeReading struct {
	// Text is the evidence, already clipped from the tail where it was too long.
	Text string
	// Clipped reports that Text is only part of what the probe read.
	Clipped bool
}

type Rails struct {
	// PerRunUSD is the most one firing may spend, probe and sentinel included.
	//
	// ZERO IS NO LIMIT, and it always was at the place that enforces it —
	// internal/session's standing_run.go has only ever stopped a firing when
	// `PerRunUSD > 0` — so a person who wants a standing order bounded by
	// nothing but the daily rail writes 0 here and gets exactly that.
	// [Item.Validate] used to refuse that number, which made the enforcement
	// site's own contract unreachable.
	PerRunUSD float64 `json:"perRunUsd"`
	// MaxPerDay is how many times it may fire in one local day.
	MaxPerDay int `json:"maxPerDay"`
	// Expires retires the item at that moment. Zero is never. A WhenAt item
	// expires a day after its moment whatever this says.
	Expires time.Time `json:"expires,omitempty"`
}

type Runner interface {
	// Probe runs the item's probe and answers what it saw, with whether the
	// reader had to cut it short. A CLIPPED READING IS NOT AN IDENTITY (see
	// [ProbeReading]): the runner that cut it must say so, because a tail that
	// fits under the cap is indistinguishable from a whole short reading.
	Probe(ctx context.Context, item Item) (ProbeReading, error)
	// Say delivers one line: into the origin conversation if it is open in
	// this process, else into its inbox, and always onto the item.
	Say(ctx context.Context, item Item, text string) (Outcome, error)
	// Run runs the item's task brief in a fresh headless session at runDir,
	// with the evidence available to the brief, bounded by the item's rails.
	Run(ctx context.Context, item Item, runDir, evidence string) (Outcome, error)
}

type RunningMark struct {
	PID   int       `json:"pid"`
	Since time.Time `json:"since"`
	// What is [RunningChecking] or [RunningFiring]. A surface says it in those
	// words — "checking now", "firing now" — so it is the person's vocabulary
	// and not a state name.
	What string `json:"what"`
}

type Sentinel func(ctx context.Context, judgment Judgment) (yes bool, line string, usd float64, err error)

type SentinelReading int

type SentinelVerdict func(ctx context.Context, judgment Judgment) (verdict SentinelReading, line string, usd float64, err error)

type SkippedDoc struct {
	Name   string
	Reason string
}

type Spend struct {
	USD   float64
	Fired int
}

type Status string

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

type TaskInflight struct {
	// RunDir is the run folder the attempt was given, so the person can open it.
	RunDir string `json:"runDir,omitempty"`
	// Started is when the attempt began.
	Started time.Time `json:"started"`
	// Attempts counts attempts that reached this marker, so a task that keeps
	// dying can be surfaced rather than retried forever.
	Attempts int `json:"attempts,omitempty"`
}

type Ticker struct {
	Store    *Store
	Sentinel Sentinel
	Runner   Runner
	Idle     Idle
	// Tidy is the consolidation pass over what is remembered, run once at the
	// end of a pass and only when the session lane supplied one.
	Tidy Tidy
	// SentinelVerdict, when set, is the three-valued judgment and replaces the
	// legacy Sentinel. Nil means the legacy [Sentinel] is used, if it is set.
	SentinelVerdict SentinelVerdict
	// DailyRailUSD is the ceiling on everything standing spends in one day,
	// from settings. Zero is no rail, which the card says out loud.
	DailyRailUSD float64
	// Now is the clock, injectable for tests.
	Now func() time.Time
}

type Tidied struct {
	Merged     int
	Superseded int
	USD        float64
}

type Tidy func(ctx context.Context) (Tidied, error)

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

type Watch interface {
	Ensure(ctx context.Context) error
	Install(ctx context.Context) error
	Uninstall(ctx context.Context) error
	Status() (WatchStatus, error)
}

type WatchDrift struct {
	// Present is a definition file on disk, whatever it says.
	Present bool
	// Executable is the program that definition names, or empty when the file
	// could not be parsed for one. It is read for the log line the repair
	// writes; nothing decides on it.
	Executable string
	// Gone is Executable naming a path with no program on it — the build was
	// deleted, or moved and the old path left empty.
	Gone bool
	// Stale is a definition for THIS timer's home that this launch may repair:
	// the program it names is gone, or the bytes are not what this build writes
	// for that pair (an older build wrote them, or somebody edited them).
	//
	// IT IS NEVER TRUE FOR A TIMER THAT IS SOMEBODY ELSE'S: one naming another
	// home, or one naming another program that can still run. Repairing either
	// would be this launch taking the machine's one timer away from a pair that
	// was serving it, which is the flip this law exists to end. Turning the
	// settings row off and on is the one hand that moves it on purpose.
	Stale bool
}

type WatchOptions struct {
	Platform   string
	HomeDir    string
	Executable string
	// StateRoot is the home the timer ticks — CODEAF_HOME when set, the
	// login's default otherwise — and the half of the pair a test has to name
	// for a home it is not running under. Empty is this process's own.
	StateRoot string
	UID       int
	Runner    WatchRunner
	// WakeLog is where passes leave their one line each — [Store.WakeLogPath].
	// It is a path rather than a store because the timer has no business
	// reading items, only proof that something woke.
	WakeLog string
	Now     func() time.Time
}

type WatchRunner interface {
	Run(ctx context.Context, name string, args ...string) error
}

type WatchStatus struct {
	// Installed means the OS timer's definition on disk matches byte for byte
	// what this build writes.
	Installed bool
	LastWake  time.Time
	NextDue   time.Time
}

type When struct {
	Kind  WhenKind `json:"kind"`
	Words string   `json:"words,omitempty"`
	// At is the one moment of a WhenAt.
	At time.Time `json:"at,omitempty"`
	// Every is a WhenEvery's rhythm: a five-field cron line ("0 9 * * 1") or
	// a Go duration ("20m", "2h"). [ParseEvery] is the one reader of it.
	Every string `json:"every,omitempty"`
	// Glob is a WhenFile's pattern, relative to the item's workspace.
	Glob string `json:"glob,omitempty"`
	// IdleFor is how quiet the machine must have been for a WhenIdle.
	IdleFor time.Duration `json:"idleFor,omitempty"`
	// Probe is a WhenProbe's look at the world, taken every ProbeEvery.
	Probe      Probe         `json:"probe,omitempty"`
	ProbeEvery time.Duration `json:"probeEvery,omitempty"`
	// Hint is the MODEL'S OWN reading, written at proposal time, of what a yes
	// to this condition would look like in the probe's output: "yes when any
	// run on main shows conclusion=failure". It is a note the sentinel is
	// shown, never the person's criterion: [Item.Words] is what is judged, so
	// a match to the hint does not settle a condition the person phrased more
	// narrowly or more broadly than the guess.
	Hint string `json:"hint,omitempty"`
	// OneShot is a WhenProbe's one-shot intent: the condition watch fires when the
	// condition FIRST turns true, delivers its one line, and retires. It is the
	// compiled difference between "notify me once when ready becomes true" (set)
	// and "tell me every time it is ready" (unset, the rising-edge default).
	//
	// IT IS A COMPILED FIELD, NOT A WORD MATCH. The model reads the sentence
	// once, at proposal time, and this is what it wrote; nothing here scans the
	// person's English on every pass. It rides the approval card and the stored
	// document like every other field, and it is fenced at [Schema] so an older
	// reader skips it rather than silently re-arming a one-shot forever.
	OneShot bool `json:"once,omitempty"`
}

type WhenKind string