@volter/twin-fireworks 0.1.0

package/dist/src/fireworks-twin.js

@@ -0,0 +1,1426 @@
+// Fireworks twin REQUEST HANDLER — the canonical Fireworks API surface for the twin.
+// Contract: handleFireworksTwinRequest({method, path, body}) -> {status, body}. It is the
+// faithful Fireworks API the official clients (the `fireworks` Python SDK, `@ai-sdk/fireworks`,
+// plain OpenAI clients pointed at api.fireworks.ai/inference/v1) talk to UNMODIFIED.
+//
+// Fireworks serves TWO planes on ONE host, and the twin serves both under the paths the vendor
+// actually publishes:
+//   • INFERENCE — `/inference/v1/…` (OpenAI-compatible: chat/completions, completions, responses,
+//     embeddings, rerank) plus the Anthropic-compatible `/inference/v1/messages`. The twin cannot
+//     run a model, so generative output is a DETERMINISTIC STUB (fireworks-stub.ts), clearly
+//     labeled — never pretending to be real inference. The wire around it is faithful, INCLUDING
+//     Fireworks' documented OpenAI differences:
+//       - streaming usage arrives in the final chunk BY DEFAULT (OpenAI makes it opt-in);
+//       - `context_length_exceeded_behavior` defaults to `truncate`, not `error`;
+//       - `service_tier` accepts only 'priority' — every other value is treated as 'default'
+//         (documented; NOT an error);
+//       - validation failures answer the FastAPI `422 HTTPValidationError` envelope the vendor's
+//         own spec declares on these operations.
+//   • CONTROL — the Gateway REST API under `/v1/accounts/{account_id}/…`: deployments, datasets,
+//     batch-inference and supervised-fine-tuning jobs, users + their apiKeys, secrets, models.
+//     Stateful over the kernel action log; google.rpc-style errors (gatewayStatus {code,message});
+//     list envelopes `{<plural>, nextPageToken, totalSize}`; create ids passed as QUERY params
+//     (deployments/datasets/users) or inside the body (datasets), per the vendor's own spec.
+//
+// State lives in the kernel action log (D1): all writes are local actions, reads are the
+// projection. No real Fireworks API is ever called from this path (D4). Streaming uses an
+// INJECTED sink — no real sockets / setTimeout (D5 verify is offline + deterministic).
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { FIREWORKS_MODEL_IDS } from "./fireworks-models.js";
+import { contentToText, countPromptTokens, estimateTokens, fnv1a, pseudoEmbedding, stubAssistantText, stubReasoningText, stubRelevanceScore, } from "./fireworks-stub.js";
+import { realizeFireworksRespond } from "./fireworks-scenario.js";
+const SERVICE = 'fireworks';
+/** The inference base path. The vendor's inference server root is `https://api.fireworks.ai/inference`
+ *  and every OpenAI-compat operation hangs off `/v1/…` under it. */
+export const FIREWORKS_INFERENCE_PREFIX = '/inference/v1';
+/** The control-plane base path: everything Gateway REST hangs off `/v1/accounts/{account_id}/…`. */
+export const FIREWORKS_ACCOUNTS_PREFIX = '/v1/accounts';
+// ── vendor-shaped errors ──────────────────────────────────────────────────────────────
+// TWO error envelopes, one per plane — mixing them would be a wire lie:
+//   • the inference plane's OpenAI-compat surface answers `{ error: { message, … } }` (the
+//     OpenAI shape the clients parse); the Anthropic-compat /v1/messages answers
+//     `{ type: 'error', error: { type, message }, request_id }` (the Anthropic shape);
+//   • the control plane answers google.rpc-style `{ code: <gatewayCode>, message }` — the shape
+//     the vendor's own spec embeds on every resource (`gatewayStatus`) and its gatewayCode enum.
+function errBody(message, extra = {}) {
+    return { error: { message, ...extra } };
+}
+function invalidRequest(message, extra = {}) {
+    return { status: 400, body: errBody(message, { code: 400, ...extra }) };
+}
+function notFound(message) {
+    return { status: 404, body: errBody(message, { code: 404 }) };
+}
+function authError(message) {
+    return { status: 401, body: errBody(message, { code: 401 }) };
+}
+/** The FastAPI validation envelope the vendor's own spec declares on the inference operations
+ *  (`422 HTTPValidationError` → `detail: [{loc, msg, type}]`). */
+function validationError(loc, msg, type) {
+    return { status: 422, body: { detail: [{ loc, msg, type }] } };
+}
+/** The google.rpc-style control-plane error. `code` is a gatewayCode string, mapped from the
+ *  HTTP status the way the vendor's own status embedding implies (NOT_FOUND → 'NOT_FOUND', …). */
+function gatewayError(status, message) {
+    const code = status === 400 ? 'INVALID_ARGUMENT' :
+        status === 401 ? 'UNAUTHENTICATED' :
+            status === 403 ? 'PERMISSION_DENIED' :
+                status === 404 ? 'NOT_FOUND' :
+                    status === 409 ? 'ALREADY_EXISTS' :
+                        'UNKNOWN';
+    return { status, body: { code, message } };
+}
+// ── modeled authentication (401) ────────────────────────────────────────────────────────
+// Real Fireworks requires a bearer credential on every request (docs.fireworks.ai/api-reference/
+// introduction: "All requests … must include an Authorization header with a valid Bearer token")
+// and answers 401 Unauthorized when it is missing or invalid (the vendor's own error-code table).
+// The twin can't validate against real keys, so it models the CHECKABLE failures: a missing
+// credential, and a reserved sentinel for the invalid-key path. Any other non-empty key is
+// accepted. Trusted in-process calls carry NEITHER `headers` nor `apiKey` and are NOT auth-gated;
+// the official clients always send a key → they pass.
+function checkAuth(req) {
+    const auth = req.headers?.['authorization'];
+    const bearer = typeof auth === 'string' && auth.toLowerCase().startsWith('bearer ') ? auth.slice(7).trim() : '';
+    const key = (req.apiKey ?? '').trim() || bearer;
+    if (!key || key === 'fw_invalid' || key === 'invalid') {
+        // Each plane answers 401 in its OWN envelope — a control-plane 401 carrying the OpenAI shape
+        // would mix the envelopes the header above calls a wire lie.
+        if (req.path.startsWith(`${FIREWORKS_INFERENCE_PREFIX}/messages`)) {
+            return anthropicError(401, 'authentication_error', 'Unauthorized: missing or invalid API key');
+        }
+        if (req.path.startsWith(`${FIREWORKS_ACCOUNTS_PREFIX}/`)) {
+            return gatewayError(401, 'Unauthorized: missing or invalid API key');
+        }
+        return authError('Unauthorized: missing or invalid API key');
+    }
+    return null;
+}
+function nowEpoch(occurredAt) {
+    return Math.floor((occurredAt ? Date.parse(occurredAt) : 0) / 1000);
+}
+// ── kernel helpers ──────────────────────────────────────────────────────────────────────
+/**
+ * Rows of `type`, SCOPED TO ONE ACCOUNT. Every control-plane resource is stored with the
+ * `accountId` it was created (or pulled) under, and every read goes through this — a resource
+ * addressed under a different account's path is invisible here, which is what makes the
+ * cross-account GET/PATCH/DELETE answer the vendor's own NOT_FOUND. `accountId === undefined`
+ * means the caller reads a plane with NO account segment (the inference plane's stored
+ * responses) — those rows are not account-scoped and the filter is skipped for them.
+ */
+/** A row is gone when the TWIN deleted it (`_deleted`, the twin's own marker) or when the
+ *  CONNECTOR observed it vanish from the vendor (`deleted`, the kernel's tombstone field).
+ *  Reading only the first served a resource the pull had correctly tombstoned (round-four review). */
+export function isTombstoned(r) {
+    return r._deleted === true || r.deleted === true;
+}
+function rows(type, accountId, root) {
+    return projectResources(SERVICE, root).filter((r) => r.type === type && (accountId === undefined || r._account === accountId));
+}
+/**
+ * Mint the next local id for `type`. Derived from the ID SET ALREADY IN STATE (a scan of the
+ * projection), never a row count — a count-mint silently clobbers a pulled vendor id sitting in a
+ * gap above the count (ADDING_A_TWIN.md §5). The `_twin_` infix namespaces LOCAL mints, so a
+ * pulled Fireworks id can never be matched by this regex and therefore can never be re-minted;
+ * the scan includes TOMBSTONED rows, so the counter RATCHETS across delete→recreate. The scan is
+ * PER ACCOUNT (rows() filters by `_account`) and matches the id SUFFIX after the account
+ * namespace, so two tenants each mint their own `dep_twin_1` without colliding.
+ */
+function nextId(type, prefix, accountId, root) {
+    let max = 0;
+    for (const r of rows(type, accountId, root)) {
+        const local = accountId !== undefined && typeof r.id === 'string' && r.id.startsWith(`${accountId}/`)
+            ? r.id.slice(accountId.length + 1)
+            : String(r.id);
+        const m = new RegExp(`^${prefix}_twin_(\\d+)$`).exec(local);
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return `${prefix}_twin_${max + 1}`;
+}
+/**
+ * Resolve one row by its BARE (wire) id inside one account. The kernel subject is the
+ * ACCOUNT-NAMESPACED id `${accountId}/${id}` — matching the vendor's own name grammar
+ * `accounts/{account}/{collection}/{id}` — so (type, subject) is unique per tenant and account
+ * B's create of the same id can never land on account A's row. Pulled rows carry the same
+ * namespaced id (the connector's mappers emit it), so created and pulled rows share one id space.
+ */
+function getRow(type, id, accountId, root) {
+    const full = accountId === undefined ? id : `${accountId}/${id}`;
+    return rows(type, accountId, root).find((r) => r.id === full);
+}
+/** Strip the kernel's housekeeping fields and the twin's private underscore-prefixed fields. */
+function strip(r) {
+    const out = {};
+    for (const [k, v] of Object.entries(r)) {
+        if (k === 'type' || k === 'updatedAt' || k === 'deleted' || k.startsWith('_'))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+// ── request parsing ─────────────────────────────────────────────────────────────────────
+function parseJson(body) {
+    if (!body || !body.trim())
+        return {};
+    try {
+        const v = JSON.parse(body);
+        return v && typeof v === 'object' ? v : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** A deterministic id suffix from the request (so ids are stable + assertable). */
+function stableSuffix(seedText) {
+    return fnv1a(seedText).toString(36);
+}
+// ── model catalog (the 404 the vendor answers for an unknown model id) ──────────────────
+/**
+ * The model ids the INFERENCE plane accepts: the static catalog (fireworks-models.ts, sourced)
+ * PLUS every model row the control plane holds (a create/pull under /v1/accounts/.../models —
+ * an account-owned model is addressable for inference exactly as the vendor allows, including
+ * the fine-tunes). A pulled/created row of the same id as a static entry just re-states it.
+ * Real Fireworks answers 404 "Model id not found" for an id outside this set — the twin must
+ * refuse the same way, never answer 200 for any string.
+ */
+function servedModelIds(root) {
+    const ids = new Set(FIREWORKS_MODEL_IDS);
+    for (const r of projectResources(SERVICE, root)) {
+        if (r.type !== 'model' || isTombstoned(r))
+            continue;
+        // A control-plane-created model is addressed ONLY by its FULL resource name on the
+        // inference plane (`accounts/{account}/models/{id}`) — the `name` the create handler
+        // minted. The bare suffix is NOT an alias: the vendor's own inference API takes full
+        // resource names for account-owned models (the static catalog's short aliases are
+        // documented serverless serving paths, a different thing), and accepting the bare suffix
+        // leaked one account's model into EVERY account's inference plane — a model created only
+        // under SECRETACCT answered 200 as the bare id while its qualified name 404'd under
+        // another account (inverted tenancy). The kernel subject stays the account-namespaced id
+        // (`{account}/{id}`); only the wire `name` joins the catalog.
+        if (typeof r.name === 'string')
+            ids.add(r.name);
+    }
+    return ids;
+}
+/** The vendor's own refusal for an unknown model id (its error table: 404 covers "the model
+ *  doesn't exist, the model is not deployed, or you don't have permission to access it"). */
+function unknownModel(model) {
+    return notFound(`Model id not found: ${model}`);
+}
+// ── chat completions: validate the request the way Fireworks does ───────────────────────
+const SERVICE_TIERS = ['auto', 'default', 'flex', 'priority'];
+const CONTEXT_BEHAVIORS = ['error', 'truncate'];
+/**
+ * The inference sampling parameters' documented ranges, from the pinned spec's own field
+ * descriptions (temperature "0 to 2", n "between 1 and 128", top_k "between 0 and 100",
+ * top_p "Required range: `0 <= x <= 1`" — CompletionRequest's own wording; ChatCompletionRequest
+ * carries the same nucleus-sampling semantics, frequency/presence_penalty "between -2 and 2")
+ * plus the OpenAI-compat types (role enum, stream boolean). The vendor's server (FastAPI)
+ * answers each violation with the 422 HTTPValidationError envelope and the pydantic error
+ * `type` — the twin answers the same, per parameter and constraint. `loc` matches where the
+ * field rides in the request body.
+ */
+const SAMPLING_RULES = [
+    { field: 'temperature', kind: 'number', min: 0, max: 2 },
+    { field: 'top_p', kind: 'number', min: 0, max: 1 },
+    { field: 'n', kind: 'number', min: 1, max: 128, integer: true },
+    { field: 'top_k', kind: 'number', min: 0, max: 100, integer: true },
+    { field: 'frequency_penalty', kind: 'number', min: -2, max: 2 },
+    { field: 'presence_penalty', kind: 'number', min: -2, max: 2 },
+];
+/** Validate the sampling/typing rules; returns the FastAPI 422 envelope on violation. Shared by
+ *  the chat and legacy-completions doors so the two surfaces cannot drift. The message ROLE enum
+ *  is checked per message by the chat door's own loop (the role rides inside `messages`). */
+function validateSampling(params) {
+    for (const rule of SAMPLING_RULES) {
+        const v = params[rule.field];
+        if (v === undefined || v === null)
+            continue;
+        if (rule.kind === 'number') {
+            // pydantic v2's kinds: a JSON string/bool where a number belongs is int_parsing (for an
+            // integer field) or float_parsing (for a float field) — int_type/float_type are
+            // python-typed-argument errors that never fire on a JSON body; a float where an integer
+            // belongs is int_from_float.
+            if (typeof v !== 'number' || Number.isNaN(v)) {
+                return validationError(['body', rule.field], `Input should be a valid ${rule.integer ? 'integer' : 'number'}`, rule.integer ? 'int_parsing' : 'float_parsing');
+            }
+            if (rule.integer && !Number.isInteger(v))
+                return validationError(['body', rule.field], 'Input should be a valid integer', 'int_from_float');
+            if (rule.min !== undefined && v < rule.min)
+                return validationError(['body', rule.field], `Input should be greater than or equal to ${rule.min}`, 'greater_than_equal');
+            if (rule.max !== undefined && v > rule.max)
+                return validationError(['body', rule.field], `Input should be less than or equal to ${rule.max}`, 'less_than_equal');
+        }
+    }
+    if (params.stream !== undefined && params.stream !== null && typeof params.stream !== 'boolean') {
+        return validationError(['body', 'stream'], 'Input should be a valid boolean', 'bool_type');
+    }
+    return null;
+}
+/** The OpenAI-compat message role enum (the spec's ChatCompletionRequestMessage.role). */
+const MESSAGE_ROLES = ['system', 'user', 'assistant', 'tool', 'function', 'developer'];
+/**
+ * Fireworks' documented OpenAI differences are the fidelity surface here:
+ *   • `max_tokens`/`max_completion_tokens` are MUTUALLY EXCLUSIVE (the spec's own note: "Alias for
+ *     max_tokens. Cannot be specified together with max_tokens.") — OpenAI allows both;
+ *   • `service_tier` is a closed enum whose values are all ACCEPTED but only 'priority' is
+ *     honored — the others are treated as 'default', never an error;
+ *   • `context_length_exceeded_behavior` defaults to 'truncate' (OpenAI's is 'error').
+ * The twin has no real context window, so the truncate path is modeled as the documented
+ * SEMANTIC (max_tokens lowered to fit) whenever a stub context is exceeded.
+ */
+function validateChat(params) {
+    if (params.model === undefined)
+        return { error: validationError(['body', 'model'], 'Field required', 'missing') };
+    if (typeof params.model !== 'string' || !params.model)
+        return { error: validationError(['body', 'model'], 'Input should be a valid string', 'string_type') };
+    if (!Array.isArray(params.messages))
+        return { error: validationError(['body', 'messages'], 'Field required', 'missing') };
+    if (params.messages.length === 0)
+        return { error: invalidRequest("'messages' must not be empty") };
+    const messages = params.messages;
+    for (const [i, m] of messages.entries()) {
+        if (!m || typeof m !== 'object' || typeof m.role !== 'string') {
+            return { error: validationError(['body', 'messages'], 'Input should be a valid dictionary', 'model_attributes_type') };
+        }
+        if (!MESSAGE_ROLES.includes(m.role)) {
+            // FastAPI's loc carries the message INDEX (`body.messages.<i>.role`), not just the field.
+            return { error: validationError(['body', 'messages', i, 'role'], `Input should be one of ${MESSAGE_ROLES.map((r) => `'${r}'`).join(', ')}`, 'enum') };
+        }
+    }
+    // The sampling/typing table (temperature/n/top_k/penalties/stream) — the same rules the legacy
+    // door applies, so the two inference surfaces cannot drift.
+    const sampling = validateSampling(params);
+    if (sampling)
+        return { error: sampling };
+    if (params.max_tokens !== undefined && params.max_tokens !== null && params.max_completion_tokens !== undefined && params.max_completion_tokens !== null) {
+        return { error: invalidRequest("'max_tokens' and 'max_completion_tokens' cannot both be specified — 'max_completion_tokens' is an alias for 'max_tokens'") };
+    }
+    const maxRaw = params.max_completion_tokens ?? params.max_tokens;
+    let maxTokens;
+    if (maxRaw !== undefined && maxRaw !== null) {
+        // pydantic parses the JSON value BEFORE any range check: a string is int_parsing, a float
+        // int_from_float, and only a parsed integer then hits the ≥1 bound.
+        maxTokens = Number(maxRaw);
+        if (typeof maxRaw !== 'number' || Number.isNaN(maxRaw))
+            return { error: validationError(['body', 'max_tokens'], 'Input should be a valid integer', 'int_parsing') };
+        if (!Number.isInteger(maxTokens))
+            return { error: validationError(['body', 'max_tokens'], 'Input should be a valid integer', 'int_from_float') };
+        if (maxTokens < 1)
+            return { error: validationError(['body', 'max_tokens'], 'Input should be a valid integer greater than or equal to 1', 'greater_than_equal') };
+    }
+    let stop;
+    if (params.stop !== undefined && params.stop !== null) {
+        if (typeof params.stop === 'string')
+            stop = [params.stop];
+        else if (Array.isArray(params.stop))
+            stop = params.stop;
+        else
+            return { error: validationError(['body', 'stop'], 'Input should be a valid string or array of strings', 'string_type') };
+    }
+    let serviceTier = 'default';
+    if (params.service_tier !== undefined && params.service_tier !== null) {
+        if (typeof params.service_tier !== 'string' || !SERVICE_TIERS.includes(params.service_tier)) {
+            return { error: validationError(['body', 'service_tier'], `Input should be one of ${SERVICE_TIERS.map((t) => `'${t}'`).join(', ')}`, 'enum') };
+        }
+        // The vendor's own semantics: "Only 'priority' is supported, while all other values will be
+        // treated as 'default' tier." Every enum value is ACCEPTED; 'auto'/'flex' do NOT error.
+        serviceTier = params.service_tier === 'priority' ? 'priority' : 'default';
+    }
+    let contextBehavior = 'truncate';
+    if (params.context_length_exceeded_behavior !== undefined && params.context_length_exceeded_behavior !== null) {
+        if (typeof params.context_length_exceeded_behavior !== 'string' || !CONTEXT_BEHAVIORS.includes(params.context_length_exceeded_behavior)) {
+            return { error: validationError(['body', 'context_length_exceeded_behavior'], "Input should be one of 'error', 'truncate'", 'enum') };
+        }
+        contextBehavior = params.context_length_exceeded_behavior;
+    }
+    let responseFormat;
+    const rf = params.response_format;
+    if (rf && typeof rf === 'object') {
+        if (rf.type === 'json_object')
+            responseFormat = { type: 'json_object' };
+        else if (rf.type === 'json_schema')
+            responseFormat = { type: 'json_schema', schema: rf.json_schema };
+        else if (rf.type !== undefined && rf.type !== 'text')
+            return { error: invalidRequest("'response_format.type' must be one of 'text', 'json_object', 'json_schema'") };
+    }
+    const stream = params.stream === true;
+    // Fireworks streams usage BY DEFAULT (the documented OpenAI difference); `include_usage: false`
+    // is the opt-OUT — the inverse of OpenAI's opt-IN.
+    const streamOptions = params.stream_options;
+    const includeUsage = streamOptions?.include_usage !== false;
+    return {
+        args: {
+            model: params.model,
+            messages,
+            promptText: messages.map((m) => contentToText(m.content)).join('\n'),
+            ...(params.tools !== undefined ? { tools: params.tools } : {}),
+            ...(maxTokens !== undefined ? { maxTokens } : {}),
+            ...(stop !== undefined ? { stop } : {}),
+            stream,
+            includeUsage,
+            serviceTier,
+            contextBehavior,
+            ...(responseFormat !== undefined ? { responseFormat } : {}),
+            ...(params.reasoning_effort !== undefined && params.reasoning_effort !== null ? { reasoningEffort: params.reasoning_effort } : {}),
+        },
+    };
+}
+/** Build ONE deterministic stub chat completion. */
+function buildChatCompletion(args, occurredAt, decision) {
+    const promptTokens = countPromptTokens(args.messages);
+    // Scenario scripting first — the DECISION was made (and any fault honored) by the request
+    // handler through the engine's serve(); only a content decision reaches here. A matching
+    // handler scripts the answer; a miss answers the labeled stub with a pointer naming the miss
+    // and the features seen.
+    let scripted = null;
+    let missTeach = '';
+    if (decision) {
+        if (decision.kind === 'handler') {
+            scripted = realizeFireworksRespond(decision.respond);
+        }
+        else {
+            missTeach = `\n[twin-scenario miss — no handler matched. Author one in the world dir's handlers/fireworks.json (GET /twin explains; GET /twin/scenario lists handlers + misses). Features seen: ${JSON.stringify(decision.miss.features)}]`;
+        }
+    }
+    if (scripted) {
+        const message = { role: 'assistant', content: scripted.text ?? '', ...(scripted.toolCalls.length ? { tool_calls: scripted.toolCalls } : {}) };
+        if (scripted.reasoning !== null)
+            message.reasoning_content = scripted.reasoning;
+        const completionTokens = estimateTokens(JSON.stringify(scripted.toolCalls.length ? scripted.toolCalls : scripted.text ?? ''));
+        return {
+            id: `chatcmpl-twin-${stableSuffix(JSON.stringify(args.messages) + args.model)}`,
+            object: 'chat.completion',
+            created: nowEpoch(occurredAt),
+            model: args.model,
+            choices: [{ index: 0, message, finish_reason: scripted.finishReason, logprobs: null }],
+            usage: { prompt_tokens: promptTokens, total_tokens: promptTokens + completionTokens, completion_tokens: completionTokens },
+        };
+    }
+    let text = args.responseFormat?.type === 'json_object' || args.responseFormat?.type === 'json_schema'
+        ? `${stubAssistantText(args.model, args.promptText)}\n{"twin_stub":true}`
+        : stubAssistantText(args.model, args.promptText);
+    if (missTeach)
+        text += missTeach;
+    let finish = 'stop';
+    // Truncate at the EARLIEST-occurring stop sequence across the whole `stop` list.
+    let stopAt = -1;
+    for (const s of args.stop ?? []) {
+        if (!s)
+            continue;
+        const i = text.indexOf(s);
+        if (i >= 0 && (stopAt < 0 || i < stopAt))
+            stopAt = i;
+    }
+    if (stopAt >= 0) {
+        text = text.slice(0, stopAt);
+        finish = 'stop';
+    }
+    // THE VENDOR DIFFERENCE: exceeding the (stub) context truncates max_tokens by default instead
+    // of erroring. The stub context is generous and fixed; the behavior is the fidelity surface.
+    const stubContextTokens = 8192;
+    if (promptTokens + (args.maxTokens ?? 0) > stubContextTokens) {
+        if (args.contextBehavior === 'error') {
+            return invalidRequest(`This model's maximum context length is ${stubContextTokens} tokens. However, you requested ${(args.maxTokens ?? 0) + promptTokens} tokens in the messages, which exceeds the model's context limit.`);
+        }
+        // truncate: max_tokens is lowered to fit.
+        if (args.maxTokens !== undefined)
+            args.maxTokens = Math.max(1, stubContextTokens - promptTokens);
+    }
+    if (args.maxTokens !== undefined && estimateTokens(text) > args.maxTokens) {
+        text = text.slice(0, args.maxTokens * 4);
+        finish = 'length';
+    }
+    const message = { role: 'assistant', content: text };
+    // reasoning_effort (any truthy non-'none'/'false' value) surfaces Fireworks' separate
+    // `reasoning_content` field — the field the vendor's reasoning models answer with.
+    const effortOn = args.reasoningEffort !== undefined && args.reasoningEffort !== 'none' && args.reasoningEffort !== false;
+    if (effortOn)
+        message.reasoning_content = stubReasoningText(args.model, args.promptText);
+    const completionTokens = estimateTokens(text) + estimateTokens(message.reasoning_content ?? '');
+    const usage = { prompt_tokens: promptTokens, total_tokens: promptTokens + completionTokens, completion_tokens: completionTokens };
+    const id = `chatcmpl-twin-${stableSuffix(JSON.stringify(args.messages) + args.model)}`;
+    return {
+        id,
+        object: 'chat.completion',
+        created: nowEpoch(occurredAt),
+        model: args.model,
+        choices: [{ index: 0, message, finish_reason: finish, logprobs: null }],
+        // usage is carried unconditionally (the vendor's streaming behavior implies it is always
+        // computed; the schema marks it nullable only for the echo/logprobs edge paths).
+        usage,
+    };
+}
+/** Split text into deterministic streaming chunks (≤ ~20 chars each), preserving order. */
+function chunkText(text) {
+    if (!text)
+        return [];
+    const out = [];
+    for (let i = 0; i < text.length; i += 20)
+        out.push(text.slice(i, i + 20));
+    return out;
+}
+/**
+ * Emit the vendor-faithful Fireworks streaming sequence into the injected sink (NO sockets, NO
+ * setTimeout). THE VENDOR DIFFERENCE (docs.fireworks.ai/tools-sdks/openai-compatibility): "For
+ * streaming responses, the `usage` field is returned in the very last chunk on the response (i.e.
+ * the one having `finish_reason` set)" — BY DEFAULT, no `stream_options.include_usage` needed
+ * (OpenAI makes it opt-in; Fireworks makes it opt-OUT via `include_usage: false`).
+ */
+function streamChat(args, sink, occurredAt, decision) {
+    const built = buildChatCompletion(args, occurredAt, decision);
+    if ('status' in built)
+        return built;
+    const full = built;
+    const base = { id: full.id, object: 'chat.completion.chunk', created: full.created, model: full.model };
+    sink({ data: { ...base, choices: [{ index: 0, delta: { role: 'assistant', content: '' }, finish_reason: null }], usage: null } });
+    if (full.choices[0].message.reasoning_content) {
+        sink({ data: { ...base, choices: [{ index: 0, delta: { reasoning_content: full.choices[0].message.reasoning_content }, finish_reason: null }], usage: null } });
+    }
+    for (const piece of chunkText(full.choices[0].message.content ?? '')) {
+        sink({ data: { ...base, choices: [{ index: 0, delta: { content: piece }, finish_reason: null }], usage: null } });
+    }
+    // The final chunk carries finish_reason AND — by default — the usage.
+    sink({
+        data: {
+            ...base,
+            choices: [{ index: 0, delta: {}, finish_reason: full.choices[0].finish_reason }],
+            ...(args.includeUsage ? { usage: full.usage } : { usage: null }),
+        },
+    });
+    sink({ done: true });
+    return full;
+}
+// ── legacy completions (/v1/completions) ────────────────────────────────────────────────
+/** Stream a legacy completion the OpenAI-compatible way: chunks carry the delta in
+ *  `choices[].text` (`object: 'text_completion'` throughout — the legacy stream has no separate
+ *  chunk object), ending with the finish chunk that — the Fireworks default — carries `usage`. */
+function streamCompletion(full, sink, includeUsage) {
+    const base = { id: full.id, object: 'text_completion', created: full.created, model: full.model };
+    for (const choice of full.choices) {
+        sink({ data: { ...base, choices: [{ index: choice.index, text: choice.text, finish_reason: null, logprobs: choice.logprobs }], usage: null } });
+    }
+    sink({
+        data: {
+            ...base,
+            choices: full.choices.map((c) => ({ index: c.index, text: '', finish_reason: c.finish_reason, logprobs: c.logprobs })),
+            ...(includeUsage ? { usage: full.usage } : { usage: null }),
+        },
+    });
+    sink({ done: true });
+    return full;
+}
+function handleCompletion(params, occurredAt, sink, root) {
+    if (params.model === undefined)
+        return { status: 422, body: { detail: [{ loc: ['body', 'model'], msg: 'Field required', type: 'missing' }] } };
+    if (params.prompt === undefined)
+        return { status: 422, body: { detail: [{ loc: ['body', 'prompt'], msg: 'Field required', type: 'missing' }] } };
+    if (typeof params.model !== 'string' || !params.model)
+        return { status: 422, body: { detail: [{ loc: ['body', 'model'], msg: 'Input should be a valid string', type: 'string_type' }] } };
+    if (!servedModelIds(root).has(params.model))
+        return unknownModel(params.model);
+    // The same sampling/typing table the chat door applies.
+    const sampling = validateSampling(params);
+    if (sampling)
+        return sampling;
+    const prompts = Array.isArray(params.prompt) ? params.prompt.map(String) : [String(params.prompt)];
+    const maxRaw = params.max_completion_tokens ?? params.max_tokens;
+    if (params.max_tokens !== undefined && params.max_tokens !== null && params.max_completion_tokens !== undefined && params.max_completion_tokens !== null) {
+        return invalidRequest("'max_tokens' and 'max_completion_tokens' cannot both be specified — 'max_completion_tokens' is an alias for 'max_tokens'");
+    }
+    let maxTokens;
+    if (maxRaw !== undefined && maxRaw !== null) {
+        // The same pydantic parse order the chat door applies (string → int_parsing, float →
+        // int_from_float, then the ≥1 bound).
+        maxTokens = Number(maxRaw);
+        if (typeof maxRaw !== 'number' || Number.isNaN(maxRaw))
+            return { status: 422, body: { detail: [{ loc: ['body', 'max_tokens'], msg: 'Input should be a valid integer', type: 'int_parsing' }] } };
+        if (!Number.isInteger(maxTokens))
+            return { status: 422, body: { detail: [{ loc: ['body', 'max_tokens'], msg: 'Input should be a valid integer', type: 'int_from_float' }] } };
+        if (maxTokens < 1)
+            return { status: 422, body: { detail: [{ loc: ['body', 'max_tokens'], msg: 'Input should be a valid integer greater than or equal to 1', type: 'greater_than_equal' }] } };
+    }
+    const model = String(params.model);
+    const promptTokens = prompts.reduce((sum, p) => sum + estimateTokens(p), 0);
+    const choices = prompts.map((p, i) => {
+        let text = stubAssistantText(model, p);
+        let finish = 'stop';
+        if (maxTokens !== undefined && estimateTokens(text) > maxTokens) {
+            text = text.slice(0, maxTokens * 4);
+            finish = 'length';
+        }
+        return { index: i, text, finish_reason: finish, logprobs: null };
+    });
+    const completionTokens = choices.reduce((sum, c) => sum + estimateTokens(c.text), 0);
+    const body = {
+        id: `cmpl-twin-${stableSuffix(JSON.stringify(prompts) + model)}`,
+        object: 'text_completion',
+        created: nowEpoch(occurredAt),
+        model,
+        choices,
+        // The spec marks `usage` REQUIRED on Completion (nullable only on chat).
+        usage: { prompt_tokens: promptTokens, total_tokens: promptTokens + completionTokens, completion_tokens: completionTokens },
+    };
+    // The server hands a sink only for `stream:true`; ignoring it would answer a 200 event stream
+    // with zero frames — a fake success on the wire.
+    const streamOptions = params.stream_options;
+    if (sink)
+        return { status: 200, body: streamCompletion(body, sink, streamOptions?.include_usage !== false) };
+    return { status: 200, body };
+}
+// ── Responses API (/v1/responses — stateful CRUD over the kernel log) ───────────────────
+/**
+ * Fireworks' Responses API stores responses server-side (`store` defaults true; `store:false`
+ * answers with a NULL id per the vendor's own schema: "Will be None if store=False"). The twin
+ * mirrors that: stored responses live in the kernel action log and are retrievable/deletable;
+ * a store=false response is answered id-less and NOT stored.
+ */
+function responseView(r) {
+    return { id: r.id, ...strip(r) };
+}
+async function createResponse(params, req) {
+    if (params.model === undefined)
+        return { status: 422, body: { detail: [{ loc: ['body', 'model'], msg: 'Field required', type: 'missing' }] } };
+    if (params.input === undefined)
+        return { status: 422, body: { detail: [{ loc: ['body', 'input'], msg: 'Field required', type: 'missing' }] } };
+    if (typeof params.model !== 'string' || !params.model)
+        return { status: 422, body: { detail: [{ loc: ['body', 'model'], msg: 'Input should be a valid string', type: 'string_type' }] } };
+    const store = params.store !== false;
+    const inputText = typeof params.input === 'string' ? params.input : JSON.stringify(params.input);
+    const promptTokens = estimateTokens(inputText);
+    const text = stubAssistantText(String(params.model), inputText);
+    const completionTokens = estimateTokens(text);
+    const outputItem = {
+        type: 'message',
+        id: `msg_twin_${stableSuffix(text)}`,
+        role: 'assistant',
+        status: 'completed',
+        content: [{ type: 'output_text', text }],
+    };
+    const base = {
+        object: 'response',
+        created_at: nowEpoch(req.occurredAt),
+        status: 'completed',
+        model: params.model,
+        output: [outputItem],
+        usage: { prompt_tokens: promptTokens, total_tokens: promptTokens + completionTokens, completion_tokens: completionTokens },
+        ...(params.instructions !== undefined ? { instructions: params.instructions } : {}),
+        ...(params.metadata !== undefined ? { metadata: params.metadata } : {}),
+        ...(params.previous_response_id !== undefined ? { previous_response_id: params.previous_response_id } : {}),
+        ...(params.temperature !== undefined ? { temperature: params.temperature } : {}),
+        ...(params.max_output_tokens !== undefined ? { max_output_tokens: params.max_output_tokens } : {}),
+        store,
+    };
+    if (!store) {
+        // The vendor's own contract: id is null when store=false, and nothing is retrievable later.
+        return { status: 200, body: { ...base, id: null } };
+    }
+    const id = `resp_twin_${stableSuffix(inputText + String(params.model))}`;
+    await applyTwinWrite(SERVICE, {
+        operation: 'response.create',
+        subjectType: 'response',
+        subjectId: id,
+        fields: base,
+        ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+        actor: { kind: 'agent' },
+    }, req.root);
+    return { status: 200, body: responseView(getRow('response', id, undefined, req.root) ?? { ...base, id }) };
+}
+function handleListResponses(req) {
+    const url = new URL(req.path, 'http://twin');
+    const limit = Number(url.searchParams.get('limit') ?? 20);
+    const data = rows('response', undefined, req.root).filter((r) => !isTombstoned(r)).map(responseView);
+    const page = data.slice(0, Number.isFinite(limit) && limit > 0 ? limit : 20);
+    return { status: 200, body: { object: 'list', data: page, has_more: data.length > page.length, first_id: page[0]?.id ?? null, last_id: page[page.length - 1]?.id ?? null } };
+}
+function handleGetResponse(id, req) {
+    const r = getRow('response', id, undefined, req.root);
+    if (!r || isTombstoned(r))
+        return notFound(`No response found with id '${id}'.`);
+    return { status: 200, body: responseView(r) };
+}
+async function handleDeleteResponse(id, req) {
+    const r = getRow('response', id, undefined, req.root);
+    if (!r || isTombstoned(r))
+        return notFound(`No response found with id '${id}'.`);
+    await applyTwinWrite(SERVICE, {
+        operation: 'response.delete', subjectType: 'response', subjectId: id, fields: { _deleted: true },
+        ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+    }, req.root);
+    return { status: 200, body: { id, object: 'response', deleted: true } };
+}
+// ── Anthropic-compatible /v1/messages ───────────────────────────────────────────────────
+/** The Anthropic error envelope — a DIFFERENT shape from the OpenAI-compat plane's. */
+function anthropicError(status, type, message) {
+    return { status, body: { type: 'error', error: { type, message }, request_id: null } };
+}
+function validateAnthropicMessages(params) {
+    if (params.model === undefined)
+        return { error: anthropicError(400, 'invalid_request_error', 'model: Field required') };
+    if (!Array.isArray(params.messages) || params.messages.length === 0) {
+        return { error: anthropicError(400, 'invalid_request_error', 'messages: Field required') };
+    }
+    for (const m of params.messages) {
+        if (!m || typeof m !== 'object' || (m.role !== 'user' && m.role !== 'assistant')) {
+            return { error: anthropicError(400, 'invalid_request_error', "messages: each message must have role 'user' or 'assistant'") };
+        }
+    }
+    return { ok: true };
+}
+function buildAnthropicMessage(params, occurredAt) {
+    const bad = validateAnthropicMessages(params);
+    if ('error' in bad)
+        return bad.error;
+    const messages = params.messages;
+    const promptText = messages.map((m) => contentToText(m.content)).join('\n');
+    const systemText = typeof params.system === 'string' ? params.system : Array.isArray(params.system) ? params.system.map((b) => contentToText(b.text)).join('\n') : '';
+    const inputTokens = estimateTokens(promptText + systemText);
+    // max_tokens is OPTIONAL on Fireworks (required on Anthropic — the documented difference).
+    const maxTokens = typeof params.max_tokens === 'number' ? params.max_tokens : undefined;
+    let text = stubAssistantText(String(params.model), promptText.trim() || systemText);
+    let stopReason = 'end_turn';
+    if (maxTokens !== undefined && estimateTokens(text) > maxTokens) {
+        text = text.slice(0, maxTokens * 4);
+        stopReason = 'max_tokens';
+    }
+    const content = [{ type: 'text', text, citations: null }];
+    const outputTokens = estimateTokens(text);
+    const body = {
+        id: `msg_twin_${stableSuffix(promptText + String(params.model))}`,
+        type: 'message',
+        role: 'assistant',
+        content,
+        model: String(params.model),
+        stop_reason: stopReason,
+        stop_sequence: null,
+        // Usage is included in BOTH streaming and non-streaming responses (the documented difference
+        // from Anthropic, where streaming omits it until the final delta).
+        usage: { input_tokens: inputTokens, output_tokens: outputTokens },
+    };
+    return { status: 200, body };
+}
+/** The Anthropic SSE sequence: message_start → content_block_start → content_block_delta* →
+ *  content_block_stop → message_delta (carrying the ACTUAL usage — the one message_delta per
+ *  stream) → message_stop. */
+function streamAnthropicMessage(params, sink, occurredAt) {
+    const built = buildAnthropicMessage(params, occurredAt);
+    if (built.status !== 200)
+        return built;
+    const full = built.body;
+    const content = full.content;
+    const usage = full.usage ?? { input_tokens: 0, output_tokens: 0 };
+    sink({ data: { type: 'message_start', message: { ...full, content: [], stop_reason: null, usage: { input_tokens: usage.input_tokens, output_tokens: 0 } } } });
+    sink({ data: { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } } });
+    for (const piece of chunkText(content[0].type === 'text' ? content[0].text : '')) {
+        sink({ data: { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: piece } } });
+    }
+    sink({ data: { type: 'content_block_stop', index: 0 } });
+    // ONE message_delta, carrying the ACTUAL token counts (the vendor's own note: the message_start
+    // usage is always 0 and should be ignored for metering).
+    sink({ data: { type: 'message_delta', delta: { stop_reason: full.stop_reason, stop_sequence: null }, usage: { input_tokens: usage.input_tokens, output_tokens: usage.output_tokens } } });
+    sink({ data: { type: 'message_stop' } });
+    sink({ done: true });
+    return built;
+}
+// ── embeddings + rerank (deterministic pseudo-vectors / scores) ─────────────────────────
+/** The largest vector the twin will ever allocate from a client number. The vendor's resizable
+ *  embedding models truncate DOWN to the requested `dimensions` (never produce longer vectors
+ *  than the model's native output); the catalog's largest native dimensionality across the
+ *  served embedders is the Qwen3 embedding family's 4096. Every array sized from a REQUEST
+ *  value in this pack is bounded by this constant or by an input length — audited. */
+const MAX_EMBEDDING_DIMENSIONS = 4096;
+function handleEmbeddings(params, root) {
+    if (params.model === undefined)
+        return { status: 422, body: { detail: [{ loc: ['body', 'model'], msg: 'Field required', type: 'missing' }] } };
+    if (params.input === undefined)
+        return { status: 422, body: { detail: [{ loc: ['body', 'input'], msg: 'Field required', type: 'missing' }] } };
+    if (typeof params.model !== 'string' || !servedModelIds(root).has(params.model))
+        return unknownModel(String(params.model));
+    const inputs = Array.isArray(params.input) ? params.input.map((v) => (typeof v === 'string' ? v : JSON.stringify(v))) : [String(params.input)];
+    if (inputs.some((s) => s.length === 0))
+        return invalidRequest("'input' must not be an empty string");
+    // `dimensions` is validated BEFORE any allocation: the spec types it `anyOf [integer, null]`
+    // (EmbeddingRequest), so pydantic answers a non-integer with int_parsing; the range below is
+    // the vendor's own constraint — dimensions must be ≥ 1 (the API reference schema marks
+    // minimum 1) and ≤ the model's native dimensionality (the vendor's resizable models return
+    // SHORTER vectors — matryoshka truncation — never longer; the catalog's largest is the Qwen3
+    // embedding table's 4096). An unvalidated client number flowed straight into the vector
+    // allocation: 1e9 tried to allocate a 12 GB array (one-request DoS), -1/2.5 escaped as a 500,
+    // 0 answered a fake 200 with an empty vector, 'x' was silently ignored.
+    const dimsRaw = params.dimensions;
+    if (dimsRaw !== undefined && dimsRaw !== null) {
+        if (typeof dimsRaw !== 'number' || Number.isNaN(dimsRaw))
+            return validationError(['body', 'dimensions'], 'Input should be a valid integer', 'int_parsing');
+        if (!Number.isInteger(dimsRaw))
+            return validationError(['body', 'dimensions'], 'Input should be a valid integer', 'int_from_float');
+        if (dimsRaw < 1)
+            return validationError(['body', 'dimensions'], 'Input should be greater than or equal to 1', 'greater_than_equal');
+        if (dimsRaw > MAX_EMBEDDING_DIMENSIONS)
+            return validationError(['body', 'dimensions'], `Input should be less than or equal to ${MAX_EMBEDDING_DIMENSIONS}`, 'less_than_equal');
+    }
+    const dims = typeof dimsRaw === 'number' ? dimsRaw : 768;
+    const encoding = params.encoding_format === undefined ? 'float' : params.encoding_format;
+    if (encoding !== 'float' && encoding !== 'base64')
+        return invalidRequest("'encoding_format' must be one of 'float', 'base64'");
+    let promptTokens = 0;
+    const data = inputs.map((text, index) => {
+        promptTokens += estimateTokens(text);
+        const vec = pseudoEmbedding(text, dims);
+        return {
+            object: 'embedding',
+            index,
+            embedding: encoding === 'base64' ? Buffer.from(new Float32Array(vec).buffer).toString('base64') : vec,
+        };
+    });
+    return {
+        status: 200,
+        body: {
+            object: 'list',
+            data,
+            model: params.model,
+            usage: { prompt_tokens: promptTokens, total_tokens: promptTokens },
+        },
+    };
+}
+function handleRerank(params, root) {
+    if (params.query === undefined)
+        return { status: 422, body: { detail: [{ loc: ['body', 'query'], msg: 'Field required', type: 'missing' }] } };
+    if (!Array.isArray(params.documents) || params.documents.length === 0)
+        return { status: 422, body: { detail: [{ loc: ['body', 'documents'], msg: 'Field required', type: 'missing' }] } };
+    // The vendor's rerank takes a model too (the Qwen3 Reranker family); an unknown id is refused
+    // the same way chat/embeddings refuse theirs. A MISSING model is accepted (the twin's own
+    // query/document scorer needs no id; the vendor's request schema marks model optional there).
+    if (params.model !== undefined && (typeof params.model !== 'string' || !servedModelIds(root).has(params.model)))
+        return unknownModel(String(params.model));
+    const query = String(params.query);
+    const documents = params.documents.map(String);
+    const returnDocuments = params.return_documents !== false;
+    const scored = documents.map((doc, index) => ({ index, score: stubRelevanceScore(query, doc), doc }));
+    // Ordered by relevance score (highest first) — the vendor's own contract for the data array.
+    scored.sort((a, b) => b.score - a.score);
+    // `top_n` is the spec's integer (RerankRequestBody); a non-integer is refused before it can
+    // slice, and a value below 1 would answer an EMPTY result list for a valid request — the
+    // vendor's own contract keeps at least one result.
+    const topRaw = params.top_n;
+    if (topRaw !== undefined && topRaw !== null) {
+        if (typeof topRaw !== 'number' || Number.isNaN(topRaw))
+            return validationError(['body', 'top_n'], 'Input should be a valid integer', 'int_parsing');
+        if (!Number.isInteger(topRaw))
+            return validationError(['body', 'top_n'], 'Input should be a valid integer', 'int_from_float');
+        if (topRaw < 1)
+            return validationError(['body', 'top_n'], 'Input should be greater than or equal to 1', 'greater_than_equal');
+    }
+    const topN = typeof topRaw === 'number' ? topRaw : documents.length;
+    const data = scored.slice(0, Math.max(0, topN)).map((s) => ({
+        index: s.index,
+        relevance_score: s.score,
+        ...(returnDocuments ? { document: s.doc } : {}),
+    }));
+    const promptTokens = estimateTokens(query) + documents.reduce((sum, d) => sum + estimateTokens(d), 0);
+    return {
+        status: 200,
+        body: {
+            object: 'list',
+            model: params.model ?? null,
+            data,
+            usage: { prompt_tokens: promptTokens, total_tokens: promptTokens },
+        },
+    };
+}
+// ── CONTROL PLANE (Gateway REST API) ───────────────────────────────────────────────────
+// google.rpc-style resources: `name` fields follow accounts/<account>/…, `state`/`status` are
+// vendor enums, list envelopes carry nextPageToken/totalSize, and CREATE ids arrive as QUERY
+// params (deployments/datasets/users) or in the body (datasets carry datasetId in the body too).
+function resourceView(r) {
+    // The vendor's control-plane schemas (gatewayDeployment, gatewayDataset, …) carry NO `id`
+    // field — identity is the hierarchical `name`. The bare id stays a twin-internal alias and
+    // must never appear on the wire (defect: strip() was letting it through on every body).
+    const { id: _drop, ...rest } = r;
+    return strip(rest);
+}
+function paginate(items, url) {
+    const pageSize = Number(url.searchParams.get('pageSize') ?? 0);
+    const pageToken = url.searchParams.get('pageToken');
+    let start = 0;
+    if (pageToken) {
+        const n = Number(pageToken);
+        start = Number.isFinite(n) && n > 0 ? n : 0;
+    }
+    const size = Number.isFinite(pageSize) && pageSize > 0 ? pageSize : items.length;
+    const page = items.slice(start, start + size);
+    const next = start + size < items.length ? String(start + size) : null;
+    return { items: page, nextPageToken: next };
+}
+/** The gateway status embedded on resources: OK once READY, else the resource's own state. */
+function okStatus() {
+    return { code: 'OK', message: '' };
+}
+async function createControlResource(type, prefix, accountId, params, req, url, buildFields) {
+    // The vendor passes create ids where its spec puts them: QUERY params for deployments
+    // (deploymentId), users (userId), batchInferenceJobId and supervisedFineTuningJobId; BODY
+    // fields for datasets ({dataset, datasetId}) and models ({model, modelId}); the resource's own
+    // `name` for secrets. Absent → the vendor mints one; so does the twin.
+    const queryId = url.searchParams.get(`${type}Id`) ?? url.searchParams.get(`${type}_id`);
+    const wrapped = (params[type] && typeof params[type] === 'object' ? params[type] : params);
+    const bodyId = typeof wrapped[`${type}Id`] === 'string' ? wrapped[`${type}Id`]
+        : typeof params[`${type}Id`] === 'string' ? params[`${type}Id`]
+            // A secret's id is the last segment of the `name` the client supplies in its own body.
+            : type === 'secret' && typeof params.name === 'string' ? params.name.split('/').pop()
+                : undefined;
+    const id = queryId || bodyId || nextId(type, prefix, accountId, req.root);
+    // The vendor's own spec marks the id REQUIRED on datasets (CreateDatasetRequest.required:
+    // dataset + datasetId) and models (GatewayGatewayCreateModelBody.required: modelId) — a create
+    // without one is a 400 at the vendor, never a mint. The dataset body itself is required too
+    // (the same required list); a bare {datasetId} is not a create. The other collections' id
+    // params are optional (the vendor mints), so the twin keeps minting there.
+    if (type === 'dataset' || type === 'model') {
+        if (!queryId && !bodyId)
+            return gatewayError(400, `${type}Id is required`);
+        if (type === 'dataset' && !(params.dataset && typeof params.dataset === 'object')) {
+            return gatewayError(400, 'dataset is required');
+        }
+    }
+    // TENANCY: the kernel subject is the ACCOUNT-NAMESPACED id (`{account}/{id}` — the vendor's own
+    // name grammar), so the kernel's (type, subject) key is unique per tenant. Writing the bare id
+    // let a create under account B with an id account A held DESTROY A's row (the overlay folds by
+    // the bare id globally); the duplicate check below is therefore per-account by construction.
+    const subject = `${accountId}/${id}`;
+    if (getRow(type, id, accountId, req.root) && !isTombstoned(getRow(type, id, accountId, req.root))) {
+        return gatewayError(409, `Resource already exists: ${id}`);
+    }
+    const fields = buildFields(params);
+    // The account the create rode under is part of the resource's identity: every later read is
+    // scoped to it, so a row created under acct-A is invisible under acct-B's paths (the vendor's
+    // own tenancy). The `_` prefix keeps it off the wire (strip() drops it).
+    fields._account = accountId;
+    // The id is resolved HERE (query param, body field, or the twin's mint) — so the row's `name`
+    // is built from it. A caller-supplied buildFields cannot know the minted id; its PLACEHOLDER
+    // stand-in must never survive to the wire (the vendor names every row with the real id).
+    if (typeof fields.name === 'string')
+        fields.name = fields.name.replace('PLACEHOLDER', id);
+    await applyTwinWrite(SERVICE, {
+        operation: `${type}.create`,
+        subjectType: type,
+        subjectId: subject,
+        fields,
+        ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+        actor: { kind: 'agent' },
+    }, req.root);
+    return { status: 200, body: resourceView(getRow(type, id, accountId, req.root) ?? { id: subject, ...fields }) };
+}
+async function deleteControlResource(type, id, accountId, req) {
+    const r = getRow(type, id, accountId, req.root);
+    if (!r || isTombstoned(r))
+        return gatewayError(404, `Not found: ${type}/${id}`);
+    await applyTwinWrite(SERVICE, {
+        operation: `${type}.delete`, subjectType: type, subjectId: `${accountId}/${id}`, fields: { _deleted: true },
+        ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+    }, req.root);
+    // The vendor's delete operations answer `{}` (an empty object per its own spec).
+    return { status: 200, body: {} };
+}
+const DEPLOYMENT_STATES = ['STATE_UNSPECIFIED', 'CREATING', 'READY', 'DELETING', 'FAILED', 'UPDATING', 'DELETED'];
+const JOB_STATES = ['JOB_STATE_UNSPECIFIED', 'JOB_STATE_CREATING', 'JOB_STATE_RUNNING', 'JOB_STATE_COMPLETED', 'JOB_STATE_FAILED', 'JOB_STATE_CANCELLED', 'JOB_STATE_DELETING', 'JOB_STATE_WRITING_RESULTS', 'JOB_STATE_VALIDATING', 'JOB_STATE_DELETING_CLEANING_UP', 'JOB_STATE_PENDING', 'JOB_STATE_EXPIRED', 'JOB_STATE_RE_QUEUEING', 'JOB_STATE_CREATING_INPUT_DATASET', 'JOB_STATE_IDLE', 'JOB_STATE_CANCELLING', 'JOB_STATE_EARLY_STOPPED', 'JOB_STATE_PAUSED', 'JOB_STATE_DELETED', 'JOB_STATE_ARCHIVED'];
+const USER_STATES = ['STATE_UNSPECIFIED', 'CREATING', 'READY', 'UPDATING', 'DELETING'];
+const USER_ROLES = ['admin', 'user', 'contributor', 'inference-user', 'custom'];
+// ── public entry: cross-cutting protocol (auth) then route ──────────────────────────────
+export async function handleFireworksTwinRequest(req) {
+    const method = req.method.toUpperCase();
+    if (req.headers !== undefined || req.apiKey !== undefined) {
+        const authErr = checkAuth(req);
+        if (authErr)
+            return authErr;
+    }
+    return routeFireworks(req, method);
+}
+// ── router ──────────────────────────────────────────────────────────────────────────────
+async function routeFireworks(req, method) {
+    const path = (req.path.split('?')[0] ?? '/').replace(/\/+$/, '') || '/';
+    const query = req.path.includes('?') ? req.path.slice(req.path.indexOf('?')) : '';
+    const params = parseJson(req.body);
+    const dec = (s) => decodeURIComponent(s);
+    // D3: a read-only twin rejects any mutation with a vendor-shaped error — each plane's OWN
+    // envelope (the control plane's google.rpc shape, the inference plane's OpenAI shape).
+    if (req.readOnly && method !== 'GET') {
+        const message = 'twin is read-only; omit readOnly to accept writes';
+        if (path.startsWith(`${FIREWORKS_ACCOUNTS_PREFIX}/`))
+            return gatewayError(405, message);
+        return { status: 405, body: errBody(message, { code: 405 }) };
+    }
+    const url = new URL(req.path, 'http://twin');
+    // ── INFERENCE PLANE (/inference/v1/…) ──────────────────────────────────────────────────
+    if (path === FIREWORKS_INFERENCE_PREFIX || path.startsWith(`${FIREWORKS_INFERENCE_PREFIX}/`)) {
+        const seg = path.slice(FIREWORKS_INFERENCE_PREFIX.length).replace(/^\/+/, '').split('/').filter(Boolean);
+        // The Anthropic-compat surface has its OWN envelope family (AnthropicErrorResponse), so it
+        // routes separately from the OpenAI-compat operations.
+        if (seg[0] === 'messages' && seg.length === 1 && method === 'POST') {
+            if (params.stream === true) {
+                if (!req.sseSink)
+                    return anthropicError(400, 'invalid_request_error', 'streaming requires an SSE-capable connection');
+                return streamAnthropicMessage(params, req.sseSink, req.occurredAt);
+            }
+            return buildAnthropicMessage(params, req.occurredAt);
+        }
+        if (seg[0] === 'chat' && seg[1] === 'completions' && seg.length === 2 && method === 'POST') {
+            const validated = validateChat(params);
+            if ('error' in validated)
+                return validated.error;
+            const args = validated.args;
+            // The vendor refuses an unknown model id BEFORE any generation (404 "Model id not found");
+            // an account-owned model (created/pulled through the control plane) is addressable too.
+            if (!servedModelIds(req.root).has(args.model))
+                return unknownModel(args.model);
+            // R15 — the scenario engine decides AND honors a fault here, before any completion exists:
+            // a `status` fault is this vendor's own refusal envelope (rate limit, server error), a
+            // `slow` has already held the answer, a `drop` never returns. The realizers below only see
+            // a content decision.
+            let decision;
+            if (req.scenarioEngine) {
+                const served = await req.scenarioEngine.serve({ model: args.model, messages: args.messages, tools: args.tools, serviceTier: args.serviceTier });
+                if (served.kind === 'fault')
+                    return { status: served.result.status, body: served.result.body, headers: served.result.headers };
+                decision = served;
+            }
+            const result = args.stream && req.sseSink ? streamChat(args, req.sseSink, req.occurredAt, decision) : buildChatCompletion(args, req.occurredAt, decision);
+            if ('status' in result)
+                return result;
+            return { status: 200, body: result };
+        }
+        if (seg[0] === 'completions' && seg.length === 1 && method === 'POST')
+            return handleCompletion(params, req.occurredAt, req.sseSink, req.root);
+        if (seg[0] === 'responses' && seg.length === 1 && method === 'POST')
+            return createResponse(params, req);
+        if (seg[0] === 'responses' && seg.length === 1 && method === 'GET')
+            return handleListResponses(req);
+        if (seg[0] === 'responses' && seg.length === 2 && method === 'GET')
+            return handleGetResponse(dec(seg[1]), req);
+        if (seg[0] === 'responses' && seg.length === 2 && method === 'DELETE')
+            return handleDeleteResponse(dec(seg[1]), req);
+        if (seg[0] === 'embeddings' && seg.length === 1 && method === 'POST')
+            return handleEmbeddings(params, req.root);
+        if (seg[0] === 'rerank' && seg.length === 1 && method === 'POST')
+            return handleRerank(params, req.root);
+        return notFound(`Unknown request URL: ${method} ${path}.`);
+    }
+    // ── CONTROL PLANE (/v1/accounts/{account_id}/…) ────────────────────────────────────────
+    if (path.startsWith(`${FIREWORKS_ACCOUNTS_PREFIX}/`)) {
+        const seg = path.slice(FIREWORKS_ACCOUNTS_PREFIX.length).split('/').filter(Boolean).map(dec);
+        const accountId = seg[0];
+        if (!accountId)
+            return gatewayError(404, `Unknown request URL: ${method} ${path}.`);
+        const rest = seg.slice(1);
+        // The account itself: GET /v1/accounts/{account_id}. The twin holds NO account rows — an
+        // account exists only as the path prefix its resources live under, and the vendor's account
+        // row is one-per-credential vendor state the API cannot create. Fabricating a 200 row for
+        // ANY id (the old behavior) was a fake success; the vendor answers 404 for an account id it
+        // does not know, and that is what the twin answers too. The honest gap is filed as
+        // fireworks.control.get_account / fireworks.account.read (todos).
+        if (rest.length === 0 && method === 'GET') {
+            return gatewayError(404, `Not found: accounts/${accountId}`);
+        }
+        const resource = rest[0];
+        // Verb-suffixed custom methods: `:cancel`, `:resume`, `:promote`, … (the vendor's AIP-158
+        // style). The colon rides EITHER the collection segment (`jobs:cancel` — collection-level
+        // verbs) or the id segment (`conf-job:cancel` — resource-level verbs); the id is the segment
+        // before the verb.
+        const colonAt = resource?.indexOf(':') ?? -1;
+        let verb = colonAt >= 0 ? resource.slice(colonAt + 1) : undefined;
+        const baseResource = colonAt >= 0 ? resource.slice(0, colonAt) : resource;
+        let idSeg = rest[1];
+        if (verb === undefined && rest.length >= 2 && rest[1].includes(':')) {
+            const at = rest[1].indexOf(':');
+            verb = rest[1].slice(at + 1);
+            idSeg = rest[1].slice(0, at);
+        }
+        const TYPE_MAP = {
+            deployments: { plural: 'deployments', states: DEPLOYMENT_STATES, stateKey: 'state' },
+            datasets: { plural: 'datasets', states: ['STATE_UNSPECIFIED', 'UPLOADING', 'READY'], stateKey: 'state' },
+            batchInferenceJobs: { plural: 'batchInferenceJobs', states: JOB_STATES, stateKey: 'state' },
+            supervisedFineTuningJobs: { plural: 'supervisedFineTuningJobs', states: JOB_STATES, stateKey: 'state' },
+            users: { plural: 'users', states: USER_STATES, stateKey: 'state' },
+            models: { plural: 'models', states: DEPLOYMENT_STATES, stateKey: 'state' },
+            secrets: { plural: 'secrets', states: DEPLOYMENT_STATES, stateKey: 'state' },
+        };
+        const meta = baseResource ? TYPE_MAP[baseResource] : undefined;
+        if (!meta)
+            return gatewayError(404, `Unknown request URL: ${method} ${path}.`);
+        // The PATCH whitelist, per collection: exactly the MUTABLE fields the vendor's own update
+        // operations accept (create-only and output-only fields are absent — a PATCH carrying one is
+        // refused below, the way grpc-gateway refuses an unknown field; googleads-twin.ts is the
+        // estate precedent). Sourced from the pinned spec's own update-operation schemas:
+        // Gateway_UpdateDataset (displayName, exampleCount, userUploaded, evaluationResult,
+        // transformed, splitted, evalProtocol, externalUrl, format, sourceJobName), the deployments
+        // PATCH names the deployment fields, users PATCH names the user fields, secrets and models
+        // the gatewaySecret/gatewayModel fields. The job collections carry NO update op in the spec
+        // (delete+get only) — a PATCH there is the vendor's 404 (route not found), never a served
+        // no-op, so the collections are absent from this map entirely.
+        const PATCHABLE = {
+            deployments: ['displayName', 'region', 'replicaCount', 'minReplicaCount', 'maxReplicaCount', 'precision'],
+            users: ['displayName', 'email', 'role', 'permissionPreset'],
+            models: ['displayName', 'contextLength', 'description'],
+            secrets: ['keyName'],
+            datasets: ['displayName', 'exampleCount', 'userUploaded', 'evaluationResult', 'transformed', 'splitted', 'evalProtocol', 'externalUrl', 'format', 'sourceJobName'],
+        };
+        // Rows are stored under the SINGULAR type (the same noun createControlResource writes); the
+        // URL carries the plural collection.
+        const singular = baseResource === 'deployments' ? 'deployment' : baseResource === 'datasets' ? 'dataset' : baseResource === 'batchInferenceJobs' ? 'batchInferenceJob' : baseResource === 'supervisedFineTuningJobs' ? 'supervisedFineTuningJob' : baseResource === 'users' ? 'user' : baseResource === 'models' ? 'model' : 'secret';
+        // LIST: GET /v1/accounts/{id}/<plural>
+        if (rest.length === 1 && method === 'GET') {
+            const all = rows(singular, accountId, req.root).filter((r) => !isTombstoned(r)).map(resourceView);
+            const { items, nextPageToken } = paginate(all, url);
+            return { status: 200, body: { [meta.plural]: items, nextPageToken, totalSize: all.length } };
+        }
+        // CREATE: POST /v1/accounts/{id}/<plural> — and ONLY that. A verb-suffixed collection
+        // (`<plural>:estimateCost`, `apiKeys:<anything>`) is a custom method, not a create: the
+        // vendor answers it with its own 404 (or serves it), never by running the create builder —
+        // letting `POST …/supervisedFineTuningJobs:estimateCost` with a dataset body CREATE a job
+        // would make an estimate mutate state.
+        if (rest.length === 1 && method === 'POST' && !verb) {
+            const build = (p) => {
+                // The vendor's create bodies are the RESOURCE DIRECTLY for deployments,
+                // batchInferenceJobs, supervisedFineTuningJobs, users and secrets (requestBody →
+                // $ref gatewayX). Datasets and models wrap: {dataset, datasetId} / {model, modelId}.
+                const inner = (baseResource === 'datasets' && p.dataset && typeof p.dataset === 'object' ? p.dataset
+                    : baseResource === 'models' && p.model && typeof p.model === 'object' ? p.model
+                        : p);
+                const at = new Date(req.occurredAt ?? '1970-01-01T00:00:00Z').toISOString().replace(/\.\d{3}Z$/, 'Z');
+                if (baseResource === 'deployments') {
+                    if (inner.baseModel === undefined)
+                        return { __error: 'baseModel is required' };
+                    return {
+                        name: `accounts/${accountId}/deployments/PLACEHOLDER`,
+                        displayName: inner.displayName ?? '',
+                        baseModel: inner.baseModel,
+                        state: 'CREATING',
+                        status: okStatus(),
+                        createTime: at,
+                        updateTime: at,
+                        ...(inner.region !== undefined ? { region: inner.region } : {}),
+                        ...(inner.replicaCount !== undefined ? { replicaCount: inner.replicaCount } : {}),
+                        ...(inner.minReplicaCount !== undefined ? { minReplicaCount: inner.minReplicaCount } : {}),
+                        ...(inner.maxReplicaCount !== undefined ? { maxReplicaCount: inner.maxReplicaCount } : {}),
+                        ...(inner.precision !== undefined ? { precision: inner.precision } : {}),
+                    };
+                }
+                if (baseResource === 'datasets') {
+                    return {
+                        name: `accounts/${accountId}/datasets/PLACEHOLDER`,
+                        displayName: inner.displayName ?? '',
+                        state: 'UPLOADING',
+                        status: okStatus(),
+                        createTime: at,
+                        updateTime: at,
+                        exampleCount: 0,
+                        userUploaded: true,
+                        ...(inner.format !== undefined ? { format: inner.format } : {}),
+                    };
+                }
+                if (baseResource === 'batchInferenceJobs') {
+                    // The job's dataset reference must name a dataset that really landed: the vendor
+                    // validates the reference at create, and a twin that accepted any string would let a
+                    // mistyped id "create" a job over nothing.
+                    if (inner.inputDatasetId !== undefined) {
+                        const dsId = String(inner.inputDatasetId).split('/').pop() ?? '';
+                        const ds = getRow('dataset', dsId, accountId, req.root);
+                        if (!ds || isTombstoned(ds))
+                            return { __error: `inputDatasetId not found: ${String(inner.inputDatasetId)}` };
+                    }
+                    return {
+                        name: `accounts/${accountId}/batchInferenceJobs/PLACEHOLDER`,
+                        displayName: inner.displayName ?? '',
+                        state: 'JOB_STATE_CREATING',
+                        status: okStatus(),
+                        createTime: at,
+                        updateTime: at,
+                        ...(inner.model !== undefined ? { model: inner.model } : {}),
+                        ...(inner.inputDatasetId !== undefined ? { inputDatasetId: inner.inputDatasetId } : {}),
+                        ...(inner.outputDatasetId !== undefined ? { outputDatasetId: inner.outputDatasetId } : {}),
+                    };
+                }
+                if (baseResource === 'supervisedFineTuningJobs') {
+                    if (inner.dataset === undefined)
+                        return { __error: 'dataset is required' };
+                    const dsId = String(inner.dataset).split('/').pop() ?? '';
+                    const ds = getRow('dataset', dsId, accountId, req.root);
+                    if (!ds || isTombstoned(ds))
+                        return { __error: `dataset not found: ${String(inner.dataset)}` };
+                    return {
+                        name: `accounts/${accountId}/supervisedFineTuningJobs/PLACEHOLDER`,
+                        displayName: inner.displayName ?? '',
+                        dataset: inner.dataset,
+                        state: 'JOB_STATE_CREATING',
+                        status: okStatus(),
+                        createTime: at,
+                        updateTime: at,
+                        ...(inner.baseModel !== undefined ? { baseModel: inner.baseModel } : {}),
+                        ...(inner.epochs !== undefined ? { epochs: inner.epochs } : {}),
+                        ...(inner.learningRate !== undefined ? { learningRate: inner.learningRate } : {}),
+                    };
+                }
+                if (baseResource === 'users') {
+                    if (inner.role === undefined)
+                        return { __error: 'role is required' };
+                    if (!USER_ROLES.includes(inner.role))
+                        return { __error: `role must be one of ${USER_ROLES.join(', ')}` };
+                    return {
+                        name: `accounts/${accountId}/users/PLACEHOLDER`,
+                        displayName: inner.displayName ?? '',
+                        email: inner.email ?? null,
+                        role: inner.role,
+                        state: 'CREATING',
+                        status: okStatus(),
+                        createTime: at,
+                        updateTime: at,
+                        ...(inner.permissionPreset !== undefined ? { permissionPreset: inner.permissionPreset } : {}),
+                    };
+                }
+                if (baseResource === 'secrets') {
+                    // The create body IS the gatewaySecret (the spec takes the resource directly), with
+                    // `name` and `keyName` required. `name` is the FULL resource name — a bare last
+                    // segment is accepted (clients generated from the spec send the short spelling) and
+                    // stored canonically; a full name must not be double-prefixed.
+                    if (inner.name === undefined || inner.keyName === undefined)
+                        return { __error: 'name and keyName are required' };
+                    const shortName = String(inner.name).split('/').pop();
+                    return {
+                        name: `accounts/${accountId}/secrets/${shortName}`,
+                        keyName: inner.keyName,
+                        // The vendor never returns the secret value on ANY read, including the create
+                        // response. The twin keeps it out of the stored row entirely — a secret that can be
+                        // read back is a custody lie.
+                        createTime: at,
+                        updateTime: at,
+                    };
+                }
+                if (baseResource === 'models') {
+                    return {
+                        name: `accounts/${accountId}/models/PLACEHOLDER`,
+                        displayName: inner.displayName ?? '',
+                        state: 'CREATING',
+                        status: okStatus(),
+                        createTime: at,
+                        updateTime: at,
+                        public: false,
+                        ...(inner.baseModelDetails !== undefined ? { baseModelDetails: inner.baseModelDetails } : {}),
+                        ...(inner.contextLength !== undefined ? { contextLength: inner.contextLength } : {}),
+                        ...(inner.description !== undefined ? { description: inner.description } : {}),
+                    };
+                }
+                return {};
+            };
+            const fields = build(params);
+            if (fields.__error !== undefined)
+                return gatewayError(400, String(fields.__error));
+            // Replace the PLACEHOLDER name with the real id after the id is known. The singular type
+            // name is what the id params are built from (deploymentId, userId, batchInferenceJobId…).
+            const type = baseResource === 'deployments' ? 'deployment' : baseResource === 'datasets' ? 'dataset' : baseResource === 'batchInferenceJobs' ? 'batchInferenceJob' : baseResource === 'supervisedFineTuningJobs' ? 'supervisedFineTuningJob' : baseResource === 'users' ? 'user' : baseResource === 'models' ? 'model' : 'secret';
+            const prefix = baseResource === 'batchInferenceJobs' ? 'bij' : baseResource === 'supervisedFineTuningJobs' ? 'sft' : type === 'secret' ? 'secret' : `${type}`;
+            return createControlResource(type, prefix, accountId, params, req, url, (p) => build(p));
+        }
+        // SINGLE RESOURCE: GET/PATCH/DELETE /v1/accounts/{id}/<plural>/<resource_id>
+        if (rest.length === 2 && !verb) {
+            const rid = idSeg;
+            // The lookup is ACCOUNT-SCOPED: a row created under another account is invisible here and
+            // answers the same NOT_FOUND an unknown id answers (the vendor's own tenancy — an account
+            // cannot see, patch or delete another account's resource).
+            const r = getRow(singular, rid, accountId, req.root);
+            if (method === 'GET') {
+                if (!r || isTombstoned(r))
+                    return gatewayError(404, `Not found: ${baseResource}/${rid}`);
+                return { status: 200, body: resourceView(r) };
+            }
+            if (method === 'PATCH') {
+                // ONE policy for output-only fields across every collection (grpc-gateway's own): the
+                // spec's readOnly fields are REFUSED with the same unknown-field 400 an invented field
+                // gets — "Cannot find field." — never silently dropped and never written. (Silently
+                // ignoring them on deployments while datasets refused them was two policies on one
+                // plane; the refusal is grpc-gateway's own behavior for a client-set readOnly field.)
+                if (!PATCHABLE[baseResource])
+                    return gatewayError(404, `Unknown request URL: ${method} ${path}.`);
+                if (!r || isTombstoned(r))
+                    return gatewayError(404, `Not found: ${baseResource}/${rid}`);
+                const patchable = { ...params };
+                // The per-collection field whitelist (the same one create uses): an undeclared field is
+                // refused the way grpc-gateway refuses an unknown field, and an output-only field never
+                // passes (googleads-twin.ts is the estate precedent for the refusal shape).
+                const unknown = Object.keys(patchable).filter((k) => !PATCHABLE[baseResource]?.includes(k));
+                if (unknown.length)
+                    return gatewayError(400, `Invalid JSON payload received. Unknown name "${unknown[0]}": Cannot find field.`);
+                await applyTwinWrite(SERVICE, {
+                    operation: `${singular}.update`, subjectType: singular, subjectId: `${accountId}/${rid}`,
+                    fields: patchable,
+                    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+                }, req.root);
+                return { status: 200, body: resourceView(getRow(singular, rid, accountId, req.root) ?? {}) };
+            }
+            if (method === 'DELETE')
+                return deleteControlResource(singular, rid, accountId, req);
+        }
+        // CUSTOM VERB: POST /v1/accounts/{id}/<plural>/<resource_id>:<verb>
+        if (rest.length === 2 && verb && method === 'POST') {
+            const rid = idSeg;
+            const r = getRow(singular, rid, accountId, req.root);
+            // :undelete addresses a DELETED row by design; every other verb needs a live row.
+            if (!r || (isTombstoned(r) && verb !== 'undelete'))
+                return gatewayError(404, `Not found: ${baseResource}/${rid}`);
+            if (verb === 'cancel' && (baseResource === 'batchInferenceJobs' || baseResource === 'supervisedFineTuningJobs')) {
+                if (r.state === 'JOB_STATE_CANCELLED' || r.state === 'JOB_STATE_CANCELLING') {
+                    return gatewayError(400, `Cannot cancel a job in state ${String(r.state)}`);
+                }
+                await applyTwinWrite(SERVICE, {
+                    operation: `${singular}.cancel`, subjectType: singular, subjectId: `${accountId}/${rid}`,
+                    fields: { state: 'JOB_STATE_CANCELLING' },
+                    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+                }, req.root);
+                // The vendor's cancel answers `{}`.
+                return { status: 200, body: {} };
+            }
+            if (verb === 'resume' && (baseResource === 'batchInferenceJobs' || baseResource === 'supervisedFineTuningJobs')) {
+                await applyTwinWrite(SERVICE, {
+                    operation: `${singular}.resume`, subjectType: singular, subjectId: `${accountId}/${rid}`,
+                    fields: { state: 'JOB_STATE_RUNNING' },
+                    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+                }, req.root);
+                return { status: 200, body: {} };
+            }
+            if (verb === 'undelete' && baseResource === 'deployments') {
+                await applyTwinWrite(SERVICE, {
+                    operation: 'deployment.undelete', subjectType: 'deployment', subjectId: `${accountId}/${rid}`,
+                    fields: { _deleted: false, state: 'CREATING' },
+                    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+                }, req.root);
+                return { status: 200, body: resourceView(getRow('deployment', rid, accountId, req.root) ?? {}) };
+            }
+            if (verb === 'scale' && baseResource === 'deployments' && method === 'POST') {
+                const replicaCount = params.replicaCount;
+                if (typeof replicaCount !== 'number')
+                    return gatewayError(400, 'replicaCount is required');
+                await applyTwinWrite(SERVICE, {
+                    operation: 'deployment.scale', subjectType: 'deployment', subjectId: `${accountId}/${rid}`,
+                    fields: { replicaCount },
+                    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+                }, req.root);
+                return { status: 200, body: resourceView(getRow('deployment', rid, accountId, req.root) ?? {}) };
+            }
+            return gatewayError(404, `Unknown operation: ${verb} on ${baseResource}`);
+        }
+        // PATCH /v1/accounts/{id}/deployments/{deployment_id}:scale — the spec's own spelling
+        // (Gateway_ScaleDeployment, body {replicaCount}); it answers `{}`, not the resource.
+        if (rest.length === 2 && verb === 'scale' && baseResource === 'deployments' && method === 'PATCH') {
+            const rid = idSeg;
+            const r = getRow('deployment', rid, accountId, req.root);
+            if (!r || isTombstoned(r))
+                return gatewayError(404, `Not found: deployments/${rid}`);
+            const replicaCount = params.replicaCount;
+            if (typeof replicaCount !== 'number')
+                return gatewayError(400, 'replicaCount is required');
+            await applyTwinWrite(SERVICE, {
+                operation: 'deployment.scale', subjectType: 'deployment', subjectId: `${accountId}/${rid}`,
+                fields: { replicaCount },
+                ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+            }, req.root);
+            return { status: 200, body: {} };
+        }
+        // users/{user_id}/apiKeys — nested under users. The verb-suffixed collection spelling
+        // (`apiKeys:delete`) carries its verb on the apiKeys segment itself.
+        if (baseResource === 'users' && rest.length >= 3 && rest[2].split(':')[0] === 'apiKeys') {
+            const userId = rest[1];
+            const user = getRow('user', userId, accountId, req.root);
+            if (!user || user._deleted)
+                return gatewayError(404, `Not found: users/${userId}`);
+            const keySeg = rest.slice(3);
+            if (keySeg.length === 0 && method === 'GET') {
+                // The full key is returned ONCE at creation — the LIST answers it never. A list row
+                // carrying `fw_…` would be a custody lie the single-key GET two branches down doesn't
+                // commit, so the strip happens here too.
+                const keys = rows('apiKey', accountId, req.root).filter((r) => !r._deleted && r._user_id === userId).map(resourceView);
+                for (const k of keys)
+                    delete k.key;
+                return { status: 200, body: { apiKeys: keys, nextPageToken: null, totalSize: keys.length } };
+            }
+            // POST .../apiKeys:delete — the vendor's own odd verb-suffixed delete with a {keyId} body
+            // (collection-level spelling, Gateway_DeleteApiKey; answers `{}`).
+            if (keySeg.length === 0 && method === 'POST' && rest[2] === 'apiKeys:delete') {
+                const keyId = typeof params.keyId === 'string' ? params.keyId : undefined;
+                if (!keyId)
+                    return gatewayError(400, 'keyId is required');
+                const k = getRow('apiKey', keyId, accountId, req.root);
+                if (!k || k._deleted || k._user_id !== userId)
+                    return gatewayError(404, `Not found: apiKeys/${keyId}`);
+                await applyTwinWrite(SERVICE, {
+                    operation: 'apiKey.delete', subjectType: 'apiKey', subjectId: `${accountId}/${keyId}`, fields: { _deleted: true },
+                    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+                }, req.root);
+                return { status: 200, body: {} };
+            }
+            if (keySeg.length === 0 && method === 'POST' && rest[2] === 'apiKeys') {
+                // The verb check is load-bearing: `apiKeys:frobnicate` must 404 below, never mint a key.
+                const inner = (params.apiKey && typeof params.apiKey === 'object' ? params.apiKey : params);
+                const id = nextId('apiKey', 'key', accountId, req.root);
+                const at = new Date(req.occurredAt ?? '1970-01-01T00:00:00Z').toISOString().replace(/\.\d{3}Z$/, 'Z');
+                const key = `fw_${stableSuffix(id + at)}${fnv1a(id).toString(36)}`;
+                await applyTwinWrite(SERVICE, {
+                    operation: 'apiKey.create', subjectType: 'apiKey', subjectId: `${accountId}/${id}`,
+                    fields: {
+                        name: `accounts/${accountId}/users/${userId}/apiKeys/${id}`,
+                        displayName: inner.displayName ?? 'default',
+                        key, // returned ONCE at creation, never again (the vendor's own contract)
+                        prefix: key.slice(0, 6),
+                        keyId: id,
+                        _user_id: userId,
+                        _account: accountId,
+                        createTime: at,
+                        expireTime: typeof inner.expireTime === 'string' ? inner.expireTime : null,
+                    },
+                    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+                }, req.root);
+                return { status: 200, body: resourceView(getRow('apiKey', id, accountId, req.root) ?? {}) };
+            }
+            if (keySeg.length === 1 && method === 'GET') {
+                const k = getRow('apiKey', keySeg[0], accountId, req.root);
+                if (!k || k._deleted || k._user_id !== userId)
+                    return gatewayError(404, `Not found: apiKeys/${keySeg[0]}`);
+                const view = resourceView(k);
+                delete view.key; // "only available upon creation and not stored thereafter"
+                return { status: 200, body: view };
+            }
+            if (keySeg.length === 1 && method === 'PATCH') {
+                const k = getRow('apiKey', keySeg[0], accountId, req.root);
+                if (!k || k._deleted || k._user_id !== userId)
+                    return gatewayError(404, `Not found: apiKeys/${keySeg[0]}`);
+                const patchable = { ...params };
+                for (const f of ['key', 'keyId', 'prefix', 'secure', 'email', 'createTime', 'lastUsed', 'isFirepass'])
+                    delete patchable[f];
+                const unknown = Object.keys(patchable).filter((f) => !['displayName', 'expireTime'].includes(f));
+                if (unknown.length)
+                    return gatewayError(400, `Invalid JSON payload received. Unknown name "${unknown[0]}": Cannot find field.`);
+                await applyTwinWrite(SERVICE, {
+                    operation: 'apiKey.update', subjectType: 'apiKey', subjectId: `${accountId}/${keySeg[0]}`,
+                    fields: patchable,
+                    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+                }, req.root);
+                const view = resourceView(getRow('apiKey', keySeg[0], accountId, req.root) ?? {});
+                delete view.key;
+                return { status: 200, body: view };
+            }
+            // POST .../apiKeys:delete — the vendor's own odd verb-suffixed delete with a {keyId} body.
+            // The key must belong to the addressed user: the id segment is under that user's own path,
+            // and deleting another user's key through it would skip the scoping the collection-level
+            // spelling enforces one branch up.
+            if (keySeg.length === 1 && keySeg[0].endsWith(':delete') && method === 'POST') {
+                const keyId = typeof params.keyId === 'string' ? params.keyId : keySeg[0].slice(0, -':delete'.length);
+                const k = getRow('apiKey', keyId, accountId, req.root);
+                if (!k || k._deleted || k._user_id !== userId)
+                    return gatewayError(404, `Not found: apiKeys/${keyId}`);
+                await applyTwinWrite(SERVICE, {
+                    operation: 'apiKey.delete', subjectType: 'apiKey', subjectId: `${accountId}/${keyId}`, fields: { _deleted: true },
+                    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+                }, req.root);
+                return { status: 200, body: {} };
+            }
+        }
+        return gatewayError(404, `Unknown request URL: ${method} ${path}.`);
+    }
+    // Not on either plane — the twin serves nothing else.
+    return notFound(`Unknown request URL: ${method} ${path}.`);
+}