standing

type Action struct {
	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 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"`
}

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"`
	// 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"`
	// Previous are the last [Previous] sentinel lines, newest first, each with
	// what came of it.
	Previous []string `json:"previous,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"`
}

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"`
}

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
	// Notes are one sentence per thing worth saying, for the log.
	Notes []string
}

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

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 its output, clipped.
	Probe(ctx context.Context, item Item) (string, 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 Spend struct {
	USD   float64
	Fired int
}

type Status string

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

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
	// 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 {
	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 tells the sentinel what a yes looks like, in the model's words at
	// proposal time: "yes when any run on main shows conclusion=failure".
	Hint string `json:"hint,omitempty"`
}

type WhenKind string