From c4a3be90cd4be53f4e572e6668e21a69b56d71f5 Mon Sep 17 00:00:00 2001 From: santoshkumarradha Date: Fri, 11 Sep 2026 16:34:18 -0400 Subject: [PATCH 1/5] Lanes: the chooser demands the set it admitted, instead of suggesting it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit provider.order is advice. With allow_fallbacks true the router reads the list, weighs it against its own load and price, and is free to serve the request from a machine the list never named — which it does. Measured over ten days of the call log: the machine this build asked for first served 29% of the time, the machine a strict preference named served 93%. Every gate the chooser applies — the capability gate, the Pareto prune, the price ceiling with the person's own lambda, the quality floor, and above all beyondThePatience, which takes out the machines whose expected time to a usable answer is longer than this role waits — was spending its evidence on a set the router was free to ignore. internal/lane's demandOf states that set as provider.only: the admitted candidates, minus the ones this choice vetoes, when there are at least two of them. The threshold is the router's own rule and not a number chosen here — a demand of one machine IS a pin, somebody's instruction rather than a belief's opinion, and the rest of the build already reads a one-wide demand as one (demandedLane, the single legal same-machine repeat). The ranking travels inside the demand, the sort word and the ledger's order come off, and a borrowable pin joins the set rather than leading an order the same object forbids. The cost is accepted and named: a pool whose every admitted machine is busy refuses and the call walks, rather than being served by whoever is free. So dropRefusedHere had to be right about whose demand it is narrowing. A person's pin is left exactly as it stands, whatever has refused it — the one legal same-machine repeat is control.Next's to authorize and the ladder's first rung is what takes the field off. A demand the belief made is ours: a machine in it that refused this call is struck like the ranking, and when every name has gone the demand goes with it, with allow_fallbacks restored. Keeping the last name is what asked the router to serve the request from the refuser while allow_fallbacks: false forbade it the healthy machine it would otherwise have found (the seam #925 took its demand back out over). internal/provider/demand_test.go stages it on the wire: both admitted machines demanded with no fallbacks and no sort word on a healthy call; the demand narrowed to the machine that has not refused when a pool is full, never naming the refuser again on any later body; the demand emptied with allow_fallbacks restored and both refusers still vetoed; and a person's pin narrowed by nobody. Manual: lanes.md says the set is named and closed, what it costs when it runs out, and that a set of one is never made this way because a set of one is a pin. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01FSshDkszBQ9RpR4dPsC5fQ --- internal/lane/choose.go | 64 ++++++++++ internal/manual/chat/lanes.md | 28 +++++ internal/provider/demand_test.go | 193 +++++++++++++++++++++++++++++++ internal/provider/lanes.go | 83 ++++++++----- internal/provider/velocity.go | 54 +++++---- 5 files changed, 375 insertions(+), 47 deletions(-) create mode 100644 internal/provider/demand_test.go diff --git a/internal/lane/choose.go b/internal/lane/choose.go index 39f8cc5012..8054a51a9c 100644 --- a/internal/lane/choose.go +++ b/internal/lane/choose.go @@ -652,6 +652,8 @@ func (c *chooser) Choose(req Request) Choice { // of the order is a machine the router is still free to choose. This is the // only half of the veto the router can actually be made to honour. choice.Ignore = refusedInto(choice.Ignore, refused, choice.Order) + // AND WHAT SURVIVED ALL OF IT IS DEMANDED RATHER THAN SUGGESTED (demandOf). + choice.Only = demandOf(scored, choice.Ignore) // AND NOTHING ABOUT TIME. Where a rescue would go and when it would go // there are [PlanFor]'s, built for every call out of the same frontier this // carries — see the note on [Choice]. @@ -659,6 +661,68 @@ func (c *chooser) Choose(req Request) Choice { return choice } +// demandOf is the set this request may go to at all: every machine the role +// admitted and this choice did not veto, in the order it ranked them. +// +// ── WHY A DEMAND AND NOT A RANKING ────────────────────────────────────────── +// +// `provider.order` is ADVICE. With `allow_fallbacks` true the router reads the +// list, weighs it against its own load and price, and is free to serve the +// request from a machine the list never named — which it does, often. Measured +// over ten days of the call log (L10's replay, 2026-09-11): the machine this +// build asked for FIRST served 29 % of the time, while the machine a strict +// preference NAMED served 93 %. Every gate above this line — the capability +// gate, the Pareto prune, the price ceiling, the quality floor, and above all +// [beyondThePatience], which takes out the machines whose expected time to a +// usable answer is longer than this role will wait — spent its evidence on a +// set the router was then free to ignore. +// +// So the admitted set is stated as `provider.only`, which the router may not go +// outside, and the ranking travels inside it as before. What the frontier +// refused is refused, and the cost is accepted and named: a pool whose every +// admitted machine is busy REFUSES and the call walks (internal/lane/control's +// [Next] relaxes the shape, then hands the model to the session) rather than +// being served by whoever happened to be free. +// +// ── WHY TWO ───────────────────────────────────────────────────────────────── +// +// THE THRESHOLD IS THE ROUTER'S OWN RULE AND NOT A NUMBER THIS FILE CHOSE. A +// demand of ONE machine is a pin: `only: [x]` with fallbacks off means the +// request goes to x or it does not go, which is somebody's INSTRUCTION and not a +// belief's opinion — internal/provider builds exactly that object for a person's +// strict pin and for a rescue's arm, and the rest of the build reads a one-wide +// demand as a pin (its `demandedLane`, the single legal same-machine repeat). +// A belief that has admitted one machine has nothing to demand, because +// demanding it would be this build pinning somebody to a machine they never +// asked for; it ranks the one it has and leaves the router its fallbacks. +// +// THE VETOES ARE SUBTRACTED AND NOT SENT BESIDE IT, because `only` and `ignore` +// naming one machine is an empty serving set written by us, in one object, about +// a machine we just asked for — the same rule [refusedInto] keeps one line up +// and internal/provider keeps where it drops the machines that refused a call. +// A machine can be in the frontier and still be vetoed: [ignoredOf] names the +// candidates this process is SURE are far slower than the best, and the ranking +// above only has room for [orderNames] of them. +func demandOf(scored []Scored, ignore []string) []string { + if len(scored) < 2 { + return nil + } + vetoed := make(map[string]bool, len(ignore)) + for _, lane := range ignore { + vetoed[lane] = true + } + demand := make([]string, 0, len(scored)) + for _, candidate := range scored { + if candidate.ID.Lane != "" && !vetoed[candidate.ID.Lane] { + demand = append(demand, candidate.ID.Lane) + } + } + if len(demand) < 2 { + return nil + } + return demand +} + // orderNames is how many lanes the router is told to try in order. Three is the // design's figure: past the third the fallbacks are doing the choosing anyway, // and a longer list is a claim about lanes this process has barely seen. diff --git a/internal/manual/chat/lanes.md b/internal/manual/chat/lanes.md index fca49782d5..361eb6d48d 100644 --- a/internal/manual/chat/lanes.md +++ b/internal/manual/chat/lanes.md @@ -72,6 +72,34 @@ model that company serves. So the first request to a brand-new model is still routed, still has a clock on it, and asks for a fresh sheet in the background while it goes. You never wait for that fetch. +## The machines your message may go to are asked for by name — and the provider may not go outside them + +When aforge has measured enough to have an opinion, it does not merely *rank* the +machines it wants. It **names the set it will accept, and closes it**: the +provider may not serve your message from a machine outside that set. + +The list used to be advice. The provider read it, weighed it against its own +queues and prices, and was free to hand your message to somebody else — and often +did. Over ten days of this build's own call record, the machine aforge asked for +first served 29 requests in every 100; the machine a closed set names served 93. +Everything aforge works out before sending — which machines can do the job at all, +which are quick enough for how long this kind of work waits, what each one costs — +was being spent on a list the provider could put aside. + +**What it costs, and it is a real cost.** A closed set can run out. If every +machine in it is busy at once, your message is refused rather than handed to +whoever happened to be free. What follows is a move, not an ending: the machine +that refused comes off the set and the request goes straight to the next one in +it, with no wait (`trying another machine · 2 of 3`); and when the last one has +gone, the set comes off the request entirely, so the provider has its whole +roster back for the one send that needs it. + +**A set of one is never made this way.** One machine named with nothing to fall +back on is a pin — it is exactly what pinning a lane yourself sends — so aforge +closes a set only when it has at least two machines it is happy with. With one, +it ranks what it has and leaves the provider its usual freedom. Pinning a lane +still means what it always did, and nothing here narrows a set you asked for. + ## The machines one message may go to are decided once — why a retry walks the same set, and why something learned mid-answer waits for your next message Before the first byte of a request leaves, aforge decides which machines that diff --git a/internal/provider/demand_test.go b/internal/provider/demand_test.go new file mode 100644 index 0000000000..591a6f70a4 --- /dev/null +++ b/internal/provider/demand_test.go @@ -0,0 +1,193 @@ +package provider + +import ( + "context" + "testing" + "time" + + lanes "github.com/Agent-Field/aforge-v2/internal/lane" + "github.com/Agent-Field/aforge-v2/internal/lane/lanestub" +) + +// ── THE CHOOSER DEMANDS ───────────────────────────────────────────────────── +// +// `provider.order` is advice. With `allow_fallbacks` true the router reads the +// list, weighs it against its own load, and is free to serve the request from a +// machine the list never named — so every gate the chooser applied was spending +// its evidence on a set the router could ignore. The admitted set is now stated +// as `provider.only`, which the router must honour. +// +// The cost is accepted and it is what these scenarios are about: a pool whose +// admitted machines all refuse has nowhere left to go, and what it does then has +// to be exactly right — narrow to the machines that have not refused, never ask +// the refuser again, and when the last one has gone, take the demand OFF rather +// than sending a set the router has just said it cannot serve. + +// pacedPair is two machines behind one model, both believed in, and a client +// pointed at them. `refuse` names the machines whose pool is full: a 429 naming +// itself, before any stream opens, which is the commonest named refusal in the +// ten-day log. +func pacedPair(t *testing.T, refuse ...string) (*Client, *lanestub.Server, string) { + t.Helper() + const model = "openrouter/demand-model" + full := map[string]bool{} + for _, name := range refuse { + full[name] = true + } + lane := func(name string) lanestub.Lane { + profile := lanestub.Profile{TTFT: time.Millisecond, Rate: 400, Tokens: 8, Tools: true} + if full[name] { + profile.Paced = true + } + return lanestub.Lane{Name: name, Profile: profile} + } + server := lanestub.New(model, lane("deepinfra"), lane("fireworks")) + t.Cleanup(server.Close) + client, err := NewClient(Config{ + APIKey: "test-key", + BaseURL: server.URL(), + Model: model, + Routing: StaticRouting(RoutingLatency), + }) + if err != nil { + t.Fatal(err) + } + lanes.HeardPrefsCarried(server.URL()) + client.velocity = newVelocityLedger() + client.wait = func(context.Context, time.Duration) error { return nil } + // NEITHER MACHINE DOMINATES THE OTHER, which is what keeps both of them in + // the frontier: one starts sooner and costs more, the other starts later and + // costs less, so the Pareto prune has nothing to remove and the demand has + // two names in it. + primed(t, model, + laneBelief(model, "deepinfra", 400, 70, 0.60), + laneBelief(model, "fireworks", 900, 60, 0.20), + ) + return client, server, model +} + +// TestTheAdmittedSetIsDemandedAndNotMerelyRanked is the first half: what goes +// out when nothing has refused yet. +func TestTheAdmittedSetIsDemandedAndNotMerelyRanked(t *testing.T) { + client, server, _ := pacedPair(t) + + if _, err := client.CompleteWithMessages(context.Background(), userMessages("hello")); err != nil { + t.Fatal(err) + } + asks := server.Asks() + if len(asks) == 0 { + t.Fatal("nothing reached the router") + } + first := asks[0] + if len(first.Only) != 2 || !namesEndpoint(first.Only, "deepinfra") || !namesEndpoint(first.Only, "fireworks") { + t.Fatalf("only = %v, want both admitted machines demanded: %+v", first.Only, first) + } + if !first.NoFallbacks { + t.Fatalf("the request named a set and let the router go outside it: %+v", first) + } + if first.Sort != "" { + t.Fatalf("sort = %q rode beside a demand, which is a second opinion about a set that is closed", first.Sort) + } + if len(first.Ignore) != 0 { + t.Fatalf("ignore = %v named a machine beside a closed set — the two fields say opposite things about one name", first.Ignore) + } +} + +// TestADemandNarrowsToTheMachineThatHasNotRefused is the seam #925 took its +// demand back out over: a pool of two with one full. +// +// The demand narrows to the machine that has not refused, and `allow_fallbacks` +// stays off, because there is still somewhere inside the set to go. +func TestADemandNarrowsToTheMachineThatHasNotRefused(t *testing.T) { + client, server, _ := pacedPair(t, "deepinfra") + + if _, err := client.CompleteWithMessages(context.Background(), userMessages("hello")); err != nil { + t.Fatalf("the healthy machine should have answered: %v", err) + } + asks := server.Asks() + if len(asks) < 2 { + t.Fatalf("the call sent %d requests; the full pool should have cost one move", len(asks)) + } + second := asks[1] + if len(second.Only) != 1 || second.Only[0] != "fireworks" { + t.Fatalf("the second body demanded %v, want only the machine that had not refused: %+v", second.Only, second) + } + if !second.NoFallbacks { + t.Fatalf("the second body let the router go outside a set that still had a machine in it: %+v", second) + } + for index, ask := range asks[1:] { + if namesEndpoint(ask.Only, "deepinfra") { + t.Fatalf("body %d demanded the machine that had already refused this call: %+v", index+2, ask) + } + } + if served := server.Served(); len(served) == 0 || served[len(served)-1] != "fireworks" { + t.Fatalf("%v answered, want the healthy machine", served) + } +} + +// TestADemandWithNothingLeftInItComesOffTheBody is the other half of the cost, +// asked of the composed object rather than of a whole call — deliberately, and +// the reason is worth stating. On the wire a pool whose every admitted machine +// has refused has no move left: [control.Next] has tried each of them, so the +// call ends or climbs the ladder, and the ladder's first rung takes the whole +// preference off by itself. The state this guards is the one body that WOULD go +// out with an exhausted demand — a comeback the last machine named, a rung +// climbed by a door that kept the object — and it is guarded because keeping the +// last name there is what asked the router to serve the request from the machine +// that had just refused it, while `allow_fallbacks: false` forbade the healthy +// one it would otherwise have found. +func TestADemandWithNothingLeftInItComesOffTheBody(t *testing.T) { + client, _, model := pacedPair(t) + + knobs := callKnobs{intent: IntentInteractive, refused: &refusedHere{}} + knobs.refused.add("deepinfra") + knobs.refused.add("fireworks") + choice := lanes.Choice{ + Only: []string{"deepinfra", "fireworks"}, + Order: []string{"deepinfra", "fireworks"}, + } + knobs.laneChoice = &choice + + prefs := composedFor(t, client, model, knobs) + if len(prefs.Only) != 0 { + t.Fatalf("only = %v, want no demand left after every machine in it refused this call", prefs.Only) + } + if prefs.AllowFallbacks == nil || !*prefs.AllowFallbacks { + t.Fatalf("the body named no machines and still forbade the router every other one: %+v", prefs) + } + if !namesEndpoint(prefs.Ignore, "deepinfra") || !namesEndpoint(prefs.Ignore, "fireworks") { + t.Fatalf("ignore = %v, want both refusers still named so the widened body does not land back on one", prefs.Ignore) + } +} + +// TestAPersonsPinIsNarrowedByNobody keeps the other demand whole. A one-wide +// `only` is somebody's instruction — "and nowhere else" — and what happens when +// the machine it names refuses is [control.Next]'s to decide and the ladder's to +// act on, never this object's to quietly widen. +func TestAPersonsPinIsNarrowedByNobody(t *testing.T) { + client, _, model := pacedPair(t, "deepinfra") + + knobs := callKnobs{intent: IntentInteractive} + knobs.refused = &refusedHere{} + knobs.refused.add("deepinfra") + choice := lanes.Choice{Only: []string{"deepinfra"}} + knobs.laneChoice = &choice + + prefs := composedFor(t, client, model, knobs) + if len(prefs.Only) != 1 || prefs.Only[0] != "deepinfra" { + t.Fatalf("only = %v, want a person's pin left exactly as it stands", prefs.Only) + } + if prefs.AllowFallbacks == nil || *prefs.AllowFallbacks { + t.Fatalf("a pin that had been refused was quietly allowed to fall back: %+v", prefs) + } +} + +// composedFor is the object one request would actually go out with. +func composedFor(t *testing.T, client *Client, model string, knobs callKnobs) *providerPrefs { + t.Helper() + prefs := client.wirePreferences(model, knobs) + if prefs == nil { + t.Fatal("no preference object was composed at all") + } + return prefs +} diff --git a/internal/provider/lanes.go b/internal/provider/lanes.go index 01cf89a778..e980ba6cce 100644 --- a/internal/provider/lanes.go +++ b/internal/provider/lanes.go @@ -355,33 +355,33 @@ func (c *Client) applyLaneChoice(prefs *providerPrefs, model string, knobs callK return } choice := *knobs.laneChoice - // A DEMAND IS NOT A RANKING, so it replaces the object rather than joining - // it. `Only` is what a pin sends (lanepin.go): the request goes to exactly - // that machine or it does not go, which is the sentence the picker and the - // manual both promise — "every request for this conversation goes to that - // lane and nowhere else". The sort word comes off because there is nothing - // left to sort, the ledger's order comes off because it is a ranking over - // machines this request may not use, and `allow_fallbacks` goes to false - // because a fallback is precisely the thing a pin refuses. + // A DEMAND IS THE SET THE REQUEST MAY GO TO AT ALL, and it is STATED rather + // than suggested. `provider.order` is advice: with `allow_fallbacks` true the + // router reads the list, weighs it against its own load, and is free to serve + // the request from a machine the list never named — which it does. Over ten + // days of the call log the machine this build asked for first served 29 % of + // the time and the machine a strict preference NAMED served 93 %, so every + // gate the chooser applied was spending its evidence on a set the router was + // free to ignore. `only` is the half the router must honour, so the admitted + // set goes there and the ledger's own order comes off with the sort word: + // both are rankings over machines this request may not use. // - // THE PRICE CEILING COMES OFF TOO. The chooser's frontier already admitted - // and priced the demanded machine; applying the router's coarser model-list - // ceiling afterwards can only contradict that decision and make a serving - // lane look as though it refused the model. - if len(choice.Only) > 0 { - only := make([]string, 0, len(choice.Only)) - for _, lane := range choice.Only { - if lane != "" { - only = append(only, lane) - } - } - if len(only) > 0 { - no := false - prefs.Only, prefs.Order, prefs.Sort = only, nil, "" - prefs.AllowFallbacks = &no - prefs.MaxPrice = nil - return - } + // THE RANKING STAYS, INSIDE IT. A demand says WHICH MACHINES and the order + // below says IN WHAT SEQUENCE, and they are two different sentences about one + // set — internal/lane builds the order out of the same admitted candidates + // (choose.go's [lane.demandOf]), so nothing in the order can fall outside the + // demand. + // + // THE PRICE CEILING COMES OFF. The chooser's frontier already admitted and + // priced every demanded machine with the person's own λ; applying the + // router's coarser model-list ceiling afterwards can only contradict that + // decision and make a serving lane look as though it refused the model. + demand := namedLanes(choice.Only) + if len(demand) > 0 { + no := false + prefs.Only, prefs.Order, prefs.Sort = demand, nil, "" + prefs.AllowFallbacks = &no + prefs.MaxPrice = nil } // AND THE AFFINITY PIN YIELDS TO A REFUSAL, which is the one thing a warm // prefix cannot buy its way past. @@ -396,7 +396,14 @@ func (c *Client) applyLaneChoice(prefs *providerPrefs, model string, knobs callK // refused on its own declared patience (internal/lane's beyondThePatience), // and it goes on this body's `ignore` below rather than at the front of its // order. - if pinned != "" && namesEndpoint(choice.Ignore, pinned) { + // + // AND A MACHINE OUTSIDE THE DEMAND IS THE SAME FACT STATED POSITIVELY. The + // admitted set is what the role would wait for; a machine that is not in it + // is one the frontier ruled out, and leading the order with it would either + // be ignored by the router or — under `allow_fallbacks: false` — name a + // machine the same object forbids. + if pinned != "" && (namesEndpoint(choice.Ignore, pinned) || + (len(demand) > 0 && !namesEndpoint(demand, pinned))) { pinned = "" } if len(choice.Order) > 0 { @@ -525,6 +532,16 @@ func (c *Client) drawLaneChoice(knobs callKnobs, model string, request *ai.Reque // where it is so a rescue has somewhere to go when the pin stalls. if named != "" { choice.Order = append([]string{named}, withoutEndpoint(choice.Order, named)...) + // AND IT JOINS THE DEMAND, because a demand is the set the request may go + // to at all: asked for first inside a set that does not contain it, the + // machine a person named is a machine the same object forbids. It comes + // off the veto list for the same reason — `only` and `ignore` naming one + // machine is an empty serving set written by us about the machine we were + // asked for. + if len(choice.Only) > 0 { + choice.Only = append([]string{named}, withoutEndpoint(choice.Only, named)...) + } + choice.Ignore = withoutEndpoint(choice.Ignore, named) } return choice, !choice.Empty() } @@ -627,6 +644,18 @@ func struck(ignore []string) []string { return names } +// namedLanes is a lane list with the empty names taken out, which is the only +// cleaning a list that came from a belief or a person's row ever needs. +func namedLanes(lanes []string) []string { + named := make([]string, 0, len(lanes)) + for _, lane := range lanes { + if lane != "" { + named = append(named, lane) + } + } + return named +} + // namesEndpoint reports whether a preference list already names an endpoint. func namesEndpoint(list []string, name string) bool { for _, held := range list { diff --git a/internal/provider/velocity.go b/internal/provider/velocity.go index 965dd33a0f..f322e68502 100644 --- a/internal/provider/velocity.go +++ b/internal/provider/velocity.go @@ -462,13 +462,25 @@ func (c *Client) wirePreferences(model string, knobs callKnobs) *providerPrefs { // ── WHAT IT MAY NARROW AND WHAT IT MAY NOT ────────────────────────────────── // // `order` and `ignore` are RANKINGS AND VETOES and both are ours, so a refusing -// machine is simply struck from the first and added to the second. `only` is a -// DEMAND, and a demand is somebody's instruction rather than this build's -// opinion: a person's strict pin or a rescue's one machine. So a demand is -// narrowed only while something is left in it — two machines demanded and one -// refusing leaves the other — and a demand down to its last machine is left -// exactly as it stands, which is the one legal same-machine move (retry.go's -// [Client.handBack] decides what happens to it). +// machine is simply struck from the first and added to the second. +// +// `only` IS A DEMAND AND IT DEPENDS WHOSE. A demand of ONE machine is a person's +// strict pin or a rescue's own arm — somebody's instruction, "and nowhere else" +// — and it is left exactly as it stands, whatever has refused it: the one legal +// same-machine repeat is [control.Next]'s to authorize and the ladder's first +// rung is what takes the field off (`demandedLane` is the one reading of "whose +// demand is this", and it answers strict for exactly that shape). +// +// A DEMAND THE BELIEF MADE IS OURS, AND IT EMPTIES. It is the admitted set +// (internal/lane's demandOf), so a machine in it that has refused this call is a +// machine this build no longer wants — struck, like the ranking — and when every +// name has gone the demand goes with it. Keeping the last one is what asked a +// pool of two, with one refusing, to serve the request from the refuser while +// `allow_fallbacks: false` forbade the router the healthy machine it would +// otherwise have found. With the demand gone the router has its whole roster +// back for the one body that needs it, and the CALL still walks the set it +// decided on, because the plan reads the choice rather than this object +// ([requestSet]) and [control.Next] never returns a machine already tried. // // A CALL THAT HAS BEEN REFUSED BY NOBODY CHANGES NOTHING, which is every call // on every healthy path: the object is returned untouched and the request is @@ -491,9 +503,10 @@ func (c *Client) dropRefusedHere(prefs *providerPrefs, knobs callKnobs) *provide return &providerPrefs{Ignore: refused} } narrowed := *prefs + _, asked := demandedLane(knobs) for _, name := range refused { - if kept := keepingServable(narrowed.Only, name); kept != nil { - narrowed.Only = kept + if !asked { + narrowed.Only = withoutEndpoint(narrowed.Only, name) } narrowed.Order = withoutEndpoint(narrowed.Order, name) // A DEMANDED MACHINE IS NEVER ALSO VETOED. The two fields would then say @@ -504,18 +517,19 @@ func (c *Client) dropRefusedHere(prefs *providerPrefs, knobs callKnobs) *provide narrowed.Ignore = append(narrowed.Ignore, name) } } - return &narrowed -} - -// keepingServable is a demand with one machine taken out of it, or nil when -// taking it out would leave nothing to demand. A demand nobody can serve is the -// router answering "no allowed providers are available" before it asks anybody, -// which is a round trip spent to be told what this process already knew. -func keepingServable(only []string, name string) []string { - if len(only) < 2 || !namesEndpoint(only, name) { - return nil + // AND A DEMAND WITH NOTHING LEFT IN IT IS NO DEMAND. The field would + // otherwise be dropped from the encoded body by `omitempty` while + // `allow_fallbacks: false` stayed on it, which says "these machines and no + // others" about no machines at all — the router's own "no allowed providers + // are available", bought with a round trip. Both come off together, so the + // one body that had nowhere left to go carries the request the way a request + // with no belief behind it has always been carried. + if prefs.Only != nil && len(narrowed.Only) == 0 { + narrowed.Only = nil + yes := true + narrowed.AllowFallbacks = &yes } - return withoutEndpoint(only, name) + return &narrowed } // membershipNarrowing reports whether this preference object carries a From 445e4097835435ee9b0081d70af85a38545d41f2 Mon Sep 17 00:00:00 2001 From: santoshkumarradha Date: Fri, 11 Sep 2026 16:35:23 -0400 Subject: [PATCH 2/5] docs: change entry for #937 Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01FSshDkszBQ9RpR4dPsC5fQ --- .../changes/unreleased/937-chooser-demands.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 docs/changes/unreleased/937-chooser-demands.md diff --git a/docs/changes/unreleased/937-chooser-demands.md b/docs/changes/unreleased/937-chooser-demands.md new file mode 100644 index 0000000000..43b70c8879 --- /dev/null +++ b/docs/changes/unreleased/937-chooser-demands.md @@ -0,0 +1,20 @@ +--- +kind: changed +title: the chooser demands the set it admitted rather than suggesting it +pr: 937 +surface: [engine, chat, docs] +invalidates: + - "The belief's ranking went out as `provider.order` with `allow_fallbacks: true`, which is ADVICE: the router weighed it against its own load and price and was free to serve the request from a machine the list never named. Measured over ten days of the call log, the machine asked for first served 29% of the time and a machine a strict preference named served 93%. The admitted set now goes out as `provider.only` with `allow_fallbacks: false` (internal/lane's `demandOf`), and the router may not go outside it." + - "`provider.only` meant a PIN and nothing else — a person's strict row, or a rescue's one arm — and every reader of it keyed on one name. It is now also the belief's admitted set, which is two names or more; the one-wide shape still means a pin and is still what `demandedLane` answers strict for. A belief that admitted fewer than two machines makes NO demand, because a demand of one would be this build pinning somebody to a machine they never asked for." + - "A demand rode alone: the sort word, the ledger's order and the price ceiling all came off and the object returned. The ranking now travels INSIDE the demand (`order` says in what sequence, `only` says which machines), a borrowable lane pin joins the set instead of leading an order the same object forbids, and the affinity cache pin yields to a machine outside the admitted set exactly as it already yielded to a refused one." + - "`keepingServable` narrowed a demand only while two names were left, so a demand down to its last machine was left as it stood — which asked the router to serve the request from the machine that had just refused it, while `allow_fallbacks: false` forbade it the healthy machine it would otherwise have found. `dropRefusedHere` now asks WHOSE demand it is: a person's (one name, `demandedLane` strict) is left exactly as it stands, and the belief's is struck like the ranking and dropped entirely when every name has gone, with `allow_fallbacks` restored. `keepingServable` is deleted." + - "The chat manual said auto RANKS the machines it wants. It now says aforge names the set it will accept and closes it, what that costs when the set runs out, and that a set of one is never made this way because a set of one is a pin." +--- + +Stacked on #934, which is the seam it needs: the plan, the watch and the body +have to be looking at one set before the chooser can demand one. + +Owed and stated in the pull request rather than hidden: the rebase onto #925, +the `PhaseNews.Lane` fill (the machine the next body will ask for is the plan's +move, in a file this change does not own), and the measured before/after with +the L3 rig and `make replay`. From 3d17f98af11cedb71be41dab604e609499d1f13c Mon Sep 17 00:00:00 2001 From: santoshkumarradha Date: Fri, 11 Sep 2026 17:02:58 -0400 Subject: [PATCH 3/5] A demand somebody asked for is one machine wide, and demandedLane says so dropRefusedHere narrows the BELIEF's demand and leaves an asked-for one alone, and the question "is this request confined to one machine" is already answered in one place: #925's demandedLane, which reads the rescue's arm first and then a one-wide provider.only, and whose own doc says a demand naming several machines answers empty so that this function narrows it a machine at a time. Asked of it here, the set this narrows, the set requestSet confines the plan to, and the machine the veto-did-not-take law exempts cannot disagree. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01FSshDkszBQ9RpR4dPsC5fQ --- .../changes/unreleased/937-chooser-demands.md | 2 +- internal/provider/demand_test.go | 45 ++++++++++++------- internal/provider/velocity.go | 19 ++++---- 3 files changed, 41 insertions(+), 25 deletions(-) diff --git a/docs/changes/unreleased/937-chooser-demands.md b/docs/changes/unreleased/937-chooser-demands.md index 43b70c8879..07a58f538a 100644 --- a/docs/changes/unreleased/937-chooser-demands.md +++ b/docs/changes/unreleased/937-chooser-demands.md @@ -7,7 +7,7 @@ invalidates: - "The belief's ranking went out as `provider.order` with `allow_fallbacks: true`, which is ADVICE: the router weighed it against its own load and price and was free to serve the request from a machine the list never named. Measured over ten days of the call log, the machine asked for first served 29% of the time and a machine a strict preference named served 93%. The admitted set now goes out as `provider.only` with `allow_fallbacks: false` (internal/lane's `demandOf`), and the router may not go outside it." - "`provider.only` meant a PIN and nothing else — a person's strict row, or a rescue's one arm — and every reader of it keyed on one name. It is now also the belief's admitted set, which is two names or more; the one-wide shape still means a pin and is still what `demandedLane` answers strict for. A belief that admitted fewer than two machines makes NO demand, because a demand of one would be this build pinning somebody to a machine they never asked for." - "A demand rode alone: the sort word, the ledger's order and the price ceiling all came off and the object returned. The ranking now travels INSIDE the demand (`order` says in what sequence, `only` says which machines), a borrowable lane pin joins the set instead of leading an order the same object forbids, and the affinity cache pin yields to a machine outside the admitted set exactly as it already yielded to a refused one." - - "`keepingServable` narrowed a demand only while two names were left, so a demand down to its last machine was left as it stood — which asked the router to serve the request from the machine that had just refused it, while `allow_fallbacks: false` forbade it the healthy machine it would otherwise have found. `dropRefusedHere` now asks WHOSE demand it is: a person's (one name, `demandedLane` strict) is left exactly as it stands, and the belief's is struck like the ranking and dropped entirely when every name has gone, with `allow_fallbacks` restored. `keepingServable` is deleted." + - "`keepingServable` narrowed a demand only while two names were left, so a demand down to its last machine was left as it stood — which asked the router to serve the request from the machine that had just refused it, while `allow_fallbacks: false` forbade it the healthy machine it would otherwise have found. `dropRefusedHere` now asks HOW WIDE the demand is, through `demandedLane` — the same door #925's veto-law exemption reads and the same reading `requestSet` confines the plan to: a request that demanded ONE machine (a person's pin, a rescue's arm) is left exactly as it stands, and the belief's wider demand is struck like the ranking and dropped entirely when every name has gone, with `allow_fallbacks` restored. `keepingServable` is deleted." - "The chat manual said auto RANKS the machines it wants. It now says aforge names the set it will accept and closes it, what that costs when the set runs out, and that a set of one is never made this way because a set of one is a pin." --- diff --git a/internal/provider/demand_test.go b/internal/provider/demand_test.go index 591a6f70a4..4a5cd46122 100644 --- a/internal/provider/demand_test.go +++ b/internal/provider/demand_test.go @@ -160,25 +160,38 @@ func TestADemandWithNothingLeftInItComesOffTheBody(t *testing.T) { } } -// TestAPersonsPinIsNarrowedByNobody keeps the other demand whole. A one-wide -// `only` is somebody's instruction — "and nowhere else" — and what happens when -// the machine it names refuses is [control.Next]'s to decide and the ladder's to -// act on, never this object's to quietly widen. -func TestAPersonsPinIsNarrowedByNobody(t *testing.T) { +// TestADemandSomebodyAskedForIsNarrowedByNobody keeps the other demand whole. A +// demand a person pinned, and the one machine a rescue's arm exists to try, are +// instructions — "and nowhere else" — and what happens when the machine refuses +// is [control.Next]'s to decide and the ladder's to act on, never this object's +// to quietly widen. +func TestADemandSomebodyAskedForIsNarrowedByNobody(t *testing.T) { client, _, model := pacedPair(t, "deepinfra") - knobs := callKnobs{intent: IntentInteractive} - knobs.refused = &refusedHere{} - knobs.refused.add("deepinfra") - choice := lanes.Choice{Only: []string{"deepinfra"}} - knobs.laneChoice = &choice - - prefs := composedFor(t, client, model, knobs) - if len(prefs.Only) != 1 || prefs.Only[0] != "deepinfra" { - t.Fatalf("only = %v, want a person's pin left exactly as it stands", prefs.Only) + pin := lanes.Choice{Only: []string{"deepinfra"}} + belief := lanes.Choice{ + Only: []string{"deepinfra", "fireworks"}, + Order: []string{"deepinfra", "fireworks"}, } - if prefs.AllowFallbacks == nil || *prefs.AllowFallbacks { - t.Fatalf("a pin that had been refused was quietly allowed to fall back: %+v", prefs) + for _, asked := range []struct { + what string + knobs callKnobs + demand string + }{ + {"a person's strict pin", callKnobs{intent: IntentInteractive, laneChoice: &pin}, "deepinfra"}, + {"a rescue's own arm", callKnobs{intent: IntentInteractive, laneChoice: &belief, hedgeLane: "deepinfra"}, "deepinfra"}, + } { + knobs := asked.knobs + knobs.refused = &refusedHere{} + knobs.refused.add("deepinfra") + + prefs := composedFor(t, client, model, knobs) + if len(prefs.Only) != 1 || prefs.Only[0] != asked.demand { + t.Errorf("%s: only = %v, want it left exactly as it stands", asked.what, prefs.Only) + } + if prefs.AllowFallbacks == nil || *prefs.AllowFallbacks { + t.Errorf("%s: a refused demand was quietly allowed to fall back: %+v", asked.what, prefs) + } } } diff --git a/internal/provider/velocity.go b/internal/provider/velocity.go index f322e68502..fc7a4a17e2 100644 --- a/internal/provider/velocity.go +++ b/internal/provider/velocity.go @@ -464,12 +464,15 @@ func (c *Client) wirePreferences(model string, knobs callKnobs) *providerPrefs { // `order` and `ignore` are RANKINGS AND VETOES and both are ours, so a refusing // machine is simply struck from the first and added to the second. // -// `only` IS A DEMAND AND IT DEPENDS WHOSE. A demand of ONE machine is a person's -// strict pin or a rescue's own arm — somebody's instruction, "and nowhere else" -// — and it is left exactly as it stands, whatever has refused it: the one legal -// same-machine repeat is [control.Next]'s to authorize and the ladder's first -// rung is what takes the field off (`demandedLane` is the one reading of "whose -// demand is this", and it answers strict for exactly that shape). +// `only` IS A DEMAND AND IT DEPENDS HOW WIDE. A request that demanded ONE +// machine — a person's strict pin, or the machine a rescue's arm exists to try — +// is left exactly as it stands, whatever has refused it: there is no other +// machine for the next body to go to, so the one legal same-machine repeat is +// [control.Next]'s to authorize and the ladder's first rung is what takes the +// field off. That question is [demandedLane]'s and it is asked of it here rather +// than answered again: it is the same door the veto law's exemption reads and +// the same reading [requestSet] confines the plan to, so the set this narrows, +// the set the plan walks and the machine the law exempts cannot disagree. // // A DEMAND THE BELIEF MADE IS OURS, AND IT EMPTIES. It is the admitted set // (internal/lane's demandOf), so a machine in it that has refused this call is a @@ -503,9 +506,9 @@ func (c *Client) dropRefusedHere(prefs *providerPrefs, knobs callKnobs) *provide return &providerPrefs{Ignore: refused} } narrowed := *prefs - _, asked := demandedLane(knobs) + alone, _ := demandedLane(knobs) for _, name := range refused { - if !asked { + if alone == "" { narrowed.Only = withoutEndpoint(narrowed.Only, name) } narrowed.Order = withoutEndpoint(narrowed.Order, name) From 644dc49688815e65752fb7d1c3053a580cf535bf Mon Sep 17 00:00:00 2001 From: santoshkumarradha Date: Fri, 11 Sep 2026 18:07:58 -0400 Subject: [PATCH 4/5] A pin is a person's word; a demand is the set we admitted MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `control.Plan.Pinned` was `len(choice.Only) > 0`, which was the same sentence for exactly as long as `Only` held nothing but a person's strict row. The chooser now demands the set it admitted, so counting names called every ordinary routed call pinned — and everything a pin changes is person-facing: `internal/lane/control`'s hazard takes the `Ask` road before it even looks for somewhere to go, so a slow call showed `switch to auto? (y)` about a machine nobody chose and sent no rescue at all; and the primary arm stopped walking off a 429, a 5xx or a broken stream, which is the opposite of what this wave is for. So the fact is carried rather than inferred. `lane.Choice.Pinned` is written in the one place that knows a person spoke — `drawLaneChoice`'s strict-pin branch, which reads their own row — and read in the one place the plan is built. A demand is ours to relax; a pin is theirs to be asked about. Two wire scenarios are the law, both red before this: one stall, two choices, two acts (`TestADemandedCallIsRescuedAndAPersonsPinIsAsked`), and a demanded primary walking off the broken stream that is 1,884 of the census's 1,887 in-stream failures. A structural law keeps the derivation from coming back: only a person's own row may pin a call, and a pin may never be counted off `Only`. One existing scenario had to start saying it too: `TestStrictPinDoesNotWalkToAnotherEndpointAfterTransportFailure` staged a strict pin as `Only` alone, which is now what every routed call carries — so it stated the fact instead, and it is red without this change for the right reason (`only:[B]`: the pin walked). Folded in from #934's review: the two dangling `[Client.laneChoiceFor]` godoc links, `ledger.warm` read under the mutex it is written under, a line saying the single-arm invariant is staged by omission, fictional machine names in `demand_test.go`, and the manual no longer carries two stories about what auto asks for or leaves `switch to auto?` sounding like something auto can raise. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01FSshDkszBQ9RpR4dPsC5fQ --- .../changes/unreleased/937-chooser-demands.md | 12 +- internal/lane/contract.go | 21 ++- internal/lane/control/contract.go | 7 + internal/manual/chat/lanes.md | 11 ++ internal/provider/demand_test.go | 173 ++++++++++++++++-- internal/provider/lane_law_test.go | 99 ++++++++++ internal/provider/lanepin.go | 2 +- internal/provider/lanes.go | 8 +- internal/provider/offer_test.go | 5 + internal/provider/onechoice_test.go | 23 ++- internal/provider/routing_audit_test.go | 6 +- internal/provider/velocity.go | 2 +- internal/provider/waiting_law_test.go | 6 +- internal/provider/waitplan.go | 24 ++- 14 files changed, 356 insertions(+), 43 deletions(-) diff --git a/docs/changes/unreleased/937-chooser-demands.md b/docs/changes/unreleased/937-chooser-demands.md index 07a58f538a..7fbc39f8f1 100644 --- a/docs/changes/unreleased/937-chooser-demands.md +++ b/docs/changes/unreleased/937-chooser-demands.md @@ -8,13 +8,15 @@ invalidates: - "`provider.only` meant a PIN and nothing else — a person's strict row, or a rescue's one arm — and every reader of it keyed on one name. It is now also the belief's admitted set, which is two names or more; the one-wide shape still means a pin and is still what `demandedLane` answers strict for. A belief that admitted fewer than two machines makes NO demand, because a demand of one would be this build pinning somebody to a machine they never asked for." - "A demand rode alone: the sort word, the ledger's order and the price ceiling all came off and the object returned. The ranking now travels INSIDE the demand (`order` says in what sequence, `only` says which machines), a borrowable lane pin joins the set instead of leading an order the same object forbids, and the affinity cache pin yields to a machine outside the admitted set exactly as it already yielded to a refused one." - "`keepingServable` narrowed a demand only while two names were left, so a demand down to its last machine was left as it stood — which asked the router to serve the request from the machine that had just refused it, while `allow_fallbacks: false` forbade it the healthy machine it would otherwise have found. `dropRefusedHere` now asks HOW WIDE the demand is, through `demandedLane` — the same door #925's veto-law exemption reads and the same reading `requestSet` confines the plan to: a request that demanded ONE machine (a person's pin, a rescue's arm) is left exactly as it stands, and the belief's wider demand is struck like the ranking and dropped entirely when every name has gone, with `allow_fallbacks` restored. `keepingServable` is deleted." - - "The chat manual said auto RANKS the machines it wants. It now says aforge names the set it will accept and closes it, what that costs when the set runs out, and that a set of one is never made this way because a set of one is a pin." + - "A PIN AND A DEMAND WERE THE SAME FACT, because `Only` only ever held a pin: `control.Plan.Pinned` was `len(choice.Only) > 0`, and everything a pin changes — the hazard answering a stall with `switch to auto? (y)` instead of a rescue, the primary arm refusing to walk off a transient fault — hung off that count. With the chooser demanding its own admitted set, counting would have made every ordinary routed call pinned. `lane.Choice.Pinned` now carries the fact, written only where a PERSON's strict row is read (`drawLaneChoice`) and read only where the plan is built (`planFor`). A demand is ours to relax; a pin is theirs to be asked about." + - "The chat manual said auto RANKS the machines it wants. It now says aforge names the set it will accept and closes it, what that costs when the set runs out, and that a set of one is never made this way because a set of one is a pin. The `switch to auto?` page said that question belongs to a pinned lane; it now says so explicitly, because auto asks for machines by name too and is never the subject of that question." --- Stacked on #934, which is the seam it needs: the plan, the watch and the body have to be looking at one set before the chooser can demand one. -Owed and stated in the pull request rather than hidden: the rebase onto #925, -the `PhaseNews.Lane` fill (the machine the next body will ask for is the plan's -move, in a file this change does not own), and the measured before/after with -the L3 rig and `make replay`. +Owed and stated in the pull request rather than hidden: the `PhaseNews.Lane` +fill (the machine the next body will ask for is the plan's move, in a file this +change does not own). The measured before/after — the L3 rig at this head +against `dev`, and `make replay` over the ten-day call log — is in the pull +request body. diff --git a/internal/lane/contract.go b/internal/lane/contract.go index 48695377c7..f5f3b6ba4c 100644 --- a/internal/lane/contract.go +++ b/internal/lane/contract.go @@ -196,9 +196,11 @@ type Scored struct { // Choice is what one request should ask the router for. // -// Order is a preference and Only is a demand: a pin sends Only, and everything -// else sends Order with fallbacks left on, because a slow answer beats no -// answer. Ignore names the lanes we are SURE about rather than the ones we are +// Order is a preference and Only is a demand. Both are sent: the machines that +// survived the gate and the prune are DEMANDED (`provider.only` with fallbacks +// off) and ranked inside that set by Order, because the machines outside it are +// ones this process has measured and rejected rather than ones it never heard +// of. Ignore names the lanes we are SURE about rather than the ones we are // merely unlucky with, and it expires with the belief rather than on a timer. // // A zero Choice is "no opinion", which is a real answer and the right one when @@ -208,6 +210,19 @@ 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, diff --git a/internal/lane/control/contract.go b/internal/lane/control/contract.go index b803deca90..1cb95c7be4 100644 --- a/internal/lane/control/contract.go +++ b/internal/lane/control/contract.go @@ -432,6 +432,13 @@ type Plan struct { 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 diff --git a/internal/manual/chat/lanes.md b/internal/manual/chat/lanes.md index 361eb6d48d..a338aeb54c 100644 --- a/internal/manual/chat/lanes.md +++ b/internal/manual/chat/lanes.md @@ -53,6 +53,11 @@ needs — and then ranks what is left by the only thing you actually feel: how l you will be sitting there, plus what it costs, with the money converted into seconds by how much your waiting is worth. +**The machines that survive all that are asked for by name, and the provider may +not go outside them.** It is not a ranking the provider is free to put aside; it +is a closed set with the ranking applied inside it. The section below says what +that costs when every machine in the set is busy at once. + Nothing is waiting on this when nobody is waiting on you. A background errand is ranked on price, because a second saved for a machine is a second nobody spends. @@ -266,6 +271,12 @@ endpoint that was already ranked second — no new decision made at the worst possible moment. The question is asked **once** per answer, and it disappears the moment your answer starts arriving, because by then it is moot. +**You are only ever asked about a machine you pinned yourself.** On auto, aforge +also asks for machines by name — the closed set above — but that set is its own, +so a slow machine in it is simply left: the answer is started somewhere else and +you are told what is happening (`trying another machine`) rather than asked to +decide anything. The question is what your own instruction earns. + **`y` is the only key the question takes.** There is nothing to press to say no, because there is nothing to decline — the wait is happening either way, and refusing would only leave you in it. So the question is not a card you have to clear: it takes itself down the diff --git a/internal/provider/demand_test.go b/internal/provider/demand_test.go index 4a5cd46122..3f8a4d32a9 100644 --- a/internal/provider/demand_test.go +++ b/internal/provider/demand_test.go @@ -41,7 +41,7 @@ func pacedPair(t *testing.T, refuse ...string) (*Client, *lanestub.Server, strin } return lanestub.Lane{Name: name, Profile: profile} } - server := lanestub.New(model, lane("deepinfra"), lane("fireworks")) + server := lanestub.New(model, lane("cinnabar"), lane("tinder")) t.Cleanup(server.Close) client, err := NewClient(Config{ APIKey: "test-key", @@ -60,8 +60,8 @@ func pacedPair(t *testing.T, refuse ...string) (*Client, *lanestub.Server, strin // costs less, so the Pareto prune has nothing to remove and the demand has // two names in it. primed(t, model, - laneBelief(model, "deepinfra", 400, 70, 0.60), - laneBelief(model, "fireworks", 900, 60, 0.20), + laneBelief(model, "cinnabar", 400, 70, 0.60), + laneBelief(model, "tinder", 900, 60, 0.20), ) return client, server, model } @@ -79,7 +79,7 @@ func TestTheAdmittedSetIsDemandedAndNotMerelyRanked(t *testing.T) { t.Fatal("nothing reached the router") } first := asks[0] - if len(first.Only) != 2 || !namesEndpoint(first.Only, "deepinfra") || !namesEndpoint(first.Only, "fireworks") { + if len(first.Only) != 2 || !namesEndpoint(first.Only, "cinnabar") || !namesEndpoint(first.Only, "tinder") { t.Fatalf("only = %v, want both admitted machines demanded: %+v", first.Only, first) } if !first.NoFallbacks { @@ -99,7 +99,7 @@ func TestTheAdmittedSetIsDemandedAndNotMerelyRanked(t *testing.T) { // The demand narrows to the machine that has not refused, and `allow_fallbacks` // stays off, because there is still somewhere inside the set to go. func TestADemandNarrowsToTheMachineThatHasNotRefused(t *testing.T) { - client, server, _ := pacedPair(t, "deepinfra") + client, server, _ := pacedPair(t, "cinnabar") if _, err := client.CompleteWithMessages(context.Background(), userMessages("hello")); err != nil { t.Fatalf("the healthy machine should have answered: %v", err) @@ -109,18 +109,18 @@ func TestADemandNarrowsToTheMachineThatHasNotRefused(t *testing.T) { t.Fatalf("the call sent %d requests; the full pool should have cost one move", len(asks)) } second := asks[1] - if len(second.Only) != 1 || second.Only[0] != "fireworks" { + if len(second.Only) != 1 || second.Only[0] != "tinder" { t.Fatalf("the second body demanded %v, want only the machine that had not refused: %+v", second.Only, second) } if !second.NoFallbacks { t.Fatalf("the second body let the router go outside a set that still had a machine in it: %+v", second) } for index, ask := range asks[1:] { - if namesEndpoint(ask.Only, "deepinfra") { + if namesEndpoint(ask.Only, "cinnabar") { t.Fatalf("body %d demanded the machine that had already refused this call: %+v", index+2, ask) } } - if served := server.Served(); len(served) == 0 || served[len(served)-1] != "fireworks" { + if served := server.Served(); len(served) == 0 || served[len(served)-1] != "tinder" { t.Fatalf("%v answered, want the healthy machine", served) } } @@ -140,11 +140,11 @@ func TestADemandWithNothingLeftInItComesOffTheBody(t *testing.T) { client, _, model := pacedPair(t) knobs := callKnobs{intent: IntentInteractive, refused: &refusedHere{}} - knobs.refused.add("deepinfra") - knobs.refused.add("fireworks") + knobs.refused.add("cinnabar") + knobs.refused.add("tinder") choice := lanes.Choice{ - Only: []string{"deepinfra", "fireworks"}, - Order: []string{"deepinfra", "fireworks"}, + Only: []string{"cinnabar", "tinder"}, + Order: []string{"cinnabar", "tinder"}, } knobs.laneChoice = &choice @@ -155,7 +155,7 @@ func TestADemandWithNothingLeftInItComesOffTheBody(t *testing.T) { if prefs.AllowFallbacks == nil || !*prefs.AllowFallbacks { t.Fatalf("the body named no machines and still forbade the router every other one: %+v", prefs) } - if !namesEndpoint(prefs.Ignore, "deepinfra") || !namesEndpoint(prefs.Ignore, "fireworks") { + if !namesEndpoint(prefs.Ignore, "cinnabar") || !namesEndpoint(prefs.Ignore, "tinder") { t.Fatalf("ignore = %v, want both refusers still named so the widened body does not land back on one", prefs.Ignore) } } @@ -166,24 +166,24 @@ func TestADemandWithNothingLeftInItComesOffTheBody(t *testing.T) { // is [control.Next]'s to decide and the ladder's to act on, never this object's // to quietly widen. func TestADemandSomebodyAskedForIsNarrowedByNobody(t *testing.T) { - client, _, model := pacedPair(t, "deepinfra") + client, _, model := pacedPair(t, "cinnabar") - pin := lanes.Choice{Only: []string{"deepinfra"}} + pin := lanes.Choice{Only: []string{"cinnabar"}, Pinned: true} belief := lanes.Choice{ - Only: []string{"deepinfra", "fireworks"}, - Order: []string{"deepinfra", "fireworks"}, + Only: []string{"cinnabar", "tinder"}, + Order: []string{"cinnabar", "tinder"}, } for _, asked := range []struct { what string knobs callKnobs demand string }{ - {"a person's strict pin", callKnobs{intent: IntentInteractive, laneChoice: &pin}, "deepinfra"}, - {"a rescue's own arm", callKnobs{intent: IntentInteractive, laneChoice: &belief, hedgeLane: "deepinfra"}, "deepinfra"}, + {"a person's strict pin", callKnobs{intent: IntentInteractive, laneChoice: &pin}, "cinnabar"}, + {"a rescue's own arm", callKnobs{intent: IntentInteractive, laneChoice: &belief, hedgeLane: "cinnabar"}, "cinnabar"}, } { knobs := asked.knobs knobs.refused = &refusedHere{} - knobs.refused.add("deepinfra") + knobs.refused.add("cinnabar") prefs := composedFor(t, client, model, knobs) if len(prefs.Only) != 1 || prefs.Only[0] != asked.demand { @@ -195,6 +195,139 @@ func TestADemandSomebodyAskedForIsNarrowedByNobody(t *testing.T) { } } +// ── A DEMAND IS NOT A PIN ─────────────────────────────────────────────────── +// +// They are two different facts that happen to travel in one field. A PIN is a +// person's one machine, typed by hand, and it is ASKED about rather than routed +// around: `coreweave is slow · switch to auto? (y)`. A DEMAND is the set THIS +// process admitted, and it is ours to relax the instant it stops working — a +// rescue, a walk, a narrowing, none of which anybody needs to be consulted +// about. +// +// The distinction had no field of its own while `Only` held nothing but a pin, +// so the plan counted names: `Pinned = len(choice.Only) > 0`. The moment the +// chooser began demanding its own admitted set, that sentence called EVERY +// ordinary call pinned — the hazard takes the `Ask` road before it even looks +// for somewhere to go, so a person is offered `switch to auto?` about a machine +// they never chose, and no rescue is sent at all; and the primary arm stops +// walking off a 429, which is the opposite of what this wave is for. So the +// fact is carried ([lanes.Choice.Pinned]) and these two scenarios are the law +// at the wire: one stall, two choices, two different acts. + +// demandedChoice is what the chooser hands an ordinary routed call: the machines +// it admitted, demanded, and nobody's pin. +func demandedChoice(model string) lanes.Choice { + choice := choiceFor(model, 0) + choice.Only = append([]string(nil), choice.Order...) + return choice +} + +// TestADemandedCallIsRescuedAndAPersonsPinIsAsked is the whole of the +// difference, proved over one wire. +// +// The machine that goes quiet is the same machine, the belief about it is the +// same belief, and the controller's arithmetic is identical. Only the ACT +// differs, and it must: the set we admitted is ours to leave, the machine a +// person named is theirs to be asked about. +func TestADemandedCallIsRescuedAndAPersonsPinIsAsked(t *testing.T) { + for _, scenario := range []struct { + what string + choice func(model string) lanes.Choice + act string + asked bool + }{ + {"the set the chooser admitted", demandedChoice, "hedge", false}, + {"the one machine a person named", func(model string) lanes.Choice { + return pinnedChoice(model, "A", "B") + }, "ask", true}, + } { + t.Run(scenario.what, func(t *testing.T) { + told := listen(t) + rig := newLaneRig(t, "demand/act", + lanestub.Lane{Name: "A", Profile: lanestub.Profile{ + TTFT: time.Second, Rate: 2000, Tokens: 24, Heartbeats: true, + }}, + lanestub.Lane{Name: "B", Profile: lanestub.Profile{ + TTFT: 5 * time.Millisecond, Rate: 2000, Tokens: 24, + }}, + ) + rig.believes("A", 20, 2000) + rig.patience(t, 150*time.Millisecond) + + report := &HedgeReport{} + ctx := WithHedgeReport(context.Background(), report) + ctx = WithLaneChoice(ctx, scenario.choice(rig.model)) + + answers := make(chan int, 1) + go func() { + response, err := rig.client.CompleteWithMessages(ctx, userMessages("hello")) + if err != nil { + answers <- -1 + return + } + answers <- answerTokens(response) + }() + // A QUESTION IS ONLY A QUESTION IF SOMEBODY ANSWERS IT, so the + // pinned row says yes and the demanded row must never be waiting + // for anybody at all. + if scenario.asked { + if !AnswerOffer(waitForOffer(t, told), true) { + t.Fatal("the offer was gone before it was answered") + } + } + if tokens := <-answers; tokens != 24 { + t.Fatalf("the answer is %d tokens, want the rescuer's 24", tokens) + } + if got := report.Action(); got != scenario.act { + t.Fatalf("the wait was answered with %q, want %q", got, scenario.act) + } + if _, asked := told.find(PhaseAsking); asked != scenario.asked { + t.Fatalf("a question was raised: %v, want %v — %v", asked, scenario.asked, told.story()) + } + if got := rig.server.Requests("B"); got != 1 { + t.Fatalf("Requests(B) = %d, want the one rescue this scenario is about", got) + } + }) + } +} + +// TestADemandedPrimaryWalksOffAFaultThatBreaksIt is the second road out of the +// same mistake. +// +// A person's pin does not walk off a transient fault — the machine they named +// is still the machine they named, and the ladder rather than the race is what +// answers for it — and while every ordinary call read as pinned, neither did +// anything else: the primary arm stayed put with a healthy machine one line +// away. A stream that was arriving and then was not is 1,884 of the 1,887 +// in-stream failures in the census, so it is the fault this is asked about. +func TestADemandedPrimaryWalksOffAFaultThatBreaksIt(t *testing.T) { + told := listen(t) + rig := newLaneRig(t, "demand/walk", + lanestub.Lane{Name: "A", Profile: lanestub.Profile{ + TTFT: 5 * time.Millisecond, Rate: 2000, Tokens: 24, TearAfter: 4, + }}, + lanestub.Lane{Name: "B", Profile: lanestub.Profile{ + TTFT: 5 * time.Millisecond, Rate: 2000, Tokens: 24, + }}, + ) + rig.believes("A", 20, 2000) + + ctx := WithLaneChoice(context.Background(), demandedChoice(rig.model)) + response, err := rig.client.CompleteWithMessages(ctx, userMessages("hello")) + if err != nil { + t.Fatalf("a broken stream on one of two demanded machines ended the call: %v", err) + } + if tokens := answerTokens(response); tokens != 24 { + t.Fatalf("the answer is %d tokens, want the whole answer from the machine that walked on", tokens) + } + if got := rig.server.Requests("B"); got == 0 { + t.Fatal("the broken machine was never left, so the demand was read as somebody's pin") + } + if _, asked := told.find(PhaseAsking); asked { + t.Fatalf("a machine nobody pinned was asked about: %v", told.story()) + } +} + // composedFor is the object one request would actually go out with. func composedFor(t *testing.T, client *Client, model string, knobs callKnobs) *providerPrefs { t.Helper() diff --git a/internal/provider/lane_law_test.go b/internal/provider/lane_law_test.go index 5e0bfdd2bc..ea0f7fccc0 100644 --- a/internal/provider/lane_law_test.go +++ b/internal/provider/lane_law_test.go @@ -142,3 +142,102 @@ func TestOnlyOneFunctionDrawsACallsLane(t *testing.T) { } } } + +// ── A PIN IS A PERSON'S WORD, AND IT IS NEVER COUNTED ─────────────────────── +// +// `Only` carries two different facts that look identical on the wire: the set +// this process admitted, which is ours to relax the moment it stops working, +// and the one machine somebody typed, which is not. [control.Plan.Pinned] is +// what tells the build which it is holding, and everything it changes is +// person-facing: a stall on a pinned machine becomes `switch to auto? (y)` +// instead of a rescue, and the primary arm stops walking off a transient fault. +// +// It was `len(choice.Only) > 0` until the chooser began demanding its own +// admitted set, at which point that sentence made every ordinary call pinned — +// the question asked about machines nobody chose, and no rescue sent. So the +// law: a pin may be WRITTEN only where a person's own row is read, and may +// never be DERIVED from a list of names. + +// pinsACall is who may put a pin on a choice or a plan. Clearing one is not on +// this list and needs no permission: a rescue's own arm and a reconnection are +// both this process's doing, and neither of them is anybody's instruction. +var pinsACall = map[string]string{ + // THE ONE READING OF A PERSON'S ROW (lanepin.go's lanePinFor), which is the + // only place in this build that knows a machine was named by hand. + "drawLaneChoice": "reads the person's own row", + // AND THE ONE PLACE THE PLAN IS BUILT, which copies the choice's own word + // across rather than inferring one. + "planFor": "copies the choice's word onto the plan", +} + +// TestOnlyAPersonsOwnRowPinsACall is that law. +func TestOnlyAPersonsOwnRowPinsACall(t *testing.T) { + written := map[string]bool{} + for name, file := range providerSources(t) { + for _, decl := range file.Decls { + function, ok := decl.(*ast.FuncDecl) + if !ok { + continue + } + ast.Inspect(function, func(node ast.Node) bool { + value, where := pinWrite(node) + if value == nil { + return true + } + // Clearing a pin is always allowed: see above. + if ident, ok := value.(*ast.Ident); ok && ident.Name == "false" { + return true + } + if _, allowed := pinsACall[function.Name.Name]; !allowed { + t.Errorf("%s: %s pins a call at %s — a pin is a PERSON's one machine, written where "+ + "their own row is read and nowhere else. A request that merely names machines is "+ + "a demand, and a demand is ours to relax", name, function.Name.Name, where) + return true + } + if namesTheDemand(value) { + t.Errorf("%s: %s derives a pin from `Only` — that field now carries the chooser's own "+ + "admitted set as well as a person's pin, so counting it pins everybody", name, function.Name.Name) + } + written[function.Name.Name] = true + return true + }) + } + } + for name := range pinsACall { + if !written[name] { + t.Errorf("%s is permitted to pin a call and no longer does — delete the line rather than "+ + "leaving a permission nobody uses", name) + } + } +} + +// pinWrite is the value being written to a `Pinned` field, or nil. +func pinWrite(node ast.Node) (ast.Expr, string) { + switch written := node.(type) { + case *ast.AssignStmt: + for index, target := range written.Lhs { + selector, ok := target.(*ast.SelectorExpr) + if !ok || selector.Sel.Name != "Pinned" || index >= len(written.Rhs) { + continue + } + return written.Rhs[index], "an assignment" + } + case *ast.KeyValueExpr: + if key, ok := written.Key.(*ast.Ident); ok && key.Name == "Pinned" { + return written.Value, "a literal" + } + } + return nil, "" +} + +// namesTheDemand reports whether an expression reads the demanded set. +func namesTheDemand(value ast.Expr) bool { + found := false + ast.Inspect(value, func(node ast.Node) bool { + if ident, ok := node.(*ast.Ident); ok && ident.Name == "Only" { + found = true + } + return !found + }) + return found +} diff --git a/internal/provider/lanepin.go b/internal/provider/lanepin.go index 96a7ff45d5..f5b5d45354 100644 --- a/internal/provider/lanepin.go +++ b/internal/provider/lanepin.go @@ -313,7 +313,7 @@ func pinRetired(lane, model string) bool { // questions, a pin that moved between them let one request go out demanding the // machine the person had just stopped asking for — the row read under the first // lock and the retirement under the second belonging to two different rows. The -// pair is one fact about one moment (lanes.go's [Client.laneChoiceFor]). +// pair is one fact about one moment (lanes.go's [Client.drawLaneChoice]). func lanePinFor(model string) (LanePin, bool) { // THE MODEL IS FOLDED BEFORE THE LOCK IS TAKEN and the lane half of the key // is read under it, which is what makes this one read rather than two: diff --git a/internal/provider/lanes.go b/internal/provider/lanes.go index e980ba6cce..e2bf54ef96 100644 --- a/internal/provider/lanes.go +++ b/internal/provider/lanes.go @@ -524,7 +524,13 @@ func (c *Client) drawLaneChoice(knobs callKnobs, model string, request *ai.Reque } if named != "" && !pin.Borrow { // The candidate set survives and the ranking does not: see above. - return lanes.Choice{Only: []string{named}, Frontier: choice.Frontier}, true + // + // AND THIS IS THE ONE PLACE `Pinned` IS WRITTEN, because this is the one + // place that knows a PERSON named the machine. Every other call demands a + // set too ([lane.demandOf]), and a set we admitted is ours to relax while + // a machine somebody typed is not: the difference decides whether a stall + // is rescued or asked about ([control.Plan.Pinned]). + return lanes.Choice{Only: []string{named}, Frontier: choice.Frontier, Pinned: true}, true } // AND A PIN THAT MAY BE BORROWED IS A PREFERENCE, so it goes in front of // the belief's own ranking rather than replacing it: the named machine is diff --git a/internal/provider/offer_test.go b/internal/provider/offer_test.go index b749e71f06..be4e07eac6 100644 --- a/internal/provider/offer_test.go +++ b/internal/provider/offer_test.go @@ -29,9 +29,14 @@ import ( // nowhere for a `y` to go — the request would report the wait and nothing else. // That is a fact about `internal/lane`'s chooser rather than about this file, // and it is why the pin's own row is written with both. +// AND IT SAYS SO IN THE FIELD THAT MEANS IT. `Only` is what a demand and a pin +// have in common — every routed call demands the set the chooser admitted — and +// [lanes.Choice.Pinned] is what only a pin has: a person's own word, which is +// what turns the act from a rescue into a question. func pinnedChoice(model, pin string, alternatives ...string) lanes.Choice { choice := lanes.Choice{ Only: []string{pin}, + Pinned: true, Frontier: []lanes.Scored{{ID: lanes.ID{Model: model, Lane: pin}, TTFT: 2, Rate: 2000, Price: 0.01}}, } for _, lane := range alternatives { diff --git a/internal/provider/onechoice_test.go b/internal/provider/onechoice_test.go index 35d5fd1113..39e8d262f1 100644 --- a/internal/provider/onechoice_test.go +++ b/internal/provider/onechoice_test.go @@ -58,6 +58,16 @@ func (l *movingLedger) warmUp() { l.warm = true } +// warmed is the same field read the same way it is written. A scenario asks it +// after the call has ended, but the transport that warmed it ran on another +// goroutine, so an unguarded read here is a data race the detector is right +// about however settled the value looks. +func (l *movingLedger) warmed() bool { + l.mu.Lock() + defer l.mu.Unlock() + return l.warm +} + func (l *movingLedger) held() []lanes.Belief { l.mu.Lock() defer l.mu.Unlock() @@ -159,6 +169,15 @@ func (w warmingTransport) RoundTrip(request *http.Request) (*http.Response, erro // namesTheSameMachines reports whether every body of one call asked for the same // set of machines. It is the whole assertion of this file, said once. +// +// IT IS ABOUT THE BODIES THE PRIMARY SENDS, and both scenarios here have only a +// primary: a cold choice names no alternative, and the warm one cannot walk +// because nothing serves this model on a sheet the rig never publishes. A RESCUE +// ARM IS A DELIBERATE EXCEPTION to "one call, one set" — [hedgePreference] +// rewrites an arm's body to `Only=[its own lane]`, because an arm IS the machine +// it demanded — so if an arm ever fired here this would fail for a correct +// reason. The single arm is staged by omission rather than by construction, and +// saying so is cheaper than a scenario that guarantees it. func namesTheSameMachines(t *testing.T, asks []lanestub.Ask) { t.Helper() if len(asks) < 2 { @@ -202,7 +221,7 @@ func TestOneCallAsksForOneSetOfMachinesHoweverOftenItIsEncoded(t *testing.T) { if _, err := client.CompleteWithMessages(context.Background(), userMessages("hello")); err == nil { t.Fatal("three machines answering 500 produced an answer") } - if !ledger.warm { + if !ledger.warmed() { t.Fatal("the belief never warmed, so this scenario staged nothing") } namesTheSameMachines(t, server.Asks()) @@ -250,7 +269,7 @@ func TestTheRawStreamDoorAlsoDecidesItsLaneOnce(t *testing.T) { } } } - if !ledger.warm { + if !ledger.warmed() { t.Fatal("the belief never warmed, so this scenario staged nothing") } namesTheSameMachines(t, server.Asks()) diff --git a/internal/provider/routing_audit_test.go b/internal/provider/routing_audit_test.go index 30f8ed8752..013aba38f6 100644 --- a/internal/provider/routing_audit_test.go +++ b/internal/provider/routing_audit_test.go @@ -118,7 +118,11 @@ func TestStrictPinDoesNotWalkToAnotherEndpointAfterTransportFailure(t *testing.T answering(reply{status: 503, body: `{"error":{"message":"temporarily unavailable","metadata":{"provider_name":"A"}}}`})) client.wait = func(context.Context, time.Duration) error { return nil } choice := choiceFor(client.config.Model, time.Second) - choice.Only, choice.Order = []string{"A"}, nil + // A STRICT PIN IS THE PERSON'S OWN WORD AND IT SAYS SO. `Only` alone is what + // every routed call now carries — the set the chooser admitted, which this + // build may leave the moment it stops working — so the scenario has to state + // the fact it is about rather than leave it to be inferred from one name. + choice.Only, choice.Order, choice.Pinned = []string{"A"}, nil, true ctx := WithLaneChoice(WithStreamObserver(talking(), func(StreamEvent) {}), choice) if _, err := client.CompleteWithMessages(ctx, userMessages("hello")); err == nil { t.Fatal("the only permitted endpoint failed but the request succeeded") diff --git a/internal/provider/velocity.go b/internal/provider/velocity.go index fc7a4a17e2..640c945fe0 100644 --- a/internal/provider/velocity.go +++ b/internal/provider/velocity.go @@ -1241,7 +1241,7 @@ func (c *Client) refuseUpstream(request *ai.Request, knobs callKnobs, err error, // CONFIGURED. A base that is not a router gets a ledger with one row in it, not // no ledger. Nothing reaches the wire that was not already allowed to: // [Client.providerPreferences] returns nil for `routing off` and for a base that -// does not carry a preference, and [Client.laneChoiceFor] answers no choice for +// does not carry a preference, and [Client.drawLaneChoice] answers no choice for // the first — so the reading is kept and the steering is not. What it buys is // that a refusal is still a fact anybody can act on: the retry loop's own // exclusions, the stream cut's [StreamCut.Rerouted], the wall, the frontier. diff --git a/internal/provider/waiting_law_test.go b/internal/provider/waiting_law_test.go index 09e55b5f8e..f0691fde58 100644 --- a/internal/provider/waiting_law_test.go +++ b/internal/provider/waiting_law_test.go @@ -212,7 +212,11 @@ func TestAPinnedLaneCanRaiseAnOffer(t *testing.T) { // is a question nobody can answer — and the request would then report the // wait and leave a person watching a machine they chose go quiet. plan := lanes.PlanFor(choice, lanes.Pace{}, lanes.RoleTalk, time.Now()) - plan.Pinned = len(choice.Only) > 0 + // AND THE PLAN READS THE CHOICE'S OWN WORD FOR IT, exactly as `planFor` + // does. Counting `Only` here would be a second idea of what a pin is, and + // since the chooser began demanding its admitted set it would be the wrong + // one: every ordinary call would read as pinned. + plan.Pinned = choice.Pinned if !plan.Pinned { t.Fatal("a strict pin did not read as pinned, so a stall would rescue away from a machine a person named") } diff --git a/internal/provider/waitplan.go b/internal/provider/waitplan.go index 2c437aa412..607e49de78 100644 --- a/internal/provider/waitplan.go +++ b/internal/provider/waitplan.go @@ -46,14 +46,22 @@ func (c *Client) planFor(ctx context.Context, choice lanes.Choice, model string, plan := lanes.PlanFor(choice, lanes.PaceFor(lanes.ID{Model: model, Lane: lanes.HeadOf(choice)}, now), RoleFrom(ctx), now) // ── and then the four things only the transport knows // - // A STRICT PIN IS WHAT `Only` MEANS: the person named the machine, so the - // act is a question rather than a rescue (offer.go). How long the answer will - // be is the caller's own hint, and it is what makes the commitment half of the - // inequality computable. And how long this model deliberates is a fact about - // the model and the rung it was asked at, which is a knob only this layer - // resolves. THE PURSE IS NOT AMONG THEM ANY MORE: it is the plan's own budget - // and `lane.PlanFor` fills it in, which is why nothing here names money. - plan.Pinned = len(choice.Only) > 0 + // A PIN IS WHAT THE CHOICE SAYS IT IS, AND NEVER THE LENGTH OF `Only`: the + // person named the machine, so the act is a question rather than a rescue + // (offer.go). This line counted `Only` until 2026-09-11, which was the same + // sentence for exactly as long as a demand and a pin were the same field. + // Once the chooser began demanding the set it admitted ([lane.demandOf]), + // counting would have called ordinary traffic pinned — the hazard's `Ask` + // road instead of a hedge, `switch to auto?` about a machine nobody chose, + // and no rescue sent at all. A pin is a person's word and a demand is our + // own admitted set; [lane.Choice.Pinned] carries the first and `Only` the + // second. How long the answer will be is the caller's own hint, and it is + // what makes the commitment half of the inequality computable. And how long + // this model deliberates is a fact about the model and the rung it was asked + // at, which is a knob only this layer resolves. THE PURSE IS NOT AMONG THEM + // ANY MORE: it is the plan's own budget and `lane.PlanFor` fills it in, + // which is why nothing here names money. + plan.Pinned = choice.Pinned plan.Expected = expected // AND A PERSON MAY TURN RESCUING OFF OUTRIGHT (lanepin.go's [SetLaneGuard]). // It is the one thing about a plan that is neither a belief nor a role, so it From d5da8ea8b25f5216d1076044c0e9447d07b46608 Mon Sep 17 00:00:00 2001 From: santoshkumarradha Date: Fri, 11 Sep 2026 18:55:02 -0400 Subject: [PATCH 5/5] docs: the census column changed meaning, and the entry now says so MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `calllog.Record.Lane` is one name — documented as the first entry of `provider.order` — and the census family built on it reads `served != asked` as "the router went somewhere we did not choose". A demand names a SET the router may not leave while choosing which member of it serves, so the field now records the HEAD of that set and the column means "the router picked a different machine from the one we ranked first, inside the set we chose". It reads 96%/90% on dev and 42%/26% here on the same rig, while every person-visible figure improved, so anybody reading the old column will read an improvement as a regression. The entry says that outright and points at issue #969, which is the one field that makes the family readable again: the demanded set beside the name, in `internal/calllog`'s `Record` and `internal/provider/calllog.go`. Docs only — one markdown file — so the Spark proof at 644dc4968 stands for every Go package. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01FSshDkszBQ9RpR4dPsC5fQ --- docs/changes/unreleased/937-chooser-demands.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/changes/unreleased/937-chooser-demands.md b/docs/changes/unreleased/937-chooser-demands.md index 7fbc39f8f1..7de6fb6318 100644 --- a/docs/changes/unreleased/937-chooser-demands.md +++ b/docs/changes/unreleased/937-chooser-demands.md @@ -9,11 +9,12 @@ invalidates: - "A demand rode alone: the sort word, the ledger's order and the price ceiling all came off and the object returned. The ranking now travels INSIDE the demand (`order` says in what sequence, `only` says which machines), a borrowable lane pin joins the set instead of leading an order the same object forbids, and the affinity cache pin yields to a machine outside the admitted set exactly as it already yielded to a refused one." - "`keepingServable` narrowed a demand only while two names were left, so a demand down to its last machine was left as it stood — which asked the router to serve the request from the machine that had just refused it, while `allow_fallbacks: false` forbade it the healthy machine it would otherwise have found. `dropRefusedHere` now asks HOW WIDE the demand is, through `demandedLane` — the same door #925's veto-law exemption reads and the same reading `requestSet` confines the plan to: a request that demanded ONE machine (a person's pin, a rescue's arm) is left exactly as it stands, and the belief's wider demand is struck like the ranking and dropped entirely when every name has gone, with `allow_fallbacks` restored. `keepingServable` is deleted." - "A PIN AND A DEMAND WERE THE SAME FACT, because `Only` only ever held a pin: `control.Plan.Pinned` was `len(choice.Only) > 0`, and everything a pin changes — the hazard answering a stall with `switch to auto? (y)` instead of a rescue, the primary arm refusing to walk off a transient fault — hung off that count. With the chooser demanding its own admitted set, counting would have made every ordinary routed call pinned. `lane.Choice.Pinned` now carries the fact, written only where a PERSON's strict row is read (`drawLaneChoice`) and read only where the plan is built (`planFor`). A demand is ours to relax; a pin is theirs to be asked about." + - "`calllog.Record.Lane` MEANT \"the machine the router was free to ignore\", and the census family built on it — `served != asked` — meant \"the router went somewhere we did not choose\". It is one name, documented as the first entry of `provider.order`; a demand names a SET, and the router must stay inside it while choosing which member serves. So the field now records the HEAD OF THE ADMITTED SET and `served != asked` means the router picked a different machine from the set we chose. The number falls — 96%/90% on dev to 42%/26% on the same rig (L3, two homes, twenty messages, reflex tier) while the whole wait p50 went 679/536 ms to 589/312 ms and the switches 41/16 to 23/14 — and anyone reading the old column will read an improvement as a regression. The row needs the demanded set beside the name before that family can be read again: issue #969, `internal/calllog`\u0027s `Record` and `internal/provider/calllog.go`." - "The chat manual said auto RANKS the machines it wants. It now says aforge names the set it will accept and closes it, what that costs when the set runs out, and that a set of one is never made this way because a set of one is a pin. The `switch to auto?` page said that question belongs to a pinned lane; it now says so explicitly, because auto asks for machines by name too and is never the subject of that question." --- -Stacked on #934, which is the seam it needs: the plan, the watch and the body -have to be looking at one set before the chooser can demand one. +#934 is the seam this needed and it is on `dev`: the plan, the watch and the +body have to be looking at one set before the chooser can demand one. Owed and stated in the pull request rather than hidden: the `PhaseNews.Lane` fill (the machine the next body will ask for is the plan's move, in a file this