Auction code tour
From a standing quote to a cleared price: the five files that make the market, in reading order.
Five files turn standing quotes into a cleared price. They read best in pipeline order, which is also dependency order: each file consumes what the previous one produces, and the economic mechanism itself lives in exactly one of them.
1. quotes.ts: the book
Providers stream short-lived signed quotes (5 to 30 second TTL, refreshed every couple of seconds by the quoter sidecar) and the router matches requests against the book in memory, which is why the auction adds no round trip to the hot path. A quote is a firm commitment to serve at these prices up to the stated capacity: repricing means streaming a replacement, withdrawal means letting the TTL lapse or sending a signed cancel (replay-protected by nonce). The book also owns the router-measured TTFT statistics that feed the score. Measured-not-claimed is the anti-gaming cornerstone: a provider claiming 100 ms and delivering 900 ms watches its effective score decay within minutes.
2. routing.ts: which market
Cross-class routing picks the model class whose live market best fits the request (model: "auto", profiles, task fit). It deliberately stops there: once a class is chosen, auction.ts still selects the provider and clears the price. That separation keeps model choice and provider competition individually explainable instead of collapsing into a hidden price list.
3. auction.ts: the product
The header comment calls this file the product, and everything else plumbing. Winner selection is a scoring auction: a candidate's score is its expected cost for this request multiplied by a latency markup per unit of TTFT gap to the fastest candidate, an effective cost in USDC. The multiplicative form is load-bearing: an earlier additive score denominated the latency premium in the winner's own bid, which paid fast providers more for bidding higher. The winner is then paid second-score prices with two caps: the cheapest genuine rival's expected cost, and the routing profile's bounded service premium, rate by rate. With no genuine rival, a disclosed reserve or the winner's own ask sets the clear. The regimes and their incentive trade-offs are documented in Second-score clearing.
The file is deliberately session-blind. Its one extension seam is the cost view: a caller may substitute what a candidate would really cost for this request, and the scoring never learns why.
4. sessions.ts: the cost view in use
Sessions use that seam to price agentic continuations: the incumbent holding the KV cache is scored at its locked two-part tariff while challengers pay a full re-prefill, so routing is sticky by default yet contestable every turn. The incumbent's rates freeze for its committed session_ttl_s: repricing applies to new sessions, never captive ones, which deletes the hold-up rent a cache-holding provider could otherwise extract.
5. feedback.ts: what it took to win
The disclosure channel, modeled on ad-exchange minimum-bid-to-win: every funded auction writes the bucketed score a loser needed to beat and a loss reason (lost-on-price, lost-on-latency, filtered-*) into one append-only table. Outcomes are recorded by completions.ts at billing time, next to the usage record they describe, so the unpaid 402 pass never inflates the tape. Providers drain their rows in-band on quote-refresh acks; the same table serves GET /v1/analytics/providers/:id.
quotes_competing, and the second-score arithmetic all land on the signed usage receipt, and the receipt is what the hourly epoch anchor makes tamper-evident.- router/src/market/quotes.ts the standing-quote book and measured latency
- router/src/market/routing.ts cross-class market selection
- router/src/market/auction.ts scoring and second-score clearing
- router/src/api/sessions.ts the session cost view
- router/src/market/feedback.ts minimum-score-to-win disclosure