@bytesbrains/cruise-worker 0.0.0-stage → 0.12.0

package/migrations/0058_price_components.sql

@@ -0,0 +1,230 @@
+-- A price that is not per token, held once (#228, slice 3 of #220; the design
+-- #207 asked for). Decided in docs/modalities.md section 3.
+--
+-- `price_observations` holds three rates and every one is per million tokens.
+-- That was the whole truth about every host in the catalogue until the labs
+-- arrived, and it stopped being true in three places at once: Perplexity
+-- charges a fee **per request** on top of tokens, varying with the search
+-- context size the body names; Anthropic bills a web search **per search**,
+-- reported in the response's `server_tool_use`; and speech (slice 4) is per
+-- character. #207 measured what ignoring this costs — a `sonar` row priced on
+-- tokens alone silently misses $5–$14 per thousand requests, plausibly the
+-- larger half of a short query's bill — and the direction is the one 0011 made
+-- a migration of its own over: under-counting, which lets spend past a cap
+-- while reporting the cap as unbreached.
+--
+-- ## The shape
+--
+-- A second append-only log **beside** `price_observations`, not a widening of
+-- it. Same two time axes — `effective_from` is when the vendor's rate applied,
+-- `observed_at` when we recorded it — same `retracted` tombstone, same view
+-- over the latest surviving observation per key, for 0048's reason: a
+-- correction and a price change must not look alike in the data. The token
+-- resolver in `src/pricing.ts` is right for tokens and stays the one path to a
+-- token rate; this is the one path to everything else.
+--
+-- `component` is a **closed vocabulary**, CHECK-constrained, and each entry
+-- states where its count comes from (`src/pricing-components.ts` is the code
+-- that reads each one):
+--
+--   request      one per request; `variant` is the search context size
+--   search       the response's `server_tool_use.web_search_requests`
+--   character    the request's `input`, for speech
+--   image        the request's `n`; `variant` is `size/quality`
+--   image_input  the response's `input_tokens_details.image_tokens`
+--   audio_input  the response's usage, for the Gemini rows 0049 excluded
+--   cache_write  the response's usage; `variant` is the cache TTL
+--   second       the request, for audio embeddings
+--   frame        the request, for video embeddings
+--
+-- **`text_input`, `text_output` and `cached_input` are deliberately not in the
+-- set.** They are the three token columns by definition, and a component row
+-- restating one of them would be a second place a token rate lives — the
+-- tenant-isolation argument (0004) applied to prices: one path to a fact, so
+-- two rows cannot disagree. The CHECK refuses them, and a test holds it to that.
+--
+-- `variant` is what selects the rate and is **read from the request, never
+-- pinned by Cruise**: Perplexity's `web_search_options.search_context_size`,
+-- an image's `size` and `quality`. '' is the row that applies when the body
+-- names nothing and the host has one rate. A body naming a variant no row
+-- carries is bounded and settled at the **dearest** row of that component —
+-- over-counting, the safe direction — and the ledger records which applied.
+--
+-- `per` is stored rather than implied by the unit. A token rate is sub-micro
+-- per token and needs the million; an image is tens of thousands of micros
+-- and needs nothing; a host quoting "per 1,000 characters" is recorded as it
+-- quotes, so a row can be held against the page it came from by eye.
+--
+-- ## Rules the code keeps
+--
+--   A request's cost is its token part plus the sum of its components.
+--   `ledger.cost_micros` stays the total; `ledger_components` below keeps the
+--   units, so a month reconciles against an invoice per unit. Summing the
+--   units away on write is the failure 0014 named for tokens.
+--
+--   The reservation covers any rate settlement can name. The **count** is
+--   exact for a request-counted component and a ceiling for a response-counted
+--   one — one request fee, every search the body's `max_uses` allows. The
+--   **rate** is the row the body asks for, except where the host chooses the
+--   variant and reports it back, which is Perplexity's context size: there the
+--   bound holds the dearest row whatever was asked, because the host bills
+--   what it applied and settling at the asked-for rate would under-bill. A
+--   response-counted component with no stated ceiling cannot be bounded, and
+--   that is refused a billed tenant as `request_unbounded` — the same answer
+--   a chat request with no `max_tokens` gets on a model with no output cap.
+--
+--   A component in the vocabulary with **no reader in the code** fails
+--   closed: a model carrying such a row cannot be bounded for a billed tenant
+--   and settles at its reservation for an internal one. The vocabulary is the
+--   design's, the readers are this slice's, and the gap between them must
+--   refuse rather than under-bill. `request`, `search`, `character` and
+--   `image` are read today.
+
+CREATE TABLE price_components (
+  observed_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+  model          TEXT    NOT NULL,
+  effective_from TEXT    NOT NULL,
+  component      TEXT    NOT NULL CHECK (component IN (
+                   'request', 'search', 'character', 'image',
+                   'image_input', 'audio_input', 'cache_write', 'second', 'frame')),
+  variant        TEXT    NOT NULL DEFAULT '',
+  -- What `per` of the unit costs. Zero is a real rate: a host that waives a
+  -- fee on one variant says so with a row rather than with an absence.
+  micros         INTEGER NOT NULL CHECK (micros >= 0),
+  -- The count one `micros` buys: 1 request, 1000 searches, 1 image.
+  per            INTEGER NOT NULL CHECK (per > 0),
+  source         TEXT    NOT NULL,
+  note           TEXT,
+  retracted      INTEGER NOT NULL DEFAULT 0 CHECK (retracted IN (0, 1)),
+  PRIMARY KEY (model, effective_from, component, variant, observed_at)
+);
+
+CREATE INDEX idx_price_components_lookup ON price_components (model, effective_from);
+
+-- The latest surviving observation per key, as `model_prices` is over
+-- `price_observations`. Every reader reads this; nothing writes it.
+CREATE VIEW model_components AS
+SELECT c.model,
+       c.effective_from,
+       c.component,
+       c.variant,
+       c.micros,
+       c.per,
+       c.source,
+       c.observed_at AS recorded_at
+  FROM price_components c
+ WHERE c.retracted = 0
+   AND c.observed_at = (
+         SELECT max(x.observed_at)
+           FROM price_components x
+          WHERE x.model          = c.model
+            AND x.effective_from = c.effective_from
+            AND x.component      = c.component
+            AND x.variant        = c.variant
+       );
+
+-- What each request paid per unit, beside the row that holds its total. One
+-- row per component and variant that applied; a request with no components
+-- has none. `micros` is at **list** — the rate in force, before a cache
+-- discount and before a tenant's markup — because the invoice this
+-- reconciles against is the host's, and the host bills list. Written in the
+-- same `db.batch` as the ledger row, so a request cannot have its units
+-- without its total or its total without its units.
+CREATE TABLE ledger_components (
+  ledger_id TEXT    NOT NULL REFERENCES ledger(id),
+  component TEXT    NOT NULL CHECK (component IN (
+              'request', 'search', 'character', 'image',
+              'image_input', 'audio_input', 'cache_write', 'second', 'frame')),
+  variant   TEXT    NOT NULL DEFAULT '',
+  count     INTEGER NOT NULL CHECK (count >= 0),
+  micros    INTEGER NOT NULL CHECK (micros >= 0),
+  PRIMARY KEY (ledger_id, component, variant)
+);
+
+-- ## First rows: Perplexity's request fee and Anthropic's search fee (#207)
+--
+-- Read 2026-09-05 IST from each host's page. That is 2026-09-04 21:00 UTC, which
+-- is the date these rows carry, because a row dated a day ahead of the Worker's
+-- clock applies to nothing (0021). **Perplexity's figures moved between #207's
+-- reading of 2026-09-02 and this one**: that issue quoted $5/$8/$12 per
+-- thousand requests for every Sonar model, and the page now prints those for
+-- `sonar` alone, with `sonar-pro` and `sonar-reasoning-pro` at $6/$10/$14. Three
+-- days apart, on the page this repo's whole pricing argument rests on — which
+-- is the argument for `observed_at` in one sentence.
+--
+-- No Perplexity model is in `models`, and these rows put none there. #207's
+-- fourth question — whether search-grounded models are worth routing at all —
+-- is still open, and its comment of 2026-09-03 notes their chat-completions
+-- endpoint is supported only until 2026-09-27, so an upstream added the
+-- ordinary way would be a migration and a rewrite in that order. The rows cost
+-- nothing while nothing routes to them, and they are the shape's first
+-- consumer: a `request` fee with a variant, bounded exactly, settled at the
+-- context size the response's usage reports.
+--
+-- The Cruise id is `perplexity/<model>`, as every upstream's rows are named,
+-- so the day a `models` row lands the price is already there.
+--
+-- `sonar-deep-research` is **not** here. It bills per search query ($5 per
+-- 1,000) and the count is bounded by nothing in the request — the model
+-- searches as it sees fit, with no `max_uses` — so a `search` row would reserve
+-- nothing and settle from `usage.num_search_queries`: correct for an internal
+-- tenant and unbounded for a billed one. It also bills citation and reasoning
+-- tokens as separate categories this log has no component for. Both stay
+-- #207's to decide, and are recorded here so the omission is a decision.
+INSERT INTO price_components
+  (observed_at, model, effective_from, component, variant, micros, per, source, note)
+VALUES
+  ('2026-09-04 21:00:00', 'perplexity/sonar', '2026-09-04', 'request', 'low',     5000000, 1000,
+   'https://docs.perplexity.ai/getting-started/pricing',
+   'First observation (0058): per-request fee at search_context_size low. Read 2026-09-05; #207 quoted the same figure on 2026-09-02.'),
+  ('2026-09-04 21:00:00', 'perplexity/sonar', '2026-09-04', 'request', 'medium',  8000000, 1000,
+   'https://docs.perplexity.ai/getting-started/pricing', 'First observation (0058).'),
+  ('2026-09-04 21:00:00', 'perplexity/sonar', '2026-09-04', 'request', 'high',   12000000, 1000,
+   'https://docs.perplexity.ai/getting-started/pricing', 'First observation (0058).'),
+
+  ('2026-09-04 21:00:00', 'perplexity/sonar-pro', '2026-09-04', 'request', 'low',     6000000, 1000,
+   'https://docs.perplexity.ai/getting-started/pricing',
+   'First observation (0058). #207 read $5/$8/$12 on 2026-09-02; the page prints $6/$10/$14 for this model on 2026-09-05.'),
+  ('2026-09-04 21:00:00', 'perplexity/sonar-pro', '2026-09-04', 'request', 'medium', 10000000, 1000,
+   'https://docs.perplexity.ai/getting-started/pricing', 'First observation (0058).'),
+  ('2026-09-04 21:00:00', 'perplexity/sonar-pro', '2026-09-04', 'request', 'high',   14000000, 1000,
+   'https://docs.perplexity.ai/getting-started/pricing', 'First observation (0058).'),
+
+  ('2026-09-04 21:00:00', 'perplexity/sonar-reasoning-pro', '2026-09-04', 'request', 'low',     6000000, 1000,
+   'https://docs.perplexity.ai/getting-started/pricing',
+   'First observation (0058). #207 read $5/$8/$12 on 2026-09-02; the page prints $6/$10/$14 for this model on 2026-09-05.'),
+  ('2026-09-04 21:00:00', 'perplexity/sonar-reasoning-pro', '2026-09-04', 'request', 'medium', 10000000, 1000,
+   'https://docs.perplexity.ai/getting-started/pricing', 'First observation (0058).'),
+  ('2026-09-04 21:00:00', 'perplexity/sonar-reasoning-pro', '2026-09-04', 'request', 'high',   14000000, 1000,
+   'https://docs.perplexity.ai/getting-started/pricing', 'First observation (0058).');
+
+-- Anthropic's web search: $10 per 1,000 searches on every model 0053 holds,
+-- "plus standard token costs for search-generated content" — which the token
+-- columns already bill, since search results are counted as input tokens. The
+-- count is `usage.server_tool_use.web_search_requests`, a search that errors
+-- is not billed, and `max_uses` on the tool is the ceiling the reservation
+-- holds. Whether that field survives the gateway's `/compat` translation is a
+-- measurement for the first conformance run against a held credential, not an
+-- assumption here: a response carrying no count where the request allowed
+-- searches settles at the reservation rather than at zero.
+--
+-- **Cache writes remain a known gap.** 0053 recorded the cache *read* rate in
+-- `cached_input_micros_per_mtok` and noted the page's two cache *write* rates
+-- (1.25x and 2x base, by TTL) had no column. They now have a component,
+-- `cache_write` with `variant` = TTL, and no rows — because there is also no
+-- reader yet: `usage.cache_creation_input_tokens` is not parsed, and a row
+-- with no reader fails closed rather than billing. Writing the rows is the
+-- smaller half; reading the count is the half that bills, and it lands with
+-- the reader.
+INSERT INTO price_components
+  (observed_at, model, effective_from, component, variant, micros, per, source, note)
+VALUES
+  ('2026-09-04 21:00:00', 'anthropic/claude-fable-5-1',          '2026-09-04', 'search', '', 10000000, 1000,
+   'https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool',
+   'First observation (0058): web search, $10 per 1,000 searches, counted from usage.server_tool_use.web_search_requests.'),
+  ('2026-09-04 21:00:00', 'anthropic/claude-opus-5',             '2026-09-04', 'search', '', 10000000, 1000,
+   'https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool', 'First observation (0058).'),
+  ('2026-09-04 21:00:00', 'anthropic/claude-sonnet-5',           '2026-09-04', 'search', '', 10000000, 1000,
+   'https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool', 'First observation (0058).'),
+  ('2026-09-04 21:00:00', 'anthropic/claude-haiku-4-5-20251001', '2026-09-04', 'search', '', 10000000, 1000,
+   'https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool', 'First observation (0058).');

package/migrations/0059_speech.sql

@@ -0,0 +1,151 @@
+-- Speech: the first route whose whole bill is known before the request is sent,
+-- and the first host this repo reaches through an adapter rather than a URL
+-- (#229, slice 4 of #220, decided in `docs/modalities.md`).
+--
+-- 0058 built the log for a price that is not per token and gave it two consumers
+-- that route nowhere. This is the first that routes: `tts-1` and `tts-1-hd` on a
+-- host the gateway already carries, then ElevenLabs on a path of our own.
+--
+-- ## What the hosts charge, read 2026-09-05 IST
+--
+-- That is 2026-09-04 21:47 UTC, which is the date every row below carries —
+-- 0057's lesson, a third time: `date('now')` is UTC and a row dated the 5th is
+-- a row not yet in force for another two hours.
+--
+-- **OpenAI** prices `tts-1` at $15.00 and `tts-1-hd` at $30.00 **per 1M
+-- characters**, on the pricing page under audio. So `per = 1000000`, as the
+-- page quotes it. `gpt-4o-mini-tts` is on the same page at $0.60 per 1M text
+-- tokens in and $12.00 per 1M audio tokens out — per token, with audio output
+-- priced above text — and is **not here**: the `audio_output` reading of the
+-- component log does not exist yet, and a row priced on the text columns alone
+-- would under-count the audio by twenty times.
+--
+-- **ElevenLabs** bills text to speech per character and prints the rate **per
+-- 1,000 characters** on its API pricing page: $0.10 for v3 and Multilingual v2,
+-- $0.05 for Flash and v3 Conversational. So `per = 1000` — recorded as quoted,
+-- which is the reason `per` is a column rather than a convention (0058).
+--
+-- Three ElevenLabs rows and the exclusions are 0049's rule: `eleven_turbo_v2_5`
+-- and `eleven_turbo_v2` are listed deprecated on the models page;
+-- `eleven_flash_v2` is superseded by 2.5 at the same price with a smaller
+-- limit; `eleven_v3_conversational` publishes no character limit to hold the
+-- request to. Each of those is a row the day somebody asks for it.
+--
+-- ## The count is known before the request is sent
+--
+-- For every row here the bill is `characters × rate` and nothing else: the
+-- count is the length of the request's `input`, exact, and the response's usage
+-- is irrelevant to it. Two things follow that the route relies on:
+--
+--   The reservation **is** the settlement. There is no ceiling and no
+--   give-back; `x-cruise-budget-reserved` is the charge to the micro.
+--
+--   `usage_reported` is not consulted. `docs/modalities.md` section 4 narrows
+--   that flag to a statement about *where a count comes from*, and no count
+--   here comes from the response — so a speech row is billable to a billed
+--   tenant with the flag NULL, and `src/billing-block.ts` says so per modality
+--   rather than per response.
+--
+-- ## `max_input_chars`, and why it is a column
+--
+-- Both hosts refuse a request over a stated character ceiling: OpenAI at 4,096
+-- (API reference, `input`: "The maximum length is 4096 characters"), ElevenLabs
+-- per model on its models page. The route holds the request to it for the
+-- reason `checkLimits` holds `max_tokens` to `max_output` and the image route
+-- holds `n` to 10: the figure multiplies the reservation, and a request the
+-- host would refuse anyway must not first hold — or be refused *for* — a bound
+-- the size of its whole text. NULL means the host states none, and a chat row
+-- is NULL because the question does not arise for it.
+--
+-- Never written from memory: every figure below names the page it was read
+-- from and the date. 0011 and 0020 are why.
+
+ALTER TABLE models ADD COLUMN max_input_chars INTEGER
+  CHECK (max_input_chars IS NULL OR max_input_chars > 0);
+
+-- ── ElevenLabs, reached directly ──────────────────────────────────────────────
+--
+-- Not a gateway provider in any form, so `base_url` as 0050 built it for Meta.
+-- What is new is that the wire format is ElevenLabs' own — the voice is a path
+-- segment, the model a body field, the response raw audio — and
+-- `src/speech-elevenlabs.ts` is the mapping from OpenAI's `audio/speech` shape
+-- onto it. That mapping is the adapter, and it is the first this repo has
+-- needed; `docs/upstreams.md` tier 4 said a lab speaking a different wire
+-- format is real code, and this is the instance.
+--
+-- The credential is `PROVIDER_KEY_ELEVENLABS`, sent as the host's own
+-- `xi-api-key` header rather than as a bearer token, and the header set is a
+-- fresh object for a third party — never the gateway's with keys deleted.
+--
+-- `data_retention` is NULL and must not be guessed: the terms are a property
+-- of the plan the key bills on, so whoever sets the secret reads them and
+-- writes what they read, as 0049 asked for Google.
+
+INSERT INTO upstreams (id, name, kind, base_url) VALUES
+  ('elevenlabs', 'ElevenLabs', 'provider', 'https://api.elevenlabs.io/v1');
+
+INSERT INTO models (id, upstream_id, upstream_model, modality, max_input_chars,
+                    data_retention, data_retention_source, data_retention_as_of) VALUES
+  -- OpenAI: the same your-data page 0057 read for the image rows, one day
+  -- earlier; the terms are the account's, not the model's.
+  ('openai/tts-1',    'openai', 'tts-1',    'speech', 4096,
+   'retained', 'https://developers.openai.com/api/docs/guides/your-data', '2026-09-04'),
+  ('openai/tts-1-hd', 'openai', 'tts-1-hd', 'speech', 4096,
+   'retained', 'https://developers.openai.com/api/docs/guides/your-data', '2026-09-04'),
+  -- ElevenLabs: limits from https://elevenlabs.io/docs/models, read 2026-09-05.
+  ('elevenlabs/eleven_multilingual_v2', 'elevenlabs', 'eleven_multilingual_v2', 'speech', 10000,
+   NULL, NULL, NULL),
+  ('elevenlabs/eleven_flash_v2_5',      'elevenlabs', 'eleven_flash_v2_5',      'speech', 40000,
+   NULL, NULL, NULL),
+  ('elevenlabs/eleven_v3',              'elevenlabs', 'eleven_v3',              'speech', 5000,
+   NULL, NULL, NULL);
+
+-- `max_context` and `max_output` are NULL on all five, as on the image rows:
+-- both count tokens of a completion, and a speech model has none.
+--
+-- No `price_observations` row for any of these, and that is the point rather
+-- than a gap. A speech model has no token part — not a token part of zero
+-- recorded as a fact, but no term at all — so a row of zeros here would be a
+-- number nobody fetched and, worse, would read as "priced" to every gate the
+-- moment somebody forgot the character row. The gate reads the component log
+-- for this modality (`src/billing-block.ts`), and the catalogue prints the
+-- token rates as zero beside the character line because that is what a speech
+-- request pays per token.
+
+INSERT INTO price_components
+  (observed_at, model, effective_from, component, variant, micros, per, source, note)
+VALUES
+  ('2026-09-04 21:47:00', 'openai/tts-1',    '2026-09-04', 'character', '', 15000000, 1000000,
+   'https://developers.openai.com/api/docs/pricing',
+   'First observation (0059): $15.00 per 1M characters, read 2026-09-05 IST. The count is the request''s input; the reservation is the settlement.'),
+  ('2026-09-04 21:47:00', 'openai/tts-1-hd', '2026-09-04', 'character', '', 30000000, 1000000,
+   'https://developers.openai.com/api/docs/pricing',
+   'First observation (0059): $30.00 per 1M characters.'),
+
+  ('2026-09-04 21:47:00', 'elevenlabs/eleven_multilingual_v2', '2026-09-04', 'character', '', 100000, 1000,
+   'https://elevenlabs.io/pricing/api',
+   'First observation (0059): $0.10 per 1,000 characters, quoted per thousand and recorded as quoted.'),
+  ('2026-09-04 21:47:00', 'elevenlabs/eleven_flash_v2_5',      '2026-09-04', 'character', '', 50000, 1000,
+   'https://elevenlabs.io/pricing/api',
+   'First observation (0059): $0.05 per 1,000 characters — the models page says "50% lower price per character for API generations".'),
+  ('2026-09-04 21:47:00', 'elevenlabs/eleven_v3',              '2026-09-04', 'character', '', 100000, 1000,
+   'https://elevenlabs.io/pricing/api',
+   'First observation (0059): $0.10 per 1,000 characters.');
+
+-- ── The transport, which is measured before it is relied on ───────────────────
+--
+-- OpenAI's rows take the gateway's provider path, `…/openai/audio/speech`, on
+-- the same footing as 0057's image rows: documented for chat and responses,
+-- implied for the rest, and not measurable from outside a deployed Worker
+-- because both gateways authenticate before they route. The first conformance
+-- run against `PROVIDER_KEY_OPENAI` is the measurement, and the fallback is a
+-- `base_url` on the `openai` upstream row rather than a change of code —
+-- which would move chat and images direct too, and is therefore a decision
+-- for whoever measures.
+--
+-- Nothing is seeded routable. Every row here is unmeasured, and the speech
+-- check set (`src/conformance-speech.ts`) is what measures it: the response is
+-- audio in the format asked for and non-empty, for a fixed input. No chat
+-- flag applies, so a speech row that passes carries `measured_at` and every
+-- capability column NULL — which for this modality is *not applicable* rather
+-- than *unmeasured*, and the reference says so.

package/migrations/0060_embeddings.sql

@@ -0,0 +1,131 @@
+-- Embeddings: the modality that already fitted, and the one gate that would
+-- have refused every one of them (#230, slice 5 of #220, decided in
+-- `docs/modalities.md`).
+--
+-- The cheapest of the three non-chat routes, and last for that reason. An
+-- embedding is priced **per input token with no output**, which the three
+-- columns `price_observations` has held since 0048 express exactly: an
+-- `input_micros_per_mtok` and an `output_micros_per_mtok` of **0**. That zero
+-- is a fact rather than a placeholder — an embedding produces a vector, and a
+-- vector is not completion tokens — and it is why this slice needs no new
+-- price unit, no component row, and no new column on the price log.
+--
+-- ## What the hosts charge, read 2026-09-05
+--
+-- The wall clock that wrote this read 11:12 IST and the UTC date is the same
+-- day, so 0021's trap does not apply here and every date below is 2026-09-05.
+-- Stated rather than assumed, because it has been the other way twice: 0057
+-- and 0059 were both written after midnight UTC-plus-five-thirty and had to
+-- carry the previous day's date.
+--
+--   text-embedding-3-small   $0.02 / 1M tokens   1536 dimensions
+--   text-embedding-3-large   $0.13 / 1M tokens   3072 dimensions
+--   gemini-embedding-001     $0.15 / 1M tokens   3072 dimensions
+--
+-- Sources: https://developers.openai.com/api/docs/pricing and its embeddings
+-- guide for the dimensions and the 8,192-token input limit;
+-- https://ai.google.dev/gemini-api/docs/pricing and
+-- https://ai.google.dev/gemini-api/docs/embeddings for Google's. Both fetched
+-- 2026-09-05.
+--
+-- ## Two rows deliberately absent
+--
+-- **`text-embedding-ada-002`** is the previous generation: $0.10 per 1M
+-- tokens against `3-small`'s $0.02, at the same 1536 dimensions, and the
+-- host's own guide says a `3-large` embedding shortened to 256 outperforms an
+-- unshortened ada-002 at 1536. Five times the price for less. 0049's rule —
+-- the current catalogue minus what is retiring or superseded.
+--
+-- **`gemini-embedding-2-preview`** is the multimodal one, and leaving it out
+-- is the same decision 0059 made about `gpt-4o-mini-tts` and 0049 made about
+-- Gemini's audio input. Its bill has **per-image, per-second and per-frame**
+-- rates beside the text one, and `price_components` has no reader for any of
+-- the three (0058: a component in the vocabulary with no reader fails closed).
+-- A row carrying its text rate alone would price an image embedding at the
+-- text rate, which is under-counting — the direction 0011 exists to prevent
+-- and the one a cap cannot survive. #230 asked for "Gemini's text embedding,
+-- text input only"; the text-only model *is* that row, and the multimodal one
+-- waits for the readers rather than being half-priced.
+--
+-- ## The dimension is a published fact, and conformance needs it
+--
+-- What a check means for this modality is "a vector of the published
+-- dimension" (`docs/modalities.md` section 4), and until now nothing recorded
+-- what that dimension is. It is a property of the model as the host states
+-- it, like `max_context` and `max_output` beside it, so it goes in the same
+-- table rather than in the check — which would put a number nobody fetched
+-- into code, the failure 0011 and 0020 both name.
+--
+-- It is also the figure a caller sizes a vector column by, so `/v1/models`
+-- publishes it. `dimensions` on the request shortens the vector where the
+-- host supports it (OpenAI's `text-embedding-3` and later, Google's
+-- `output_dimensionality`); this column is what comes back when nothing asks.
+
+ALTER TABLE models ADD COLUMN dimensions INTEGER
+  CHECK (dimensions IS NULL OR dimensions > 0);
+
+INSERT INTO models (id, upstream_id, upstream_model, modality, max_context, dimensions,
+                    data_retention, data_retention_source, data_retention_as_of) VALUES
+  ('openai/text-embedding-3-small', 'openai', 'text-embedding-3-small', 'embedding', 8192, 1536,
+   'retained', 'https://developers.openai.com/api/docs/guides/your-data', '2026-09-05'),
+  ('openai/text-embedding-3-large', 'openai', 'text-embedding-3-large', 'embedding', 8192, 3072,
+   'retained', 'https://developers.openai.com/api/docs/guides/your-data', '2026-09-05'),
+  -- `data_retention` NULL on Google for 0049's reason and not for want of
+  -- looking: the terms follow the account tier rather than the model, so
+  -- whoever sets `PROVIDER_KEY_GOOGLE_AI_STUDIO` reads which tier that key
+  -- bills on and writes what they read.
+  ('google-ai-studio/gemini-embedding-001', 'google-ai-studio', 'gemini-embedding-001', 'embedding', 2048, 3072,
+   NULL, NULL, NULL);
+
+-- `max_context` is the host's stated **input** limit — 8,192 tokens on both
+-- OpenAI rows, 2,048 on Google's — and it is recorded rather than enforced.
+-- Enforcing it would need a token count for the input, and the only counter on
+-- the request path is the byte bound, which over-counts English roughly four
+-- times: refusing on it would refuse legitimate work, which is the trap
+-- `checkLimits` already describes for `max_context` on chat. The host refuses
+-- an over-long input loudly, and a loud refusal is what that rule prefers.
+--
+-- `max_output` is NULL on all three and that is the same fact as on the image
+-- and speech rows: it counts tokens of a completion, and there is none.
+
+INSERT INTO price_observations
+  (observed_at, model, effective_from, prompt_tokens_from, peak_utc,
+   input_micros_per_mtok, output_micros_per_mtok, cached_input_micros_per_mtok, source, note)
+VALUES
+  ('2026-09-05 05:42:00', 'openai/text-embedding-3-small', '2026-09-05', 0, '',
+    20000, 0, NULL, 'https://developers.openai.com/api/docs/pricing',
+   'First observation (0060): $0.02 per 1M input tokens. The output rate is 0 because an embedding has no completion — a fact, not a placeholder.'),
+  ('2026-09-05 05:42:00', 'openai/text-embedding-3-large', '2026-09-05', 0, '',
+   130000, 0, NULL, 'https://developers.openai.com/api/docs/pricing',
+   'First observation (0060): $0.13 per 1M input tokens.'),
+  ('2026-09-05 05:42:00', 'google-ai-studio/gemini-embedding-001', '2026-09-05', 0, '',
+   150000, 0, NULL, 'https://ai.google.dev/gemini-api/docs/pricing',
+   'First observation (0060): $0.15 per 1M input tokens, the text-only Gemini embedding. The multimodal gemini-embedding-2 is not in this catalogue — see the migration.');
+
+-- `cached_input_micros_per_mtok` is NULL rather than 0: neither host prints a
+-- cached rate for an embedding, and NULL is "not published" where 0 would be
+-- "free". `priceUsage` charges the full input rate for a cached token it has
+-- no rate for, which over-counts, and over-counting is the safe direction.
+--
+-- ## What this makes true of the whole catalogue
+--
+-- With `/v1/embeddings` served, **every modality the schema allows has a
+-- route**. `blocked_by: 'unrouted'` — the state 0056 introduced for a row
+-- catalogued ahead of its route — is now unreachable, and stays in the code
+-- and in the published enum because the next modality will need it. The
+-- assertion that keeps that honest is in `test/modality.test.ts`, and it fails
+-- the day a fifth value is added to the CHECK constraint without a route,
+-- which is exactly when somebody should be reading `docs/modalities.md`.
+--
+-- ## The transport, measured before it is relied on
+--
+-- The same open question 0057 and 0059 left, for the third time: `/compat` is
+-- chat-only, so an embedding request takes the gateway's provider path, which
+-- is documented for chat and implied for the rest. It could not be measured
+-- from outside a deployed Worker — both gateways authenticate before they
+-- route — so the first conformance run against a held credential is the
+-- measurement. Google's OpenAI-compatibility layer does document
+-- `client.embeddings.create` against `gemini-embedding-001`
+-- (https://ai.google.dev/gemini-api/docs/openai, read 2026-09-05), so what is
+-- unmeasured is the gateway leg rather than the host's own shape. The
+-- fallback, as before, is a `base_url` on the upstream row rather than code.

package/migrations/0061_data_retention_backfill.sql

@@ -0,0 +1,121 @@
+-- What each host does with a prompt, written down for the first time (#195).
+--
+-- `models.data_retention` has existed since 0007 and **no migration wrote it
+-- until the labs arrived**. The gate that reads it is correct and has been
+-- since 0030 — `no-training-on-data` allows `none` and `retained`, so NULL
+-- fails closed — and it has been guarding nothing, because a gate with no data
+-- refuses good models and catches no bad ones. That is the third instance of
+-- one shape in this repository: `max_output` before 0023, `ACCOUNT_ID_SALT`
+-- before #172, and this.
+--
+-- It has been harmless by luck rather than by design. Measured on production
+-- 2026-09-05: **50 of 69 enabled rows carry no value**, and every enabled lane
+-- has at least one such member — `bb/chat-assistant`, `bb/agentic-coding`,
+-- `bb/code-completion`, `bb/code-review` and `bb-adm/code-review` among them.
+-- Allocation is price-first, so end-user content goes to whichever of those is
+-- cheapest this hour, with no retention gate consulted, which is the failure
+-- `docs/auto-mode.md` names in as many words.
+--
+-- ## What was read, 2026-09-05, and it splits cleanly in two
+--
+-- **Two hosts state their terms for the API plainly, and those are written
+-- below.** The other four make the answer depend on a setting only the account
+-- holder can see, and for those NULL stays — with the reason recorded, which is
+-- the difference between "nobody looked" and "looked, and it depends on us".
+--
+-- Retention is a property of the **host**, not of the model, which is why each
+-- statement below updates by `upstream_id` rather than listing ids. A model
+-- moving hosts would move its answer with it, and a row added to one of these
+-- upstreams later inherits nothing — which is what the test in
+-- `test/catalogue.test.ts` is for.
+
+-- ── Workers AI: `none` ────────────────────────────────────────────────────────
+-- https://developers.cloudflare.com/workers-ai/platform/data-usage/, read
+-- 2026-09-05:
+--
+--   "Cloudflare does not use your Customer Content to (1) train any AI models
+--    made available on Workers AI or (2) improve any Cloudflare or third-party
+--    services, and would not do so unless we received your explicit consent."
+--
+--   "Your Customer Content for Workers AI may be stored by Cloudflare if you
+--    specifically use a storage service (e.g., R2, KV, DO, Vectorize, etc.) in
+--    conjunction with Workers AI."
+--
+-- So the prompt is not retained unless *we* store it, and Cruise stores no
+-- payload: `gw-sensitive` is the default gateway and logs none, which is the
+-- invariant at the top of CLAUDE.md. `none` rather than `retained`, and the
+-- distinction is real — `retained` would claim a copy exists somewhere.
+
+UPDATE models
+   SET data_retention        = 'none',
+       data_retention_source = 'https://developers.cloudflare.com/workers-ai/platform/data-usage/',
+       data_retention_as_of  = '2026-09-05'
+ WHERE upstream_id = 'workers-ai';
+
+-- ── xAI: `retained` ───────────────────────────────────────────────────────────
+-- https://docs.x.ai/developers/faq/security, read 2026-09-05:
+--
+--   "All API requests and responses are stored on our servers (encrypted at
+--    rest) for 30 days for auditing purposes in the event of suspected abuse or
+--    misuse."
+--
+--   "xAI never trains on your API inputs or outputs without your explicit
+--    permission."
+--
+-- Kept and not trained on, which is exactly what `retained` means. The thirty
+-- days and the encryption are not modelled — the column has three values and a
+-- fourth would be a schema change for a fact no gate reads.
+
+UPDATE models
+   SET data_retention        = 'retained',
+       data_retention_source = 'https://docs.x.ai/developers/faq/security',
+       data_retention_as_of  = '2026-09-05'
+ WHERE upstream_id = 'grok';
+
+-- ── Mistral and DeepSeek: NULL stays, and this is the finding ─────────────────
+--
+-- Both carry **production traffic today**, and neither can be given a value
+-- from its own pages, because for both the answer is an account setting.
+--
+-- **Mistral.** help.mistral.ai, "Do you use my user data to train your
+-- artificial intelligence models?", read 2026-09-05: on the API's free mode
+-- *"we may use your data (input and output) to train our artificial
+-- intelligence models"*, with a right to opt out; on pay-as-you-go
+-- *"customers retain full control over this processing and have the right to
+-- opt out at any time"*. So the default is training and the remedy is a
+-- setting. Nine rows, and `mistral/mistral-small-latest`, `codestral-2508`,
+-- `mistral-medium-2604`, `ministral-3b-2512` and `ministral-8b-2512` are
+-- members of four live lanes between them.
+--
+-- **DeepSeek.** The Open Platform Terms of Service say nothing about training
+-- or retention at all — section 4.2 assigns rights in Inputs and Outputs and
+-- stops there. The privacy policy is not API-specific and says data is used
+-- *"to train and improve our technology, such as our machine learning models
+-- and algorithms"*, with *"the right to opt-out of using your Personal Data
+-- for training our models"*. Three rows, in three live lanes.
+--
+-- **Neither is written as `trains`**, and that is deliberate rather than
+-- generous. `trains` would be a claim about what our account actually does,
+-- and nobody has read our own opt-out state; a guess in the safe direction is
+-- still a guess, and 0011 and 0020 are both migrations undoing exactly that.
+-- NULL and `trains` are identical at the gate — both fail `no-training-on-data`
+-- closed — so nothing is served differently by leaving it. What differs is
+-- what a person reads, and NULL with this comment beside it is the honest one.
+--
+-- **What resolves them is not a migration.** Whoever holds each account opens
+-- it, reads the training setting, and writes what they read — the same act
+-- 0049 asked for on Google and 0059 on ElevenLabs. Until then these ten rows
+-- are the reason a lane requiring `no-training-on-data` is nearly empty.
+
+-- Google AI Studio (five rows, 0049) and ElevenLabs (three rows, 0059) are
+-- untouched here for the same reason and already carry it in their own
+-- migrations: Google's terms follow the account tier, ElevenLabs' the plan.
+
+-- ## What this migration deliberately does not change
+--
+-- **Allocation.** A lane still ranks price-first and consults retention only
+-- where the lane carries the requirement. Ranking an unknown-retention member
+-- below a known-safe one is the change #195 asks for next, and it is a change
+-- to what live traffic does with a cost attached — `bb/chat-assistant` would
+-- start preferring Workers AI rows over cheaper Mistral ones — so it is a
+-- decision with a price, made by somebody, not a line smuggled into a backfill.