lane

type Advice struct {
	Hedge  bool
	Reason string
}

type Belief struct {
	ID      ID
	Facts   Facts
	TTFT    Posterior
	Rate    Posterior
	Quality Beta
	At      time.Time
	// QualityAt is the moment of the last OUTCOME, and it is a second moment
	// rather than a second use of At because quality is not a timing
	// observation: an answer that arrived promptly and could not be used moves
	// one of these beliefs and not the other. Both are forgotten over
	// [HalfLife] and each needs to know how long it personally has been sitting
	// still. Zero is "nothing to forget", never "since 1970".
	QualityAt time.Time
	// Availability is the believed share of requests this lane ANSWERS, fed by
	// [Outcome.Refused] and by every answer, and forgotten over
	// [AvailabilityHalfLife]. It is not a gate; it multiplies the expected wait,
	// because a lane that refuses four requests in five costs five sends for
	// one answer. Before this axis existed a 429 taught the belief nothing, and
	// the next request for the same model asked the same pool two seconds later
	// (825 of 1,010 in the three days to 2026-09-10).
	Availability   Beta
	AvailabilityAt time.Time
	// Spread is how much ONE first token from this lane has been SEEN to move
	// around what is believed about it, in nats of log-spread — zero on a lane
	// nothing has been measured of, where the sheet's published dispersion
	// ([ledger.Draw]) is the answer instead.
	//
	// IT IS NOT [Posterior.P] AND THE DIFFERENCE IS THE WHOLE POINT, which is
	// the law [SpreadFloor] already states: P is the variance of the ESTIMATE
	// and shrinks toward nothing after a few dozen observations, while how
	// variable ONE DRAW is never shrinks below the lane's own variability. A
	// machine that answers in a second half the time and in a minute the other
	// half has a median nothing is unsure about and a tail that is the whole of
	// what a person pays, and nothing on this type could say so.
	//
	// It is measured with the same three floats and the same pooled-and-floored
	// law a thinking duration is ([chains.widen], [chains.draw]), folded on the
	// same lock and in the same call as the median it sits beside, and FORGOTTEN
	// WITH THAT MEDIAN when a change point fires ([chains.note]) — the two are
	// readings of one body of evidence, and an account that kept the old regime's
	// variance would widen a machine for ever on a tail it no longer has.
	//
	// IT IS THE FIRST TOKEN'S DISPERSION AND NOT THE RATE'S, deliberately. A
	// machine whose GENERATION rate swings is not held here at all: a rate that
	// moves within a regime is what the posterior's own spread covers, and a rate
	// that moves BETWEEN regimes — the 2026-09-11 ninefold collapse — is the
	// change point's job, which is why the rate chain has an alarm on it and no
	// dispersion account. Adding a second one would be two answers to "how fast
	// does this machine write" with nothing deciding between them.
	Spread float64
}

type Beta struct {
	A float64
	B float64
}

type Chain [Levels]Component

type Choice struct {
	Order  []string
	Only   []string
	Ignore []string
	// PINNED IS A PERSON'S OWN WORD AND IT IS NOT THE SAME FACT AS A DEMAND.
	// A demand is OURS — the set this process admitted, which it may relax the
	// moment the set stops working — and a pin is THEIRS: one machine, named
	// by hand, which nothing may quietly route around. The two looked alike for
	// exactly as long as `Only` held nothing but a pin, and the day the chooser
	// began demanding its own set, counting `Only` would have called every
	// ordinary call pinned: the rescue road turns into a question
	// ([control.Plan.Pinned] takes the `Ask` road), and the person is offered
	// `switch to auto?` about a machine they never asked for. So the fact is
	// carried rather than inferred, written in the one place that knows whether
	// a person spoke (`internal/provider`'s lanepin.go and drawLaneChoice), and
	// read in the one place the plan is built.
	Pinned bool
	// IT SAYS NOTHING ABOUT TIME, and the absence is the law. Routing and
	// waiting are two questions and they must never share one nil: this answers
	// WHICH LANE, and [control.Plan] — built for every token-generating call,
	// whether or not any preference was expressed — answers WHEN TO ACT. They
	// were one value once, so a ledger that had never heard of a model produced
	// no routing opinion AND no clock, and the request that most needed a
	// deadline was the one request that got none. [PlanFor] is the other half
	// and `law_test.go` is what keeps them apart.
	//
	// Frontier is the candidate set after the gate and the Pareto prune — the
	// three to five lanes actually worth choosing between — with the numbers
	// each was scored on. It is what the picker's `auto` row says out loud.
	Frontier []Scored
	// Why is one short sentence in a person's own words, empty when there is
	// nothing honest to say. It is shown under the cursor in the picker.
	Why string
}

type Chooser interface {
	Choose(Request) Choice
}

type Component struct {
	X float64
	P float64
}

type Facts struct {
	// Tools is whether this lane honours a tool call.
	Tools bool
	// Quant is the weight precision the lane serves at, spelled as the sheet
	// spells it ("fp8", "bf16", "fp4"), empty when the sheet did not say.
	Quant string
	// MaxOut is the longest answer the lane will write, and Context the longest
	// conversation it will read. Zero is "the sheet did not say", never "none".
	MaxOut  int
	Context int
	// Uptime5m is the share of the last five minutes the lane was answering, 0
	// to 100. It is the freshest availability figure the sheet carries and it
	// is what lets a lane earn its way back without a penalty box.
	Uptime5m float64
	// PriceIn, PriceOut and PriceCache are the lane's own tariff per token for
	// a fresh prompt token, an output token, and a token read back out of its
	// prompt cache. THEY ARE THE LANE'S AND NOT THE MODEL'S: an endpoint's
	// tariff is its own, and the model id's published list price is a figure
	// none of them is obliged to match.
	PriceIn    float64
	PriceOut   float64
	PriceCache float64
	// Caches is whether the lane holds a prompt prefix between requests. It is
	// what makes price path-dependent: the cheapest lane on the sheet is not
	// the cheapest lane for a request whose prefix another lane already holds.
	Caches bool
	// Status is THE ROUTER'S OWN HEALTH WORD for the lane, as it publishes it:
	// zero is healthy and anything else is an endpoint the router has itself
	// marked down. It is a gate and never a weight, for the reason quality is:
	// a machine whose operator has flagged it is not a machine to weigh against
	// a cheaper tariff.
	//
	// IT IS THE ONE FIELD HERE WHOSE ZERO MEANS "FINE" RATHER THAN "THE SHEET
	// DID NOT SAY", and it is safe to read that way round because the sheet
	// publishes the column for every row: a row that omits it is a row the
	// router is not derating. The gate that ignored this column was the second
	// of the two reasons the reference model and the shipped build did not
	// admit the same lanes (bench/lanelab/REPORT.md, "the two capability gates
	// do not admit the same lanes").
	Status int
}

type Fetcher interface {
	Fetch(ctx context.Context, url, bearer string) (io.ReadCloser, error)
}

type Hierarchy interface {
	// Wait is the chain over ln first-token in MILLISECONDS for one pair, aged
	// to now.
	Wait(id ID, now time.Time) Chain
	// Rate is the chain over ln tokens-a-second for one pair, aged to now.
	Rate(id ID, now time.Time) Chain
	// Think is the chain over ln SECONDS of a whole thinking phase for one
	// MODEL. It is keyed on the model alone because how long a model deliberates
	// is a property of the model and of the effort rung it was asked at; a lane
	// can only make the same thought arrive faster, which the rate chain already
	// says.
	Think(model string, rung string, now time.Time) Chain
	// Draw is how much ONE ANSWER from this pair varies around what is
	// believed about it, in nats of log-spread: the first token and the gap
	// between two tokens.
	//
	// IT IS THE OTHER HALF OF [Chain.Survival] AND IT IS NOT THE CHAIN'S. A
	// chain holds how well a median is known and that is a belief this process
	// sharpens by watching; how variable one answer is around it is a property
	// of the machine, and the sheet publishes it as the distance between a p50
	// and a p90. A pair nothing has been published about answers [SpreadFloor],
	// which is the prior for the same quantity.
	Draw(id ID) (first, gap float64)
	// ThinkDraw is the same quantity for the one clock no sheet speaks about:
	// how much ONE run of thought by this model at this rung varies around what
	// is believed about it.
	//
	// IT IS MEASURED WHERE [Hierarchy.Draw] IS READ, and that is the only
	// difference between them. Nobody publishes how variable a thinking phase
	// is, so [Hierarchy.NoteThinking]'s own observations are the dispersion, and
	// [SpreadFloor] is the prior for a model nothing has been watched of.
	ThinkDraw(model, rung string) float64
	// Shifted reports whether a change point has just reset this pair's own
	// component toward its parents, and clears the flag. It is what the call log
	// records and what the HUD may explain a sudden re-route with.
	Shifted(id ID) bool
	// NoteThinking folds in how long one whole run of reasoning lasted.
	//
	// IT IS ON THIS DOOR RATHER THAN ON [Ledger] because it is the only
	// observation in the design that is not about a deployment: a lane cannot
	// make a model think less, it can only make the same thought arrive faster,
	// which the rate chain already says. [Hierarchy.Think] is what reads it back,
	// and the two belong to one another — a build that could predict a thinking
	// phase but never record one would be predicting from the prior forever.
	NoteThinking(model, rung string, took time.Duration, at time.Time)
}

type ID struct {
	Model string
	Lane  string
}

type Ledger interface {
	// Note folds one timed answer in.
	Note(Sighting)
	// NoteOutcome folds in whether an answer could be used.
	NoteOutcome(Outcome)
	// Belief is what is believed about one lane, false when nothing is.
	Belief(ID) (Belief, bool)
	// Beliefs is every lane believed in for one model, in no promised order.
	Beliefs(model string) []Belief
	// Prime folds a sheet row in as a PSEUDO-OBSERVATION worth 1/k of a real
	// sighting. The sheet is a thirty-minute aggregate over everybody's
	// prompts and our own measurements are about our prompts from our region:
	// both are evidence, neither is truth, and k is how much less the public
	// one weighs. It is also what gives a lane nobody has used a prior, so
	// that nothing is blind on the first call of a process.
	Prime(row Row, k float64)
}

type Level uint8

type Outcome struct {
	ID       ID
	Accepted bool
	Reason   string
	At       time.Time
	// Refused says the lane did not answer at all — a 429 naming its pool, a
	// dead path, an upstream 4xx — as opposed to answering badly. It is the
	// AVAILABILITY axis rather than the quality one, and the two are kept apart
	// because they forget at different speeds: a pool that is full now is
	// usually fine in five minutes, while a lane that writes broken tool calls
	// is not. Accepted is false whenever Refused is true.
	Refused bool
}

type Pace struct {
	First control.Survival
	Gap   control.Survival
}

type Posterior struct {
	X float64
	P float64
}

type ProbeGate func(model string) bool

type ProbeSend func(ctx context.Context, model, lane string) (time.Duration, error)

type Prober interface {
	Probe(ctx context.Context, model string, lanes []string)
}

type ProberConfig struct {
	Send   ProbeSend
	Gate   ProbeGate
	Ledger Ledger
	Now    func() time.Time
	// Every is the shortest interval between pairs, [probeEvery] when zero.
	Every time.Duration
}

type Queue interface {
	// Wanted is the models that have been asked for and not yet fetched.
	Wanted() <-chan string
}

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

type Request struct {
	// Model is the model as it was asked for, normalized.
	Model string
	// PromptTokens is roughly how long the conversation is. It is the noise
	// term on a first-token measurement — most of a long prompt's wait is
	// prefill, which is not the lane's fault — and it is half of the price.
	PromptTokens int
	// Prefix identifies the conversation whose prompt cache is at stake, empty
	// when there is none. A lane that served this prefix recently probably
	// still holds it, and a switch forfeits it: the score pays that forfeit
	// explicitly, which is also what stops the router flapping between two
	// lanes that are otherwise equal.
	Prefix string
	// Visible is how many tokens of this answer a person will read and Hidden
	// how many they will not — reasoning, tool-call JSON, anything that is
	// pure waiting. The split is what [PerceivedSeconds] needs and it is the
	// difference between a talk turn and a tool loop.
	Visible int
	Hidden  int
	// Tools says the request carries tools, and MaxTokens the ceiling on the
	// answer. Both are gate facts: a lane that cannot take a tool call or
	// cannot write that many tokens is dropped, never scored.
	Tools     bool
	MaxTokens int
	// ValueOfTime is λ, IN SECONDS PER DOLLAR: how many seconds of waiting one
	// dollar is worth buying out of. It is a property of who is waiting and
	// what their wait costs, and it is computed per request from attention and
	// slack rather than set in a config — a person watching an empty line is
	// worth about ninety seconds to the dollar, a node with slack off the
	// critical path is worth nothing and price wins outright.
	//
	// ZERO IS PRICE ONLY. It is the honest reading of "nobody is waiting" and
	// it is what the routing row's `price` word sets for everything.
	ValueOfTime float64
	// QualityNeed is the share of answers that must come back usable for a
	// lane to stay in the candidate set — higher for work than for talk. It is
	// a GATE and never a weight.
	QualityNeed float64
	// Horizon is roughly how many more calls this session will make. It scales
	// exploration: a three-call session should never explore and a
	// five-hundred-call swarm should explore early, and Thompson sampling on
	// its own is blind to the difference.
	Horizon int
	// Role is WHO this call is being made for, carried whole rather than
	// flattened into the two or three numbers a chooser happens to want today.
	//
	// IT IS THE ONE PLACE A POLICY ABOUT WAITING MAY COME FROM. The role table
	// (roles.go) already declares how long this kind of call waits and whether
	// anybody reads its stream, and those two columns are the whole of what
	// separates a preference from a veto and a median from a tail
	// ([patience]). Copying a column into a field here would be a second table
	// to keep in step with the first; naming a role in a condition would be a
	// third. A role added to the table gets the right behaviour with nothing in
	// this package edited.
	//
	// EMPTY IS A CALL SITE THAT DID NOT SAY, AND IT REFUSES NOTHING. The two
	// behavioural columns read from [RoleUnknown]'s row — how a call nobody
	// described is treated, which the table has always answered — but the
	// DEADLINE is left at zero rather than borrowed from it, because a deadline
	// is a refusal and a refusal made out of a default nobody wrote down is a
	// machine struck off the wire's table on behalf of a call site that never
	// said anything. So an unnamed call is ranked by the same expectation as
	// everybody else and vetoes no machine at all, which is exactly what every
	// call did before this field existed. See [patienceFor].
	Role Role
	// Now is the moment the request is being made. See the note on the type.
	Now time.Time
	// Typical, when set, ranks on posterior means and does not sample.
	// It is the display question: which machine would auto pick if it
	// were not exploring this turn. The send path never sets it. A
	// picker that asked the send-path question on every frame named a
	// different via each paint, because Choose seeds its draws on Now.
	Typical bool
}

type Role string

type RoleFacts struct {
	// Interactive and Critical are what [Lambda] is asked, in that order: is
	// somebody waiting on this answer, and is it on the path to something else
	// that is waiting.
	//
	// AN UNATTENDED NODE IS NEITHER, and the second half of that is worth
	// stating because it looks like an oversight. A node nobody is watching is
	// on the path to a report nobody has asked to read yet, and paying to make
	// it arrive sooner buys a person nothing: the seconds are only worth money
	// once somebody is there to spend them. That is the argument
	// [Agent.turnLambda] has always made and this row is where it now lives.
	Interactive bool
	Critical    bool
	// QualityNeed is the share of answers that must come back usable, and it
	// is a GATE and never a weight (Decision 10's law). Zero is "no bar", which
	// is the honest reading for an errand that can simply be asked again.
	QualityNeed float64
	// Horizon is roughly how many more calls a session in this role will make.
	// It scales exploration: a role that will ask once must not spend that once
	// on a lane it is curious about.
	Horizon int
	// Visible says whether a person is reading THIS stream as it arrives, which
	// is what decides whether the phase clock and the served segment are this
	// call's to move.
	Visible bool
	// Streams says whether this role produces a token stream at all. A role
	// that does not — media — has no first token, no rate and no drift test,
	// so it takes the deadline-only half of the watch and its phase is a
	// single word with a clock under it.
	Streams bool
	// Verb is the phase word for this role while it is producing. It is
	// "writing" for everything that makes text and "drawing" for media, and it
	// is here rather than in the surface because a role is what decides it.
	Verb string
	// Patience is how many times [VisiblePatience] this role will wait before
	// something is done about the silence, whatever is believed about the lane.
	//
	// IT SCALES THE CEILING AND NEVER DECIDES WHETHER THERE IS ONE. That is the
	// funnel law said about waiting: a role sets what a second is worth and how
	// long is too long, and no role is exempt from being asked. A role with no
	// figure here reads as [RoleUnknown]'s, which is the conservative direction
	// — a background errand waits longer than a person does, never less.
	Patience float64
}

type Roster interface {
	Roster() []string
}

type Row struct {
	ID    ID
	Facts Facts

	// At is when this reading was taken, zero when nobody said.
	//
	// IT IS HERE BECAUSE A ROW IS AN OBSERVATION LIKE ANY OTHER, and every other
	// observation in this package carries its moment ([Sighting.At],
	// [Outcome.At]). Without it the ledger folds a FRESH public reading into a
	// belief still holding the certainty it had ten minutes ago, and a lane this
	// process stopped sending to — whose belief is therefore both stale and
	// confident — can never be corrected by the sheet saying it recovered. That
	// is a penalty box, arrived at by arithmetic rather than by a timer, and §5
	// of the design forbids it either way.
	At time.Time

	TTFTp50 float64
	TTFTp75 float64
	TTFTp90 float64
	TTFTp99 float64

	Ratep50 float64
	Ratep75 float64
	Ratep90 float64
	Ratep99 float64
}

type Scored struct {
	ID      ID
	Score   float64
	TTFT    float64
	Rate    float64
	Price   float64
	Quality float64
}

type Servable func(model string) string

type Sheet interface {
	// Rows is what is known about model's lanes right now, from memory, with
	// no clock and no connection. It returns nothing when nothing has been
	// fetched, which is a normal state and not an error.
	Rows(model string) []Row
	// Refresh fetches model's sheet and replaces what Rows returns. It is
	// called from the beat.
	Refresh(ctx context.Context, model string) error
}

type Sighting struct {
	ID ID
	// TTFT is the wait before the first token, and Gen is the window from the
	// first token to the last. Gap is the widest quiet stretch inside the
	// answer, which is how a lane that assembles the reply server-side and
	// delivers it in lumps tells on itself.
	TTFT time.Duration
	Gen  time.Duration
	Gap  time.Duration
	// Tokens is what the answer was worth in output tokens. PromptTokens and
	// CachedTokens are what it cost to be read, and the second of them is the
	// only evidence there is that a lane really held our prefix.
	Tokens       int
	PromptTokens int
	CachedTokens int
	// Probe marks a sighting bought on purpose: a one-token request sent while
	// somebody was still typing, which measures exactly our path to this lane
	// right now. It is a first-token measurement and NEVER a rate one — an
	// answer one token long rates the handshake.
	Probe bool
	At    time.Time
}

type Store interface {
	Load() ([]Belief, error)
	Save([]Belief) error
}

type Wanter interface {
	// Wants queues one model for the next beat and returns at once.
	Wants(model string)
}

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

type Workload struct {
	Model   string    `json:"model"`
	Class   string    `json:"class"`
	Visible int       `json:"visible"`
	Hidden  int       `json:"hidden"`
	At      time.Time `json:"at"`
}

type Workloads interface {
	NoteWorkload(Workload)
	Workload(model, class string, now time.Time) (visible, hidden int, known bool)
}