@bytesbrains/cruise-worker 0.0.0-stage → 0.12.0

package/migrations/0099_wallet_low_water_backfill.sql

@@ -0,0 +1,47 @@
+-- Every capped wallet gets the low-water mark a signup wallet starts with (#583).
+--
+-- ## Why
+--
+-- `readWallet` reports `low` only where `soft_micros` is set. Signup wallets
+-- have carried $1 since `walletInsert` (`src/tenants-prepaid.ts`), but a tenant
+-- made before prepaid signup got its wallet from its first credit grant, and
+-- that insert (`capRecompute`, `src/payments.ts`) never wrote one. Read on
+-- 2026-10-09 (UTC), that is exactly two wallets: `bb-adm` on production and
+-- `bytesbrains` on staging. Both read `ok` until they read `exhausted`, and
+-- `bb-adm` did it to an agent tenant's Builder run on call 49, six minutes in
+-- (agents#822). Staging's read `ok` at $0.0495, which cannot cover
+-- one request.
+--
+-- ## Why overwriting NULL overrides nobody
+--
+-- Nothing has ever set a wallet's threshold after creation: no route, no CLI.
+-- `soft_micros` on a tenant row is written by `walletInsert` (always $1) and
+-- now by the grant's insert (the same), and by nothing else. So a NULL here
+-- means "never set", never "chosen to be none". Should a route to choose one
+-- arrive, its NULL would be a decision, and this migration has already run.
+--
+-- ## Scope
+--
+-- Capped wallets only (`hard_micros IS NOT NULL`). An uncapped wallet has no
+-- balance to be low on, and `walletCannotWarn` (`src/doctor-wallet.ts`) asks
+-- about capped ones for the same reason. `updated_by` says who wrote it, so
+-- the row carries its own reason; `updated_at` moves with it.
+--
+-- ## The demo
+--
+-- It runs there too, where the prepaid backfill deliberately does not
+-- (`docs/provisioning.md`). Harmless: the demo makes no wallets (`prepaidOn`)
+-- and holds none, so the `WHERE` matches nothing.
+--
+-- ## Order
+--
+-- Independent of the Worker: it reads `soft_micros` already. Before or after
+-- the deploy, `low` appears from the moment this runs.
+
+UPDATE budgets
+   SET soft_micros = 1000000,
+       updated_by = 'migration:0099 (#583)',
+       updated_at = datetime('now')
+ WHERE scope = 'tenant'
+   AND soft_micros IS NULL
+   AND hard_micros IS NOT NULL;

package/migrations/0100_rag_grounded_answers_lane.sql

@@ -0,0 +1,92 @@
+-- `bb/rag-grounded-answers`: the platform lane for answers over retrieved
+-- passages (#627).
+--
+-- The vocabulary has carried `rag-grounded-answers` since 0029, and the job
+-- CHECK already admits it, so this is rows and no rebuild. It was deferred
+-- because "no gate distinguishes it from `chat-assistant` with a long window"
+-- (docs/vocabulary.md). That stopped being true when `json_schema` became a
+-- measured flag: `bb/extraction` has required it since 0030, and production's
+-- 2026-10-08 conformance run measured it on every member below. The lane's
+-- promise is the conjunction the job needs and `chat-assistant` does not
+-- make — room for many retrieved chunks *and* an answer whose citations parse.
+--
+-- ## Requirements
+--
+--   long-context:200000 — a retrieval context is the long input. 131,072 (the
+--                         bare constraint's default) admits the 128k models,
+--                         which a top-k of a few dozen 2-4k chunks plus the
+--                         conversation fills; 200k is the vocabulary's own
+--                         worked example and every member clears 262,144.
+--   json-schema         — grounded answers are cited answers, and a citation
+--                         list a client cannot parse is not one.
+--
+-- Not `tools-required`: the retrieval happened before the request, in the
+-- caller's store. The issue's `strict_faithfulness` has no column and no
+-- conformance check, so it is not a constraint here — an unmeasurable promise
+-- is the thing "unknown capabilities fail closed" exists to refuse
+-- (src/lanes.ts). A judged faithfulness check is #627's follow-up, not a row.
+--
+-- ## Aliases: `bb/rag-search` and `bb/retrieval` (#627)
+--
+-- The id is the canonical vocabulary job (0029's CHECK: a global lane's id is
+-- `bb/` || job). Callers requesting `bb/rag-search` or `bb/retrieval` (from #627
+-- and the video masterclass) are resolved directly to `bb/rag-grounded-answers`
+-- at admission (`src/admission-resolve.ts`).
+--
+-- The companion `bb/web-search` is tracked separately: no catalogued model is
+-- currently measured to search on AI Gateway `/compat` without native agent
+-- wire protocols (see #629 for Perplexity Agent API integration).
+-- That work has its own dedicated upstream issues.
+--
+-- Nothing here enables a search: Cruise injects no tool into a lane request,
+-- so a member answers from the passages it was sent.
+--
+-- ## Members
+--
+-- Every one measured on production 2026-10-08 (Gemini 2026-09-30): json_schema
+-- = 1, streaming = 1, tools = 1, max_context >= 262,144 — so the lane's
+-- streaming capability, the intersection, stays true. Five hosts, so one
+-- host's outage leaves four. Rates per million in / out, from the migration
+-- each row's price came from:
+--
+--   anthropic/claude-haiku-5-5                $0.10 / $0.50   ($0.50 / $2.50 over 100K — 0094)
+--   workers-ai/@cf/zai-org/glm-5.3-flash      $0.15 / $0.50
+--   mistral/mistral-small-latest              $0.15 / $0.60
+--   openai/gpt-5.6-luna                       $0.20 / $1.20   ($0.40 / $1.80 over 272K)
+--   google-ai-studio/gemini-3.5-flash-lite    $0.30 / $2.50
+--   workers-ai/@cf/deepseek-ai/deepseek-v4-flash-0731  $0.44 / $1.32
+--
+-- Haiku's long-prompt row is the one a RAG request most often lands on, and
+-- the lane's price is the maximum across variants (src/lanes.ts), so the
+-- catalogue quotes $0.50 / $2.50 for it rather than the headline.
+--
+-- Left out: Sonnet 5.5 and Mistral Medium, more than ten times the cheapest
+-- member (`DEAR_FACTOR`, src/lanes-warnings.ts) — under `cheap` they would
+-- serve only when every cheaper member is refused, which is when a bill
+-- surprises someone. GLM-5.3, Gemini 3.8 Flash, Gemma 4, Nemotron and
+-- Kimi K2.6 clear both requirements but measured streaming = 0, and one of
+-- them would make the lane refuse every streamed request in the catalogue's
+-- picture of it.
+--
+-- `cheap`, the default, as for `bb/summarization`: saver is the vocabulary's
+-- default posture and grounded answering is not the job where it is wrong
+-- (that is `deep-reasoning`). quality_rank 1 is best, declared rather than
+-- measured, as 0070's are. cache_ttl_seconds stays 0, as for every lane
+-- (0069): a retrieval store changes under a fixed question, so a cached answer
+-- is the caller's call, by `x-cruise-cache: max-age=…`.
+
+INSERT INTO lanes (id, job, description) VALUES
+  ('bb/rag-grounded-answers', 'rag-grounded-answers',
+   'Answers grounded in passages the caller retrieved and sent: a long context in, a cited answer out. No web access; the model answers from what it was given.');
+
+INSERT INTO lane_members (lane_id, model_id, position, quality_rank) VALUES
+  ('bb/rag-grounded-answers', 'anthropic/claude-haiku-5-5',                        1, 1),
+  ('bb/rag-grounded-answers', 'openai/gpt-5.6-luna',                               2, 1),
+  ('bb/rag-grounded-answers', 'google-ai-studio/gemini-3.5-flash-lite',            3, 2),
+  ('bb/rag-grounded-answers', 'workers-ai/@cf/deepseek-ai/deepseek-v4-flash-0731', 4, 2),
+  ('bb/rag-grounded-answers', 'mistral/mistral-small-latest',                      5, 2),
+  ('bb/rag-grounded-answers', 'workers-ai/@cf/zai-org/glm-5.3-flash',              6, 3);
+
+INSERT INTO lane_requires (lane_id, constraint_, value) VALUES
+  ('bb/rag-grounded-answers', 'long-context', '200000'),
+  ('bb/rag-grounded-answers', 'json-schema',  NULL);

package/migrations/0101_perplexity_agent_api.sql

@@ -0,0 +1,125 @@
+-- Perplexity, through the Agent API (#629, from #207 and 0090).
+--
+-- 0058 priced `perplexity/sonar*` per request and 0090 recorded that Sonar's
+-- `/chat/completions` endpoint ended on 2026-09-27, so the next person to add
+-- Perplexity "starts from the Agent API". This is that start. Every figure
+-- read 2026-10-11 UTC from Perplexity's own pages, cited per row.
+--
+-- ## What the Agent API is, and why this catalogues one model
+--
+-- `POST https://api.perplexity.ai/v1/agent` takes the OpenAI **Responses**
+-- shape, and it is mostly a resale counter: its model list is OpenAI,
+-- Anthropic, Google, xAI, Z.AI, Moonshot and NVIDIA models at those labs'
+-- rates. `docs/upstreams.md` decided 2026-09-03 that Cruise buys each lab
+-- direct and reaches a reseller only for what cannot be got direct, so none of
+-- those rows are here. What only Perplexity sells is **`perplexity/sonar`**
+-- and **its web search** — and those are this migration.
+--
+-- **`sonar-pro` and `sonar-reasoning-pro` are not on the Agent API.** #629
+-- names both; Perplexity's model page lists one Perplexity model, `sonar`, and
+-- maps Sonar Pro's behaviour to its `low` *preset* — a Perplexity-managed
+-- bundle of another lab's model ("Presets are not pinned to a specific
+-- version"), which a measured catalogue row cannot describe. 0058's rows for
+-- the two stay as they are: they price a model nothing routes, as they did.
+--
+-- ## The upstream: direct, not through the gateway
+--
+-- `kind = 'provider'` with a `base_url`, the shape 0050 built for Meta. The
+-- gateway's `/compat` route translates chat completions, and the chat endpoint
+-- it would translate to is the one that ended. The adapter
+-- (`src/chat-perplexity-agent.ts`) builds the Agent API body itself and names
+-- `/agent` rather than the `/responses` alias, because the same host serves a
+-- different, tool-less Orchestrator API at `/router/v1/responses`.
+-- The id is `perplexity` so 0058's component rows, already keyed
+-- `perplexity/sonar`, name this model; the secret is `PROVIDER_KEY_PERPLEXITY`.
+INSERT INTO upstreams (id, name, kind, base_url) VALUES
+  ('perplexity', 'Perplexity', 'provider', 'https://api.perplexity.ai/v1');
+
+-- ── The model ─────────────────────────────────────────────────────────────────
+-- https://docs.perplexity.ai/docs/agent-api/models
+--
+-- `upstream_model` keeps the prefix: the Agent API's ids are `provider/model`,
+-- so Perplexity's own id for this model is `perplexity/sonar`.
+--
+-- **No context window and no output cap are published** — not on the model
+-- page, and `GET /v1/models` answers with id and pricing alone. So the window
+-- is **measured, as a lower bound**: on 2026-10-12 UTC the Agent API served a
+-- 300,028-token prompt to this model (status `completed`, $0.075 charged), and
+-- 300,000 is written. A bound below the truth refuses a prompt that would have
+-- fit; one above it sends a prompt the host will refuse — so the error is put
+-- on the side that costs a caller a retry rather than a failed upstream call.
+-- Raise it when a page or a probe says more. `max_output` stays NULL — 0011's
+-- rule, never write a number you did not fetch — so a billed caller sends
+-- `max_tokens` (`request_unbounded` otherwise).
+--
+-- **`data_retention` is `retained`**, read 2026-10-12 from two of Perplexity's
+-- own pages, which have to be read together:
+--
+--   https://docs.perplexity.ai/docs/resources/faq — "We do not retain any
+--   query data sent through the API and do not train on any of your data."
+--
+--   https://docs.perplexity.ai/api-reference/agent-post — `store`: "When
+--   false, the response is hidden from later retrieve calls ... It can still
+--   be used as a `previous_response_id` continuation source." Responses with
+--   `store` omitted can be retrieved by id.
+--
+-- The second contradicts "do not retain" for the Agent API as plainly as it
+-- can: a response retrievable later, or usable as a continuation later, is
+-- held somewhere. So not `none`; and not trained on, which both pages agree
+-- leaves `retained` (the same reading 0061 gave xAI). The adapter sends
+-- `store: false`, which narrows who can read it back and does not change the
+-- answer. The Privacy & Security page's zero-retention promise names "the
+-- Chat Completions API" — the endpoint that ended — and is not cited for that
+-- reason. The API terms on perplexity.ai answer 403 to a fetch, as xAI's did.
+INSERT INTO models (id, upstream_id, upstream_model, max_context, max_output,
+                    data_retention, data_retention_source, data_retention_as_of) VALUES
+  ('perplexity/sonar', 'perplexity', 'perplexity/sonar', 300000, NULL,
+   'retained', 'https://docs.perplexity.ai/api-reference/agent-post', '2026-10-12');
+
+-- $0.25 in, $2.50 out, $0.0625 cache read, per million tokens.
+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-10-11 00:00:00', 'perplexity/sonar', '2026-10-11', 0, '',
+   250000, 2500000, 62500, 'https://docs.perplexity.ai/docs/agent-api/models',
+   'First token observation: Sonar on the Agent API (#629, 0101).');
+
+-- ── The components: the request fee ends, the search fee begins ───────────────
+-- https://docs.perplexity.ai/docs/getting-started/pricing
+--
+-- **The request fee is zero, written as a row.** 0058's `request` grid for
+-- `perplexity/sonar` ($5/$8/$12 per thousand, by search context size) was
+-- Sonar chat's, and the Agent API has neither the fee nor the size: its
+-- migration guide maps `search_context_size` to "no named-size equivalent".
+-- Left alone those rows would stay in force and charge every Agent API
+-- request a fee nobody bills. A component is in force per model and
+-- component at its latest effective date (`componentRowsInForceFor`), so one
+-- '' row at zero, dated today, supersedes the whole grid — and 0058's own
+-- comment is the reason it is a row and not a deletion: "a host that waives a
+-- fee on one variant says so with a row rather than with an absence".
+--
+-- **Search is per invocation.** $2.50 per thousand for standard search, $1.00
+-- with `search_type: "fast"`. Standard is the '' row because it is what the
+-- host does when the tool names no type ("otherwise uses `web`"); a body
+-- naming `web` finds no exact row and takes '', which is the same rate.
+--
+-- The count is settled from `usage.tool_calls_details.search_web.invocation`
+-- and is **not bounded by anything a request can say**: the Agent API's
+-- request schema has `max_steps` and no per-tool ceiling. So a request that
+-- lets Sonar search is refused a billed tenant as `request_unbounded` and
+-- served to an internal one at the flat reservation (`pricing-components.ts`,
+-- `uncapped_by_host`). A request with no search tool does not search, has no
+-- search to bound, and is served to anyone.
+INSERT INTO price_components
+  (observed_at, model, effective_from, component, variant, micros, per, source, note)
+VALUES
+  ('2026-10-11 00:00:00', 'perplexity/sonar', '2026-10-11', 'request', '', 0, 1,
+   'https://docs.perplexity.ai/docs/getting-started/pricing',
+   'Agent API: no per-request fee. Supersedes 0058''s Sonar chat grid, which ended with that endpoint on 2026-09-27.'),
+  ('2026-10-11 00:00:00', 'perplexity/sonar', '2026-10-11', 'search',  '',     2500000, 1000,
+   'https://docs.perplexity.ai/docs/getting-started/pricing',
+   'web_search, standard (search_type web, the default): $2.50 per 1,000 invocations.'),
+  ('2026-10-11 00:00:00', 'perplexity/sonar', '2026-10-11', 'search',  'fast', 1000000, 1000,
+   'https://docs.perplexity.ai/docs/getting-started/pricing',
+   'web_search with search_type fast: $1.00 per 1,000 invocations.');

package/migrations/0102_web_search_job_and_flag.sql

@@ -0,0 +1,137 @@
+-- A `web-search` job, and a measured `web_search` flag (#627).
+--
+-- #627 asks for two search lanes. The RAG half shipped as
+-- `bb/rag-grounded-answers` (0100); this is the first half of the other:
+-- the word, and the measurement a lane on it will gate on. No lane is created
+-- here — a `bb/` lane needs three routable, measured members, and until a
+-- conformance run has written this flag no model has it.
+--
+-- ## The job: ahead of the board, as `hunter` and `builder` were
+--
+-- The model board (`naderu.com/data/model-board.json`, read 2026-10-12) has no
+-- web-search job: it files hosted search under `rag-grounded-answers`, as a
+-- price line beside retrieval. The two are different work for a router —
+-- retrieval answers over passages the caller sends, web search goes and gets
+-- them — and different bills: a search is a per-invocation fee (0058, 0101),
+-- a retrieved passage is input tokens. So Cruise names it now, the way 0074
+-- named `hunter` and `builder` (#409), and a later board rename is a
+-- migration, the same as 0029's `bulk-extraction` → `extraction`.
+--
+-- ## Why a rebuild, and the window it has
+--
+-- SQLite cannot widen a CHECK, and `lanes.job` carries the closed set. 0067
+-- refused a rebuild for `selection_policy` and chose expand-and-contract;
+-- that is not available here, because the global-lane CHECK pins
+-- `id = 'bb/' || job` and no added column can make `job` hold a word its own
+-- CHECK refuses. So this is 0074's shape, for 0074's reason, over the schema
+-- as it stands now — 0087's `router` and `router_input`, 0096's `compress`.
+--
+-- **The window is real and is stated rather than argued small**: each
+-- statement is its own transaction on D1, so between `DROP TABLE lanes` and
+-- the `RENAME` a lane lookup finds no table and fails. Run it at the quietest
+-- hour, and expect a handful of lane requests to 500 if traffic lands inside.
+-- Pinned-model requests do not read `lanes` and are unaffected.
+--
+-- ## The flag
+--
+-- A column like 0093's, tri-state, written only by conformance
+-- (`web_search`, `src/conformance.ts`). The check sends a `web_search` tool
+-- and passes only when the host's **usage reports a search count** — the
+-- field `pricing-components.ts` settles the `search` component from — so
+-- "can search" and "can be billed for searching" are one observation, and a
+-- host that searches without saying so measures absent rather than free.
+--
+-- NULL fails closed: `src/capabilities.ts` refuses a request carrying a
+-- search tool for a model nobody has checked. **So the rollout order is
+-- load-bearing, as 0093's was**: this migration, then a conformance run (the
+-- conformance key is exempt from the gate, and the Worker that predates this
+-- passes the tool through), then the Worker that gates on it.
+
+ALTER TABLE models ADD COLUMN web_search INTEGER CHECK (web_search IN (0, 1));
+
+CREATE TABLE lanes_new (
+  id          TEXT PRIMARY KEY,
+  tenant_id   TEXT REFERENCES tenants(id),
+  job         TEXT NOT NULL CHECK (job IN (
+                'chat-assistant', 'deep-reasoning', 'summarization', 'translation',
+                'content-writing', 'extraction', 'code-completion', 'agentic-coding',
+                'hunter', 'builder', 'web-search',
+                'code-review', 'document-understanding', 'speech', 'rag-grounded-answers',
+                'computer-use', 'content-moderation', 'other')),
+  description TEXT NOT NULL,
+  enabled     INTEGER NOT NULL DEFAULT 1,
+  created_by  TEXT NOT NULL DEFAULT 'migration',
+  created_at  TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at  TEXT NOT NULL DEFAULT (datetime('now')),
+  archived_at TEXT,
+  selection   TEXT NOT NULL DEFAULT 'cheap'
+              CHECK (selection IN ('cheap', 'random', 'weighted')),
+  selection_policy TEXT NOT NULL DEFAULT 'cheap'
+              CHECK (selection_policy IN ('cheap', 'random', 'weighted', 'graduated')),
+  cache_ttl_seconds INTEGER NOT NULL DEFAULT 0
+              CHECK (cache_ttl_seconds BETWEEN 0 AND 2592000),
+  cache_scope TEXT NOT NULL DEFAULT 'model'
+              CHECK (cache_scope IN ('model', 'lane')),
+  max_chain   INTEGER
+              CHECK (max_chain IS NULL OR max_chain BETWEEN 1 AND 3),
+  router      TEXT
+              CHECK (router IS NULL OR router IN ('jev')),
+  router_input TEXT NOT NULL DEFAULT 'hint'
+              CHECK (router_input IN ('hint', 'prompt')),
+  compress    INTEGER NOT NULL DEFAULT 0
+              CHECK (compress IN (0, 1) AND (compress = 0 OR tenant_id IS NOT NULL)),
+  CHECK (
+    (tenant_id IS NULL     AND substr(id, 1, 3) = 'bb/') OR
+    (tenant_id IS NOT NULL AND substr(id, 1, length(tenant_id) + 1) = tenant_id || '/'
+                           AND substr(id, 1, 3) <> 'bb/')
+  ),
+  CHECK (tenant_id IS NOT NULL OR (id = 'bb/' || job AND job <> 'other'))
+);
+
+INSERT INTO lanes_new (
+  id, tenant_id, job, description, enabled, created_by, created_at, updated_at,
+  archived_at, selection, selection_policy, cache_ttl_seconds, cache_scope, max_chain,
+  router, router_input, compress
+)
+SELECT id, tenant_id, job, description, enabled, created_by, created_at, updated_at,
+       archived_at, selection, selection_policy, cache_ttl_seconds, cache_scope, max_chain,
+       router, router_input, compress
+  FROM lanes;
+
+CREATE TABLE lane_members_new (
+  lane_id      TEXT NOT NULL REFERENCES lanes_new(id),
+  model_id     TEXT NOT NULL REFERENCES models(id),
+  position     INTEGER NOT NULL,
+  weight       REAL NOT NULL DEFAULT 1 CHECK (weight > 0),
+  quality_rank INTEGER,
+  PRIMARY KEY (lane_id, model_id)
+);
+
+INSERT INTO lane_members_new (lane_id, model_id, position, weight, quality_rank)
+SELECT lane_id, model_id, position, weight, quality_rank FROM lane_members;
+
+CREATE TABLE lane_requires_new (
+  lane_id     TEXT NOT NULL REFERENCES lanes_new(id),
+  constraint_ TEXT NOT NULL CHECK (constraint_ IN (
+                'long-context', 'tools-required', 'json-schema', 'vision-required',
+                'no-training-on-data',
+                'low-latency', 'high-throughput', 'open-weights', 'data-residency',
+                'audio-required', 'batch-api')),
+  value       TEXT,
+  PRIMARY KEY (lane_id, constraint_)
+);
+
+INSERT INTO lane_requires_new (lane_id, constraint_, value)
+SELECT lane_id, constraint_, value FROM lane_requires;
+
+DROP INDEX idx_lane_members_lane;
+DROP INDEX idx_lanes_tenant;
+DROP TABLE lane_requires;
+DROP TABLE lane_members;
+DROP TABLE lanes;
+ALTER TABLE lanes_new RENAME TO lanes;
+ALTER TABLE lane_members_new RENAME TO lane_members;
+ALTER TABLE lane_requires_new RENAME TO lane_requires;
+
+CREATE INDEX idx_lane_members_lane ON lane_members (lane_id, position);
+CREATE INDEX idx_lanes_tenant ON lanes (tenant_id, enabled);

package/migrations/0103_openai_web_search_price.sql

@@ -0,0 +1,44 @@
+-- OpenAI's web search fee, for the six chat models Cruise routes (#627).
+--
+-- Production conformance measured every OpenAI chat model `web_search = 0`:
+-- Chat Completions takes a search tool and searches nothing. The search is the
+-- Responses API's built-in `web_search` tool, which `src/chat-openai-search.ts`
+-- now sends, so a request that searches can be counted — and a count with no
+-- rate in force fails closed rather than billing, so the rate lands first.
+--
+-- ## The rate
+--
+-- Read 2026-10-12 UTC from https://developers.openai.com/api/docs/pricing
+-- (`platform.openai.com/docs/pricing` 301s there): "Web search — all models —
+-- $10.00 / 1k calls + Search content tokens billed at model rates." The page
+-- names `gpt-5` and the o-series as reasoning models and does not list the
+-- 5.6 or 6.x lines by name; "all models" is the row that covers them, and the
+-- $25 / 1k preview rate is for non-reasoning models only, which none of these
+-- six is (each refuses function tools on Chat Completions, #545).
+--
+-- **The count is `tool_usage.web_search.num_requests`**, measured live the
+-- same day on `gpt-5.6-luna`: 1 for one search, 4 for four. A call the host
+-- began and `max_tool_calls` stopped (`status: "searching"`) was not counted,
+-- so the billed number is that field and not the number of `web_search_call`
+-- output items.
+--
+-- **The search content tokens are already billed**, by the token columns:
+-- one search read back as 8,496 input tokens against a ~20-token prompt. That
+-- is why `reservation.ts` cannot bound a search (`search_input_unbounded`), and
+-- nothing here changes it — this row bounds and settles the fee only.
+INSERT INTO price_components
+  (observed_at, model, effective_from, component, variant, micros, per, source, note)
+VALUES
+  ('2026-10-12 11:00:00', 'openai/gpt-5.6-luna',  '2026-10-12', 'search', '', 10000000, 1000,
+   'https://developers.openai.com/api/docs/pricing',
+   'First observation (0103): web search, $10 per 1,000 calls, counted from tool_usage.web_search.num_requests.'),
+  ('2026-10-12 11:00:00', 'openai/gpt-5.6-terra', '2026-10-12', 'search', '', 10000000, 1000,
+   'https://developers.openai.com/api/docs/pricing', 'First observation (0103).'),
+  ('2026-10-12 11:00:00', 'openai/gpt-5.6-sol',   '2026-10-12', 'search', '', 10000000, 1000,
+   'https://developers.openai.com/api/docs/pricing', 'First observation (0103).'),
+  ('2026-10-12 11:00:00', 'openai/gpt-6-luna',    '2026-10-12', 'search', '', 10000000, 1000,
+   'https://developers.openai.com/api/docs/pricing', 'First observation (0103).'),
+  ('2026-10-12 11:00:00', 'openai/gpt-6-astra',   '2026-10-12', 'search', '', 10000000, 1000,
+   'https://developers.openai.com/api/docs/pricing', 'First observation (0103).'),
+  ('2026-10-12 11:00:00', 'openai/gpt-6.1-sol',   '2026-10-12', 'search', '', 10000000, 1000,
+   'https://developers.openai.com/api/docs/pricing', 'First observation (0103).');

package/migrations/0104_web_search_lane.sql

@@ -0,0 +1,82 @@
+-- `bb/web-search`: the platform lane for answers grounded in a live search of
+-- the open web (#627).
+--
+-- 0102 named the job and the `web_search` flag and created no lane, because a
+-- `bb/` lane needs three routable, measured hosts and none had one. They do
+-- now, each measured on production on 2026-10-12: Perplexity (0101, #630),
+-- Anthropic through the Messages API (#636, run `966ca16c`) and OpenAI through
+-- the Responses API (#643, runs `34c25547`, `656f2f83`, `d1f3f6e6`). Every
+-- check sent one search and read `searches=1` back from the host's usage, which
+-- is the number the `search` component settles from.
+--
+-- ## No requirement row, and why that is not a gap
+--
+-- There is no `web-search` constraint in `lane_requires`, and none is needed.
+-- A request on this lane that carries no search tool is given one before
+-- allocation (`src/lanes-search.ts`), so every request on it asks to search,
+-- and the `web_search` capability gate (`src/capabilities.ts`) refuses a
+-- member not measured able to. A member that stops searching drops out at the
+-- gate the next time conformance writes 0; it is not served a request it
+-- cannot ground. `lanes-warnings.ts` warns on any member without the flag.
+--
+-- ## Billed tenants are refused, on purpose, until a ceiling is measured
+--
+-- **Every request on this lane is `search_input_unbounded` for a billed
+-- tenant** (`src/reservation.ts`, #636). The search fee is bounded — `max_uses`
+-- caps it, `max_tool_calls` on OpenAI — but the results come back as input
+-- tokens, and no host states a ceiling on them: one OpenAI search read back as
+-- 8,496 input tokens against a ~20-token prompt (0103). A guessed ceiling is
+-- not a bound, and a cap that drifts by a guess is not a cap. So the lane
+-- serves internal keys, which reserve the floor, and refuses billed ones with
+-- a message naming the reason. Opening it to billed tenants is a measured
+-- per-search token ceiling, tracked on #654, not a change here.
+--
+-- That also settles the question #627 left open for Perplexity, which cannot
+-- enforce `max_uses` (`searchBoundedByHost`) and so could not be bounded even
+-- for the fee. While every search is unboundable for billed tenants, a
+-- Perplexity member costs them nothing they had; when the ceiling lands, the
+-- reservation will need Perplexity's own bound, and `search.bound` already
+-- returns null for it.
+--
+-- ## Members
+--
+-- The cheapest searching model per host. Rates per million in / out, at the
+-- dearest variant (the lane's price is the maximum, src/lanes.ts), and the
+-- per-search fee:
+--
+--   openai/gpt-6-luna           $0.20 / $0.75   $10 / 1k searches (0103)
+--   perplexity/sonar            $0.25 / $2.50   $1.00–$2.50 / 1k (0101)
+--   openai/gpt-5.6-luna         $0.40 / $1.80   $10 / 1k searches (0103)
+--   anthropic/claude-haiku-5-5  $0.50 / $2.50   $10 / 1k searches (0094)
+--
+-- All four measured streaming = 1, tools = 1, json_schema = 1, so the lane's
+-- capabilities, the intersection, hold all three. Two OpenAI members because
+-- the host is the one with two cheap searching models, and a lane of three
+-- single members loses a third of itself to one outage.
+--
+-- Sonar's 300,000-token window is the lane's (`narrow_member`); the others
+-- take a million. A search question is short and the results are the host's
+-- to fit, so the narrower window costs the job nothing, and dropping Sonar
+-- would cost it a host.
+--
+-- Left out: Haiku 4.5, dearer than Haiku 5.5 for an older model; every
+-- Sonnet, Opus, Fable, and the 5.6/6.x Sol, Terra and Astra lines, at least
+-- four times the cheapest member and past `DEAR_FACTOR` for most — a search
+-- answer is a summary of what was found, and the job does not need a
+-- frontier model to write it. A tenant who wants one names it, or builds a
+-- lane.
+--
+-- `cheap`, the default, as for `bb/rag-grounded-answers`. quality_rank 1 is
+-- best, declared rather than measured, as 0070's are. cache_ttl_seconds stays
+-- 0 here: a short TTL for trending queries is #627's cache item, a separate
+-- change with its own billing question.
+
+INSERT INTO lanes (id, job, description) VALUES
+  ('bb/web-search', 'web-search',
+   'Answers grounded in a live search of the open web, billed per search. A request that sends no search tool is given one, capped at one search. Internal keys only until a per-search input ceiling is measured.');
+
+INSERT INTO lane_members (lane_id, model_id, position, quality_rank) VALUES
+  ('bb/web-search', 'openai/gpt-6-luna',          1, 1),
+  ('bb/web-search', 'anthropic/claude-haiku-5-5', 2, 1),
+  ('bb/web-search', 'perplexity/sonar',           3, 2),
+  ('bb/web-search', 'openai/gpt-5.6-luna',        4, 2);

package/migrations/0105_web_search_lane_billed.sql

@@ -0,0 +1,22 @@
+-- `bb/web-search` serves billed tenants (#654).
+--
+-- 0104 seeded the lane with a description saying it was for internal keys
+-- only, because a request that searched could not be bounded: the results are
+-- billed as input tokens and no host states a ceiling on them. #654 bounds them
+-- at the one ceiling a host cannot exceed, the context window, once per search
+-- `max_uses` allows (`src/reservation-search.ts`). The lane injects
+-- `max_uses: 1`, so a plain request on it now has a bound, and the reservation
+-- holds it — about $0.21 on `openai/gpt-6-luna`, $0.50 on Haiku 5.5 — and
+-- settles to what was used.
+--
+-- `perplexity/sonar` stays a member and serves internal keys. A billed key
+-- skips it: its host does not enforce `max_uses` (#630), so the bound has no
+-- `k` to multiply by (`searchUnboundableFor`).
+--
+-- The description is all that changes. It is what `/v1/models` shows a caller,
+-- and a caller reading "internal keys only" would not try.
+
+UPDATE lanes
+   SET description = 'Answers grounded in a live search of the open web, billed per search. A request that sends no search tool is given one, capped at one search. A billed key reserves one context window of input per allowed search, settled to what was used, and is not routed to a member whose host cannot enforce the cap.',
+       updated_at = datetime('now')
+ WHERE id = 'bb/web-search';

package/migrations/0106_reservations_journal.sql

@@ -0,0 +1,64 @@
+-- The reservations journal: every hold that has not yet settled (#594).
+--
+-- A request is charged in two steps. The reserve is durable, a D1 write before
+-- the upstream call; the settle runs only inside the invocation that served the
+-- request, in the stream drain or in `waitUntil` after it. When that invocation
+-- dies between the two (a client gone past `waitUntil`'s grace, a deploy during
+-- traffic: both production leaks since v0.9.2 fall on deploy days), nothing
+-- recorded that a hold was still open. The counter kept the whole hold, the
+-- ledger got no row, and `spend_vs_ledger` reported drift every day from
+-- 2026-09-17 with zero recorded failures (#562, #597, #598).
+--
+-- So a hold is now a row. It is written in the same batch as the reserve, and
+-- only when the reserve moved the counter (`changes()`, `src/reservation-journal.ts`):
+-- a refused request leaves none. It is deleted in the same batch as the settle
+-- or the release, and the counter correction in that batch is conditional on
+-- the row still existing and unclaimed. The daily sweep claims it in a single
+-- statement before writing anything. Whichever of the two gets the row first is
+-- the one that adjusts the counter and writes the ledger row, so a request is
+-- never settled twice.
+--
+-- A row the sweep finds older than the threshold is a request whose invocation
+-- died. It becomes a ledger row charged the whole hold, which is the same rule
+-- as `no_usage`: nothing reported what was used, so the counter is left where
+-- the reserve put it, and the ledger is brought up to it (decided on #594).
+--
+-- Deliberately no `tenant_id`: a project belongs to one tenant, and the sweep
+-- reads it from `projects` (migration 0004's one path). `wallet_held` says
+-- whether the tenant's lifetime row held a share, which is all a release needs.
+--
+-- The ledger fields are the ones a settled row would carry and that are known
+-- at admission. `model` is the first candidate the chain would try: for a lane
+-- the member that was allocated, for a pinned model the model itself, for a
+-- cache hit the model that produced the cached answer.
+CREATE TABLE reservations (
+  id              TEXT PRIMARY KEY,
+  at              TEXT NOT NULL DEFAULT (datetime('now')),
+  project_id      TEXT NOT NULL,
+  reserved_micros INTEGER NOT NULL CHECK (reserved_micros >= 0),
+  period          TEXT NOT NULL,
+  -- The window the reserve charged, by the same expression it used, so a
+  -- release names exactly the row the hold went to (#347).
+  period_start    TEXT NOT NULL,
+  wallet_held     INTEGER NOT NULL DEFAULT 0 CHECK (wallet_held IN (0, 1)),
+  model           TEXT NOT NULL,
+  upstream_id     TEXT NOT NULL,
+  requested_model TEXT NOT NULL,
+  key_prefix      TEXT NOT NULL,
+  traffic_class   TEXT NOT NULL,
+  lane            TEXT NOT NULL,
+  account         TEXT NOT NULL,
+  streamed        INTEGER NOT NULL DEFAULT 0,
+  -- Set by the sweep's first statement, which is its claim. The sweep runs
+  -- from the admin CLI, whose batch is sequential rather than atomic
+  -- (`scripts/d1-http.ts`), so it cannot rely on one batch to beat a settle:
+  -- it claims the row in one statement, and from then on a settle, which only
+  -- touches rows with this NULL, stands down. A sweep that dies after the
+  -- claim leaves the row for the next one to finish.
+  swept_at        TEXT
+);
+
+-- The sweep reads the oldest rows first; a project's open holds are what an
+-- exact `spend_vs_ledger` would add to its ledger sum.
+CREATE INDEX idx_reservations_at ON reservations (at);
+CREATE INDEX idx_reservations_project ON reservations (project_id, period_start);