@bytesbrains/cruise-worker 0.0.0-stage → 0.12.0

package/migrations/0053_anthropic_groq_and_xai.sql

@@ -0,0 +1,172 @@
+-- Three labs we hold keys for and had no rows against (#188).
+--
+-- All three are on Cloudflare's unified `/compat` endpoint, so this is the tier-1
+-- shape [`upstreams.md`](../docs/upstreams.md) describes — a key, a migration
+-- and a conformance run — with one addition: **xAI has no `upstreams` row**, and
+-- gets one here. That is tier 3, and it is still no request-path code.
+--
+-- Every figure fetched 2026-09-02 UTC from the host's own pages, cited per
+-- section. The wall clock read after midnight IST; the dates are the 2nd because
+-- `pricesInForce` resolves against `date('now')`, which is UTC. Same trap as
+-- 0020, 0021, 0050 and 0052.
+--
+-- **`data_retention` is read for two of the three, and NULL for the third
+-- because its terms could not be read.** The first draft of this migration left
+-- all ten NULL and called that a principle; it was not one. The rule is that a
+-- term is written only when somebody read it on the host's page, and nobody had
+-- looked. Raised in review of PR #206, and the reviewer was right.
+--
+-- Anthropic and Groq both answer plainly and are recorded per model below.
+-- **xAI could not be read**: `x.ai/legal/privacy-policy` and
+-- `x.ai/legal/terms-of-service-enterprise` both answer 403 to an ordinary
+-- fetch, and `docs.x.ai/docs/data-privacy` is a 404. So those four rows keep
+-- NULL, which fails closed — refused by any lane carrying
+-- `no-training-on-data` — and the attempts are recorded here so the next person
+-- does not repeat them. #195 owns the column across the whole catalogue.
+
+-- ── xAI ───────────────────────────────────────────────────────────────────────
+-- **The upstream id must be `grok`, not `xai`.** `upstreamModelString` builds
+-- `<upstream_id>/<model>` and that string is what the gateway parses to select a
+-- provider; Cloudflare's slug is `grok` and its documented model form is
+-- `grok/{model}`. An `xai` row would produce `xai/grok-4.6`, which the gateway
+-- does not recognise. The derived secret is therefore `PROVIDER_KEY_GROK`, which
+-- is what is set on both environments.
+INSERT INTO upstreams (id, name, kind) VALUES ('grok', 'xAI', 'compat');
+
+-- Prices and windows: https://docs.x.ai/docs/models.
+--
+-- Every model is priced in two tiers by prompt size, and the boundary is stated
+-- as **"< 200k" / "≥ 200k"** — so `prompt_tokens_from` is 200000, at the
+-- boundary. Note this differs from Gemini's `> 200k` in 0049, which starts at
+-- 200001. The two hosts genuinely differ by one token and the column means "at
+-- least this long", so both are written as the page states rather than made
+-- uniform.
+--
+-- No page states a maximum output for any Grok model, so `max_output` is NULL
+-- and `checkLimits` derives a bound from the window (0023). `data_retention` is
+-- NULL for the reason in the header: xAI's legal pages refuse an ordinary
+-- fetch, so nobody has read the terms. Not an assumption that they train — an
+-- absence of evidence either way, which is what NULL means.
+INSERT INTO models (id, upstream_id, upstream_model, max_context, max_output) VALUES
+  ('grok/grok-4.6',        'grok', 'grok-4.6',        500000,  NULL),
+  ('grok/grok-4.5',        'grok', 'grok-4.5',        500000,  NULL),
+  ('grok/grok-4.3',        'grok', 'grok-4.3',       1000000,  NULL),
+  ('grok/grok-build-0.1',  'grok', 'grok-build-0.1',  256000,  NULL);
+
+-- The `grok-4.20-0309-*` variants are left out: the pricing page gives them "the
+-- same pricing as grok-4.3" rather than a row of their own, and a rate quoted by
+-- reference to another model is not a rate this table should hold. They also
+-- carry a dated snapshot id, so they are a pin of something already listed.
+-- `grok-imagine-*` generate images and video and are not chat models.
+
+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-02 00:00:00', 'grok/grok-4.6', '2026-09-02',      0, '',
+   2000000,  6000000,  500000, 'https://docs.x.ai/docs/models', 'First observation: xAI added to the catalogue (0053).'),
+  ('2026-09-02 00:00:00', 'grok/grok-4.6', '2026-09-02', 200000, '',
+   4000000, 12000000, 1000000, 'https://docs.x.ai/docs/models', 'Long-prompt tier, stated as prompts at or above 200k tokens.'),
+  ('2026-09-02 00:00:00', 'grok/grok-4.5', '2026-09-02',      0, '',
+   2000000,  6000000,  300000, 'https://docs.x.ai/docs/models', 'First observation: xAI added to the catalogue (0053).'),
+  ('2026-09-02 00:00:00', 'grok/grok-4.5', '2026-09-02', 200000, '',
+   4000000, 12000000,  600000, 'https://docs.x.ai/docs/models', 'Long-prompt tier, stated as prompts at or above 200k tokens.'),
+  ('2026-09-02 00:00:00', 'grok/grok-4.3', '2026-09-02',      0, '',
+   1250000,  2500000,  200000, 'https://docs.x.ai/docs/models', 'First observation: xAI added to the catalogue (0053).'),
+  ('2026-09-02 00:00:00', 'grok/grok-4.3', '2026-09-02', 200000, '',
+   2500000,  5000000,  400000, 'https://docs.x.ai/docs/models', 'Long-prompt tier, stated as prompts at or above 200k tokens.'),
+  ('2026-09-02 00:00:00', 'grok/grok-build-0.1', '2026-09-02',      0, '',
+   1000000,  2000000,  200000, 'https://docs.x.ai/docs/models', 'First observation: xAI added to the catalogue (0053).'),
+  ('2026-09-02 00:00:00', 'grok/grok-build-0.1', '2026-09-02', 200000, '',
+   2000000,  4000000,  400000, 'https://docs.x.ai/docs/models', 'Long-prompt tier, stated as prompts at or above 200k tokens.');
+
+-- ── Anthropic ─────────────────────────────────────────────────────────────────
+-- Prices: https://platform.claude.com/docs/en/about-claude/pricing.
+-- Ids, windows and maximum output: the models overview on the same host.
+--
+-- `cached_input` is the **cache read** rate, which is the one a served request
+-- pays. The page also prints two cache *write* rates (1.25x and 2x base, by TTL)
+-- and this table has no column for either, so a cached-write-heavy workload is
+-- under-counted here. Recorded rather than hidden: it is the same shape of gap
+-- as the audio rates 0049 excluded Gemini rows over, and it belongs to whoever
+-- takes #5.
+--
+-- Claude Fable 5.1 is the exception the page flags itself: its cache read is
+-- 0.025x base rather than the usual 0.1x, which is why $10 input pairs with
+-- $0.25 rather than $1.
+-- `retained` on the host's own words: *"By default, we will not use your inputs
+-- or outputs from our commercial products to train our models."* Retention with
+-- no training right is exactly what the middle value means.
+INSERT INTO models (id, upstream_id, upstream_model, max_context, max_output,
+                    data_retention, data_retention_source, data_retention_as_of) VALUES
+  ('anthropic/claude-fable-5-1',           'anthropic', 'claude-fable-5-1',           1000000, 128000,
+   'retained', 'https://privacy.claude.com/en/articles/7996868-is-my-data-used-for-model-training', '2026-09-02'),
+  ('anthropic/claude-opus-5',              'anthropic', 'claude-opus-5',              1000000, 128000,
+   'retained', 'https://privacy.claude.com/en/articles/7996868-is-my-data-used-for-model-training', '2026-09-02'),
+  ('anthropic/claude-sonnet-5',            'anthropic', 'claude-sonnet-5',            1000000, 128000,
+   'retained', 'https://privacy.claude.com/en/articles/7996868-is-my-data-used-for-model-training', '2026-09-02'),
+  -- The one id here that is dated. Its alias `claude-haiku-4-5` resolves to this
+  -- snapshot, and 0020's rule is that the table pins what the alias points at.
+  ('anthropic/claude-haiku-4-5-20251001',  'anthropic', 'claude-haiku-4-5-20251001',  200000,  64000,
+   'retained', 'https://privacy.claude.com/en/articles/7996868-is-my-data-used-for-model-training', '2026-09-02');
+
+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-02 00:00:00', 'anthropic/claude-fable-5-1', '2026-09-02', 0, '',
+   10000000, 50000000, 250000, 'https://platform.claude.com/docs/en/about-claude/pricing',
+   'First observation: Anthropic added to the catalogue (0053). Cache read is 0.025x base on this model, which the page states explicitly.'),
+  ('2026-09-02 00:00:00', 'anthropic/claude-opus-5', '2026-09-02', 0, '',
+    5000000, 25000000, 500000, 'https://platform.claude.com/docs/en/about-claude/pricing',
+   'First observation: Anthropic added to the catalogue (0053).'),
+  ('2026-09-02 00:00:00', 'anthropic/claude-sonnet-5', '2026-09-02', 0, '',
+    2000000, 10000000, 200000, 'https://platform.claude.com/docs/en/about-claude/pricing',
+   'First observation: Anthropic added to the catalogue (0053). The page notes the scheduled rise to $3/$15 on 2026-09-01 will not occur, so this is the standard rate rather than an introductory one.'),
+  ('2026-09-02 00:00:00', 'anthropic/claude-haiku-4-5-20251001', '2026-09-02', 0, '',
+    1000000,  5000000, 100000, 'https://platform.claude.com/docs/en/about-claude/pricing',
+   'First observation: Anthropic added to the catalogue (0053).');
+
+-- ── Groq ──────────────────────────────────────────────────────────────────────
+-- Prices, windows and maximum output: https://console.groq.com/docs/models.
+--
+-- **Two rows out of nine, and the reason is worth reading.** Groq's API serves
+-- nine chat models to this key, and the console prices exactly two of them. The
+-- Llama rows say "Contact Sales", and `groq/compound`, `groq/compound-mini`,
+-- `qwen/qwen3.6-27b`, `qwen/qwen3.8-27b` and `allam-2-7b` print no rate at all.
+-- An unpriced model is charged its **whole reservation** rather than its usage,
+-- so inserting them would quietly distort every budget they touched.
+--
+-- The two that are priced are both models this catalogue already holds through
+-- Workers AI, and that is the point rather than a redundancy to trim. Groq is
+-- **cheaper on both axes** — $0.15/$0.60 against Workers AI's $0.35/$0.75 for
+-- the 120b — on a separate billing relationship, which is exactly the
+-- independence argument #188 makes from the day the DeepSeek account went
+-- overdrawn and every `deepseek/…` request answered 402 for twenty hours.
+--
+-- Neither price row states a cached-input rate, so it stays NULL and a cache hit
+-- is billed at the full input rate. The safe direction, and still drift.
+-- `retained`, and Groq's services agreement is the clearest of the three:
+-- *"Groq is not permitted to use Inputs or Outputs for training or fine-tuning
+-- any AI Model Services or other models, unless explicitly granted permission
+-- or instructed by Customer."* Its privacy policy is the wrong document and says
+-- so — it *"does not apply to the information that we process as a 'data
+-- processor' on behalf of customers"* — which is worth knowing before reading it
+-- and concluding nothing.
+INSERT INTO models (id, upstream_id, upstream_model, max_context, max_output,
+                    data_retention, data_retention_source, data_retention_as_of) VALUES
+  ('groq/openai/gpt-oss-120b', 'groq', 'openai/gpt-oss-120b', 131072, 65536,
+   'retained', 'https://console.groq.com/docs/legal/services-agreement', '2026-09-02'),
+  ('groq/openai/gpt-oss-20b',  'groq', 'openai/gpt-oss-20b',  131072, 65536,
+   'retained', 'https://console.groq.com/docs/legal/services-agreement', '2026-09-02');
+
+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-02 00:00:00', 'groq/openai/gpt-oss-120b', '2026-09-02', 0, '',
+   150000, 600000, NULL, 'https://console.groq.com/docs/models',
+   'First observation: Groq added to the catalogue (0053).'),
+  ('2026-09-02 00:00:00', 'groq/openai/gpt-oss-20b', '2026-09-02', 0, '',
+    75000, 300000, NULL, 'https://console.groq.com/docs/models',
+   'First observation: Groq added to the catalogue (0053).');

package/migrations/0054_tier_service_keys.sql

@@ -0,0 +1,60 @@
+-- A service key that can change a tenant's tier and do nothing else (#203).
+--
+-- The gap: #191 made a tier changeable and gave it one caller, `npm run
+-- tier:set` — a person at a terminal holding a Cloudflare API token and a
+-- checkout of this repo. So a customer who outgrows Free is still stopped at
+-- the write, and the answer is still "ask us", which arrives at the moment
+-- they are trying to give us money. `setTier` already does the hard parts: it
+-- refuses a downgrade the tenant does not fit and it writes the audit row
+-- that was #191's actual gap. What it lacks is a caller that is not a laptop.
+--
+-- 0034 said a tier is the name that ties a subscription to its quotas, so the
+-- thing that learns a subscription changed is the thing that should set it —
+-- the payments plane, beside `credits`, `balance` and `provision`, rather than
+-- a platform-operator role invented under `/admin` to carry one command (#91).
+--
+-- `purpose` gains a fourth value on 0038's terms, not beyond them: one
+-- capability per key, issued for one value and never two. `tier` reads a
+-- tenant's tier, caps and usage and sets it; it mints nothing, creates
+-- nothing, and cannot see a balance. A `provision` key is refused at the tier
+-- write for 0042's reason turned around — creating a namespace and changing
+-- what it is entitled to are separate powers, and the second one has a price
+-- attached.
+--
+-- The one route the two share is the uid → tenants lookup, which both a
+-- provision and a tier key may make: it answers "which tenants does this
+-- person already have", which is the question each of them must ask *before*
+-- writing anything, and neither can act on it without its own capability.
+--
+-- Naming that as the widening it is: it is the first read a `provision` key
+-- gets of state it did not write, so a leaked provisioning credential now
+-- learns which tenants a uid it guesses belongs to. Accepted because that key
+-- already learns an owner uid from `tenant_owner_conflict` and creates the
+-- tenants it would be asking about, and because the alternative — a second
+-- credential on the provisioning screen for one read — is the shape 0038 was
+-- written to avoid. The trigger to split it is a provision key held by anybody
+-- who is not the party that provisions.
+--
+-- SQLite cannot widen a CHECK in place, so the table is rebuilt, and 0038's
+-- and 0042'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 a `tier` 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')),
+  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/0055_output_defaults.sql

@@ -0,0 +1,79 @@
+-- What happens when the caller states no `max_tokens` (#217).
+--
+-- #219 stopped the reservation guessing: an unread output cap became unknown
+-- rather than the whole context window, which had produced a 4,456,448µ bound
+-- on `bb-adm/code-review` for requests that cost about 30µ. What it left is a
+-- request nobody can bound — served on the flat floor for internal traffic,
+-- refused outright for a billed tenant.
+--
+-- Filling `models.max_output` was the obvious next step and turns out to rest
+-- on a premise that does not hold. Read 2026-09-04: **no host in this catalogue
+-- publishes an output ceiling.** Cloudflare's per-model pages publish a context
+-- window and `max_tokens` as a parameter with `default: 256`; Mistral's API
+-- reference publishes one rule, "the token count of your prompt plus
+-- `max_tokens` cannot exceed the model's context length"; Meta publishes
+-- neither. So there is nothing to read into the column that exists.
+--
+-- What there *is* to read is a different fact, and the question it answers is
+-- the one that actually governs an unbounded request: **what does this platform
+-- do when the caller sends nothing.** Two columns, because the answer lives at
+-- two levels and pretending otherwise is what made `max_output` ambiguous:
+--
+--   upstreams.default_output   the platform's own API default. Cloudflare's is
+--                              256, documented identically on every model page
+--                              — verified on four spanning four families
+--                              (llama-3.3-70b-instruct-fp8-fast, gpt-oss-120b,
+--                              qwq-32b, mistral-small-3.1-24b-instruct) on
+--                              2026-09-04. It is a property of the API, not of
+--                              any model, which is why it belongs here.
+--
+--   models.default_output      an override for a model that differs from its
+--                              platform. Null means inherit. Nothing sets it
+--                              today; it exists so the first model that
+--                              contradicts its host is a row rather than a
+--                              rewrite.
+--
+-- **Null at both levels stays unbounded, deliberately.** Mistral and Meta
+-- publish no default, and their effective behaviour is to run to the context
+-- window — which is exactly the bound #219 removed for being true and useless.
+-- Recording "we read it and there is nothing" is the honest state, and it keeps
+-- those requests on the path that says so: the flat floor internally, and a
+-- `request_unbounded` a billed tenant can act on. `docs/upstreams.md` takes the
+-- same position on `data_retention`: the read-and-absent case and the not-yet-
+-- read case look identical in the column and are distinguished here, in the
+-- migration, rather than by a second column nothing would branch on.
+--
+-- The value is not a ceiling and must never be used as one. `checkLimits` still
+-- validates a caller's own `max_tokens` against `max_output` and the window; a
+-- default is what happens in the absence of a request, not a limit on one.
+--
+-- Positive or absent, on both: zero is not a default, it is a model that emits
+-- nothing, and a negative one is a typo that would bound every request at the
+-- flat floor while looking like a limit that had been read. Raised by review of
+-- PR #221, and the same guard `projects.default_max_tokens` carries below.
+ALTER TABLE upstreams ADD COLUMN default_output INTEGER
+  CHECK (default_output IS NULL OR default_output > 0);
+ALTER TABLE models ADD COLUMN default_output INTEGER
+  CHECK (default_output IS NULL OR default_output > 0);
+
+UPDATE upstreams SET default_output = 256 WHERE id = 'workers-ai';
+
+-- The per-project cap, for a caller that would rather state it once than on
+-- every request (#217).
+--
+-- A billed tenant is refused an unbounded request, because a reservation that
+-- is not a bound is the gap a wallet cannot survive (#96) — and the alternative
+-- considered first was for Cruise to inject a platform-wide `max_tokens` on
+-- everyone's behalf. That was rejected on this repo's own evidence: #142
+-- documents sixty production rows where a cap on a reasoning model produced a
+-- completion of pure reasoning and no content at all — a 200, a bill, and
+-- nothing to show. Imposing a cap manufactures that failure for requests that
+-- did not ask for one, and silent truncation is a worse answer than a refusal
+-- naming what to send.
+--
+-- So the cap is the project's own decision, opt-in, null meaning no default.
+-- Where it is set, Cruise sends it upstream, which is what makes it a *bound*
+-- rather than an assumption: the figure the reservation holds is the figure the
+-- provider was told to stop at.
+ALTER TABLE projects ADD COLUMN default_max_tokens INTEGER
+  CHECK (default_max_tokens IS NULL OR default_max_tokens > 0);

package/migrations/0056_model_modality.sql

@@ -0,0 +1,37 @@
+-- What a row *is*, now that not every row will be a chat model (#226, #220).
+--
+-- `models` has never needed to say. Every route is chat, so every row was, and
+-- nothing had a reason to ask. `docs/modalities.md` decided 2026-09-04 that the
+-- data plane grows past chat — images first, then speech, then embeddings —
+-- and the moment one such row exists two things go wrong silently:
+--
+--   The chat route forwards a chat body to it. The provider's 400 looks like
+--   the caller's fault, which is the shape docs/v0.md §3 already names for a
+--   misconfigured `upstream_model`, and nothing on our side said no.
+--
+--   `/v1/models` lists it as a chat-capable row with every capability NULL —
+--   which reads as "unmeasured", the honest state for a chat model nobody has
+--   run the suite against, and is instead a model the suite could never
+--   measure that way at all.
+--
+-- One column, closed set, defaulted to the only value that has ever been true.
+-- Every existing row is `chat`, and that is a fact rather than a placeholder:
+-- 0050 and 0052 left `muse-image-1.0` and `muse-voice-transcribe-1.0` out of
+-- the catalogue precisely because there was nowhere to say what they were.
+--
+-- The set is the four modalities the decision names and no more. A fifth is a
+-- migration, on purpose — `job` in 0029 took the same position, so that a new
+-- word is a decision somebody wrote down rather than a string somebody typed.
+-- Video is deliberately absent: #220 says nobody is blocked on it, and a value
+-- nothing can route would read exactly like one something can.
+--
+-- What reads it, in this migration's companion change: the chat route refuses
+-- any other value with `unsupported_capability` (the request needs a capability
+-- the model lacks, and the code exists); a lane write refuses members of two
+-- modalities, so a lane is never mixed; `/v1/models` and `/admin/models` carry
+-- it; the conformance runner measures chat rows only, since its checks are
+-- chat checks and a fail recorded against an image model would blame the
+-- wrong thing. No new route, no new price unit, no new capability column —
+-- those are #227 to #231, and each assumes this.
+ALTER TABLE models ADD COLUMN modality TEXT NOT NULL DEFAULT 'chat'
+  CHECK (modality IN ('chat', 'image', 'speech', 'embedding'));

package/migrations/0057_openai_image_models.sql

@@ -0,0 +1,177 @@
+-- The first non-chat rows that a route can reach, and the bound that makes one
+-- billable (#227, slice 2 of #220, decided in `docs/modalities.md`).
+--
+-- 0056 gave a row a modality and nothing else; every value but `chat` named a
+-- thing the data plane could not serve. This is the first that it can.
+--
+-- ## What the host charges, read 2026-09-04
+--
+-- The issue that opened this assumed images are priced per image. They are not,
+-- on this host: `gpt-image-*` prices a generation **per token** — text prompt
+-- tokens in, image tokens out — and the response carries both in `usage`. So
+-- the three columns `price_observations` already has price an image generation
+-- exactly, and slice 2 needs **no new price unit**. That is the whole reason
+-- images come before speech, which does need one (#228).
+--
+-- Source: https://developers.openai.com/api/docs/pricing, fetched 2026-09-04
+-- **UTC** — and this is the first migration here where that word earns its
+-- keep. The wall clock that wrote it read 01:47 on the **5th**, in +05:30, and
+-- the two are the same instant. Every date below is the UTC one, because that
+-- is what `date('now')` returns and therefore what `effective_from <= date('now')`
+-- compares against: a row dated the 5th is a row not yet in force, so the
+-- catalogue would have read these three as unpriced for another four hours.
+-- 0021 corrected exactly this after the fact; here it was caught by the test
+-- that prices every inserted model, which is the check 0021 left behind.
+--
+-- Three rows, and the exclusions are 0049's rule again — the current catalogue
+-- minus what is retiring, aliased, or unpriceable:
+--
+--   gpt-image-1           superseded by 2, and dearest of the four on output
+--                         ($40/Mtok against $30). A weekly conformance bill for
+--                         a model a price-first lane would never pick.
+--   chatgpt-image-latest  an alias, priced identically to 1.5. 0020's rule: an
+--                         alias moving is a rate change with no signal.
+--
+-- **The image *input* rate is deliberately not recorded.** The page prints one
+-- ($8.00/Mtok on 2 and 1.5, $2.50 on mini) and it applies to an *edit*, where a
+-- reference image is sent in. This ledger has one input rate per row, so writing
+-- the image rate would misprice every generation and writing both is what
+-- `price_components` exists for (#228). Until that lands, `/v1/images/edits` is
+-- not served at all — a route that cannot bill correctly is better absent than
+-- present and under-counting, which is the direction 0011 exists to prevent.
+-- `src/images.ts` refuses a *generation* whose response reports image input
+-- tokens for the same reason: it charges the reservation rather than a figure it
+-- knows is short.
+
+INSERT INTO models (id, upstream_id, upstream_model, modality,
+                    data_retention, data_retention_source, data_retention_as_of) VALUES
+  ('openai/gpt-image-2',      'openai', 'gpt-image-2',      'image',
+   'retained', 'https://developers.openai.com/api/docs/guides/your-data', '2026-09-04'),
+  ('openai/gpt-image-1.5',    'openai', 'gpt-image-1.5',    'image',
+   'retained', 'https://developers.openai.com/api/docs/guides/your-data', '2026-09-04'),
+  ('openai/gpt-image-1-mini', 'openai', 'gpt-image-1-mini', 'image',
+   'retained', 'https://developers.openai.com/api/docs/guides/your-data', '2026-09-04');
+
+-- `max_context` and `max_output` are NULL on all three, and that is a fact
+-- rather than a gap. Both mean tokens of a *completion*, and the host publishes
+-- neither for an image model: what bounds an image request is how many output
+-- tokens one image at one size and quality costs, which is the table below.
+-- `checkLimits` reads those two columns and is a chat gate; the image route
+-- reads the variants instead (`src/routing-image.ts`).
+
+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-04 00:00:00', 'openai/gpt-image-2',      '2026-09-04', 0, '',
+    5000000, 30000000, 1250000, 'https://developers.openai.com/api/docs/pricing',
+   'First observation: the first image models in the catalogue (0057). Text input, image output, cached text input. The image *input* rate is not this column — see the migration.'),
+  ('2026-09-04 00:00:00', 'openai/gpt-image-1.5',    '2026-09-04', 0, '',
+    5000000, 32000000, 1250000, 'https://developers.openai.com/api/docs/pricing',
+   'First observation: the first image models in the catalogue (0057).'),
+  ('2026-09-04 00:00:00', 'openai/gpt-image-1-mini', '2026-09-04', 0, '',
+    2000000,  8000000,  200000, 'https://developers.openai.com/api/docs/pricing',
+   'First observation: the first image models in the catalogue (0057).');
+
+-- No long-context tier, unlike the 5.6 rows 0049 wrote: the page prints one rate
+-- per column for these and the models' own pages state no threshold. Batch
+-- pricing is printed beside it at half, and is not recorded for 0049's reason —
+-- Cruise sends standard requests, and a second rate with nothing selecting
+-- between them is a chance to bill the wrong one.
+
+-- ── The bound ─────────────────────────────────────────────────────────────────
+--
+-- A reservation must cover what a request could cost before the response says
+-- what it did. For chat that figure is `max_tokens` or the model's published
+-- output cap. For an image it is **the output tokens one image costs at the size
+-- and quality asked for**, times `n`.
+--
+-- **The host does not publish that grid.** Checked 2026-09-04: the pricing page
+-- gives one output rate per model in dollars per million tokens and says *"for
+-- image generation cost estimates, use the calculator in the image generation
+-- guide"*; the guide lists the sizes and the quality tiers and no token counts;
+-- the model pages carry none. There is a calculator and no table.
+--
+-- So the figure is **measured, not fetched** — which is this repository's rule
+-- for capabilities already, arriving at prices' door. A variant is a row here
+-- because a generation at that size and quality was made and its `usage`
+-- read. That has three consequences worth stating before they surprise someone:
+--
+--   Nothing is seeded. This migration writes **no variant rows**, so until
+--   conformance runs there is not one image request Cruise will bound — which
+--   is moot, because `measured_at` is NULL on all three rows and an unmeasured
+--   model is not routable anyway. The order is 0049's: inserting is not
+--   admitting.
+--
+--   A variant nobody has measured is refused rather than guessed, with
+--   `limit_exceeded` naming what *is* measured. Over-reserving refuses a
+--   request that would have fit; guessing low sells an image for less than it
+--   cost, and on a $30/Mtok output rate at 4K the two are not close.
+--
+--   `size: "auto"` and `quality: "auto"` — the host's own defaults, and what an
+--   OpenAI client sends when it names neither — bound at the **dearest measured
+--   variant** for that model. The host picks; we hold enough for its worst
+--   choice and give back the rest at settlement. Refusing `auto` instead would
+--   mean an unmodified OpenAI client cannot call this route at all, which is
+--   the product.
+--
+-- One row per (model, size, quality) rather than a column of the dearest, which
+-- #227 left open. The dearest alone would bound every request at 4K high — an
+-- order of magnitude over a 1024² low — and a cap that refuses affordable
+-- requests is the failure #219 spent a migration undoing. The grid is also what
+-- `/v1/models` publishes as the sizes and tiers a caller may ask for, and a
+-- single number cannot say that.
+
+CREATE TABLE model_image_variants (
+  model         TEXT    NOT NULL REFERENCES models(id),
+  -- As the caller sends them, and as the host names them: `1024x1024`,
+  -- `1536x1024`, `low`, `high`. Never `auto` — that is the absence of a choice,
+  -- resolved against these rows rather than stored as one of them.
+  size          TEXT    NOT NULL CHECK (size != 'auto'),
+  quality       TEXT    NOT NULL CHECK (quality != 'auto'),
+  -- What one image at this variant cost in image output tokens, from the
+  -- response's `usage.output_tokens` at `n = 1`.
+  output_tokens INTEGER NOT NULL CHECK (output_tokens > 0),
+  measured_at   TEXT    NOT NULL,
+  -- The run that measured it, as `models.measured_by` records one.
+  measured_by   TEXT,
+  -- Where the figure came from. `conformance` is the only writer today; a URL
+  -- would mean the host started publishing the grid, which would be better.
+  source        TEXT    NOT NULL DEFAULT 'conformance',
+  PRIMARY KEY (model, size, quality)
+);
+
+-- The catalogue reads every variant of a model at once, and the bound reads
+-- every variant of every candidate in a chain. Both are covered by the primary
+-- key's leading column, so there is no second index here on purpose.
+
+-- ── The transport, which is not measured and is why this says so ──────────────
+--
+-- Cloudflare's unified `/compat` endpoint serves chat completions and nothing
+-- else, so an image request cannot take the path every other request in this
+-- repository takes. The provider path is documented for `chat/completions` and
+-- `responses` and says to replace `api.openai.com/v1` with the gateway prefix,
+-- which implies but does not state that `images/generations` proxies through.
+--
+-- #227 asks for that to be measured before the route relies on it. **It has not
+-- been, and could not be from here.** Probed 2026-09-04 against
+-- `gateway.ai.cloudflare.com/v1/<account>/gw-sensitive-staging/openai/…`: both
+-- gateways authenticate, so every path — `compat/chat/completions`,
+-- `openai/images/generations`, and a deliberately nonsensical one — answers the
+-- same `AiGatewayError 2009 Unauthorized` before any routing decision is
+-- visible. The measurement needs `AI_GATEWAY_TOKEN`, which is a Worker secret
+-- and cannot be read back, so it happens from a deployed Worker or not at all.
+-- The first conformance run against `PROVIDER_KEY_OPENAI` is that run.
+--
+-- What keeps the guess from costing a tenant a request: conformance generates
+-- *through* `/v1/images/generations` with its own key, and a variant row is
+-- written only from a `usage` that came back. Until one exists the limits gate
+-- refuses every request to the model, so no tenant request can reach a
+-- transport that has not already carried a measured generation.
+--
+-- What that costs if the guess is wrong is one row, not a code change:
+-- `src/images.ts` sends a direct request whenever `upstreams.base_url` is set
+-- and a gateway provider-path request otherwise, which is the same `isDirect`
+-- split 0050 built for Meta. Setting `base_url` on the `openai` upstream moves
+-- every image request off the gateway; it also moves chat, which is why that is
+-- a decision for whoever measures rather than a default written here.