taxonomy

type Action string

type Class string

type Evidence struct {
	// Status is the HTTP status the failure arrived under, 0 when it never
	// reached one.
	Status int

	// PlanPaused says a fixed-price subscription window is temporarily spent.
	// It is a transport fact with no recovery move: retrying, rotating endpoints
	// or hopping models would turn a spending boundary into ordinary pacing.
	PlanPaused bool

	// Upstream is the provider the router NAMED as the one that refused, empty
	// when the router refused on its own account. The emptiness is the fact: a
	// 4xx that named nobody is our own bytes being read and rejected, and every
	// endpoint alive will say the same thing about the same request — UNLESS
	// Routing says otherwise.
	Upstream string

	// Routing says the ROUTER emptied the endpoint set for this request — a
	// list, an account setting, a price ceiling or a demand left it nothing to
	// ask — so another machine or another model can serve the same bytes. The
	// transport decided it at its refusal door (internal/provider's
	// [provider.RoutingRefusal]) and it is carried here as a fact, never
	// re-read from the sentence.
	//
	// IT IS THE ONE 4xx NAMING NOBODY THAT IS NOT OUR OWN BYTES, and before
	// this field existed it was indistinguishable from one: the measured turn of
	// 2026-09-10 ended on `the request itself was refused` for a 404 that an
	// account's privacy setting had produced, and the same words sent again a
	// minute later were answered.
	Routing bool

	// Account says the exclusion that emptied the set is the ACCOUNT'S OWN —
	// a privacy switch, a paid-training guardrail, a standing ignore list — so
	// it is true of every model and not of this one, and no machine was asked.
	//
	// It is a narrowing of Routing and never a substitute for it: both are set
	// together, because the MOVE is the same (somewhere else) and only the
	// journal line and the ledger care which list it was. It is here so that the
	// ledger's reading and the control answer come off ONE piece of evidence:
	// before this field, `provider/refusalobject.go` decided it for the ledger,
	// `taxonomy` decided a neighbouring question for the action, and
	// `session/taxonomy_boundary.go` decided a third for the ending.
	Account bool

	// Withdrawn says the ROUTER DOES NOT CARRY THIS MODEL any more — the sheet
	// has no row for it and its own error envelope names no upstream. Every
	// machine is fine and the request is fine; the id is gone.
	//
	// ITS MOVE IS THE MODEL AND NOTHING ELSE, which is why it is a field rather
	// than a shade of Routing. There is no machine to rotate to and no shape to
	// relax, so a retry budget spent on one is a person waiting through 2s, 4s
	// and 8s for three identical 404s (#838). It hops at once.
	Withdrawn bool

	// OurBytes says the router read THIS REQUEST and refused it on its own
	// account: a 4xx that named no upstream and is not Routing, Account or
	// Withdrawn. Nobody was asked, and every machine alive would say the same
	// thing about the same bytes.
	//
	// IT IS CARRIED RATHER THAN INFERRED. `Status >= 400 && Upstream == ""` was
	// the inference, and it was made in three places with three different lists
	// of exceptions bolted onto it — which is the defect docs/design/recovery
	// §2.6 counts. The transport decides it once, at its refusal door
	// ([provider.APIError.OurRequest]), and it travels here as a fact.
	OurBytes bool

	// Overflow says the request DID NOT FIT: the transcript is longer than the
	// window the model will take.
	//
	// IT IS STRUCTURAL AND NEVER A PHRASE. The old test was a seven-alternative
	// regex over the provider's prose (`context.?length|token.?limit|…`) run
	// forty lines after the verdict had already been computed, and it returned
	// before the verdict could be read — so a routing 404 whose sentence
	// happened to miss every pattern ended a turn that had three moves left.
	// What sets this is the request-too-large status and the router's own error
	// envelope code ([provider.APIError.Overflow]).
	Overflow bool

	// Compacted says this turn has ALREADY made the request smaller once. It is
	// the difference between [ActionCompact] and giving the overflow back as
	// [Work]: compaction that did not fit is a request that is not going to fit,
	// and asking for it twice is a loop.
	Compacted bool

	// Spent says the TRANSPORT'S OWN SHAPE LADDER has been climbed and has run
	// out: the price ceiling dropped, the reasoning knob off, the output cap off,
	// the tools off, and the router still refusing (internal/provider's
	// [provider.RefusalError]).
	//
	// IT IS A BUDGET THAT IS GONE AND NOT A JUDGEMENT. Nothing about the work has
	// been learned and nothing about the model has; what has been established is
	// that no SHAPE of this request will be served, which leaves exactly one move
	// — another model — and that move belongs to the caller. So it is Transport
	// with its budget declared spent, never [Work]: a turn that reads it as the
	// work ends with the router's own sentence on the screen while a chain the
	// person configured sits unasked, which is the failure
	// docs/design/recovery/DESIGN.md §5 is written about.
	Spent bool

	// OutOfTime says the CALLER'S OWN DEADLINE is gone: the plan's give-up, in
	// the person's time (`lane.Role.GiveUp` scaled by [Limits.Patience]), which
	// is the one thing that bounds how long a failing request may go on
	// recovering (docs/design/recovery/DESIGN.md §4).
	//
	// IT IS THE COUNT'S REPLACEMENT AND NOT THE LADDER'S. `TransportAttempts`
	// used to answer "is there another try in this" from a number; the number is
	// gone, because the transport under every caller was already bounded by the
	// same deadline and two budgets on one axis multiply. What is NOT said here
	// is anything about the failure: the reason a person reads stays the shape
	// that actually failed — a refusal, a reset, a reply that arrived empty —
	// where [Spent] would say "no shape of this request could be served", which
	// is a different claim and usually a false one.
	OutOfTime bool

	// Unserved says THE ACCOUNT could not be served at all: no key, a key this
	// model or bound plan door is not permitted, or a balance that ran out. It
	// arrives as a 401, 402 or 403, or as a vendor's structured payment/no-plan
	// refusal.
	//
	// IT IS THE ONE REFUSAL WITH NO MOVE IN IT. Another machine, another shape
	// and another model all lead to the identical answer, so there is nothing to
	// rotate to and nothing to relax — the person has to act. And it is
	// nevertheless not about the WORK, which is the half that matters to a task
	// node's ending: a run that died on somebody's expired key learned nothing
	// about the job and must not spend the job's ceiling (#513).
	//
	// It is carried rather than switched on, because "401, 402, 403" written out
	// at a call site is exactly how the three-classifier defect was spelled
	// (session/taxonomy_boundary.go's deleted providerCouldNotServe).
	Unserved bool

	// Message is the failure's own sentence, for the journal line's `reason`
	// when nothing more specific applies.
	Message string

	// Empty is an HTTP 200 that carried no content and no tool calls. It is not
	// a short answer; it is an endpoint that did not answer.
	Empty bool

	// Malformed is a tool call whose arguments did not parse — the shape that
	// arrives as `function.arguments must be valid JSON` or an unterminated
	// string, from one endpoint in a pool while its neighbours are fine.
	Malformed bool

	// Timeout is a deadline or a stall wall: context deadline exceeded, a read
	// that never finished.
	Timeout bool

	// Idle is a subprocess that is alive, silent, and doing nothing.
	Idle bool

	// Cut is a stream the guard ended.
	Cut bool

	// Wire is the catch-all the caller's OWN transport pattern matched: a socket
	// that hung up, a name that would not resolve, an upstream that reset before
	// headers. It carries no status and no shape of its own, and this package
	// deliberately keeps no list of its own to recognise it by — the caller has
	// one and a second would drift.
	Wire bool

	// Attempt is which transport attempt this is, 1-based. It counts the
	// requests this model FAILED OUTRIGHT — a refusal, a reset, a deadline —
	// and never the ones a stream guard cut, which are counted beside it in
	// Cuts and spend a budget of their own shape.
	Attempt int

	// Cuts is how many of this model's attempts were streams the guard ended,
	// this one included and 0 when this failure is not a cut.
	//
	// IT IS THE SAME BUDGET AS Attempt AND A DIFFERENT KIND OF SPENDING. A
	// request that failed is evidence the endpoint is failing and earns the
	// full ladder with its waits; a stream that was cut is not — the request
	// succeeded and the reply came apart — so it earns a shorter allowance with
	// no wait in front of it. One model, one budget, two ways to spend it.
	Cuts int

	// Degenerate says the cut was the reply ceasing to be language — repetition,
	// jumbled text, the model's own internal markup — rather than the stream
	// going quiet. If the same transcript produces that twice, the transcript is
	// the suspect and a third ask spends the whole prompt to be told so again.
	Degenerate bool

	// Rerouted says this cut actually took an endpoint out of the caller's
	// routing, so the attempts after it are genuinely served by somebody else.
	//
	// FALSE IS THE CASE THAT MATTERS. A cut that struck nothing — routing turned
	// off by the person, or a stream that died before any chunk named who served
	// it — leaves the next attempt landing in the same place by the same rules,
	// so the extra asks buy nothing and the allowance narrows.
	Rerouted bool

	// FallbackAvailable says the caller has a NEXT MODEL to ask when this one's
	// budget is spent. It is the whole difference between [ActionHop] and
	// [ActionGiveUp], and it is the caller's fact: an empty chain, a completer
	// with none to offer and a person who pinned one model all spell it false,
	// and each of those makes the move ABSENT rather than broken.
	FallbackAvailable bool

	// Refuted is how many SEMANTIC failures this tier has: checks that read the
	// finished work and found gaps, with no transport failure under them. A
	// refutation of a round whose calls died on the wire is not one of these,
	// and [Tally] is what keeps the two apart.
	Refuted int

	// TransportSeen is how many transport failures happened under this piece of
	// work. It is carried so a capability verdict can say WHY it is holding.
	TransportSeen int

	// Found says a check has just read the finished work and named gaps in it.
	// It is what makes a finding a CAPABILITY question at all, and it is separate
	// from Refuted because the two answer different halves: Found is "a check
	// spoke", Refuted is "how many times it has spoken about this tier with the
	// wire ruled out". A finding whose round died on the wire has Found set and
	// Refuted unmoved, which is exactly the case that must hold rather than buy.
	Found bool

	// Passed is a check that has just passed. It is the de-escalation question
	// and the only piece of good news this struct carries.
	Passed bool

	// Escalated says the work is already on a tier something lifted it onto.
	Escalated bool

	// SpentUSD is what the lifted tier has cost this piece of work so far.
	SpentUSD float64
}

type Limits struct {
	// Patience is how much of a role's own give-up the person wants spent on one
	// request before the harness moves on: 1 is the measured figure
	// (`lane.Role.GiveUp`), 3 is three times as long.
	//
	// IT WAS A COUNT OF SENDS AND IT IS A MULTIPLIER ON A DEADLINE. `N attempts`
	// bounded nothing after docs/design/recovery/DESIGN.md §4 — the transport
	// under it already stopped at the plan's deadline, so a person who asked for
	// eight tries bought eight identical requests inside the same ninety seconds
	// and a number that multiplied the one below it. The intent behind the knob
	// is patience, and patience is TIME; this is that intent, read honestly, on
	// the one figure that really ends a call. A person still spells it
	// `response.attempts` (internal/config), because it is still the same
	// question: how hard should this try before it tells me it could not.
	Patience float64

	// TransportBackoff is the first wait. Each further wait doubles it, so this
	// one number is the whole schedule.
	TransportBackoff time.Duration

	// SemanticFailures is K: how many checks must read the finished work and
	// find gaps in it, on the same tier, before a stronger one is bought. It
	// counts REFUTATIONS WITH NOTHING ON THE WIRE UNDER THEM and nothing else.
	SemanticFailures int

	// TierCapUSD is what a lifted tier may cost ONE piece of work. Past it the
	// capability policy stops buying and the verdict comes back as work. 0 is no
	// cap, which is what this build had.
	TierCapUSD float64
}

type Policy interface {
	// Class is the one class this policy answers for.
	Class() Class
	// Decide is the policy's answer. The limits it is handed have already been
	// floored ([Limits.floor]), so an implementation never has to defend itself
	// against a zero.
	Decide(Evidence, Limits) Verdict
}

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

type Verdict struct {
	// Class is what the evidence was.
	Class Class

	// Action is what the class's policy says to do.
	Action Action

	// Reason is one short phrase, plain words, written into the journal and read
	// by a person doing an autopsy. It is never a stack trace and never a
	// payload.
	Reason string

	// Attempts is how many transport tries the policy allows in total, so a
	// caller's loop bound is the policy's number rather than its own constant.
	// Zero on every non-transport verdict.
	Attempts int

	// Backoff is how long to wait before the retry this verdict asks for. Zero
	// on everything that is not [ActionRetry].
	Backoff time.Duration

	// Rotate says the retry should be served by somebody else if the routing
	// underneath can arrange it. It is true for exactly the failures where the
	// endpoint is the suspect.
	Rotate bool
}