control

type Act struct {
	Kind    Kind
	Lane    string
	Reason  string
	Silence time.Duration
	// Wait is E[remaining] at the moment of the act, and Cost what acting was
	// expected to cost. Both are [Seconds] rather than floats because either
	// can honestly be nothing — an unmeasured belief, a request with nowhere to
	// act to — and a row that carries no number is the emptiness law rather
	// than a gap.
	Wait Seconds
	Cost Seconds
}

type Alternative struct {
	// Lane is the machine, spelled as the wire spells it.
	Lane string
	// First is what it would take to say its first word FROM COLD, including
	// the second request's own handshake.
	First Survival
	// Rate is how fast it is believed to write, in tokens a second. Zero is
	// unknown, under which regenerating visible text is priced at the serving
	// lane's own rate rather than at a guess.
	Rate float64
	// Extra is what this second request is expected to add to the bill, in
	// dollars. It is what λ converts into seconds.
	Extra float64
}

type Controller interface {
	// Note folds in one moment of the stream and says what to do about it.
	Note(Reading) Act
	// Quiet says nothing has arrived by now, and asks the same question.
	Quiet(now time.Time) Act
	// Serving re-points the controller at the machine that is really answering,
	// with what is believed about it. A router honours any of an order and says
	// which way it went on every chunk.
	Serving(lane string, first, gap Survival, now time.Time)
	// Deadline is the next moment worth waking for, so the beat arms a timer
	// rather than polls. It moves as the belief and the phase move, and a zero
	// moment means there is nothing scheduled.
	Deadline() time.Time
	// Phase is which distribution is governing right now.
	Phase() Phase
	// Acted reports whether this controller has already fired an act of this
	// kind, which is how a caller tells a rescue that was refused from one that
	// was never asked for.
	Acted(Kind) bool
}

type Factory func(Plan) Controller

type Kind uint8

type Move struct {
	// Kind is which of the four the design's order this move is.
	Kind MoveKind
	// Model is the model this move is on. The dispatcher never changes it —
	// there is exactly one model hop in this build and it belongs to the
	// session (docs/design/recovery/DESIGN.md §4) — so every move of one plan
	// carries the same name, and it is here so a row can say which.
	Model string
	// Lane is the machine, spelled as the wire spells it.
	Lane string
	// Shape is which rung of the relaxation ladder the request is in, zero
	// being the request as the caller wrote it. It is an OPAQUE COUNT here on
	// purpose: what a rung takes off is the transport's business
	// (internal/provider's relaxSet), and this package compares shapes for
	// equality and orders them, nothing more.
	Shape uint8
	// Wait is the comeback the machine itself named, and it is non-zero on
	// exactly one kind of move ([MoveWait]). A move to a DIFFERENT machine
	// costs no wait at all: a backoff is what is paid to ask the same machine
	// again, and it is the only thing it is for (retry.go's `moved`).
	Wait time.Duration
}

type MoveKind uint8

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

type Phase uint8

type Plan struct {
	// Lane is the machine expected to serve, empty when nobody was named. It is
	// re-pointed by [Controller.Serving] the moment the stream says who is
	// really answering.
	Lane string
	// Model is what is being asked, and every move of one plan carries it. The
	// dispatcher NEVER changes it: there is exactly one model hop in this build
	// and it belongs to the session (docs/design/recovery/DESIGN.md §4).
	Model string
	// Deadline is when this call stops trying, in the person's own time, and it
	// is the ONLY bound on how long a failed call may go on recovering.
	//
	// IT REPLACED A PRODUCT NOBODY COULD STATE. Attempts times paced sends
	// times arms times rungs times models, each with its own wall clock over
	// it, is not a number anybody could have told a person before this field
	// existed; `lane.Role.GiveUp` is, and it is measured (lane/roles.go's
	// [TurnGiveUp]). A zero moment is NO deadline, which is the honest reading
	// for a plan somebody built by hand and the reason [Plan.Spent] asks.
	Deadline time.Time
	// SpendUSD is what this call may spend on RESCUING ITSELF, zero being
	// unbounded. It is the second half of one budget: the deadline above bounds
	// how long, and this bounds how much.
	//
	// IT IS DERIVED AND IT IS NOT A KNOB. The money a call may spend buying its
	// wait back is what that wait is worth to whoever is waiting through it, and
	// that is two factors: how long it may still be, and what one second of it is
	// worth to them.
	//
	//	SpendUSD = GiveUp × (λ / AttentionValue) / AttentionValue
	//
	// [Plan.Lambda] is SECONDS PER DOLLAR — a dollar buys `AttentionValue`
	// seconds of somebody's attention back — so the rate at the top of the scale
	// is `1 / AttentionValue` dollars a second, and `λ / AttentionValue` is how
	// much less this role's seconds are worth than that. A wait nobody is sitting
	// through is worth a quarter of one somebody is, which is what
	// `lane.UnattendedValue` says and all this reads off it.
	//
	// AND THE DISCOUNT MUST BE A MULTIPLIER, WHICH IS THE BUG IT WAS SHIPPED
	// WITH. `GiveUp / λ` reads the same ratio upside down: the smaller λ of an
	// unwatched call makes its seconds four times DEARER, so a conversation a
	// person was reading got $1.00 to rescue itself and a background task node
	// got $12.00 — the one rail in front of a rescue sized in the opposite order
	// to who is waiting. `lane.spendable` carries the derivation and
	// `lane.worth` is the arithmetic; the law that no watched second may be worth
	// less than an unwatched one is beside them.
	//
	// Nothing else in this build states a per-call dollar ceiling, and a figure
	// invented here would be a number nobody measured deciding what somebody's
	// time is worth. A plan built by hand carries zero, which is unbounded — the
	// honest reading for a plan nobody priced.
	SpendUSD float64
	// Moves is what this question has already tried, shared by every arm of it.
	// A nil log is empty and decides nothing.
	Moves *MoveLog
	// Comeback is what the machine that last refused asked us to wait, zero
	// when it asked for nothing. It is the one input [Next] needs that changes
	// between moves, and it is what makes the single legal repeat legal.
	Comeback time.Duration
	// Shapes are the relaxation rungs this particular request has, in the order
	// they are climbed, spelled as the person reads them ("removed reasoning").
	// A request carrying no tools, no cap and no knob has none, and then the
	// ladder is not a move this call has.
	Shapes []string
	// ShapeRefused says the last refusal was about the request's SHAPE and not
	// about the machine that answered it: "no endpoints found that can handle the
	// requested parameters" is the router saying that every machine it can see
	// has already answered for this body, so another machine is not a move.
	//
	// IT IS THE ONE FACT [Next] CANNOT WORK OUT FOR ITSELF. The serving set of
	// such a request is usually OPEN — nobody named a pool — and an open set has
	// another machine in it forever (see [Plan.serving]), so a ladder that asked
	// for its rung without this would be handed a machine every time and would
	// never climb. It is set by the one caller that holds such a refusal's own
	// body (internal/provider's dispatch.go, [Client.recoverFromRefusal]).
	ShapeRefused bool
	// AccountRefused says the last refusal was about the ACCOUNT and not about
	// the machine that relayed it: a router with a pool behind this model asked
	// the whole key to slow down and named no pool while doing it. Every machine
	// it could have picked is behind the same ceiling.
	//
	// IT IS [Plan.ShapeRefused]'S SIBLING AND THE SAME KIND OF FACT: something
	// [Next] cannot see for itself, because the serving set of such a request is
	// usually OPEN — nobody named a pool — and an open set has another machine in
	// it forever ([Plan.serving]). That rule is sound only because each body
	// carries a longer exclusion list than the last, and an account ceiling is
	// exactly the refusal that gives the list nothing to grow by. Without this
	// field the generator answered it with a machine move every time and the
	// dispatcher sent the identical bytes again behind a doubling wait, for as
	// long as the deadline lasted — ninety seconds of `waiting` on 2026-09-11
	// with nothing whatever changing between the sends.
	//
	// A BASE WITH NO POOL BEHIND IT IS NOT THIS. An endpoint that paces us and
	// has one machine is saying "come back later" and repeating really is all
	// there is; what makes a pace an ACCOUNT'S is that a set exists and the
	// refusal named none of it. The one caller that holds the refusal decides
	// both halves (internal/provider's dispatch.go).
	AccountRefused bool
	// Role is who the call is being made for, spelled as `lane.Role` spells it.
	// It is carried rather than looked up so the dispatcher, the hazard and the
	// row all read the same word.
	Role string
	// Ceiling is the hard bound on time-to-action for this call: past it the
	// controller acts whatever it believes, because a belief that says "keep
	// waiting" past a person's patience is a belief answering the wrong
	// question. It is the role's, and every role has one.
	//
	// IT BOUNDS A STILL WIRE. An endpoint that is writing — visibly, or a run
	// of reasoning nobody can read — is not a silence this figure is about, and
	// the one exception is a visible rate that has collapsed, which is a person
	// waiting whatever the wire is doing. See [hazard.stillSince].
	Ceiling time.Duration
	// Floor is the shortest silence that may be acted on. Below it a second
	// request is racing the network rather than the lane.
	Floor time.Duration
	// Lambda is what a second of this call's wait is worth, in SECONDS PER
	// DOLLAR. Zero is "nobody is waiting", under which no amount of money buys
	// speed and the controller only ever reports.
	Lambda float64
	// Margin is the hysteresis: how much better acting has to look before it is
	// done, in seconds. It is what stops a controller flapping at the crossing.
	Margin float64
	// First, Gap and Think are the three distributions of the three phases:
	// the serving lane's first token, the gap between two visible tokens, and
	// how long a whole thinking phase lasts on this MODEL. The third is a model
	// property and not a lane's — a lane cannot make a model think less — which
	// is why it is carried separately.
	First Survival
	Gap   Survival
	Think Survival
	// Alts are the lanes acting could go to, best first, already gated. An
	// empty list is a real state and the reason [Report] exists.
	Alts []Alternative
	// Pinned says a person named this lane themselves. It changes the ACT and
	// never the arithmetic: where an unpinned call hedges, a pinned one asks.
	//
	// IT IS NOT "THE REQUEST NAMED MACHINES". Nearly every request names
	// machines — the chooser demands the set it admitted — and a set this
	// process admitted is this process's to leave the moment it stops working.
	// Only a person's own word turns a rescue into a question, which is why
	// what fills this is carried from the one place that knows one was spoken
	// (`internal/lane`'s Choice.Pinned) and never counted off a list of names.
	Pinned bool
	// Purse is the spend rail, nil when nothing bounds it.
	Purse Purse
	// Expected is roughly how long this answer will be in visible tokens, zero
	// when nobody knows. It is what makes the commitment half of the same
	// inequality computable.
	Expected int
	// Began is when the request went out.
	Began time.Time
}

type Purse interface {
	Allows(usd float64, now time.Time) bool
}

type Reading struct {
	At      time.Time
	Visible int
	Hidden  int
	Beat    bool
}

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

type Survival struct {
	// Mu is the mean of ln T with T in seconds, Sigma its standard deviation.
	// Sigma is the PREDICTIVE spread — how variable one draw is — and never the
	// spread of the estimate of the median, which shrinks to nothing after a few
	// dozen observations and would make every tail look impossible.
	Mu    float64
	Sigma float64
}