@bytesbrains/cruise-worker 0.0.0-stage → 0.12.1

package/migrations/0007_routing_table.sql

@@ -0,0 +1,93 @@
+-- Routing table and per-model capability flags (#2). Spec: docs/v0.md §3
+-- component 4, v0.md §4.
+--
+-- Ours to build; nothing in the platform provides it. Maps a requested model
+-- string to a gateway target plus the flags that make routing safe.
+--
+-- **Capabilities are per model, not per upstream.** v0.md §7 measured two models behind
+-- one Ollama endpoint disagreeing about tool calling: `devstral` returned proper
+-- `tool_calls`, while `qwen2.5-coder:7b` emitted the call as prose with
+-- `finish_reason: stop` and no `tool_calls` array — nothing in the response shape
+-- signalling failure. An agentic client routed to the second gets a JSON blob as
+-- text and no way to know why.
+--
+-- **Flags are three-state, and that is the load-bearing decision here.** #2 says
+-- they must be populated from the conformance suite and never hand-written, but
+-- #10 does not exist yet. So NULL means *not measured* — distinct from 0, which
+-- means measured and absent. Unknown then fails closed for anything treated as a
+-- hard gate: a request needing tools against a model whose tool support has never
+-- been measured is refused, not attempted hopefully. The alternative is a table
+-- full of optimistic guesses that reads exactly like measurement.
+
+CREATE TABLE upstreams (
+  id      TEXT PRIMARY KEY,
+  name    TEXT NOT NULL,
+  -- Whether the upstream is reachable on the unified /compat endpoint or only
+  -- through its own provider path (v0.md §3, corrected 2026-08-13).
+  kind    TEXT NOT NULL CHECK (kind IN ('compat', 'provider')),
+  enabled INTEGER NOT NULL DEFAULT 1
+);
+
+CREATE TABLE models (
+  -- What a caller asks for. A self-hosted model family can be addressed
+  -- `<family>/<model>@<version>`, with its rows read from that family's own
+  -- serving manifests rather than restated here, so one validator stays the single
+  -- source of truth for what a version means.
+  id             TEXT PRIMARY KEY,
+  upstream_id    TEXT NOT NULL REFERENCES upstreams(id),
+  -- The id at the upstream, which is often not the id we expose.
+  upstream_model TEXT NOT NULL,
+  enabled        INTEGER NOT NULL DEFAULT 1,
+
+  -- Capability flags. NULL = not measured, 0 = measured absent, 1 = measured present.
+  tools               INTEGER,
+  parallel_tool_calls INTEGER,
+  streaming           INTEGER,
+  usage_reported      INTEGER,
+  vision              INTEGER,
+  json_schema         INTEGER,
+  max_context         INTEGER,
+  max_output          INTEGER,
+
+  -- What the provider may do with submitted content. Auto mode ranks partly on
+  -- price, and free or promotional access frequently carries training rights, so
+  -- without this as a hard gate a router optimising for cost will eventually send
+  -- end-user content to whichever provider is cheapest that week — turning v0.md §8's
+  -- webapp.example exposure from a decision someone makes into one nobody makes.
+  --
+  -- Recorded from the provider's terms with the date they were read, because a
+  -- stale answer here is worse than no answer.
+  data_retention        TEXT CHECK (data_retention IN ('none', 'retained', 'trains')),
+  data_retention_source TEXT,
+  data_retention_as_of  TEXT,
+
+  -- Provenance. #2 requires flags come from conformance output and never a hand
+  -- edit; until #10 exists, this records that they came from nowhere.
+  measured_at   TEXT,
+  measured_by   TEXT,
+
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX idx_models_upstream ON models (upstream_id);
+
+INSERT INTO upstreams (id, name, kind) VALUES
+  ('workers-ai',      'Cloudflare Workers AI', 'compat'),
+  ('openai',          'OpenAI',                'compat'),
+  ('anthropic',       'Anthropic',             'compat'),
+  ('google-ai-studio','Google AI Studio',      'compat'),
+  ('deepseek',        'DeepSeek',              'compat'),
+  ('mistral',         'Mistral AI',            'compat'),
+  ('groq',            'Groq',                  'compat'),
+  -- The tail. Kimi arrives here or not at all: Moonshot is not a supported
+  -- provider (v0.md §3, corrected 2026-08-13).
+  ('openrouter',      'OpenRouter',            'provider');
+
+-- The only model actually exercised end to end so far, and the flags recorded are
+-- only the ones genuinely observed on 2026-08-13: a chat completion returned, a
+-- stream terminated by [DONE], and usage present in both. Tool calling, vision,
+-- structured output and the context limits are left NULL because nobody has
+-- measured them, and guessing here is the failure this table exists to prevent.
+INSERT INTO models (id, upstream_id, upstream_model, streaming, usage_reported, measured_at, measured_by) VALUES
+  ('workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast', 'workers-ai',
+   '@cf/meta/llama-3.3-70b-instruct-fp8-fast', 1, 1, '2026-08-13', 'front-door end-to-end run');

package/migrations/0008_measurement_provenance.sql

@@ -0,0 +1,24 @@
+-- Make the bootstrap exception explicit (#2), from review of PR #25.
+--
+-- #2's acceptance is that capability flags are regenerated from conformance
+-- output with no hand-edited rows. 0007 seeded `streaming` and `usage_reported`
+-- for one model from a manual end-to-end run and recorded that in `measured_by`,
+-- which is provenance in prose rather than provenance you can query.
+--
+-- The review is right that this is inconsistent with the doctrine the same table
+-- enforces: unmeasured capabilities are refused precisely because "someone
+-- believes it works" is not measurement. A row asserting `streaming = 1` from a
+-- one-off curl is that belief with a date attached.
+--
+-- Rather than NULL the flags — which would refuse streaming against the only
+-- model wired up, on a technicality about who ran the test — the distinction
+-- becomes a column. `bootstrap` rows are real observations that did not come from
+-- the conformance suite; `conformance` rows did. #10 overwrites the former, and
+-- until it does, anyone can find every flag not yet backed by a conformance run
+-- with a one-line query instead of reading commit history.
+
+ALTER TABLE models
+  ADD COLUMN measurement_source TEXT
+    CHECK (measurement_source IN ('conformance', 'bootstrap'));
+
+UPDATE models SET measurement_source = 'bootstrap' WHERE measured_at IS NOT NULL;

package/migrations/0009_conformance.sql

@@ -0,0 +1,37 @@
+-- Conformance results (#10). Spec: docs/v0.md §3 component 10, §7.
+--
+-- Nothing in the platform tells us whether a model honours tool calls, and the
+-- failures are silent: v0.md §7 measured `qwen2.5-coder:7b` returning a tool call as
+-- prose with `finish_reason: stop` and no `tool_calls` array, on the same
+-- endpoint where `devstral` did it properly. A well-formed, wrong response.
+--
+-- Results are kept as history rather than overwritten, because the thing this is
+-- really watching for is **drift**. DeepSeek-V4-Flash was retrained on 2026-07-31
+-- under an unchanged id at an unchanged price; nothing in a pricing feed or a
+-- routing table detects that, and every measurement taken before that date
+-- silently described different weights. Keeping runs lets a flag that flipped be
+-- seen as having flipped.
+
+CREATE TABLE conformance_runs (
+  id          TEXT PRIMARY KEY,
+  started_at  TEXT NOT NULL DEFAULT (datetime('now')),
+  finished_at TEXT,
+  -- Which deployment was exercised. The suite runs *through* Cruise rather than
+  -- against the gateway, so it tests the real path including our own gates.
+  environment TEXT NOT NULL,
+  note        TEXT
+);
+
+CREATE TABLE conformance_results (
+  run_id     TEXT NOT NULL REFERENCES conformance_runs(id),
+  model      TEXT NOT NULL,
+  check_name TEXT NOT NULL,
+  outcome    TEXT NOT NULL CHECK (outcome IN ('pass', 'fail', 'skip', 'error')),
+  -- What was actually seen. `finish_reason` vocabularies differ per model, and a
+  -- suite that only records pass/fail throws away the interesting half.
+  observed   TEXT,
+  detail     TEXT,
+  PRIMARY KEY (run_id, model, check_name)
+);
+
+CREATE INDEX idx_conformance_results_model ON conformance_results (model, check_name);

package/migrations/0010_conformance_key.sql

@@ -0,0 +1,20 @@
+-- A key that may measure what the gates would otherwise refuse (#10).
+--
+-- #10 requires the suite run *through* Cruise so it exercises the real path. But
+-- #2's gate refuses any capability that has never been measured — so a
+-- conformance run testing tool calling is refused by the very gate whose data it
+-- exists to produce, the runner records a failure, and `tools` is set to 0
+-- permanently. The suite would conclude that no model supports tools because we
+-- stopped it from asking.
+--
+-- The fix is a per-key exemption rather than a bypass of the whole path. A
+-- conformance key still authenticates, still resolves to a project, still passes
+-- budget reservation, still gets its metadata injected and its spend recorded —
+-- everything #1 and #7 care about. It skips exactly one thing: the capability and
+-- verification gates, which exist to protect callers from unmeasured behaviour
+-- and are meaningless for the caller whose job is measuring it.
+--
+-- Default 0, so this is something a key is deliberately granted.
+
+ALTER TABLE virtual_keys
+  ADD COLUMN conformance INTEGER NOT NULL DEFAULT 0;

package/migrations/0011_correct_workers_ai_price.sql

@@ -0,0 +1,30 @@
+-- Correct the one price row, and stop it claiming a provenance it did not have.
+--
+-- 0005 seeded Workers AI at 290,000 / 2,250,000 micros per million tokens and
+-- labelled the source `cloudflare-published`. The published figures are $0.293
+-- and $2.253 per million tokens, so both were rounded guesses wearing the label
+-- of a citation — under-counting input by ~1%.
+--
+-- The direction matters more than the size. v0.md §8 warns that a stale pricing table
+-- produces attribution that looks authoritative and is wrong, and an
+-- under-counting ledger is the version that lets spend past a cap while
+-- reporting the cap as unbreached.
+--
+-- Also worth recording, since it was an open worry: Workers AI meters in
+-- *neurons*, not tokens, so a per-token ledger looked like a unit mismatch. It is
+-- not. Cloudflare publishes both and they reconcile exactly —
+--   26,668 neurons/Mtok × $0.011/1,000 = $0.2933
+--  204,805 neurons/Mtok × $0.011/1,000 = $2.2529
+-- — so per-token pricing is the neuron price already converted. The mismatch
+-- would be real for a provider that published neurons alone; this one does not.
+--
+-- `source` now carries the URL rather than an adjective, so the next person can
+-- check it in one click instead of trusting the word "published".
+
+UPDATE model_prices
+   SET input_micros_per_mtok  = 293000,
+       output_micros_per_mtok = 2253000,
+       source     = 'https://developers.cloudflare.com/workers-ai/platform/pricing/',
+       as_of      = '2026-08-14',
+       updated_at = datetime('now')
+ WHERE model = 'workers-ai/@cf/meta/llama-3.3-70b-instruct-fp8-fast';

package/migrations/0012_rate_limits.sql

@@ -0,0 +1,28 @@
+-- Per-key rate limiting (#7), the half of that issue that was never built.
+--
+-- `virtual_keys.rate_limit_per_min` has existed since 0001, is read by
+-- `resolveVirtualKey`, and was enforced nowhere. A column that exists and does
+-- nothing is worse than an absent one, because the configuration reads as live —
+-- the same defect review caught in `upstreams.enabled`, found the same way.
+--
+-- Sliding window rather than fixed, because a fixed window admits twice the limit
+-- across a boundary: a key capped at 60/min can send 60 at 11:59:59 and 60 more
+-- at 12:00:00. #7 asks for sliding on those grounds.
+--
+-- Implemented as the two-bucket approximation. Each minute is a row; the count is
+-- the current bucket plus the previous one weighted by how much of it still falls
+-- inside the trailing window. That costs two integers per key per minute instead
+-- of a timestamp per request, and its error is bounded by the assumption that the
+-- previous minute's requests were evenly spread. Exact sliding would mean storing
+-- every request time, which is a row per request on the hot path to make a
+-- rate limiter more precise than the thing it protects.
+
+CREATE TABLE key_rate_buckets (
+  key_id TEXT NOT NULL REFERENCES virtual_keys(id) ON DELETE CASCADE,
+  -- Unix minute: strftime('%s','now') / 60.
+  bucket INTEGER NOT NULL,
+  count  INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (key_id, bucket)
+);
+
+CREATE INDEX idx_key_rate_buckets_bucket ON key_rate_buckets (bucket);

package/migrations/0013_deepseek_and_mistral.sql

@@ -0,0 +1,42 @@
+-- Two more upstreams, so the measurement programme has more than one data point.
+--
+-- Conformance has measured exactly one model, which makes v0.md §7's whole programme a
+-- single observation and #2's capability flags a table with one row. Three models
+-- across three providers is where per-model capability, price drift and the
+-- conformance canary start being worth having.
+--
+-- Both arrive **unmeasured**, so neither is routable until conformance has run
+-- (#10). That is the flow working rather than an oversight: a model becomes
+-- routable by being measured, not by being inserted.
+
+INSERT INTO models (id, upstream_id, upstream_model) VALUES
+  -- Pinned to the concrete model rather than the `deepseek-chat` alias.
+  --
+  -- `deepseek/deepseek-chat` works, and reports back `deepseek-v4-flash` — the
+  -- exact drift #10 exists for, found on the first request we ever sent it. The
+  -- alias is free to move to `deepseek-v4-pro`, which costs 3x, and a price row
+  -- keyed on the alias would silently under-count from that moment. Pinning makes
+  -- a provider changing what we get an error rather than a surprise invoice.
+  ('deepseek/deepseek-v4-flash',   'deepseek', 'deepseek-v4-flash'),
+
+  -- Mistral has no concrete-version id we could verify, so this keeps `-latest`
+  -- and accepts the drift. Conformance records what actually answered, which is
+  -- the mitigation available when pinning is not.
+  ('mistral/mistral-small-latest', 'mistral',  'mistral-small-latest');
+
+-- Published figures, cited rather than remembered — the Workers AI row was seeded
+-- from memory and was wrong by ~1% in the under-counting direction (0011).
+INSERT INTO model_prices (model, input_micros_per_mtok, output_micros_per_mtok, source, as_of) VALUES
+  ('deepseek/deepseek-v4-flash', 140000, 280000,
+   'https://api-docs.deepseek.com/quick_start/pricing', '2026-08-14');
+
+-- Mistral is deliberately left unpriced. Neither the pricing page nor the models
+-- overview gives a per-model figure that could be cited, and guessing is the
+-- mistake 0011 exists to correct. Unpriced is handled rather than ignored: usage
+-- lands in `unpriced_usage` and the request is charged its full reservation, so
+-- an unpriced model cannot be used to spend without limit.
+--
+-- One known gap that applies to DeepSeek and eventually to others: they bill
+-- cached input at $0.0028/M against $0.14/M, and this ledger has one input price.
+-- Requests hitting provider-side prompt caching are therefore over-counted, which
+-- is the safe direction but still drift. v0.md §8 names this; #5 owns fixing it.

package/migrations/0014_cost_ledger.sql

@@ -0,0 +1,104 @@
+-- The cost ledger (#5). Spec: docs/v0.md §3 component 5, §4, §7.
+--
+-- #5 says the scope shrank because "AI Gateway logs already carry provider,
+-- model, tokens, cost, duration, cache status, and our metadata", leaving us to
+-- configure retention rather than instrument requests. That was written before
+-- v0.md §4's retention correction: `gw-sensitive` runs with **logging off**, and it is
+-- the default carrying every project with end-user content. Gateway logs
+-- therefore cover internal traffic only.
+--
+-- So the Worker is the ledger's source of truth, not the gateway. It already sees
+-- every request and every response, and it is the only thing that does for the
+-- traffic that matters most.
+
+-- One row per request that reached an upstream.
+--
+-- Aggregate spend per project already existed in `project_spend`, which is what
+-- budget enforcement reads. That answers "can this project spend more" and none
+-- of v0.md §7's questions: spend by project × model × month, cost per completed request
+-- per lane, cost per account. Those need the dimensions kept per request rather
+-- than summed away on write.
+CREATE TABLE ledger (
+  id         TEXT PRIMARY KEY,
+  at         TEXT NOT NULL DEFAULT (datetime('now')),
+
+  -- The five metadata dimensions, plus what they were spent on. `account` is the
+  -- opaque hashed identifier from v0.md §1 — never an email, never anything
+  -- identifying, which is what keeps it compatible with a retention-off gateway.
+  tenant_id     TEXT NOT NULL,
+  project_id    TEXT NOT NULL,
+  traffic_class TEXT NOT NULL,
+  lane          TEXT NOT NULL,
+  account       TEXT NOT NULL,
+
+  model       TEXT NOT NULL,
+  upstream_id TEXT NOT NULL,
+  key_prefix  TEXT NOT NULL,
+
+  -- Metered as the upstream billed, never as the client submitted. v0.md §7 measured
+  -- `devstral` reporting 1,230 prompt tokens for a ten-token message because its
+  -- template injects a system prompt we never see.
+  prompt_tokens     INTEGER NOT NULL DEFAULT 0,
+  completion_tokens INTEGER NOT NULL DEFAULT 0,
+
+  -- Kept separately because providers meter them differently and treating them
+  -- uniformly is how a ledger drifts from an invoice while looking authoritative.
+  -- DeepSeek bills cached input at roughly a fiftieth of the miss rate, and
+  -- reasoning tokens are completion tokens that produced no content.
+  reasoning_tokens     INTEGER NOT NULL DEFAULT 0,
+  cached_input_tokens  INTEGER NOT NULL DEFAULT 0,
+
+  cost_micros INTEGER NOT NULL DEFAULT 0,
+  priced      INTEGER NOT NULL DEFAULT 0,
+
+  -- A request that was not billed must not read as a zero-cost success. A refusal
+  -- returned as HTTP 200 is the case auto-mode.md §10 names: the response is well formed, the
+  -- cost is nil, and a naive ledger records a free win.
+  outcome TEXT NOT NULL
+    CHECK (outcome IN ('served', 'refusal', 'empty', 'unpriced', 'no_usage', 'upstream_error')),
+
+  cache_status TEXT,
+  streamed     INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX idx_ledger_project_at ON ledger (project_id, at);
+CREATE INDEX idx_ledger_model_at   ON ledger (model, at);
+CREATE INDEX idx_ledger_account_at ON ledger (account, at);
+CREATE INDEX idx_ledger_lane_at    ON ledger (lane, at);
+
+-- Prices become history rather than a current value.
+--
+-- The old table was keyed on `model` alone, so 0011 correcting the Workers AI
+-- rate rewrote every past request's basis along with it. #5 requires that a cost
+-- change is dated and never rewrites historical rows, and the reason is not
+-- tidiness: reconciling a month against an invoice is impossible if the rate the
+-- month was charged at has been overwritten by the rate in force today.
+CREATE TABLE model_prices_new (
+  model                  TEXT NOT NULL,
+  -- The date this rate took effect. A lookup takes the latest row not after the
+  -- request, so a correction is a new row and old requests keep their basis.
+  effective_from         TEXT NOT NULL,
+  input_micros_per_mtok  INTEGER NOT NULL,
+  output_micros_per_mtok INTEGER NOT NULL,
+  -- What a *cached* input token costs, where the provider prices it separately.
+  -- Null means unknown, and unknown is charged at the full input rate, which
+  -- over-counts — the safe direction.
+  cached_input_micros_per_mtok INTEGER,
+  source                 TEXT NOT NULL,
+  recorded_at            TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (model, effective_from)
+);
+
+INSERT INTO model_prices_new
+  (model, effective_from, input_micros_per_mtok, output_micros_per_mtok, source)
+SELECT model, as_of, input_micros_per_mtok, output_micros_per_mtok, source FROM model_prices;
+
+DROP TABLE model_prices;
+ALTER TABLE model_prices_new RENAME TO model_prices;
+
+-- DeepSeek prices cached input at $0.0028/M against $0.14/M. Recorded now so the
+-- gap between what we charge and what the invoice says has a stated cause rather
+-- than being discovered as an unexplained discrepancy.
+UPDATE model_prices
+   SET cached_input_micros_per_mtok = 2800
+ WHERE model = 'deepseek/deepseek-v4-flash';

package/migrations/0015_memberships.sql

@@ -0,0 +1,33 @@
+-- Who may administer what (#22). Spec: docs/v0.md §4.
+--
+-- The rule this table exists to enforce: **authenticate against the identity
+-- provider, authorize against D1.** Firebase says who someone is; which tenant
+-- and which projects they may touch is a Cruise question answered from Cruise's
+-- own tables, keyed by uid, never from claims stamped into the token.
+--
+-- That separation is what keeps a later change of identity provider — which the
+-- multi-tenancy in v0.md §6 may well force — a rewrite of one verification function
+-- rather than of the whole permission model.
+--
+-- Deliberately unseeded. #22 requires that a valid Firebase token for a uid with
+-- no membership is *rejected* rather than defaulted into a tenant, and seeding a
+-- row would make that criterion untestable. The first membership is granted
+-- explicitly, by the CLI, and recorded in the audit log like everything else.
+
+CREATE TABLE memberships (
+  uid       TEXT NOT NULL,
+  tenant_id TEXT NOT NULL REFERENCES tenants(id),
+
+  -- `viewer` reads; `admin` also writes; `owner` also grants membership. Roles
+  -- exist from the start because v0.md §2 says no interface may assume the operator and
+  -- the customer are the same person, and a single implicit role assumes exactly
+  -- that.
+  role TEXT NOT NULL CHECK (role IN ('owner', 'admin', 'viewer')),
+
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  created_by TEXT,
+
+  PRIMARY KEY (uid, tenant_id)
+);
+
+CREATE INDEX idx_memberships_tenant ON memberships (tenant_id);

package/migrations/0016_latency.sql

@@ -0,0 +1,23 @@
+-- Measure time, not only money (#6).
+--
+-- #6 is explicit that the case for serving from cache is latency rather than
+-- cost — "the case for phase 1a is time, not money, so measure time" — and the
+-- ledger recorded none. Without it the phase 1a gate in v0.md §6 cannot be evaluated
+-- even once real traffic exists, because the quantity it turns on was never
+-- captured.
+--
+-- What is recorded is time to response headers from the gateway, not total
+-- duration. For a stream those are wildly different and the first is the
+-- interesting one: it is what a caller waits before anything appears, and
+-- therefore exactly what a cache hit removes. Total duration on a stream mostly
+-- measures how much text was generated.
+
+ALTER TABLE ledger ADD COLUMN upstream_ms INTEGER;
+
+-- What the caller actually received. Kept because a ledger of only successes
+-- cannot answer #6's "429 and 5xx rate per provider", and because a 429 from an
+-- upstream and a 429 from our own budget are different facts that look alike in
+-- an aggregate.
+ALTER TABLE ledger ADD COLUMN http_status INTEGER;
+
+CREATE INDEX idx_ledger_class_at ON ledger (traffic_class, at);

package/migrations/0017_ledger_provider_index.sql

@@ -0,0 +1,8 @@
+-- The report groups by provider and nothing indexed it (#6).
+--
+-- `ledger` gained an index per dimension as each query appeared — project, model,
+-- account, lane, class — and `byProvider()` was written without one, so the
+-- provider table in the report is the only part of it doing a full scan. Cheap
+-- to fix while the table is small, and awkward once it is not.
+
+CREATE INDEX idx_ledger_upstream_at ON ledger (upstream_id, at);

package/migrations/0018_fallback_chains.sql

@@ -0,0 +1,34 @@
+-- Fallback chains (#8). Spec: docs/v0.md §3 component 7.
+--
+-- #8 says the scope shrank to configuring Dynamic Routing, which expresses
+-- chains natively. It is not used, for the reason already recorded in v0.md §4: a
+-- dynamic route's `model` node names a concrete provider and model, so routing
+-- through one decides the model rather than passing the caller's through. The
+-- same objection that moved budget enforcement into the Worker applies here, and
+-- a chain evaluated in the Worker can do something a route cannot — check the
+-- capability flags of each candidate against the request in hand.
+
+CREATE TABLE model_fallbacks (
+  model          TEXT NOT NULL REFERENCES models(id) ON DELETE CASCADE,
+  -- Lower is tried first. Explicit rather than insertion-ordered, so reordering
+  -- a chain is an update rather than a delete and re-insert.
+  position       INTEGER NOT NULL,
+  fallback_model TEXT NOT NULL REFERENCES models(id) ON DELETE CASCADE,
+  PRIMARY KEY (model, position)
+);
+
+-- What the caller asked for, beside what actually answered.
+--
+-- The ledger records the model that served. Without the requested one there is no
+-- way to answer #8's "how often each chain fired", because a fallback and a
+-- direct call to the same model are indistinguishable after the fact.
+ALTER TABLE ledger ADD COLUMN requested_model TEXT;
+
+-- Chains are only useful between models that can do the same job, so the seeded
+-- pair is the one measured to share capabilities: both have tools, streaming and
+-- usage, and both are cheap. llama is deliberately not in a chain — conformance
+-- measured it at one tool call, so falling back to it from a model that
+-- parallelises would convert a rate limit into a silent capability downgrade.
+INSERT INTO model_fallbacks (model, position, fallback_model) VALUES
+  ('deepseek/deepseek-v4-flash',   1, 'mistral/mistral-small-latest'),
+  ('mistral/mistral-small-latest', 1, 'deepseek/deepseek-v4-flash');

package/migrations/0019_rate_buckets.sql

@@ -0,0 +1,27 @@
+-- Generalise the rate limiter so it can count something other than a key (#58,
+-- adapted from jisey-socials).
+--
+-- `key_rate_buckets` was keyed on a virtual key, which cannot count the case that
+-- matters here: a request that presented **no valid credential at all**. Those
+-- never reach the limiter, because resolution fails first — so authentication
+-- failures are unlimited.
+--
+-- Rather than duplicate the atomic two-bucket SQL for a second subject, the table
+-- takes a scope. Duplicating that statement is how the two would drift, and it is
+-- the piece most easily got subtly wrong.
+
+CREATE TABLE rate_buckets (
+  -- 'key' for a virtual key, 'auth' for an unauthenticated caller by address.
+  scope   TEXT NOT NULL,
+  subject TEXT NOT NULL,
+  bucket  INTEGER NOT NULL,
+  count   INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (scope, subject, bucket)
+);
+
+CREATE INDEX idx_rate_buckets_bucket ON rate_buckets (bucket);
+
+INSERT INTO rate_buckets (scope, subject, bucket, count)
+SELECT 'key', key_id, bucket, count FROM key_rate_buckets;
+
+DROP TABLE key_rate_buckets;

package/migrations/0020_mistral_price_and_pin.sql

@@ -0,0 +1,62 @@
+-- Price Mistral, and pin it to the version that price belongs to.
+--
+-- 0013 left Mistral deliberately unpriced: "neither the pricing page nor the
+-- models overview gives a per-model figure that could be cited, and guessing is
+-- the mistake 0011 exists to correct." That was true, and the cost of it showed
+-- up in the first production conformance run on 2026-08-15 — six requests, 405
+-- tokens, and **300,000 micros** of recorded spend, because an unpriced model is
+-- charged its full reservation. Mistral appeared to cost roughly four hundred
+-- times what DeepSeek did for a third of the tokens, and being wrong in the safe
+-- direction does not make a v0.md §7 figure usable.
+--
+-- The figure is now citable. Mistral Small 4:
+--   https://docs.mistral.ai/models/model-cards/mistral-small-4-0-26-03
+--   $0.15 / M input, $0.60 / M output
+--
+-- Cached input is left NULL. Mistral publishes no separate cached rate, and NULL
+-- charges the full input rate — over-counting, which is the safe direction for
+-- anything a budget reads (0014).
+
+-- ── the pin ──────────────────────────────────────────────────────────────────
+--
+-- 0013 kept `-latest` because "Mistral has no concrete-version id we could
+-- verify". It has one now: `GET /v1/models` lists `mistral-small-2603` carrying
+-- `mistral-small-latest` among its aliases, so the mapping is verifiable rather
+-- than assumed.
+--
+-- That verification took a second attempt worth recording. A completion sent to
+-- `mistral-small-latest` comes back reporting `model: "mistral-small-latest"` —
+-- the alias, echoed. DeepSeek answers the same question honestly, reporting
+-- `deepseek-v4-flash` for `deepseek-chat`, which is how that drift was caught on
+-- the first request ever sent to it. **Mistral's response cannot tell you which
+-- model answered**, so the response-level canary #10 relies on does not work
+-- here, and the models endpoint is the only place the truth is written down.
+--
+-- Pinning matters more once a price exists than it did without one. Mistral
+-- Small 3.1 is $0.10 / $0.30 and Small 4 is $0.15 / $0.60: the alias moving is a
+-- **2x change in the output rate**, arriving with no announcement and no signal
+-- in any response we could read. Pinned, that becomes a model-not-found error
+-- rather than an invoice nobody predicted.
+UPDATE models
+   SET upstream_model = 'mistral-small-2603'
+ WHERE id = 'mistral/mistral-small-latest';
+
+-- The exposed id keeps saying `-latest` while the target is pinned, which reads
+-- oddly and is deliberate: the ledger, the conformance results and the price row
+-- all key on it, and renaming it would orphan the measurement taken on
+-- 2026-08-15 and leave the model unroutable until conformance ran again. Worth
+-- renaming when there is a reason to run conformance anyway.
+
+-- ── the price ────────────────────────────────────────────────────────────────
+--
+-- Dated the day it was verified, not backdated. The six conformance requests
+-- already in the ledger keep the basis they were charged at — a correction is a
+-- new row and never rewrites history (0014), and those rows are honestly
+-- labelled `unpriced` with their tokens preserved in `unpriced_usage`. What they
+-- are not is a cost figure, and nothing here pretends otherwise.
+INSERT OR REPLACE INTO model_prices
+  (model, effective_from, input_micros_per_mtok, output_micros_per_mtok,
+   cached_input_micros_per_mtok, source)
+VALUES
+  ('mistral/mistral-small-latest', '2026-08-16', 150000, 600000, NULL,
+   'https://docs.mistral.ai/models/model-cards/mistral-small-4-0-26-03');

package/migrations/0021_mistral_price_date_is_utc.sql

@@ -0,0 +1,35 @@
+-- 0020's price row was dated in the wrong timezone, so it did nothing.
+--
+-- `effective_from` was written as '2026-08-16', taken from a machine clock
+-- reading 03:21 IST. Everything in this system is UTC — `date('now')` and
+-- `datetime('now')` in D1 both are — and at that moment UTC was still
+-- 2026-08-15. `priceUsage` selects `WHERE effective_from <= date('now')`, so the
+-- row existed, read correctly in every query, and applied to nothing.
+--
+-- Verified end to end after 0020: a real production request to Mistral came back
+-- `outcome=unpriced, cost=50000` — the full reservation, exactly as before the
+-- price was added. Nothing about the database looked wrong. A check that the
+-- model *has* a price row passes; only a check that a price is **in force**
+-- catches it:
+--
+--   SELECT ... FROM models m WHERE NOT EXISTS (
+--     SELECT 1 FROM model_prices p
+--      WHERE p.model = m.id AND p.effective_from <= date('now'))
+--
+-- The failure mode is worth naming because it is the quiet kind: a future-dated
+-- price does not error, it under-prices. Had this been a *correction* to an
+-- existing rate rather than a first price, the model would have kept billing at
+-- the old one for a day with no signal at all.
+
+DELETE FROM model_prices
+ WHERE model = 'mistral/mistral-small-latest'
+   AND effective_from = '2026-08-16';
+
+-- The date the figure was verified, in UTC. Same source, same rates:
+-- https://docs.mistral.ai/models/model-cards/mistral-small-4-0-26-03
+INSERT OR REPLACE INTO model_prices
+  (model, effective_from, input_micros_per_mtok, output_micros_per_mtok,
+   cached_input_micros_per_mtok, source)
+VALUES
+  ('mistral/mistral-small-latest', '2026-08-15', 150000, 600000, NULL,
+   'https://docs.mistral.ai/models/model-cards/mistral-small-4-0-26-03');

package/migrations/0022_drop_unenforced_key_budget.sql

@@ -0,0 +1,32 @@
+-- Remove the per-key monthly budget, because nothing enforced it.
+--
+-- `budget_micros_month` has been on `virtual_keys` since 0001. It is written by
+-- `issueKey`, exposed as `--budget` on the CLI in dollars, loaded into
+-- `ResolvedKey` on every single request — and read by no decision anywhere. A
+-- key issued with `--budget 50` accepted the number, stored it, reported it
+-- back, and spent without limit.
+--
+-- That is worse than not offering it. An absent cap is a known gap; a cap that
+-- is accepted and ignored is a control someone relies on. v0.md §1 records that an
+-- absent cap is exactly what made the pipelines unsafe to switch on, and this
+-- was an absent cap wearing the costume of a present one.
+--
+-- Zero of the 22 keys across staging and production carried a value, so nothing
+-- is lost here.
+--
+-- **Not wired up instead, deliberately.** Enforcing it means a second atomic
+-- reservation beside the project's, plus a compensating release when the second
+-- fails after the first succeeded. A second path that has to repeat the first
+-- path's controls is the precise shape of the three worst bugs this project has
+-- had — fallback skipping the key's model scope, fallback carrying one
+-- provider's credential to another, and the control plane charging successes
+-- against a failure budget. Doing it as a "small addition" to the reservation is
+-- how the fourth one arrives.
+--
+-- Nothing needs it today either: keys belong to projects, projects have budgets
+-- that are enforced and tested under concurrency, and this tenant's six projects
+-- map to products rather than to customers. It becomes worth designing when keys
+-- are handed to people outside BytesBrains — v0.md §8's phase 4 — and at that point it
+-- deserves the same atomic treatment `project_spend` already has, not a column.
+
+ALTER TABLE virtual_keys DROP COLUMN budget_micros_month;