@bytesbrains/cruise-worker 0.0.0-stage → 0.12.0

package/migrations/0062_gemini_embedding_disabled.sql

@@ -0,0 +1,125 @@
+-- The Google embedding row cannot serve, and the first run that could ask
+-- found out (#253, and 0060's own open question answered).
+--
+-- 0060 catalogued three embedding rows and said in as many words which part of
+-- them was unmeasured: *"`/compat` is chat-only, so an embedding request takes
+-- the gateway's provider path, which is documented for chat and implied for
+-- the rest ... the first conformance run against a held credential is the
+-- measurement."* That run happened on 2026-09-05 — dispatched, narrowed to the
+-- six image and embedding rows by #250's `--modality`, run
+-- `9031a8c6-5e62-4291-859d-f0bebedc91e4` — and the answer is:
+--
+--   openai/text-embedding-3-small   embedding_vector  pass   1536 dimensions
+--   openai/text-embedding-3-large   embedding_vector  pass   3072 dimensions
+--   google-ai-studio/gemini-embedding-001  embedding_vector  FAIL  HTTP 404
+--   google-ai-studio/gemini-embedding-001  embedding_usage   FAIL  HTTP 404
+--
+-- Two of three, and the third is the one 0060 flagged as resting on an implied
+-- behaviour rather than a documented one.
+--
+-- ## What the evidence says, and where it stops
+--
+-- **What is measured:** the OpenAI rows and the Google row take the *same*
+-- route through the *same* Worker code — `providerPath` in `route-run.ts`
+-- builds one URL shape for both — and one pair passes while the other 404s.
+-- So the embedding route, the gateway, the credential and the request body are
+-- all exonerated: whatever is wrong is specific to the `google-ai-studio` leg.
+--
+-- **What is inferred, and is not yet proven.** `providerPath` sends
+--
+--   {gateway}/v1/{account}/{gw}/{upstream}/v1/embeddings
+--
+-- so the tail `/v1/embeddings` is appended to whatever base the gateway's
+-- provider path resolves to. For OpenAI that lands on `api.openai.com/v1/
+-- embeddings`, which is the real endpoint. Google's OpenAI-compatible
+-- embeddings endpoint is **not** at `/v1/embeddings` — the compatibility layer
+-- 0060 cited (https://ai.google.dev/gemini-api/docs/openai) is published under
+-- `/v1beta/openai/`, and `/v1/embeddings` on `generativelanguage.googleapis.com`
+-- is not a path that exists. A 404 is exactly what that mismatch produces, and
+-- exactly what we got.
+--
+-- That is a hypothesis with the right shape, not a finding. **What would settle
+-- it** is reading the response body rather than its status: the run recorded
+-- `detail` as empty, so nobody has yet seen whether the 404 came from Google
+-- naming an unknown path or from the gateway naming an unknown model. Worth
+-- fixing in the runner before the next such introduction — a status code alone
+-- could not distinguish these two, and both were live possibilities here.
+--
+-- ## Why disabled rather than fixed here
+--
+-- If the inference is right the fix is a URL, and 0060 already named the shape
+-- it would take: *"the fallback, as before, is a `base_url` on the upstream row
+-- rather than code."* But `base_url` is per **upstream**, not per route, and
+-- `isDirect` reads it for every modality — so setting one on `google-ai-studio`
+-- would also take Google's five **chat** rows off `/compat` and send them
+-- direct. Those rows serve today. A migration that fixes an embedding row by
+-- moving working chat traffic onto an untested path is not a fix, it is a
+-- larger change wearing one's clothes, and it needs its own measurement.
+--
+-- So: the row is disabled, the reason is written down, and the repair is #253's
+-- to make deliberately.
+--
+-- ## Disabled, never deleted
+--
+-- The usual reason, and one more. `price_observations` carries the row's
+-- 2026-09-05 first observation and `conformance_results` carries the two
+-- failures; both reference this id and must outlive it. And the failure is the
+-- most useful thing we know about this model — deleting the row would delete
+-- the record that we tried.
+--
+-- ## This is also the record of a change already made by hand
+--
+-- Production was updated directly on 2026-09-05, minutes after the run, to stop
+-- an unservable model being routable. This migration is that same change made
+-- durable: it is why the production database already reads `enabled = 0`, and
+-- it is what brings staging — where the row is enabled and has never been
+-- measured, so harmless but drifting — back into agreement.
+
+-- ## Two flags, because one of them is a false statement
+--
+-- `enabled = 0` is the decision: this row does not serve, so stop offering it.
+--
+-- Clearing the measurement is not a second decision, it is a correction. The
+-- row asserted `measured_at = 2026-09-05` for a model that answered 404 to
+-- every check that day — and `measured_at` is not a log of when somebody
+-- looked, it is the **input to the gate**. `verificationOf` reads it and
+-- `listRoutableModels` serves anything it calls verified, so the row as it
+-- stood was one `enabled = 1` away from routing again, with nothing in it
+-- saying why that would be wrong. A person re-enabling it — a migration, a
+-- console, the same hand-run UPDATE that disabled it — would get a model the
+-- gate believes in.
+--
+-- The first draft of this migration left the date, arguing it was evidence of
+-- how it got there. That was wrong twice. The evidence is in
+-- `conformance_results`, which keeps both failures and is untouched here, and
+-- in this file. And #253 argues in as many words that a model whose every
+-- check failed should read *unmeasured*, so that the existing
+-- `model_unmeasured` refusal names the real situation. Writing the opposite
+-- into the first migration after saying so was an inconsistency, and review of
+-- PR #255 caught it.
+--
+-- What this does **not** do is answer #253. That is the general rule — should
+-- a run ever stamp a model whose every check failed — and it belongs in the
+-- runner, where the next such model will not have somebody watching. This
+-- corrects one row.
+
+UPDATE models
+   SET enabled            = 0,
+       measured_at        = NULL,
+       measured_by        = NULL,
+       measurement_source = NULL
+ WHERE id = 'google-ai-studio/gemini-embedding-001';
+
+-- ## What does not change
+--
+-- **The price row.** $0.15 per 1M input tokens is still what Google charges; a
+-- model we cannot reach is not a model that became free, and
+-- `price_observations` is append-only besides.
+--
+-- **`conformance_results`.** Both 404s stay. They are the reason this migration
+-- exists and the only record of what was actually observed.
+--
+-- **The capability flags** (`usage_reported = 0` and the rest). They are
+-- derived from the failures and mean nothing now that the row is unmeasured —
+-- the gate stops at `measured_at` before it reads them — but rewriting them
+-- would assert a second thing nobody checked.

package/migrations/0063_google_provider_path_prefix.sql

@@ -0,0 +1,59 @@
+-- The Google embedding row can serve after all; the path was ours (#253).
+--
+-- 0062 disabled `google-ai-studio/gemini-embedding-001` after both of its
+-- checks answered HTTP 404, and inferred — carefully labelled as inference —
+-- that the fault was the URL: Google's OpenAI-compatible endpoints live under
+-- `/v1beta/openai/`, and the provider-path leg was sending something else.
+-- The run's own record could not confirm it, because the 404 carried no body.
+--
+-- ## Measured, 2026-09-05
+--
+-- Three requests through the staging gateway, with the gateway token and a
+-- Google key, sent by hand:
+--
+--   /google-ai-studio/embeddings                          404, empty body,
+--                                                         content-type text/html,
+--                                                         server-timing gfet4t7
+--   /google-ai-studio/v1beta/openai/embeddings            200, a 3072-value vector
+--   /google-ai-studio/v1beta/models/…:embedContent        401 (a bearer header
+--                                                         Google's native API rejects;
+--                                                         irrelevant, and not pursued)
+--
+-- `gfet4t7` is Google's front end. So the gateway forwards whatever path it is
+-- given after the provider segment, Google answered the first with an empty
+-- 404 for a path it does not serve, and the second is the path. 0062's
+-- inference was right about the shape and wrong about one detail: the leg
+-- appends `/embeddings`, not `/v1/embeddings` — `providerPath` in
+-- `route-run.ts` adds no version segment of its own — and for OpenAI that is
+-- correct because the gateway's `openai` provider supplies `/v1` itself.
+-- Google's provider supplies nothing, and Google needs `/v1beta/openai`.
+--
+-- ## A column, not a base_url, and not code
+--
+-- 0060 named `base_url` as the fallback, and PR #255 explained why it is not
+-- one: `base_url` is per upstream and makes every route to it direct,
+-- including the five chat rows that serve today over `/compat`. What differs
+-- here is narrower — the gateway leg is fine, only the path under the
+-- provider segment is Google's rather than OpenAI's — and it is a fact about
+-- the upstream, like `kind` and `base_url` beside it. So it is a column the
+-- Worker reads, not a branch on the upstream id in `providerPath`, which would
+-- be the second place after `speech-elevenlabs.ts` that a host's shape lives
+-- in code, and this one need not.
+--
+-- Chat is unaffected: `chat.ts` builds `/compat/chat/completions` and never
+-- reads this. NULL for every other upstream, which is the value that means
+-- "append the OpenAI-shaped path as before" and is what every measured row
+-- was measured against.
+ALTER TABLE upstreams ADD COLUMN provider_path_prefix TEXT;
+
+UPDATE upstreams SET provider_path_prefix = '/v1beta/openai' WHERE id = 'google-ai-studio';
+
+-- ## Re-enabled, still unmeasured
+--
+-- The reason 0062 gave for disabling is gone, so the row is offered to the
+-- conformance run again. `measured_at` stays NULL: this migration measured a
+-- URL by hand, not the model through Cruise, and the gate refuses an unmeasured
+-- row whichever order this and the Worker deploy land in. If the run reaches
+-- it before the deploy, it 404s again and `foldFlags` clears it with a note
+-- (#253); after, it measures. Neither order routes traffic to a 404.
+UPDATE models SET enabled = 1 WHERE id = 'google-ai-studio/gemini-embedding-001';

package/migrations/0064_economics_service_keys.sql

@@ -0,0 +1,51 @@
+-- A service key that can read the platform's books and do nothing else (#249).
+--
+-- The gap: every route carrying a cost or revenue figure is scoped to the
+-- caller's own tenant and opened by a Firebase token — a person in a
+-- browser. `/admin/billing/statement` answers what one tenant was charged;
+-- nothing answers what the platform's traffic cost at list, what it charged
+-- for that traffic, and what it kept, across every tenant. The dashboard's
+-- operator screen was asking, and there is also no route that lists tenants,
+-- so it could not fan out either: it would have to already know every id.
+--
+-- `purpose` gains a fifth value on 0038's terms: one capability per key,
+-- issued for one value and never two. `economics` reads one month's totals,
+-- by upstream and by charge line, and has no other route. It mints nothing,
+-- creates nothing, changes no tier, and reads no wallet.
+--
+-- Why not the `balance` key, which also only reads. 0038 and the wallet
+-- route both go to some length to make "no list of every tenant's balance"
+-- mean something — one tenant per call, and a tenant that is not there
+-- answers like one with no wallet, so a leaked sweep key cannot harvest the
+-- platform's books one id at a time. Opening a platform-wide read to that
+-- key would hand it exactly the aggregate that discipline withholds. And the
+-- figure this route carries that no other does is the **cost basis** — what
+-- the platform pays upstream — which the issue names as commercial posture,
+-- the same reason `/admin/upstreams` refuses a customer who is `owner` of
+-- their own workspace. The holder of an `economics` key is an operator
+-- screen; the holder of a `balance` key is a sweep. Different consumers,
+-- different keys.
+--
+-- SQLite cannot widen a CHECK in place, so the table is rebuilt, and 0038's,
+-- 0042's and 0054's note on why that is safe applies unchanged: the name and
+-- every column stay identical, so code deployed before this migration and
+-- code deployed after read exactly the same shape. Widening is the safe
+-- direction on its own — no existing row can fail the new CHECK, and a Worker
+-- deployed before this simply never matches an `economics` row, because
+-- `authenticate` names the purposes it will accept in the lookup itself.
+CREATE TABLE service_keys_new (
+  id         TEXT PRIMARY KEY,
+  prefix     TEXT NOT NULL UNIQUE,
+  key_hash   TEXT NOT NULL,
+  purpose    TEXT NOT NULL CHECK (purpose IN ('credits', 'balance', 'provision', 'tier', 'economics')),
+  created_by TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  revoked_at TEXT,
+  last_used_at TEXT
+);
+
+INSERT INTO service_keys_new (id, prefix, key_hash, purpose, created_by, created_at, revoked_at, last_used_at)
+SELECT id, prefix, key_hash, purpose, created_by, created_at, revoked_at, last_used_at FROM service_keys;
+
+DROP TABLE service_keys;
+ALTER TABLE service_keys_new RENAME TO service_keys;

package/migrations/0065_lane_selection.sql

@@ -0,0 +1,66 @@
+-- How a lane chooses among the members that passed its gates (#202).
+--
+-- Since 0026 there has been exactly one rule — cheapest first — and it was
+-- not a setting, it was `allocate()`. That rule is right for a bill and wrong
+-- for learning: #19 built cost per *completed* request from the ledger, the
+-- number lanes should rank on, and found `qwen3.8-27b` completing 28% of its
+-- requests while winning on price. That number exists only for members that
+-- got traffic, and the cheapest member gets essentially all of it, so every
+-- other member's completion rate is measured on whatever trickle reached it
+-- through a rate-limit cooldown. Price-first allocation biases the ledger
+-- against ever learning anything else.
+--
+-- So a lane carries a **selection policy**, and a request may override it
+-- (`x-cruise-selection`). Three values:
+--
+--   cheap     what every lane has always done, byte for byte. The default.
+--   random    uniform over the eligible members.
+--   weighted  by each member's `weight`, renormalised over the eligible
+--             members per request, so a member a gate rejected has its share
+--             redistributed rather than leaving a chance of choosing nothing.
+--
+-- `random` and `weighted` are exploration policies, not toys: a lane running
+-- 90/10 in favour of its cheapest member still learns something about the
+-- other members every day, and 0027 already records what each of them would
+-- have cost, so the cost half of the comparison is free. Only traffic produces
+-- the behaviour half.
+--
+-- **Whatever the policy, it chooses among the survivors of the hard gates and
+-- never around them.** Scope, measurement, the lane's own requirements, the
+-- request's capabilities, the limits, billing: a `random` that could return a
+-- member failing `no-training-on-data` would turn a privacy gate into a coin
+-- flip. The policy decides which passing member goes *first*; the rest follow
+-- cheapest-first, as the fallback chain always has.
+--
+-- One member the draw leaves out that the gates let through: a member the
+-- provider rate-limited in the last few minutes, while anything else is in
+-- the pool. The allocator ranks it last because the next request very likely
+-- gets a 429 too, and a draw that picked it would spend an upstream deadline
+-- learning nothing. So `random` is uniform over the survivors that are not
+-- cooling down, and a 90/10 lane drifts from 90/10 while one is. A member
+-- merely failing stays in — exploration is what finds out whether it still
+-- is (`src/lanes-select.ts`).
+--
+-- The weight is REAL, and that is not the money rule slipping. A weight is not
+-- a quantity of anything — it is a ratio the request normalises before use,
+-- and `[0.2, 0.1, 0.5, 0.25, 0.4]` (which the issue says sums to 1.55 and in
+-- fact sums to 1.45 — either way not one, which is why these are weights and
+-- not probabilities) has to read back as written. An integer
+-- scale would round what the operator typed. Positive, because a member that
+-- may never be chosen is a member that should not be in the lane; the write
+-- refuses zero and negative before the CHECK does.
+--
+-- The ledger says which policy ran, per request (NULL for a pinned model). A
+-- random choice is not reproducible, so a month under `weighted` would be
+-- unexplainable without it, and 0027's counterfactual could not be read: the
+-- served member is `model`, the chosen one is `lane_alternatives` at position
+-- 1, and they differ only when the chain fell over. Cheap now, archaeology
+-- later — 0048's argument about prices.
+
+ALTER TABLE lanes ADD COLUMN selection TEXT NOT NULL DEFAULT 'cheap'
+  CHECK (selection IN ('cheap', 'random', 'weighted'));
+
+ALTER TABLE lane_members ADD COLUMN weight REAL NOT NULL DEFAULT 1 CHECK (weight > 0);
+
+ALTER TABLE ledger ADD COLUMN selection TEXT
+  CHECK (selection IS NULL OR selection IN ('cheap', 'random', 'weighted'));

package/migrations/0066_tenant_default_selection.sql

@@ -0,0 +1,42 @@
+-- A tenant's own default selection policy, and the first column on `tenants`
+-- that belongs to the tenant rather than to us (#288).
+--
+-- 0065 gave a lane a selection policy and defaulted it to `cheap`. That
+-- default is a module constant — `DEFAULT_SELECTION` in `src/lanes-select.ts`
+-- — so a tenant whose posture is exploration has to remember `selection` on
+-- every create, and forgetting is silent: the lane serves cheapest-first and
+-- looks exactly like a lane that meant to. The question that produced this was
+-- a dashboard one, and the answer to most of it was "already works": a tenant
+-- can hold `acme/review-cheap` and `acme/review-weighted` side by side today,
+-- because only the lane *id* is unique and `job` is not, and each is listed by
+-- `/v1/models` as its own model id. The default was the piece with nowhere to
+-- live.
+--
+-- **Nullable, and NULL means "no preference".** Not `NOT NULL DEFAULT 'cheap'`
+-- like the lane column: there the value is a fact about that lane, here the
+-- absence is the fact — a tenant that has never expressed a posture is a
+-- different thing from one that chose `cheap`, and only the first should start
+-- following a changed platform default. It also needs no backfill, and the
+-- read resolves NULL the way `tierOf` resolves an unknown tier: to the
+-- platform value, failing closed on the behaviour every lane had before #202.
+--
+-- **Consulted at create, never at allocation.** `createLane` reads this once
+-- and writes a concrete value into `lanes.selection`; nothing on the request
+-- path looks here. Resolving it per request would mean changing this column
+-- silently repoints every lane that never named a policy — lanes made years
+-- apart, for unrelated reasons — and the ledger's own `selection` column, the
+-- one that exists so a month under `weighted` can be explained at all, would
+-- stop agreeing with the lane it describes. The audit row for `lane.create`
+-- already records the policy, so the receipt says what a lane became and when.
+--
+-- **`weights` deliberately gets no equivalent.** A weight belongs to a member
+-- list — one per member, in the members' order — so a tenant-wide default
+-- weight is a number with nothing to attach to. `selection` is the half of the
+-- pair that is a posture rather than a shape.
+--
+-- The CHECK repeats 0065's three values rather than referencing them, for the
+-- same reason 0065 did: SQLite has no enum, and a policy this column allowed
+-- that `parseSelection` rejects would be a row nothing can serve.
+
+ALTER TABLE tenants ADD COLUMN default_selection TEXT
+  CHECK (default_selection IS NULL OR default_selection IN ('cheap', 'random', 'weighted'));

package/migrations/0067_graduated_selection.sql

@@ -0,0 +1,103 @@
+-- A fourth selection policy: `graduated`, which works its own weights out (#290).
+--
+-- `weighted` (0065) draws by weight and the weights are typed in by hand. That
+-- is workable for `[0.9, 0.1]` on two members and unusable for eight — the
+-- operator invents eight numbers, keeps them in the members' order, and redoes
+-- them whenever the membership changes. So a lane that wants exploration in
+-- practice gets `random`, which spends as much on the dearest member as on the
+-- cheapest, or gets nothing. `graduated` derives each member's share from its
+-- rank, so the best-ranked serves most requests, each next one fewer, and none
+-- serves none.
+--
+-- The reason to want it is 0065's own argument with #19's evidence: cost per
+-- *completed* request is what a lane should rank on, and it exists only for
+-- members that got traffic. Under `cheap` the cheapest member takes nearly
+-- every request, so every other member's completion rate is measured on a
+-- trickle. `random` fixes the learning and breaks the bill; this fixes both.
+--
+-- **Harmonic, 1 / (rank + 1), not a halving.** The obvious reading of "80-20"
+-- is geometric decay, and it starves the tail at the sizes the tiers allow
+-- (0034: Core 8 members, Pro 20). Halving gives the twentieth member 0.0001%
+-- of traffic — against the 3,997 ledger rows production held when this was
+-- written, zero requests — while harmonic gives it 1.4%, about 56. A member
+-- seen sixteen times has no usable completion rate either, so geometric would
+-- fail this policy's own purpose while appearing to run.
+--
+-- **Rank means the allocator's position, not a fresh price sort.**
+-- `lanes-allocate.ts` orders candidates on rate-limited, then failing, then
+-- price, so a cheap member that is failing already sinks below a dearer
+-- healthy one — the `qwen3.8-27b` case in that file's comment, 48 failures in
+-- 74 requests and winning on price. Weighting by a price sort would hand that
+-- member the largest share of the lane.
+--
+-- ── Why this adds columns instead of changing three ──────────────────────────
+--
+-- Three CHECK constraints enumerate the policies — `lanes.selection` and
+-- `ledger.selection` from 0065, `tenants.default_selection` from 0066 — and
+-- SQLite cannot alter a CHECK. Neither of the two obvious answers is safe here,
+-- and the second one is the mistake this migration was rewritten to undo.
+--
+-- **Not a table rebuild** (0028's answer), because 0050 already recorded why:
+-- D1 enforces foreign keys where SQLite does not, so `DROP TABLE tenants`
+-- fails outright while `memberships` and `projects` reference it, and
+-- `PRAGMA defer_foreign_keys` does not survive because each statement lands in
+-- its own transaction. Rebuilding the children reaches `virtual_keys` through
+-- `projects`.
+--
+-- **And not a column swap** — add, copy, drop, rename — which is what the first
+-- version of this file did. It touches no table and needs no foreign key
+-- deferred, and it is still wrong: between the `DROP` and the `RENAME` the
+-- column `selection` does not exist, and because each statement is its own
+-- transaction a request served in that gap faults on a column that is missing.
+-- The file argued the window was sub-millisecond and therefore acceptable.
+-- **That is the argument 0035 already lost.** The phase-5 deploy
+-- recorded it serving 500s "for under a minute" and a review bot's traffic
+-- landing inside — a window is not small enough until it is absent. Raised in
+-- review of PR #291, and the reviewer was right.
+--
+-- So: expand and contract. This migration only **adds**, and every column it
+-- adds is new, so no name the running Worker reads ever stops existing.
+--
+--   0067 (here)   add `*_policy` beside each old column, with the four-value
+--                 CHECK, and backfill it.
+--   deploy        the Worker reads and writes the new columns only. The old
+--                 ones keep the value they held at migration time, so a Worker
+--                 version still finishing a request reads valid data rather
+--                 than an error.
+--   0068 (later)  drop the three old columns, once no Worker reads them. That
+--                 migration removes a column nothing queries, which is the one
+--                 shape of schema change that has no window at all.
+--
+-- **The new names are permanent**, because reclaiming the old ones would mean a
+-- `RENAME` and a `RENAME` is the very gap this avoids. `selection_policy` is
+-- the better name anyway — the prose in `lanes-select.ts` has called it a
+-- selection policy since 0065, and bare `selection` never said what it held.
+--
+-- One inconsistency this accepts, deliberately: a lane created by the new
+-- Worker writes `selection_policy` and leaves the old `selection` at its
+-- DEFAULT, so a Worker version still serving mid-rollout would read `cheap`
+-- for a lane that is really `graduated`. That is a stale read for the seconds a
+-- version switch takes, not a fault, and it is the strictly better failure than
+-- the missing column it replaces. It is also why the old columns keep their
+-- values rather than being nulled.
+--
+-- **Deploy order is migrate first, then the Worker.** Adding a column is
+-- invisible to code that does not name it, so the old Worker is unaffected;
+-- new code naming a column that is not there is what would fail.
+
+-- lanes.selection_policy — what a lane is configured to do.
+ALTER TABLE lanes ADD COLUMN selection_policy TEXT NOT NULL DEFAULT 'cheap'
+  CHECK (selection_policy IN ('cheap', 'random', 'weighted', 'graduated'));
+UPDATE lanes SET selection_policy = selection;
+
+-- ledger.selection_policy — which policy actually ran, per request. NULL for a
+-- pinned model, which is why this one's CHECK admits NULL.
+ALTER TABLE ledger ADD COLUMN selection_policy TEXT
+  CHECK (selection_policy IS NULL OR selection_policy IN ('cheap', 'random', 'weighted', 'graduated'));
+UPDATE ledger SET selection_policy = selection;
+
+-- tenants.default_selection_policy — what a lane created without a policy is
+-- stamped with (0066). NULL means the tenant has never chosen.
+ALTER TABLE tenants ADD COLUMN default_selection_policy TEXT
+  CHECK (default_selection_policy IS NULL OR default_selection_policy IN ('cheap', 'random', 'weighted', 'graduated'));
+UPDATE tenants SET default_selection_policy = default_selection;

package/migrations/0068_cache_scope.sql

@@ -0,0 +1,73 @@
+-- What the cache did, kept beside what it charged (#276, epic #272).
+--
+-- #98 gave a hit a price and `cache_status` gave it a name, which was enough
+-- to bill and not enough to explain. auto-mode.md §8 is blunt about why that
+-- matters: "a router that saves 40% and cannot say why an answer changed
+-- loses to a config file", and a cache is the same router problem seen from
+-- the other side — a caller who receives a replay is entitled to know it was
+-- one, from which model, and how old. The header half of that ships in the
+-- same PR; these two columns are the half that survives the request.
+--
+-- ## `cache_scope`
+--
+-- Which scope actually served the answer: `model` today, `lane` once #278
+-- lands, NULL on every row that was not a hit and on every row written before
+-- this migration. Not derivable from anything already here — `cache_status`
+-- says an answer came from a cache and cannot say *how wide* the cache was
+-- allowed to be, and that is precisely the question the lane cache exists to
+-- make answerable. `GET /admin/ledger?by=cache_scope` groups on it and
+-- `npm run report` segments hits by it beside traffic class, never blended,
+-- for the reason #6 gives about every other rate in that report: scheduled
+-- pipelines re-run near-identical prompts by construction, so a blended
+-- figure flatters us and generalises to nobody.
+--
+-- ## `cache_origin_model_id`
+--
+-- The model whose stored answer was replayed.
+--
+-- **It equals `model` today, and that is not a reason to leave it out.** The
+-- two columns answer different questions and are only accidentally the same
+-- one. `model` is the row the bill is priced from — `accounting.ts` reads it
+-- to resolve a rate — and a hit must price from whichever model produced the
+-- usage, so the two coincide at model scope by construction. `cache_origin_
+-- model_id` is a fact about the *entry*: what the cache had. When #21 asks
+-- whether the tier rule held — "a hit may be served only from an equal-or-
+-- better model, never a worse one" — it is asking about the entry, and it is
+-- asking after the fact, of rows written by a version of the code that no
+-- longer exists. A question of that shape needs its own column, not an
+-- inference from a column chosen for another purpose.
+--
+-- The violation it makes findable: a hit row whose origin ranks below the
+-- model that would have served the request live. That is the worst failure
+-- auto-mode.md §6 names, because it is invisible to the caller — a worse
+-- answer reported as an upgrade — and the counter #281 puts on it reads this
+-- column.
+--
+-- **A foreign key, where `model` is not one.** `ledger.model` has been bare
+-- TEXT since 0014 and stays that way: it records what a request was served by
+-- at the time, and the catalogue is allowed to move underneath a historical
+-- row. The origin is different in kind — it is only ever a model this
+-- platform stored an answer from, and the analysis above is a join against
+-- `models`, so a value that joins to nothing is a row the analysis silently
+-- drops rather than one it flags. "Disable, never delete" (CLAUDE.md) is what
+-- makes the constraint affordable: a model that stops being routable keeps
+-- its row, so the reference outlives the routing.
+--
+-- Both columns are NULL for every existing row, which is correct rather than
+-- backfilled: nothing has ever been served from the Worker's cache before
+-- #275, and the gateway hits recorded under `cache_status = 'HIT'` have no
+-- scope and no known origin — they were the gateway's, keyed on a body that
+-- already carried the model. Guessing `model` into them would manufacture a
+-- fact.
+
+ALTER TABLE ledger ADD COLUMN cache_scope TEXT
+  CHECK (cache_scope IS NULL OR cache_scope IN ('model', 'lane'));
+
+ALTER TABLE ledger ADD COLUMN cache_origin_model_id TEXT REFERENCES models(id);
+
+-- The tier-rule query (#21) and the scope report both start from the hits, and
+-- the hits are a small minority of the table. Partial, so the index costs
+-- nothing on the rows that will never satisfy it.
+CREATE INDEX IF NOT EXISTS idx_ledger_cache_scope
+  ON ledger (cache_scope, at)
+  WHERE cache_scope IS NOT NULL;

package/migrations/0069_lane_cache_settings.sql

@@ -0,0 +1,50 @@
+-- A lane holds its own freshness (#277, epic #272). Spec: auto-mode.md §6.
+--
+-- "A code fix ages slowly; anything touching current events ages
+-- immediately." There is no global freshness answer, which is why the lane is
+-- the place to keep one: it is the object a customer already configures per
+-- job, by someone who knows what that job's answers are worth an hour later.
+--
+-- ## Zero is off, and every lane starts there
+--
+-- `cache_ttl_seconds` defaults to 0 and 0 means the lane caches nothing. Not
+-- a conservative default to be tuned later — the honest one. auto-mode.md §8
+-- puts it plainly: the TTL is the customer's setting, not ours, and every
+-- lever that could widen the cache to manufacture margin is either absent or
+-- not ours to pull. A default of, say, sixty seconds would be us deciding on
+-- their behalf that their answers keep, and it would apply to eight global
+-- lanes and every tenant lane already written, none of whose owners were
+-- asked.
+--
+-- ## The ceiling is thirty days, and it is the measurement window's
+--
+-- `MEASUREMENT_MAX_AGE_DAYS = 30` refuses a model measured longer ago than
+-- that, because a model changes under a fixed id and an aged measurement is
+-- unverified rather than last-known-good (`src/routing.ts`). A cached answer
+-- is the same claim in the same direction: it asserts that this model, today,
+-- would answer this way. Letting an entry outlive the measurement that says
+-- the model is still the model it was would serve an answer from a version of
+-- the model nothing has checked since. So the two horizons are the same
+-- horizon, and `CACHE_MAX_TTL_SECONDS` in `src/cache-policy.ts` holds the
+-- same figure for a pinned request, which has no lane to bound it.
+--
+-- ## `cache_scope` defaults to `model`
+--
+-- The narrow one. A lane-scoped hit crosses models within the lane and is
+-- where most of the saving is (auto-mode.md §6), and it is also where the
+-- tier rule lives — serve from a member ranking below the one that would have
+-- answered and you report an upgrade while delivering a downgrade, invisibly.
+-- That is a decision a lane's owner makes deliberately, and #278 is what
+-- makes it servable at all: until then the platform's `CACHE_MODE` caps the
+-- scope and `planCache` keys on the model regardless, so a lane set to `lane`
+-- today is served, honestly, as `model`.
+--
+-- Both columns are NOT NULL with a default, so every existing lane reads back
+-- a setting rather than a null anybody would have to interpret — and the
+-- setting it reads back is "off", which is what it has been doing all along.
+
+ALTER TABLE lanes ADD COLUMN cache_ttl_seconds INTEGER NOT NULL DEFAULT 0
+  CHECK (cache_ttl_seconds BETWEEN 0 AND 2592000);
+
+ALTER TABLE lanes ADD COLUMN cache_scope TEXT NOT NULL DEFAULT 'model'
+  CHECK (cache_scope IN ('model', 'lane'));