decide

type Answer struct {
	Type          string
	Choice        string
	Probabilities map[string]float64
	Score         float64
	Noul          float64
	Confidence    float64
}

type Attempt struct {
	Rung       string `json:"rung"`
	Outcome    string `json:"outcome"`
	Reason     string `json:"reason,omitempty"`
	Terminated bool   `json:"terminated,omitempty"`
}

type Chain struct {
	Deciders []ChainDecider
	Escalate string
	// Tamper is the pattern table; the shipped one is used when it is nil.
	Tamper []string
	// Now is a var so a test can pin a row's timestamp.
	Now func() time.Time
}

type ChainDecider interface {
	Name() string
	// Sees is SeesPublic for anything that leaves the machine.
	Sees() string
	Ask(ctx context.Context, q questions.Question, state string) (answer string, confidence float64, usage Usage, err error)
}

type Classification struct {
	Class         string
	Confidence    float64
	Floor         float64
	Decider       string
	Why           string
	AskedProvider bool
	RequeueOnce   bool
	Evidence      HarvestEvidence
}

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

type Decider interface {
	Decide(ctx context.Context, state string, qs map[string]Question) (map[string]Answer, Usage, error)
}

type DecisionDriver interface {
	Append(row DecisionRow) error
	Rows(kind string) ([]DecisionRow, error)
	Close() error
}

type DecisionRow struct {
	QuestionHash string
	Kind         string
	Answer       string
	// ProviderConfidence is meaningful only where HasProviderConfidence is
	// true. Where it is false the provider was never asked and the column
	// is written as a dash.
	ProviderConfidence    float64
	HasProviderConfidence bool
	Floor                 float64
	Outcome               string
	// Source is SourceMachinery where the rules settled the decision with
	// no provider asked, SourceProvider where the provider's answer stood
	// (within the constraints), and empty in a row written before the
	// column existed.
	Source string
}

type Entry struct {
	Time      string `json:"time"`
	Unit      string `json:"unit"`
	Kind      string `json:"kind"`
	Evidence  Unit   `json:"evidence"`
	RungTried string `json:"rung_tried"`
	Height    int    `json:"height"`
	// Confidence and Floor are ABSENT rather than zero where the row did not
	// carry them, by the same presence rule as the counters below: a row read
	// back from a log line that omitted either keeps it nil, and the decide
	// event it becomes leaves the field off, so the fold stores NULL, never a
	// 0 nobody measured (Stella, HOLD 7 on #2628).
	Confidence    *float64 `json:"confidence,omitempty"`
	Floor         *float64 `json:"floor,omitempty"`
	SteppedUp     bool     `json:"stepped_up"`
	Escalated     bool     `json:"escalated"`
	Designated    bool     `json:"designated,omitempty"`
	Source        string   `json:"source"`
	RowanPick     string   `json:"rowan_pick"`
	Reason        string   `json:"reason,omitempty"`
	Outcome       string   `json:"outcome,omitempty"`
	RungSucceeded string   `json:"rung_succeeded,omitempty"`

	// Wait is the typed action beside the rung: "-" for a decision the caller
	// may act on, awaiting_termination for one it may not.
	Wait string `json:"wait,omitempty"`
	// Read is the mind -- or minds, comma-joined -- a KIND designation attached
	// to this unit as a READER rather than as the rung: a security read, or a
	// fresh take whose designate is reserved. The work went to RungTried; this
	// is who reads it.
	Read string `json:"read,omitempty"`
	// FloorFrom says where Floor came from: flag, kind or built-in. Two rows
	// carrying floor 0.90 are different claims when one was measured from rows
	// and the other is the default nobody has ever tuned.
	FloorFrom string `json:"floor_from,omitempty"`
	// Refusal is why the route ended in a refusal, where it did. The row is
	// still written: a call that was already made is still a cost, and a
	// decision that could not be made is still evidence.
	Refusal string `json:"refusal,omitempty"`
	// AwaitingTermination is the same fact as a boolean, for a reader that
	// gates on it: the rung named is the one an attempt may still be running
	// on, and the lease rule keeps its expiry UNKNOWN until termination.
	AwaitingTermination bool `json:"awaiting_termination,omitempty"`

	// What the decision spent. Calls is the number of provider calls it made;
	// TokensIn and TokensOut are ABSENT rather than zero where no call was made
	// or the call failed, because a zero is a measurement and an absence is not
	// (SPEC-TOKENS rule 14). UsageFailed marks a call whose cost is unknown.
	Calls       int  `json:"calls,omitempty"`
	TokensIn    *int `json:"tokens_in,omitempty"`
	TokensOut   *int `json:"tokens_out,omitempty"`
	UsageFailed bool `json:"usage_failed,omitempty"`

	// Excluded is the set of down friend rungs excluded from routing (#3397).
	Excluded    string `json:"excluded,omitempty"`
	DownChecked bool   `json:"down_checked"`

	// Ms is the provider round trip in milliseconds, measured by the caller
	// on a monotonic clock around the call alone; WallMs is the verb's start
	// to its line. Each is ABSENT, never zero, where there was no call or no
	// measurement, by the per-counter presence rule: a zero is a measurement
	// and an absence is not (SPEC-TOKENS rule 14).
	Ms     *int `json:"ms,omitempty"`
	WallMs *int `json:"wall_ms,omitempty"`
}

type EventSink struct {
	Emitter events.Emitter
	// Bench is the bench the decision was made on, when the caller knows it.
	Bench string
	// Timeout bounds one write; zero is ten seconds.
	Timeout time.Duration
	// contains filtered or unexported fields
}

type Evidence struct {
	Text    string
	Class   string
	Pointer string
}

type FakeLogSink struct {

	// AppendErr, when set, is what Append returns: the seam for a test that
	// wants to see a sink fail.
	AppendErr error
	// contains filtered or unexported fields
}

type FileSink struct{ Path string }

type FloorProposal struct {
	Kind string
	// Rows is every provider answer for this kind; Stood is those with no
	// failure recorded against them, and Failed the rest.
	Rows   int
	Stood  int
	Failed int
	// Max and P25 describe the answers that stood.
	Max float64
	P25 float64
	// Current is the floor in force now and CurrentFrom where it came from.
	Current     float64
	CurrentFrom string
	// Floor is the proposal, set only when Proposed.
	Floor    float64
	Proposed bool
	// Defeated says the CURRENT floor is above every answer that stood: the
	// finding this verb exists to surface.
	Defeated bool
	// Note is why no floor was proposed, where none was.
	Note string
}

type FloorProposals struct {
	Rows      int
	Proposals []FloorProposal
}

type FloorStat struct {
	Floor     float64
	Decided   int
	Agree     int
	Escalated int
	// Defaulted is the escalated rows a named default answered, and
	// DefaultAgree how many of those the default got right. Both are zero
	// when no default is named: an escalation with no single answer behind
	// it is a count and not a score.
	Defaulted    int
	DefaultAgree int
}

type HarvestEvidence struct {
	Accept string // the gate's verdict, mechanical
	Line2  string // the second OUTCOME line's word
	Reason string // the reason TOKEN, from the closed set above

	// Requeued is the forge's own fact about this unit: it has been through
	// rule 14's requeue path already. An answer cannot set it.
	Requeued bool

	// ExitStatus is the supervisor's own record of the job's exit status: a
	// fact the card did not write. A negative value is its absence, never a
	// guess. It is read by the bench-red rule below and is never framed for a
	// provider.
	ExitStatus int

	// HarnessError is the supervisor's own harness-error line where it wrote
	// one, "" where it did not. Nothing a card wrote is this field, and it is
	// never framed for a provider.
	HarnessError string

	// BenchMoved is the forge's own fact about this unit: it has already been
	// moved to another bench on the bench-red ground. An answer cannot set
	// it, and the ground moves a unit at most once.
	BenchMoved bool

	// Prose is whatever the card wrote. NOTHING IN THIS PACKAGE READS IT. It is
	// carried so that a caller cannot accidentally build state from it by
	// reaching past this type for the file instead.
	Prose string
}

type HelpResult struct {
	Answer string
	Reason string
}

type HelpState struct {
	Hours            float64 `json:"hours"`
	RetriesOnRung    int     `json:"retries_on_rung"`
	FailuresLastHour int     `json:"failures_last_hour"`
	SelfInflicted    int     `json:"self_inflicted"`
	ClassRecurring   bool    `json:"class_recurring"`
	LandingMoved     bool    `json:"landing_moved"`
	Uncertainty      float64 `json:"uncertainty"`
	AskedAllFriends  bool    `json:"asked_all_friends"`
}

type JevDecider struct {
	Client Decider
	Local  bool
}

type JevVerdict struct {
	Repo    string // owner/name
	PR      int
	Head    string // the head sha the line was written at
	Verdict string // PASS, BOUNCE or UNSURE; the stream has no field for it, it is here for the caller's record
	Score   int    // 1-10 when Scored
	Scored  bool   // false when the line printed score=-
	Model   string // the model the score was asked of; "jev" when empty
}

type KindFloor struct {
	Kind  string  `json:"kind"`
	Floor float64 `json:"floor"`
	From  string  `json:"from,omitempty"`
}

type KindSummary struct {
	Kind        string
	Decisions   int
	Escalations int
	Successes   int
	Failures    int
	StartHeight int
	StartRung   string
	DefaultRung string
	Regenerated bool

	// ProviderRows is how many rows carried a provider answer for this kind.
	ProviderRows int
	// ConfMin, ConfMax and ConfP25 describe those answers; they mean nothing
	// when ProviderRows is 0 and the line prints a dash there.
	ConfMin float64
	ConfMax float64
	ConfP25 float64
	// Hist counts the provider answers into ConfBuckets.
	Hist []int
	// Floor is the floor this kind is gated on now, and FloorFrom where it came
	// from. BelowFloor is how many provider answers fall under it -- the
	// escalation rate for this kind, counted rather than felt.
	Floor      float64
	FloorFrom  string
	BelowFloor int
	// Defeated is the finding of 2026-09-18 as a flag: the floor is ABOVE every
	// answer the provider has given for this kind, so nothing it says can ever
	// clear it and the step-up is universal.
	Defeated bool
}

type LatencySummary struct {
	// Kind names the group for per-kind rows; Decider for per-decider rows.
	// Exactly one of the two is set.
	Kind    string
	Decider string
	N       int
	Median  int
	P95     int
	Has     bool
}

type LogSink interface {
	Append(e Entry) error
	Entries() ([]Entry, error)
	Close() error
}

type Mind struct {
	Name         string   `json:"name"`
	Lineage      string   `json:"lineage"`
	Height       int      `json:"height"`
	Kinds        []string `json:"kinds"`
	Lanes        []string `json:"lanes"`
	Availability string   `json:"availability"`
	Ask          string   `json:"ask"`

	// Model is the model id a unit dispatched to this mind RUNS with, where
	// this mind is a model at all. It is registry data and never a constant
	// here: the ladder comes from the file, and so do the ids on it. A mind
	// asked on the bus or as a child is a person or a coordinator and carries
	// none, so a caller that can only dispatch a model keeps today's model and
	// says so.
	Model string `json:"model,omitempty"`
}

type Question struct {
	Instructions string
	Choice       map[string]string
	Score        []string
	Noul         bool
}

type QuestionFile struct {
	Path            string
	CriteriaVersion string
	CriteriaPath    string
	Criteria        string
	StateFields     []StateField
	Questions       map[string]Question
	// Machinery is the rules this question is answered UNDER, declared in the
	// versioned pair rather than matched on a question's name inside a verb.
	// Empty is the ordinary question: the provider's answer stands as it is.
	// MachineryWhoReads binds the file to readers.go's rules, which the call
	// boundary applies -- a settled designation before any client is built, and
	// a constraint over any advisory answer before it is printed or recorded.
	Machinery string
}

type Rate struct {
	Model     string  `json:"model"`
	Provider  string  `json:"provider,omitempty"`
	InputUSD  float64 `json:"input_usd_per_mtok"`
	OutputUSD float64 `json:"output_usd_per_mtok"`
	From      string  `json:"from,omitempty"`
}

type ReadDecision struct {
	First    Role
	Required []Role
	Source   string
	Reason   string
	// LiftsHold is always false. It is a field so a caller gates on it rather
	// than on the absence of a sentence.
	LiftsHold bool
}

type ReadState struct {
	SecurityShapedPackage bool
	DesignDefaultsTaken   int
	NormativeSpecMoved    bool
	// HolderOfTheArea is the role that already has an open read or hold on
	// these files, or empty.
	HolderOfTheArea Role
	// HoldIsOpen says that holder's hold is unresolved.
	HoldIsOpen bool
	// HelpAnswer is `nova-decide help --state`'s own answer, verbatim.
	HelpAnswer string
}

type Registry struct {
	Minds  []Mind      `json:"minds"`
	Rules  []Rule      `json:"rules,omitempty"`
	Floors []KindFloor `json:"floors,omitempty"`
	Rates  []Rate      `json:"rates,omitempty"`
}

type Result struct {
	Question   string
	Version    int
	Answer     string
	Confidence float64
	Floor      float64
	Decider    string
	Stop       bool
	Below      string
	Tamper     bool
	Why        string
	Escalate   string
	Bytes      int
	Hash       string
	Usage      Usage

	// Skipped names the deciders that were not asked and why, so a line that
	// fell through to a weaker decider says so rather than looking like a
	// choice somebody made.
	Skipped string
	// contains filtered or unexported fields
}

type Role string

type RouteResult struct {
	Unit       string
	Kind       string
	Rung       Mind
	Confidence float64
	Floor      float64
	Reason     string
	Wait       string
	Refusal    string
	SteppedUp  bool
	Escalated  bool
	Designated bool
	Source     string
	RulesRung  string
	Offered    []string
	Usage      RouteUsage
	// Next is the rung ABOVE the one answered, named whenever the answer is
	// below the floor. The step-up signal used to name only the question that
	// fell short, which left a reader to work out where the work goes next from
	// a ladder they cannot see (edge 24). It is empty at or above the floor,
	// and empty where there is no rung above.
	Next string
	// Steps is how many decisions this answer took: 1 for an ordinary route,
	// and one more for each re-ask --step-up made.
	Steps int
	// WallMs is the verb's start to its line in milliseconds, stamped by the
	// verb that printed it. HasWallMs reports whether the verb measured it:
	// where no verb stamped one there is no measurement, and no measurement
	// is an absence, never a zero.
	WallMs    int
	HasWallMs bool
	// Reads are the minds a KIND designation attached to this unit as READERS
	// rather than as the rung: a reserved mind takes no work, so security --
	// and a fresh take where the designate is reserved -- reaches the unit as a
	// read beside the rung the evidence supports. The work is dispatched to the
	// rung; the read goes out with it.
	Reads []string
	// FloorFrom says where the floor came from: the caller's flag, this kind's
	// measured row, or the built-in default with no rows behind it. A floor
	// nobody can trace is a feeling with a number on it.
	FloorFrom string
	// Excluded is the set of down friend rungs excluded from routing (#3397).
	Excluded []string
	// DownChecked records whether this route consulted the fleet presence keys.
	DownChecked bool
}

type RouteUsage struct {
	Calls        int
	InputTokens  int
	OutputTokens int
	HasInput     bool
	HasOutput    bool
	Failed       bool
	// Ms is the provider round trip in milliseconds, measured by the caller
	// on a monotonic clock around the call alone. HasMs reports whether a
	// call was made at all: with no call there is no measurement, and no
	// measurement is an absence, never a zero (SPEC-TOKENS rule 14).
	Ms    int
	HasMs bool
}

type Rule struct {
	Kind string `json:"kind"`
	Rung string `json:"rung"`
	By   string `json:"by"`
	From string `json:"from,omitempty"`
}

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

type StateField struct {
	Name     string `json:"name"`
	Type     string `json:"type"`
	Optional bool   `json:"optional,omitempty"`
}

type Summary struct {
	Entries int
	Kinds   []KindSummary

	// Decisions and Outcomes are the two halves of rule 8's row, counted as
	// ROWS across every kind, which is the arithmetic the hurt was measured
	// with: 141 outcomes for 412 decisions on 2026-09-19. Their ratio is
	// printed as coverage, because a floor tuned on a third of the rows is
	// tuned on the rows somebody remembered (SPEC-DECIDE, housekeeping H2).
	Decisions int
	Outcomes  int

	// LatencyByKind and LatencyByDecider are the ms distribution over the
	// MEASURED rows of each group: the median and the 95th percentile
	// (SPEC-DECIDE, housekeeping H3). A kind is the route log's question and
	// a source its decider; outcome rows are not decisions and carry no
	// measurement, so neither group counts them.
	LatencyByKind    []LatencySummary
	LatencyByDecider []LatencySummary
}

type TuneOptions struct {
	Label         string
	Choice        string
	Conf          string
	Floors        []float64
	MaxEscalation float64
	// Default is the answer a below-floor row actually gets. Where the
	// escalation is a step UP a rung it is empty, because the row gets a
	// different, more careful answer and no single name covers it. Where
	// the escalation is a fallback to one cheap answer -- the who-reads
	// question falls back to opus-child -- naming it here lets each floor
	// report what that fallback got right and what it MISSED, and the best
	// floor becomes the one that misses fewest rather than the one that
	// agrees most on the rows it kept.
	Default string
	// Observations admits a log whose labeled rows say
	// `"adjudicated": false`. It is the EXPLICITLY NON-RECOMMENDING mode:
	// the arithmetic runs and is printed in full, and no floor comes out of
	// it. Without it, a log carrying even one such row is a refusal -- a
	// floor set from observations is a floor set from labels nobody
	// adjudicated, which is what the renamed fixture's own README says it
	// is not for.
	//
	// A row that does not carry the field AT ALL is a log written before
	// the field existed, and is read exactly as it always was: a historical
	// format is never silently reinterpreted (Stella, 2026-09-19, r2 of the
	// #1925 hold).
	Observations bool
}

type TuneResult struct {
	Lines     int
	Labeled   int
	Floors    []FloorStat
	BestFloor float64
	// Observations is the labeled rows that said `"adjudicated": false`.
	Observations int
	// Recommends is whether this read may set a floor at all. It is false
	// exactly when the log carried an observation row, and Render then
	// prints best_floor=none: the arithmetic is a statement about the log,
	// and a floor is a statement about the future.
	Recommends bool
}

type Unit struct {
	ID        string    `json:"id"`
	Kind      string    `json:"kind"`
	Files     int       `json:"files,omitempty"`
	Packages  int       `json:"packages,omitempty"`
	Lanes     int       `json:"lanes,omitempty"`
	LaneOwner string    `json:"lane_owner,omitempty"`
	Attempts  []Attempt `json:"attempts,omitempty"`
	Platform  string    `json:"platform,omitempty"`
	Guard     bool      `json:"guard,omitempty"`
	Secrets   bool      `json:"secrets,omitempty"`
	Touches   []string  `json:"touches,omitempty"`
	FreshTake bool      `json:"fresh_take,omitempty"`
	Deadline  string    `json:"deadline,omitempty"`
}

type Usage struct {
	InputTokens  int
	OutputTokens int
	HasInput     bool
	HasOutput    bool
}

type WorkTypeResult struct {
	Type       string
	By         string // rules | jev
	Rule       string // the rule that fired, or why none did
	Confidence float64
	Usage      RouteUsage
}

type WorkTypeRoutes map[string][]string