@volter/twin-ai-gateway 0.1.0

package/dist/src/ai-gateway-capabilities.js

@@ -0,0 +1,772 @@
+// Capability manifest — the REAL Vercel AI Gateway surface as the denominator, authored
+// top-down from Vercel's docs (OpenAI Chat Completions API family incl. Advanced Configuration
+// and Structured Outputs, the Responses/Anthropic-Messages/OpenResponses compatibility APIs,
+// the REST API Reference: models/credits/generation/report, provider options/filtering/sorting,
+// usage & billing, authentication & BYOK) PLUS the AI SDK gateway protocol (/v3/ai) that
+// `@ai-sdk/gateway` / the `ai` package's `createGateway` — the AI SDK's default provider path —
+// actually speaks (derived from the shipped SDK: GET /config, POST /language-model with
+// ai-language-model-* headers, POST /embedding-model|image-model|video-model). Coverage is
+// honest and partial: unmodeled surfaces are `todo`; only the genuinely-impossible-for-a-
+// local twin serves deterministically is `done`; anything unserved is `todo`.
+//
+// No UI capabilities: the AI Gateway is an API product — integrators call it; the Vercel
+// dashboard is incidental key/spend tooling, not where the work happens ("Does this vendor get
+// a mirror?" in docs/contributing/adding-a-twin.md). See README ## Coverage → ### No UI mirror.
+//
+// Scenario scripting (ai-gateway-scenario.ts) is deliberately NOT a capability here — it is
+// twin-only test scaffolding outside the vendor surface (anthropic-pack convention).
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { applyTwinWrite, pendingActions, projectResources } from '@volter/world-core';
+import { checkCapabilities } from '@volter/world-tooling';
+import { handleAiGatewayTwinRequest } from "./ai-gateway-twin.js";
+import { pullAiGatewayState, } from "./ai-gateway-connector.js";
+import { performPending } from "./ai-gateway-perform-harness.js";
+async function withRoot(fn) {
+    const root = mkdtempSync(join(tmpdir(), 'ai-gateway-cap-'));
+    const h = (step) => handleAiGatewayTwinRequest({
+        method: step.m,
+        path: step.p,
+        body: step.b === undefined ? undefined : JSON.stringify(step.b),
+        root,
+        ...(step.hd ? { headers: step.hd } : {}),
+        ...(step.sseSink ? { sseSink: step.sseSink } : {}),
+    });
+    try {
+        return await fn(h);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+const done = (id, area, title, dimension, tier, verify) => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id, area, title, dimension, tier) => ({ id, area, title, dimension, tier, expected: 'todo' });
+const CHAT = (extra = {}) => ({
+    model: 'anthropic/claude-sonnet-4.6',
+    messages: [{ role: 'user', content: 'hello ai gateway twin' }],
+    ...extra,
+});
+export const AI_GATEWAY_CAPABILITIES = [
+    // ── chat completions (POST /v1/chat/completions) ─────────────────────────────────────
+    done('ai-gateway.chat.create', 'chat', 'Chat completions: create returns OpenAI-compatible envelope with a gen_ generation id', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        const b = r.body;
+        return r.status === 200 && b.object === 'chat.completion' && b.model === 'anthropic/claude-sonnet-4.6' &&
+            String(b.id).startsWith('gen_') && b.choices?.[0]?.message?.role === 'assistant' &&
+            b.choices?.[0]?.finish_reason === 'stop' && typeof b.created === 'number' &&
+            b.usage?.total_tokens === b.usage?.prompt_tokens + b.usage?.completion_tokens;
+    })),
+    done('ai-gateway.chat.stub_labeled', 'chat', 'Chat output is clearly labeled as a twin stub and echoes the prompt', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        const text = r.body.choices?.[0]?.message?.content;
+        return r.status === 200 && text.includes('[twin-stub:ai-gateway') && text.includes('hello ai gateway twin');
+    })),
+    done('ai-gateway.chat.validation', 'chat', 'Chat rejects missing model / empty or malformed messages with the vendor error envelope', 'api', 'core', () => withRoot(async (h) => {
+        const noModel = await h({ m: 'POST', p: '/v1/chat/completions', b: { messages: [{ role: 'user', content: 'x' }] } });
+        const empty = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ messages: [] }) });
+        const noRole = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ messages: [{ content: 'x' }] }) });
+        const badRole = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ messages: [{ role: 'wizard', content: 'x' }] }) });
+        const unknownModel = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ model: 'nope/nope' }) });
+        return noModel.status === 400 && noModel.body.error?.code === 'missing_parameter' && noModel.body.error?.param === 'model' &&
+            empty.status === 400 && noRole.status === 400 && badRole.status === 400 &&
+            badRole.body.error?.type === 'invalid_request_error' &&
+            unknownModel.status === 404 && unknownModel.body.error?.code === 'model_not_found';
+    })),
+    done('ai-gateway.chat.system_and_multi_turn', 'chat', 'Chat accepts system/developer turns and multi-turn history; usage counts every turn', 'api', 'core', () => withRoot(async (h) => {
+        const single = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        const multi = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({
+                messages: [
+                    { role: 'system', content: 'You are a terse assistant.' },
+                    { role: 'user', content: 'first question' },
+                    { role: 'assistant', content: 'first answer' },
+                    { role: 'user', content: 'hello ai gateway twin' },
+                ],
+            }) });
+        const echoed = multi.body.choices?.[0]?.message?.content;
+        return single.status === 200 && multi.status === 200 && echoed.includes('hello ai gateway twin') &&
+            multi.body.usage.prompt_tokens > single.body.usage.prompt_tokens;
+    })),
+    done('ai-gateway.chat.max_tokens', 'chat', 'Chat honors max_tokens/max_completion_tokens as a length cap (finish_reason length)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ max_tokens: 1 }) });
+        const alias = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ max_completion_tokens: 1 }) });
+        const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ max_tokens: 0 }) });
+        return r.status === 200 && r.body.choices?.[0]?.finish_reason === 'length' &&
+            alias.status === 200 && alias.body.choices?.[0]?.finish_reason === 'length' &&
+            bad.status === 400 && bad.body.error?.param === 'max_tokens';
+    })),
+    done('ai-gateway.chat.n_choices', 'chat', 'n (OpenAI-spec passthrough) produces multiple choices with stable indexes and n-scaled usage; the twin deterministically repeats the same stub per choice', 'api', 'niche', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ n: 3 }) });
+        const one = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        const choices = r.body.choices;
+        const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ n: 0 }) });
+        return r.status === 200 && choices?.length === 3 && choices[0].index === 0 && choices[2].index === 2 &&
+            r.body.usage?.completion_tokens === 3 * one.body.usage?.completion_tokens &&
+            bad.status === 400 && bad.body.error?.param === 'n';
+    })),
+    done('ai-gateway.chat.sampling_params', 'chat', 'Sampling params (temperature/top_p/penalties/stop) validated to their documented ranges', 'api', 'common', () => withRoot(async (h) => {
+        const ok = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ temperature: 0.7, top_p: 0.9, frequency_penalty: 0.1, presence_penalty: -0.1, stop: ['\n'] }) });
+        const badTemp = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ temperature: 3 }) });
+        const badTopP = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ top_p: 2 }) });
+        const badStop = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ stop: 42 }) });
+        return ok.status === 200 && badTemp.status === 400 && badTemp.body.error?.param === 'temperature' &&
+            badTopP.status === 400 && badStop.status === 400;
+    })),
+    done('ai-gateway.chat.image_input', 'chat', 'Multimodal messages: image_url parts (base64 data URLs) are accepted and validated', 'api', 'common', () => withRoot(async (h) => {
+        const ok = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({
+                messages: [{ role: 'user', content: [
+                            { type: 'text', text: 'describe this image' },
+                            { type: 'image_url', image_url: { url: 'data:image/png;base64,aGVsbG8=', detail: 'auto' } },
+                        ] }],
+            }) });
+        const noUrl = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({
+                messages: [{ role: 'user', content: [{ type: 'image_url', image_url: {} }] }],
+            }) });
+        const badPart = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({
+                messages: [{ role: 'user', content: [{ type: 'hologram' }] }],
+            }) });
+        const text = ok.body.choices?.[0]?.message?.content;
+        return ok.status === 200 && text.includes('describe this image') &&
+            noUrl.status === 400 && badPart.status === 400 && badPart.body.error?.message?.includes('hologram');
+    })),
+    done('ai-gateway.chat.file_input', 'chat', 'PDF/file attachments: file parts with base64 data are accepted and validated', 'api', 'common', () => withRoot(async (h) => {
+        const ok = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({
+                messages: [{ role: 'user', content: [
+                            { type: 'text', text: 'summarize this document' },
+                            { type: 'file', file: { data: 'JVBERi0=', media_type: 'application/pdf', filename: 'doc.pdf' } },
+                        ] }],
+            }) });
+        const noData = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({
+                messages: [{ role: 'user', content: [{ type: 'file', file: { filename: 'doc.pdf' } }] }],
+            }) });
+        return ok.status === 200 && String(ok.body.choices?.[0]?.message?.content).includes('summarize this document') &&
+            noData.status === 400;
+    })),
+    done('ai-gateway.chat.provider_metadata', 'chat', 'Responses carry providerMetadata.gateway (routing, decimal-string cost, generationId)', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        const gw = r.body.providerMetadata?.gateway;
+        return r.status === 200 && typeof gw?.cost === 'string' && Number(gw.cost) > 0 && gw.generationId === r.body.id &&
+            gw.routing?.originalModelId === 'anthropic/claude-sonnet-4.6' && gw.routing?.finalProvider === 'anthropic' &&
+            gw.routing?.modelAttempts?.[0]?.providerAttempts?.[0]?.credentialType === 'system';
+    })),
+    todo('ai-gateway.chat.web_search', 'chat', 'Web search augmentation (billable web search calls, search-augmented responses)', 'api', 'common'),
+    todo('ai-gateway.chat.reporting_tags', 'chat', 'Reporting attribution: providerOptions.gateway.{user,tags}, the standard user field, and the ai-reporting-tags/ai-reporting-user headers (validation limits + generation attribution)', 'api', 'niche'),
+    todo('ai-gateway.chat.zdr', 'chat', 'Zero Data Retention request option and its surcharge accounting', 'api', 'niche'),
+    todo('ai-gateway.limits.rate_limit_429', 'limits', 'Rate-limit 429 Too Many Requests envelope (deterministic twin-armed trigger, figma-style)', 'api', 'common'),
+    // ── streaming ────────────────────────────────────────────────────────────────────────
+    done('ai-gateway.streaming.chunks', 'streaming', 'Streaming emits chat.completion.chunk SSE events and terminates with [DONE]', 'api', 'core', () => withRoot(async (h) => {
+        const events = [];
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ stream: true }), sseSink: (event) => events.push(event) });
+        return r.status === 200 && events.some((event) => event.data?.object === 'chat.completion.chunk') && events.at(-1)?.done === true;
+    })),
+    done('ai-gateway.streaming.reconstruct', 'streaming', 'Streaming content deltas reconstruct the final message content', 'api', 'core', () => withRoot(async (h) => {
+        const events = [];
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ stream: true }), sseSink: (event) => events.push(event) });
+        const streamed = events.filter((event) => event.data).map((event) => (event.data.choices[0]?.delta?.content ?? '')).join('');
+        const full = r.body.choices?.[0]?.message?.content;
+        return streamed === full && streamed.includes('[twin-stub');
+    })),
+    done('ai-gateway.streaming.generation_id_first_chunk', 'streaming', 'The gen_ generation id rides on the FIRST streamed chunk (documented for stream capture)', 'api', 'common', () => withRoot(async (h) => {
+        const events = [];
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ stream: true }), sseSink: (event) => events.push(event) });
+        const firstId = String(events[0]?.data?.id ?? '');
+        return firstId.startsWith('gen_') && firstId === r.body.id;
+    })),
+    done('ai-gateway.streaming.final_usage', 'streaming', 'The final streamed chunk carries finish_reason and usage', 'api', 'common', () => withRoot(async (h) => {
+        const events = [];
+        await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ stream: true }), sseSink: (event) => events.push(event) });
+        const last = events.filter((e) => e.data).at(-1)?.data;
+        return last?.choices?.[0]?.finish_reason === 'stop' && last?.usage?.prompt_tokens > 0;
+    })),
+    done('ai-gateway.streaming.tool_call_deltas', 'streaming', 'Streaming tool calls arrive as OpenAI tool_calls deltas (id/name first, then arguments)', 'api', 'common', () => withRoot(async (h) => {
+        const events = [];
+        await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ stream: true, tools: [{ type: 'function', function: { name: 'lookup', parameters: { type: 'object', properties: { q: { type: 'string' } } } } }] }), sseSink: (event) => events.push(event) });
+        const deltas = events.filter((e) => e.data).map((e) => e.data.choices[0]?.delta?.tool_calls?.[0]).filter(Boolean);
+        const args = deltas.map((d) => d.function?.arguments ?? '').join('');
+        return deltas[0]?.function?.name === 'lookup' && JSON.parse(args).q === 'twin stub' &&
+            events.filter((e) => e.data).some((e) => e.data.choices[0]?.finish_reason === 'tool_calls');
+    })),
+    done('ai-gateway.streaming.n_choices_parity', 'streaming', 'Streaming with n>1 emits every choice index the unary body carries and bills — each reconstructs the full content, each finishes, usage rides the final chunk', 'api', 'niche', () => withRoot(async (h) => {
+        const events = [];
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ stream: true, n: 3 }), sseSink: (event) => events.push(event) });
+        const body = r.body;
+        const datas = events.filter((e) => e.data).map((e) => e.data);
+        const byIndex = (i) => datas.filter((d) => d.choices[0]?.index === i).map((d) => d.choices[0]);
+        const contentOf = (i) => byIndex(i).map((c) => c.delta?.content ?? '').join('');
+        const finished = (i) => byIndex(i).some((c) => c.finish_reason === 'stop');
+        const last = datas.at(-1);
+        return r.status === 200 && body.choices.length === 3 &&
+            [0, 1, 2].every((i) => contentOf(i) === body.choices[i].message?.content && finished(i)) &&
+            last.usage?.completion_tokens === body.usage?.completion_tokens &&
+            datas.filter((d) => d.usage).length === 1; // usage exactly once, on the final chunk
+    })),
+    // ── tool calls ───────────────────────────────────────────────────────────────────────
+    done('ai-gateway.tools.tool_call', 'tools', 'Function tools produce a tool_calls envelope with schema-conformant arguments', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({
+                tools: [{ type: 'function', function: { name: 'get_weather', parameters: { type: 'object', properties: { city: { type: 'string' }, celsius: { type: 'boolean' } } } } }],
+            }) });
+        const choice = r.body.choices?.[0];
+        const call = choice?.message?.tool_calls?.[0];
+        const parsedArgs = JSON.parse(String(call?.function?.arguments ?? '{}'));
+        return r.status === 200 && choice?.finish_reason === 'tool_calls' && call?.type === 'function' &&
+            call?.function?.name === 'get_weather' && String(call?.id).startsWith('call_') &&
+            parsedArgs.city === 'twin stub' && parsedArgs.celsius === true && choice?.message?.content === null;
+    })),
+    done('ai-gateway.tools.tool_choice', 'tools', "tool_choice: 'none' suppresses calls, a named function forces it, unknown names are rejected", 'api', 'common', () => withRoot(async (h) => {
+        const tools = [
+            { type: 'function', function: { name: 'alpha', parameters: { type: 'object' } } },
+            { type: 'function', function: { name: 'beta', parameters: { type: 'object' } } },
+        ];
+        const none = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools, tool_choice: 'none' }) });
+        const named = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools, tool_choice: { type: 'function', function: { name: 'beta' } } }) });
+        const unknown = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools, tool_choice: { type: 'function', function: { name: 'gamma' } } }) });
+        const badShape = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools, tool_choice: 'sometimes' }) });
+        return none.body.choices?.[0]?.finish_reason === 'stop' &&
+            named.body.choices?.[0]?.message?.tool_calls?.[0]?.function?.name === 'beta' &&
+            unknown.status === 400 && badShape.status === 400;
+    })),
+    done('ai-gateway.tools.tool_result_roundtrip', 'tools', 'Tool role messages (with tool_call_id) complete the round trip back to assistant text', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({
+                messages: [
+                    { role: 'user', content: 'what is the weather?' },
+                    { role: 'assistant', content: null, tool_calls: [{ id: 'call_1', type: 'function', function: { name: 'get_weather', arguments: '{}' } }] },
+                    { role: 'tool', tool_call_id: 'call_1', content: '{"temp": 21}' },
+                ],
+            }) });
+        const missing = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({
+                messages: [{ role: 'tool', content: 'orphan result' }],
+            }) });
+        return r.status === 200 && r.body.choices?.[0]?.message?.role === 'assistant' &&
+            r.body.choices?.[0]?.finish_reason === 'stop' &&
+            missing.status === 400 && missing.body.error?.message?.includes('tool_call_id');
+    })),
+    done('ai-gateway.tools.validation', 'tools', 'Malformed tools arrays are rejected with the vendor error envelope', 'api', 'common', () => withRoot(async (h) => {
+        const notArray = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools: 'lookup' }) });
+        const nameless = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools: [{ type: 'function', function: {} }] }) });
+        return notArray.status === 400 && notArray.body.error?.param === 'tools' && nameless.status === 400;
+    })),
+    // ── structured outputs ───────────────────────────────────────────────────────────────
+    done('ai-gateway.structured.json_schema', 'structured_outputs', 'response_format json_schema (OpenAI format) yields schema-conformant JSON', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({
+                response_format: { type: 'json_schema', json_schema: { name: 'weather', strict: true, schema: {
+                            type: 'object', properties: { city: { type: 'string' }, temp: { type: 'number' }, sunny: { type: 'boolean' } },
+                        } } },
+            }) });
+        const content = r.body.choices?.[0]?.message?.content;
+        let parsed = null;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch {
+            parsed = null;
+        }
+        const noName = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ response_format: { type: 'json_schema', json_schema: {} } }) });
+        return r.status === 200 && parsed?.city === 'twin stub' && parsed?.temp === 0 && parsed?.sunny === true &&
+            noName.status === 400 && noName.body.error?.param === 'response_format';
+    })),
+    done('ai-gateway.structured.legacy_json', 'structured_outputs', "Legacy gateway response_format { type: 'json', schema } yields parseable JSON", 'api', 'common', () => withRoot(async (h) => {
+        const withSchema = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({
+                response_format: { type: 'json', schema: { type: 'object', properties: { answer: { type: 'string' } } } },
+            }) });
+        const bare = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ response_format: { type: 'json' } }) });
+        const badType = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ response_format: { type: 'csv' } }) });
+        let schemaParsed = null;
+        let bareParsed = null;
+        try {
+            schemaParsed = JSON.parse(withSchema.body.choices?.[0]?.message?.content);
+            bareParsed = JSON.parse(bare.body.choices?.[0]?.message?.content);
+        }
+        catch {
+            return false;
+        }
+        return withSchema.status === 200 && schemaParsed?.answer === 'twin stub' &&
+            bare.status === 200 && bareParsed?.twin_stub === true &&
+            badType.status === 400 && badType.body.error?.param === 'response_format';
+    })),
+    done('ai-gateway.structured.json_object', 'structured_outputs', "OpenAI-spec passthrough: response_format { type: 'json_object' } yields parseable JSON", 'api', 'niche', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ response_format: { type: 'json_object' } }) });
+        let parsed = null;
+        try {
+            parsed = JSON.parse(r.body.choices?.[0]?.message?.content);
+        }
+        catch {
+            return false;
+        }
+        return r.status === 200 && parsed?.twin_stub === true && String(parsed?.echo).includes('hello ai gateway twin');
+    })),
+    // ── reasoning ────────────────────────────────────────────────────────────────────────
+    done('ai-gateway.reasoning.enabled', 'reasoning', 'reasoning.enabled surfaces message.reasoning + reasoning_details + usage reasoning_tokens', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ reasoning: { enabled: true } }) });
+        const msg = r.body.choices?.[0]?.message;
+        const details = msg?.reasoning_details;
+        const off = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        return r.status === 200 && typeof msg?.reasoning === 'string' &&
+            details?.[0]?.type === 'reasoning.text' && details?.[0]?.format === 'anthropic-claude-v1' && typeof details?.[0]?.signature === 'string' &&
+            r.body.usage?.completion_tokens_details?.reasoning_tokens > 0 &&
+            off.body.choices?.[0]?.message?.reasoning === undefined;
+    })),
+    done('ai-gateway.reasoning.effort_levels', 'reasoning', 'reasoning.effort levels scale reasoning_tokens; effort+max_tokens are mutually exclusive', 'api', 'common', () => withRoot(async (h) => {
+        const low = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ max_tokens: 1000, reasoning: { effort: 'low' } }) });
+        const high = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ max_tokens: 1000, reasoning: { effort: 'high' } }) });
+        const none = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ reasoning: { effort: 'none' } }) });
+        const both = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ reasoning: { effort: 'high', max_tokens: 100 } }) });
+        const badEffort = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ reasoning: { effort: 'turbo' } }) });
+        const lowTokens = low.body.usage?.completion_tokens_details?.reasoning_tokens;
+        const highTokens = high.body.usage?.completion_tokens_details?.reasoning_tokens;
+        return lowTokens === 200 && highTokens === 800 &&
+            none.body.choices?.[0]?.message?.reasoning === undefined &&
+            both.status === 400 && both.body.error?.message?.includes('mutually exclusive') &&
+            badEffort.status === 400;
+    })),
+    done('ai-gateway.reasoning.max_tokens_and_exclude', 'reasoning', 'reasoning.max_tokens budgets tokens exactly; exclude hides content but keeps token accounting', 'api', 'common', () => withRoot(async (h) => {
+        const budgeted = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ reasoning: { max_tokens: 64 } }) });
+        const excluded = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ reasoning: { max_tokens: 64, exclude: true } }) });
+        return budgeted.body.usage?.completion_tokens_details?.reasoning_tokens === 64 &&
+            typeof budgeted.body.choices?.[0]?.message?.reasoning === 'string' &&
+            excluded.body.choices?.[0]?.message?.reasoning === undefined &&
+            excluded.body.usage?.completion_tokens_details?.reasoning_tokens === 64;
+    })),
+    done('ai-gateway.reasoning.details_by_provider_format', 'reasoning', 'reasoning_details normalize per creator: anthropic text+signature, openai summary+encrypted', 'api', 'niche', () => withRoot(async (h) => {
+        const anthropic = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ reasoning: { enabled: true } }) });
+        const openai = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ model: 'openai/gpt-5.2', reasoning: { enabled: true } }) });
+        const a = anthropic.body.choices?.[0]?.message?.reasoning_details;
+        const o = openai.body.choices?.[0]?.message?.reasoning_details;
+        return a?.length === 1 && a[0]?.format === 'anthropic-claude-v1' &&
+            o?.length === 2 && o[0]?.type === 'reasoning.summary' && o[1]?.type === 'reasoning.encrypted' &&
+            o.every((d) => d.format === 'openai-responses-v1');
+    })),
+    done('ai-gateway.reasoning.streaming', 'reasoning', 'Streaming delivers reasoning incrementally via delta.reasoning before content', 'api', 'niche', () => withRoot(async (h) => {
+        const events = [];
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ stream: true, reasoning: { enabled: true } }), sseSink: (event) => events.push(event) });
+        const datas = events.filter((e) => e.data).map((e) => e.data.choices[0]?.delta ?? {});
+        const reasoningIdx = datas.findIndex((d) => typeof d.reasoning === 'string');
+        const contentIdx = datas.findIndex((d) => typeof d.content === 'string');
+        const streamedReasoning = datas.map((d) => d.reasoning ?? '').join('');
+        return reasoningIdx !== -1 && contentIdx !== -1 && reasoningIdx < contentIdx &&
+            streamedReasoning === r.body.choices?.[0]?.message?.reasoning;
+    })),
+    // ── provider routing ─────────────────────────────────────────────────────────────────
+    done('ai-gateway.routing.order', 'routing', 'providerOptions.gateway.order promotes providers; routing metadata records the plan', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ providerOptions: { gateway: { order: ['vertex', 'anthropic'] } } }) });
+        const routing = r.body.providerMetadata?.gateway?.routing;
+        const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ providerOptions: { gateway: { order: [42] } } }) });
+        return r.status === 200 && routing?.resolvedProvider === 'vertex' && routing?.finalProvider === 'vertex' &&
+            routing?.resolvedProviderApiModelId === 'claude-sonnet-4.6' &&
+            JSON.stringify(routing?.fallbacksAvailable) === JSON.stringify(['anthropic', 'bedrock']) &&
+            String(routing?.planningReasoning).includes('vertex') && bad.status === 400;
+    })),
+    done('ai-gateway.routing.only_filter', 'routing', 'only restricts the provider set; an empty intersection fails naming the allowed providers', 'api', 'common', () => withRoot(async (h) => {
+        const ok = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ providerOptions: { gateway: { only: ['bedrock'] } } }) });
+        const none = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ providerOptions: { gateway: { only: ['groq'] } } }) });
+        const combined = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ providerOptions: { gateway: { only: ['anthropic', 'vertex'], order: ['vertex', 'bedrock', 'anthropic'] } } }) });
+        return ok.body.providerMetadata?.gateway?.routing?.resolvedProvider === 'bedrock' &&
+            none.status === 400 && none.body.error?.code === 'no_available_providers' &&
+            none.body.error?.message?.includes('groq') &&
+            combined.body.providerMetadata?.gateway?.routing?.resolvedProvider === 'vertex' &&
+            JSON.stringify(combined.body.providerMetadata?.gateway?.routing?.fallbacksAvailable) === JSON.stringify(['anthropic']);
+    })),
+    done('ai-gateway.routing.sort', 'routing', 'sort (cost/ttft/tps) ranks providers and reports sort metadata (option/executionOrder/metrics)', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ providerOptions: { gateway: { sort: 'cost' } } }) });
+        const sort = r.body.providerMetadata?.gateway?.routing?.sort;
+        const order = sort?.executionOrder;
+        const metrics = sort?.metrics;
+        const ascending = order?.every((p, i) => i === 0 || metrics[order[i - 1]] <= metrics[p]);
+        const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ providerOptions: { gateway: { sort: 'vibes' } } }) });
+        // Combined with `order`: promoted providers lead executionOrder, the rest keep sort order,
+        // and the resolved provider is executionOrder[0] (documented combination semantics).
+        const combined = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ providerOptions: { gateway: { sort: 'cost', order: ['vertex'] } } }) });
+        const combinedSort = combined.body.providerMetadata?.gateway?.routing?.sort;
+        return r.status === 200 && sort?.option === 'cost' && order?.length === 3 && ascending === true &&
+            sort?.deprioritizedProviders?.length === 0 &&
+            r.body.providerMetadata?.gateway?.routing?.resolvedProvider === order?.[0] &&
+            combinedSort?.executionOrder?.[0] === 'vertex' &&
+            combined.body.providerMetadata?.gateway?.routing?.resolvedProvider === 'vertex' &&
+            bad.status === 400 && bad.body.error?.param === 'providerOptions.gateway.sort';
+    })),
+    done('ai-gateway.routing.provider_shorthand', 'routing', "Top-level provider:{sort} shorthand is equivalent; conflicting values fail the request", 'api', 'common', () => withRoot(async (h) => {
+        const shorthand = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ provider: { sort: 'tps' } }) });
+        const conflict = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ provider: { sort: 'tps' }, providerOptions: { gateway: { sort: 'cost' } } }) });
+        const agree = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ provider: { sort: 'cost' }, providerOptions: { gateway: { sort: 'cost' } } }) });
+        return shorthand.body.providerMetadata?.gateway?.routing?.sort?.option === 'tps' &&
+            conflict.status === 400 && conflict.body.error?.message?.includes('same value') &&
+            agree.status === 200;
+    })),
+    done('ai-gateway.routing.model_fallbacks', 'routing', 'models fallback list (top-level or providerOptions.gateway.models) recovers from a failed primary', 'api', 'common', () => withRoot(async (h) => {
+        const top = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ model: 'openai/gpt-99', models: ['anthropic/claude-sonnet-4.6'] }) });
+        const routing = top.body.providerMetadata?.gateway?.routing;
+        const viaOptions = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ model: 'openai/gpt-99', providerOptions: { gateway: { models: ['anthropic/claude-sonnet-4.6'] } } }) });
+        const allUnknown = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ model: 'openai/gpt-99', models: ['nope/nope'] }) });
+        return top.status === 200 && top.body.model === 'anthropic/claude-sonnet-4.6' &&
+            routing?.originalModelId === 'openai/gpt-99' && routing?.modelAttemptCount === 2 &&
+            routing?.modelAttempts?.[0]?.success === false && routing?.modelAttempts?.[1]?.success === true &&
+            viaOptions.status === 200 && allUnknown.status === 404 && allUnknown.body.error?.code === 'model_not_found';
+    })),
+    done('ai-gateway.routing.byok_request_scoped', 'routing', 'Request-scoped BYOK: byok credential attribution, total_cost 0.00 (provider bills), upstream_inference_cost carries the market price', 'api', 'niche', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ providerOptions: { gateway: { byok: { anthropic: [{ apiKey: 'sk-ant-test' }] } } } }) });
+        const attempt = r.body.providerMetadata?.gateway?.routing?.modelAttempts?.at(-1)?.providerAttempts?.[0];
+        const gen = (await h({ m: 'GET', p: `/v1/generation?id=${encodeURIComponent(r.body.id)}` })).body;
+        const credits = (await h({ m: 'GET', p: '/v1/credits' })).body;
+        const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ providerOptions: { gateway: { byok: { anthropic: [] } } } }) });
+        // Docs: total_cost "Returns 0.00 for BYOK requests"; upstream_inference_cost is the market
+        // price the provider would have charged — so BYOK inference must NOT consume gateway credits.
+        return r.status === 200 && attempt?.credentialType === 'byok' && gen.data?.is_byok === true &&
+            gen.data?.total_cost === 0 && gen.data?.upstream_inference_cost > 0 &&
+            r.body.providerMetadata?.gateway?.cost === '0.00' &&
+            Number(r.body.providerMetadata?.gateway?.marketCost) > 0 &&
+            credits.total_used === '0.00' && bad.status === 400;
+    })),
+    todo('ai-gateway.routing.provider_timeouts', 'routing', 'Per-provider timeouts (providerOptions.gateway.providerTimeouts.byok) for fast failover', 'api', 'niche'),
+    todo('ai-gateway.routing.health_guardrails', 'routing', 'Sort health interaction: degraded/recovering providers penalized, down providers last (deprioritizedProviders)', 'api', 'niche'),
+    // ── prompt caching ───────────────────────────────────────────────────────────────────
+    done('ai-gateway.caching.cache_control', 'caching', 'Manual cache_control markers report cached prompt tokens (usage + generation record)', 'api', 'common', () => withRoot(async (h) => {
+        const cached = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({
+                messages: [
+                    { role: 'system', content: 'You are a long cached system prompt for the gateway twin.', cache_control: { type: 'ephemeral' } },
+                    { role: 'user', content: 'hello' },
+                ],
+            }) });
+        const plain = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        const cachedTokens = cached.body.usage?.prompt_tokens_details?.cached_tokens;
+        const gen = await h({ m: 'GET', p: `/v1/generation?id=${encodeURIComponent(cached.body.id)}` });
+        return cached.status === 200 && cachedTokens > 0 &&
+            gen.body.data?.native_tokens_cached === cachedTokens &&
+            plain.body.usage?.prompt_tokens_details === undefined;
+    })),
+    done('ai-gateway.caching.auto_option', 'caching', "providerOptions.gateway.caching: 'auto' is accepted; other values rejected", 'api', 'niche', () => withRoot(async (h) => {
+        const ok = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ providerOptions: { gateway: { caching: 'auto' } } }) });
+        const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ providerOptions: { gateway: { caching: 'always' } } }) });
+        return ok.status === 200 && bad.status === 400 && bad.body.error?.param === 'providerOptions.gateway.caching';
+    })),
+    // ── models catalog ───────────────────────────────────────────────────────────────────
+    done('ai-gateway.models.list', 'models', 'GET /v1/models lists creator/model slugs with gateway fields (name/context_window/type/tags/pricing)', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v1/models' });
+        const b = r.body;
+        const sonnet = b.data?.find((m) => m.id === 'anthropic/claude-sonnet-4.6');
+        return r.status === 200 && b.object === 'list' && b.data.length >= 10 &&
+            sonnet?.object === 'model' && sonnet?.owned_by === 'anthropic' && sonnet?.context_window === 1_000_000 &&
+            sonnet?.type === 'language' && typeof sonnet?.pricing?.input === 'string' && typeof sonnet?.pricing?.output === 'string';
+    })),
+    done('ai-gateway.models.retrieve', 'models', 'GET /v1/models/{creator}/{model} retrieves one model; unknown slugs 404', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v1/models/xai/grok-4-1' });
+        const missing = await h({ m: 'GET', p: '/v1/models/nope/nope' });
+        return r.status === 200 && r.body.id === 'xai/grok-4-1' && r.body.owned_by === 'xai' &&
+            missing.status === 404 && missing.body.error?.code === 'model_not_found';
+    })),
+    done('ai-gateway.models.endpoints', 'models', 'GET /v1/models/{id}/endpoints lists per-provider endpoints with pricing/uptime/latency', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v1/models/openai/gpt-oss-120b/endpoints' });
+        const data = r.body.data;
+        const missing = await h({ m: 'GET', p: '/v1/models/nope/nope/endpoints' });
+        return r.status === 200 && data?.id === 'openai/gpt-oss-120b' &&
+            data?.endpoints?.length === 3 && data?.endpoints?.[0]?.provider_name === 'groq' &&
+            typeof data?.endpoints?.[0]?.pricing?.prompt === 'string' && data?.endpoints?.[0]?.status === 0 &&
+            typeof data?.endpoints?.[0]?.latency_last_1h?.p50 === 'number' && missing.status === 404;
+    })),
+    done('ai-gateway.models.embedding_type', 'models', 'The catalog distinguishes model types (language vs embedding) per the documented type field', 'api', 'niche', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v1/models/openai/text-embedding-3-small' });
+        return r.status === 200 && r.body.type === 'embedding' && r.body.max_tokens === 0;
+    })),
+    todo('ai-gateway.models.tiered_pricing', 'models', 'Tiered pricing (input_tiers/output_tiers with min/max token bounds)', 'api', 'niche'),
+    todo('ai-gateway.models.filtering', 'models', 'Model filtering by capability (model-filtering options)', 'api', 'niche'),
+    // ── embeddings ───────────────────────────────────────────────────────────────────────
+    done('ai-gateway.embeddings.create', 'embeddings', 'POST /v1/embeddings returns deterministic 1536-dim vectors with usage + gateway providerMetadata', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'openai/text-embedding-3-small', input: ['alpha', 'beta'] } });
+        const b = r.body;
+        const again = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'openai/text-embedding-3-small', input: 'alpha' } });
+        const deterministic = JSON.stringify(again.body.data?.[0]?.embedding) === JSON.stringify(b.data?.[0]?.embedding);
+        return r.status === 200 && b.object === 'list' && b.data?.length === 2 && b.data?.[0]?.index === 0 &&
+            Array.isArray(b.data?.[0]?.embedding) && b.data[0].embedding.length === 1536 && deterministic &&
+            b.usage?.prompt_tokens > 0 && typeof b.providerMetadata?.gateway?.cost === 'string' &&
+            b.providerMetadata?.gateway?.routing?.finalProvider === 'openai';
+    })),
+    done('ai-gateway.embeddings.dimensions', 'embeddings', 'The root-level dimensions parameter sets the vector length; invalid values rejected', 'api', 'common', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'openai/text-embedding-3-small', input: 'beach', dimensions: 8 } });
+        const bad = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'openai/text-embedding-3-small', input: 'beach', dimensions: 0 } });
+        return r.status === 200 && r.body.data?.[0]?.embedding?.length === 8 &&
+            bad.status === 400 && bad.body.error?.param === 'dimensions';
+    })),
+    done('ai-gateway.embeddings.validation', 'embeddings', 'Embeddings reject missing input, non-embedding models, and unknown models like the vendor', 'api', 'common', () => withRoot(async (h) => {
+        const noInput = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'openai/text-embedding-3-small' } });
+        const langModel = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'anthropic/claude-sonnet-4.6', input: 'x' } });
+        const unknown = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'nope/nope', input: 'x' } });
+        return noInput.status === 400 && noInput.body.error?.param === 'input' &&
+            langModel.status === 400 && unknown.status === 404;
+    })),
+    done('ai-gateway.embeddings.accounting', 'embeddings', 'Embeddings are billed like the real gateway: each call records a generation (lookup by generationId), credits move, and the spend report counts it', 'api', 'common', () => withRoot(async (h) => {
+        const before = (await h({ m: 'GET', p: '/v1/credits' })).body;
+        const r = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'openai/text-embedding-3-small', input: ['alpha', 'beta'] } });
+        const gw = r.body.providerMetadata?.gateway;
+        const after = (await h({ m: 'GET', p: '/v1/credits' })).body;
+        const gen = (await h({ m: 'GET', p: `/v1/generation?id=${encodeURIComponent(String(gw?.generationId))}` })).body;
+        const report = (await h({ m: 'GET', p: '/v1/report?start_date=1970-01-01&end_date=1970-01-02&group_by=model' })).body;
+        const row = report.results?.find((x) => x.model === 'openai/text-embedding-3-small');
+        return r.status === 200 && String(gw?.generationId).startsWith('gen_') && Number(gw?.cost) > 0 &&
+            before.total_used === '0.00' && Number(after.total_used) > 0 &&
+            Math.abs(Number(after.total_used) - Number(gw?.cost)) < 1e-9 &&
+            gen.data?.model === 'openai/text-embedding-3-small' && gen.data?.tokens_prompt > 0 &&
+            gen.data?.tokens_completion === 0 && gen.data?.streamed === false &&
+            row?.request_count === 1 && row?.input_tokens > 0 && row?.output_tokens === 0;
+    })),
+    todo('ai-gateway.embeddings.encoding_format', 'embeddings', 'encoding_format base64 for embedding vectors', 'api', 'niche'),
+    // ── AI SDK gateway protocol (/v3/ai — @ai-sdk/gateway / `createGateway`) ─────────────
+    done('ai-gateway.v3.config', 'ai_sdk_protocol', 'GET /v3/ai/config serves the model config document getAvailableModels() consumes (v3 specification blocks, decimal-string pricing, modelType)', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v3/ai/config' });
+        const models = r.body.models;
+        const sonnet = models?.find((m) => m.id === 'anthropic/claude-sonnet-4.6');
+        const embed = models?.find((m) => m.id === 'openai/text-embedding-3-small');
+        return r.status === 200 && models?.length >= 10 &&
+            sonnet?.specification?.specificationVersion === 'v3' && sonnet?.specification?.provider === 'anthropic' &&
+            sonnet?.specification?.modelId === 'anthropic/claude-sonnet-4.6' &&
+            typeof sonnet?.pricing?.input === 'string' && typeof sonnet?.pricing?.output === 'string' &&
+            sonnet?.modelType === 'language' && embed?.modelType === 'embedding';
+    })),
+    done('ai-gateway.v3.language_model.generate', 'ai_sdk_protocol', 'POST /v3/ai/language-model honors the ai-language-model-id header and returns the LanguageModelV3 result (content parts, unified finishReason, nested usage, providerMetadata.gateway) — recorded in the SAME generation fold as /v1 chats', 'api', 'core', () => withRoot(async (h) => {
+        const V3_HD = { 'ai-language-model-id': 'anthropic/claude-sonnet-4.6', 'ai-language-model-specification-version': '3', 'ai-language-model-streaming': 'false' };
+        const r = await h({ m: 'POST', p: '/v3/ai/language-model', hd: V3_HD, b: {
+                prompt: [{ role: 'user', content: [{ type: 'text', text: 'hello ai gateway twin' }] }],
+            } });
+        const b = r.body;
+        const text = b.content?.find((p) => p.type === 'text')?.text;
+        const genId = String(b.providerMetadata?.gateway?.generationId ?? '');
+        const gen = (await h({ m: 'GET', p: `/v1/generation?id=${encodeURIComponent(genId)}` })).body;
+        const credits = (await h({ m: 'GET', p: '/v1/credits' })).body;
+        return r.status === 200 && text?.includes('[twin-stub:ai-gateway') && text?.includes('hello ai gateway twin') &&
+            b.finishReason?.unified === 'stop' && b.finishReason?.raw === 'stop' &&
+            b.usage?.inputTokens?.total > 0 && b.usage?.outputTokens?.total > 0 &&
+            genId.startsWith('gen_') && gen.data?.model === 'anthropic/claude-sonnet-4.6' &&
+            gen.data?.total_cost > 0 && Number(credits.total_used) > 0;
+    })),
+    done('ai-gateway.v3.language_model.stream', 'ai_sdk_protocol', 'The ai-language-model-streaming header switches to LanguageModelV3 stream parts (response-metadata → text deltas → finish with usage), recorded streamed', 'api', 'core', () => withRoot(async (h) => {
+        const events = [];
+        const r = await h({ m: 'POST', p: '/v3/ai/language-model',
+            hd: { 'ai-language-model-id': 'anthropic/claude-sonnet-4.6', 'ai-language-model-streaming': 'true' },
+            b: { prompt: [{ role: 'user', content: [{ type: 'text', text: 'stream me' }] }] },
+            sseSink: (event) => events.push(event) });
+        const datas = events.filter((e) => e.data).map((e) => e.data);
+        const streamed = datas.filter((d) => d.type === 'text-delta').map((d) => d.delta).join('');
+        const finish = datas.find((d) => d.type === 'finish');
+        const meta = datas[0];
+        const gen = (await h({ m: 'GET', p: `/v1/generation?id=${encodeURIComponent(String(meta?.id))}` })).body;
+        const unaryText = r.body.content?.find((p) => p.type === 'text')?.text;
+        return r.status === 200 && meta?.type === 'response-metadata' && String(meta?.id).startsWith('gen_') &&
+            streamed === unaryText && streamed.includes('stream me') &&
+            finish?.finishReason?.unified === 'stop' && finish?.usage?.inputTokens?.total > 0 &&
+            events.at(-1)?.done === true && gen.data?.streamed === true;
+    })),
+    done('ai-gateway.v3.language_model.tools', 'ai_sdk_protocol', 'V3 function tools (inputSchema) yield a tool-call content part with schema-conformant input and a tool-calls finish; provider-executed tools fail loudly (unmodeled)', 'api', 'common', () => withRoot(async (h) => {
+        const V3_HD = { 'ai-language-model-id': 'openai/gpt-5.2', 'ai-language-model-streaming': 'false' };
+        const r = await h({ m: 'POST', p: '/v3/ai/language-model', hd: V3_HD, b: {
+                prompt: [{ role: 'user', content: [{ type: 'text', text: 'weather in Paris?' }] }],
+                tools: [{ type: 'function', name: 'get_weather', inputSchema: { type: 'object', properties: { city: { type: 'string' } } } }],
+                toolChoice: { type: 'tool', toolName: 'get_weather' },
+            } });
+        const call = r.body.content?.find((p) => p.type === 'tool-call');
+        const providerTool = await h({ m: 'POST', p: '/v3/ai/language-model', hd: V3_HD, b: {
+                prompt: [{ role: 'user', content: [{ type: 'text', text: 'search' }] }],
+                tools: [{ type: 'provider', id: 'gateway.parallel_search', name: 'parallel_search', args: {} }],
+            } });
+        return r.status === 200 && call?.toolName === 'get_weather' && String(call?.toolCallId).startsWith('call_') &&
+            JSON.parse(String(call?.input)).city === 'twin stub' &&
+            r.body.finishReason?.unified === 'tool-calls' &&
+            providerTool.status === 400;
+    })),
+    done('ai-gateway.v3.validation', 'ai_sdk_protocol', 'V3 calls validate the protocol headers, and unknown models fail with the model_not_found envelope the SDK maps to GatewayModelNotFoundError', 'api', 'common', () => withRoot(async (h) => {
+        const prompt = { prompt: [{ role: 'user', content: [{ type: 'text', text: 'x' }] }] };
+        const noModel = await h({ m: 'POST', p: '/v3/ai/language-model', b: prompt });
+        const badSpec = await h({ m: 'POST', p: '/v3/ai/language-model', hd: { 'ai-language-model-id': 'anthropic/claude-sonnet-4.6', 'ai-language-model-specification-version': '2' }, b: prompt });
+        const unknown = await h({ m: 'POST', p: '/v3/ai/language-model', hd: { 'ai-language-model-id': 'nope/nope' }, b: prompt });
+        const unmodeled = await h({ m: 'POST', p: '/v3/ai/embedding-model', hd: { 'ai-model-id': 'openai/text-embedding-3-small' }, b: { values: ['x'] } });
+        return noModel.status === 400 && noModel.body.error?.param === 'ai-language-model-id' &&
+            badSpec.status === 400 &&
+            unknown.status === 404 && unknown.body.error?.type === 'model_not_found' &&
+            unknown.body.error?.param?.modelId === 'nope/nope' &&
+            unmodeled.status === 404 && unmodeled.body.error?.code === 'not_found';
+    })),
+    todo('ai-gateway.v3.embedding_model', 'ai_sdk_protocol', 'POST /v3/ai/embedding-model (the AI SDK EmbeddingModelV3 wire protocol: values + ai-model-id header → embeddings/usage/providerMetadata)', 'api', 'common'),
+    todo('ai-gateway.v3.image_model', 'ai_sdk_protocol', 'POST /v3/ai/image-model (the AI SDK ImageModelV3 wire protocol)', 'api', 'niche'),
+    todo('ai-gateway.v3.video_model', 'ai_sdk_protocol', 'POST /v3/ai/video-model (the AI SDK VideoModelV3 wire protocol)', 'api', 'niche'),
+    todo('ai-gateway.v3.provider_tools', 'ai_sdk_protocol', 'Provider-executed gateway tools over the V3 protocol (gateway.parallel_search / gateway.perplexity_search tool results)', 'api', 'niche'),
+    // ── credits / generations / report (REST API Reference) ─────────────────────────────
+    done('ai-gateway.credits.get', 'credits', 'GET /v1/credits returns balance and total_used as decimal strings', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'GET', p: '/v1/credits' });
+        const b = r.body;
+        return r.status === 200 && b.balance === '100.00' && b.total_used === '0.00';
+    })),
+    done('ai-gateway.credits.spend_coupled', 'credits', 'Credits are live accounting: every chat (even identical repeats) increases total_used and decreases balance', 'api', 'common', () => withRoot(async (h) => {
+        const before = (await h({ m: 'GET', p: '/v1/credits' })).body;
+        const first = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        const second = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() }); // identical request — must still be billed
+        const cost = Number(first.body.providerMetadata?.gateway?.cost);
+        const after = (await h({ m: 'GET', p: '/v1/credits' })).body;
+        return before.total_used === '0.00' && cost > 0 &&
+            first.body.id !== second.body.id &&
+            Math.abs(Number(after.total_used) - 2 * cost) < 1e-9 &&
+            Math.abs(Number(after.balance) - (100 - 2 * cost)) < 1e-9;
+    })),
+    done('ai-gateway.generation.lookup', 'generations', 'GET /v1/generation?id returns cost/latency/token usage for a recorded generation; ids are unique so lookups never return another request\'s record', 'api', 'core', () => withRoot(async (h) => {
+        const chat = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        const id = chat.body.id;
+        const r = await h({ m: 'GET', p: `/v1/generation?id=${encodeURIComponent(id)}` });
+        const d = r.body.data;
+        // Two requests differing ONLY in routing options must mint distinct ids and each lookup
+        // must return ITS OWN provider (the §5 subject-id-collision trap).
+        const bedrock = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ providerOptions: { gateway: { order: ['bedrock'] } } }) });
+        const vertex = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ providerOptions: { gateway: { order: ['vertex'] } } }) });
+        const bedrockGen = (await h({ m: 'GET', p: `/v1/generation?id=${encodeURIComponent(bedrock.body.id)}` })).body;
+        const vertexGen = (await h({ m: 'GET', p: `/v1/generation?id=${encodeURIComponent(vertex.body.id)}` })).body;
+        return r.status === 200 && d?.id === id && d?.model === 'anthropic/claude-sonnet-4.6' &&
+            d?.provider_name === 'anthropic' && d?.finish_reason === 'stop' && d?.streamed === false &&
+            d?.total_cost > 0 && d?.usage === d?.total_cost && d?.upstream_inference_cost === 0 &&
+            d?.tokens_prompt > 0 && d?.tokens_completion > 0 && typeof d?.latency === 'number' &&
+            typeof d?.generation_time === 'number' && d?.billable_web_search_calls === 0 &&
+            bedrock.body.id !== vertex.body.id &&
+            bedrockGen.data?.provider_name === 'bedrock' && vertexGen.data?.provider_name === 'vertex';
+    })),
+    done('ai-gateway.generation.streamed_flag', 'generations', 'Generation records preserve the streamed flag for streaming completions', 'api', 'niche', () => withRoot(async (h) => {
+        const events = [];
+        const chat = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ stream: true }), sseSink: (e) => events.push(e) });
+        const r = await h({ m: 'GET', p: `/v1/generation?id=${encodeURIComponent(chat.body.id)}` });
+        return r.body.data?.streamed === true;
+    })),
+    done('ai-gateway.generation.errors', 'generations', 'Generation lookup 400s without an id and 404s for unknown ids', 'api', 'common', () => withRoot(async (h) => {
+        const noId = await h({ m: 'GET', p: '/v1/generation' });
+        const unknown = await h({ m: 'GET', p: '/v1/generation?id=gen_DOESNOTEXIST' });
+        return noId.status === 400 && noId.body.error?.param === 'id' &&
+            unknown.status === 404 && unknown.body.error?.code === 'not_found';
+    })),
+    done('ai-gateway.report.validation', 'report', 'GET /v1/report validates the documented query params (date range, group_by, date_part, credential_type, tags_match)', 'api', 'common', () => withRoot(async (h) => {
+        const noRange = await h({ m: 'GET', p: '/v1/report' });
+        const badDate = await h({ m: 'GET', p: '/v1/report?start_date=jan-1&end_date=2026-01-31' });
+        const badGroup = await h({ m: 'GET', p: '/v1/report?start_date=2026-01-01&end_date=2026-01-31&group_by=vibes' });
+        const badPart = await h({ m: 'GET', p: '/v1/report?start_date=2026-01-01&end_date=2026-01-31&date_part=minute' });
+        const badCred = await h({ m: 'GET', p: '/v1/report?start_date=2026-01-01&end_date=2026-01-31&credential_type=vault' });
+        const badMatch = await h({ m: 'GET', p: '/v1/report?start_date=2026-01-01&end_date=2026-01-31&tags=a&tags_match=some' });
+        return noRange.status === 400 && noRange.body.error?.param === 'start_date' &&
+            badDate.status === 400 && badGroup.status === 400 && badGroup.body.error?.param === 'group_by' &&
+            badPart.status === 400 && badPart.body.error?.param === 'date_part' &&
+            badCred.status === 400 && badMatch.status === 400;
+    })),
+    done('ai-gateway.report.spend_by_model', 'report', 'Spend report serves the documented results rows (grouping field + total/market cost, token counts, request_count) over recorded generations', 'api', 'common', () => withRoot(async (h) => {
+        await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+        await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() }); // identical repeat — its own generation
+        await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ model: 'zai/glm-4.6' }) });
+        const byModel = await h({ m: 'GET', p: '/v1/report?start_date=1970-01-01&end_date=1970-01-02&group_by=model' });
+        const rows = byModel.body.results;
+        const sonnet = rows?.find((r) => r.model === 'anthropic/claude-sonnet-4.6');
+        const byDay = await h({ m: 'GET', p: '/v1/report?start_date=1970-01-01&end_date=1970-01-02' });
+        const dayRow = byDay.body.results?.[0];
+        const byHour = await h({ m: 'GET', p: '/v1/report?start_date=1970-01-01&end_date=1970-01-02&date_part=hour' });
+        const hourRow = byHour.body.results?.[0];
+        const filtered = await h({ m: 'GET', p: '/v1/report?start_date=1970-01-01&end_date=1970-01-02&group_by=model&model=zai/glm-4.6' });
+        const outOfRange = await h({ m: 'GET', p: '/v1/report?start_date=2030-01-01&end_date=2030-01-31' });
+        return byModel.status === 200 && rows?.length === 2 &&
+            sonnet?.request_count === 2 && sonnet?.total_cost > 0 && sonnet?.market_cost >= sonnet?.total_cost &&
+            sonnet?.gateway_cost === 0 && sonnet?.surcharge_cost === 0 &&
+            sonnet?.input_tokens > 0 && sonnet?.output_tokens > 0 &&
+            sonnet?.cached_input_tokens === 0 && sonnet?.cache_creation_input_tokens === 0 && sonnet?.reasoning_tokens === 0 &&
+            dayRow?.day === '1970-01-01' && dayRow?.request_count === 3 &&
+            hourRow?.hour === '1970-01-01T00' && hourRow?.request_count === 3 &&
+            filtered.body.results?.length === 1 &&
+            filtered.body.results?.[0]?.model === 'zai/glm-4.6' &&
+            outOfRange.body.results?.length === 0;
+    })),
+    todo('ai-gateway.report.attribution_groupings', 'report', 'Report groupings and filters over request attribution (user/tag/api_key_name/zero_data_retention) backed by real recorded attribution', 'api', 'niche'),
+    // ── honesty / error shapes ───────────────────────────────────────────────────────────
+    done('ai-gateway.errors.envelope', 'honesty', 'Errors use the documented envelope: { error: { message, type, param, code } }', 'api', 'core', () => withRoot(async (h) => {
+        const r = await h({ m: 'POST', p: '/v1/chat/completions', b: { messages: [{ role: 'user', content: 'x' }] } });
+        const e = r.body.error;
+        return r.status === 400 && typeof e?.message === 'string' && e?.type === 'invalid_request_error' &&
+            e?.param === 'model' && e?.code === 'missing_parameter';
+    })),
+    done('ai-gateway.readonly.rejects_writes', 'honesty', 'readOnly mode rejects chat/embeddings writes with 405 while reads still serve', 'api', 'common', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'ai-gateway-cap-ro-'));
+        try {
+            const chat = await handleAiGatewayTwinRequest({ method: 'POST', path: '/v1/chat/completions', body: JSON.stringify(CHAT()), readOnly: true, root });
+            const embed = await handleAiGatewayTwinRequest({ method: 'POST', path: '/v1/embeddings', body: JSON.stringify({ model: 'openai/text-embedding-3-small', input: 'x' }), readOnly: true, root });
+            const models = await handleAiGatewayTwinRequest({ method: 'GET', path: '/v1/models', readOnly: true, root });
+            return chat.status === 405 && embed.status === 405 && models.status === 200 && models.body.data.length > 0;
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    done('ai-gateway.unmodeled.404', 'honesty', 'Unmodeled operations fail with a vendor-shaped 404 instead of fake success', 'api', 'core', () => withRoot(async (h) => {
+        const post = await h({ m: 'POST', p: '/v1/totally/unmodeled', b: { x: 1 } });
+        const responses = await h({ m: 'POST', p: '/v1/responses', b: { model: 'openai/gpt-5.2', input: 'hi' } });
+        return post.status === 404 && post.body.error?.code === 'not_found' &&
+            responses.status === 404;
+    })),
+    todo('ai-gateway.auth.bearer_enforcement', 'auth', 'Reject missing/invalid Authorization bearer with the vendor 401 shape (twin currently fakes auth)', 'api', 'core'),
+    // ── compatibility APIs not yet modeled (real gateway surface → honest todos) ─────────
+    todo('ai-gateway.responses.create', 'responses_api', 'OpenAI Responses API compatibility (POST /v1/responses)', 'api', 'common'),
+    todo('ai-gateway.responses.streaming', 'responses_api', 'Responses API streaming events', 'api', 'common'),
+    todo('ai-gateway.responses.cache_anchor', 'responses_api', 'Responses API cache_anchor_items + cache_ttl top-level fields', 'api', 'niche'),
+    todo('ai-gateway.anthropic_messages.create', 'anthropic_messages', 'Anthropic Messages API compatibility (POST /v1/messages)', 'api', 'common'),
+    todo('ai-gateway.anthropic_messages.streaming', 'anthropic_messages', 'Anthropic Messages API SSE streaming', 'api', 'common'),
+    todo('ai-gateway.openresponses.create', 'openresponses', 'OpenResponses API specification support', 'api', 'niche'),
+    todo('ai-gateway.images.generation', 'modalities', 'Image generation via multimodal chat completions', 'api', 'common'),
+    todo('ai-gateway.video.generation', 'modalities', 'Video generation models', 'api', 'niche'),
+    todo('ai-gateway.byok.persistent', 'auth', 'Persistent BYOK credential management (dashboard-configured keys influencing routing)', 'api', 'niche'),
+    // ── connector ────────────────────────────────────────────────────────────────────────
+    done('ai-gateway.connector.pull', 'connector', 'Connector pulls the model catalog + credits through an injected client idempotently', 'connector', 'common', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'ai-gateway-connector-cap-'));
+        try {
+            let calls = 0;
+            const execute = async (req) => {
+                calls++;
+                if (req.path === '/v1/models')
+                    return { status: 200, data: { object: 'list', data: [{ id: 'vendor/model-a', object: 'model', owned_by: 'vendor' }] } };
+                if (req.path === '/v1/credits')
+                    return { status: 200, data: { balance: '42.00', total_used: '8.00' } };
+                return { status: 404, data: {} };
+            };
+            await pullAiGatewayState(execute, { root });
+            await pullAiGatewayState(execute, { root });
+            const models = projectResources('ai-gateway', root).filter((r) => r.type === 'model');
+            const credits = projectResources('ai-gateway', root).filter((r) => r.type === 'credits');
+            return calls === 4 && models.length === 1 && models[0]?.id === 'model_vendor/model-a' &&
+                credits.length === 1 && credits[0]?.balance === '42.00';
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    done('ai-gateway.connector.push', 'connector', 'Connector reconciles pending generation records via GET /v1/generation through an injected client idempotently', 'connector', 'niche', async () => {
+        const root = mkdtempSync(join(tmpdir(), 'ai-gateway-connector-cap-'));
+        try {
+            await applyTwinWrite('ai-gateway', {
+                operation: 'generation.record',
+                subjectType: 'generation',
+                subjectId: 'gen_CAPTEST',
+                fields: { id: 'gen_CAPTEST', model: 'anthropic/claude-sonnet-4.6', total_cost: 0.001 },
+                occurredAt: '1970-01-01T00:00:00.000Z',
+                actor: { kind: 'system' },
+            }, root);
+            const paths = [];
+            const execute = async (req) => {
+                paths.push(req.path);
+                return { status: 200, data: { data: { id: 'gen_CAPTEST' } } };
+            };
+            const first = await performPending(execute, { root });
+            const second = await performPending(execute, { root });
+            return first === 1 && second === 0 && pendingActions('ai-gateway', root).length === 0 &&
+                paths.length === 1 && paths[0] === '/v1/generation?id=gen_CAPTEST';
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }),
+    // Pull-surface coverage audit gap (TWIN-46 / G2) — filed as a manifest todo so
+    // the demand-ordered build list is drawn from manifest todos. See pull-audit.json.
+    todo('ai-gateway.connector.pull_report', 'connector', 'Connector: pull aggregated spend (GET /v1/report) from the real account', 'connector', 'common'),
+];
+// The repo's aggregate-manifest convention (scripts/mutation-test.ts META-CHECK 1) derives the
+// export name mechanically as `<vendor>.toUpperCase() + '_CAPABILITIES'` — for the hyphenated
+// `ai-gateway` vendor id that is the (non-identifier) name "AI-GATEWAY_CAPABILITIES", exported
+// here via an ES2022 arbitrary module namespace name alias.
+export { AI_GATEWAY_CAPABILITIES as 'AI-GATEWAY_CAPABILITIES' };
+export async function aiGatewayCapabilities() {
+    return checkCapabilities('ai-gateway', AI_GATEWAY_CAPABILITIES);
+}