@volter/twin-fireworks 0.1.0

package/src/fireworks-twin.ts

@@ -0,0 +1,1427 @@
+// 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.ts';
+import {
+  contentToText,
+  countPromptTokens,
+  estimateTokens,
+  fnv1a,
+  lastUserText,
+  pseudoEmbedding,
+  stubAssistantText,
+  stubReasoningText,
+  stubRelevanceScore,
+} from './fireworks-stub.ts';
+import type { FireworksScenarioEngine, FireworksScenarioRespond, ScriptedResult } from './fireworks-scenario.ts';
+import { realizeFireworksRespond } from './fireworks-scenario.ts';
+import type { ScenarioDecision } from '@volter/world-core';
+import type {
+  FireworksAnthropicContentBlock,
+  FireworksAnthropicErrorType,
+  FireworksAnthropicMessage,
+  FireworksChatCompletion,
+  FireworksChatMessage,
+  FireworksChatRequest,
+  FireworksCompletion,
+  FireworksGatewayCode,
+  FireworksMessageParam,
+  FireworksResponseObject,
+} from './fireworks-types.ts';
+
+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';
+
+export type FireworksRequest = {
+  method: string;
+  path: string;
+  body?: string;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+  /** The credential the caller presents (the SDKs' bearer `Authorization` header). When a request
+   *  carries an auth SURFACE (this field set, or `headers` present), the twin holds it to the real
+   *  vendor rule: a credential is required → 401 on missing/invalid. In-process trusted calls
+   *  (capability verify, connector) omit BOTH and are not auth-gated. */
+  apiKey?: string;
+  /** Lower-cased request headers the HTTP server passes through so the handler can model auth. */
+  headers?: Record<string, string>;
+  /** When set on a streaming POST, chunks are written here (no sockets). */
+  sseSink?: SseSink;
+  /** Scenario scripting (fireworks-scenario.ts): when set, chat completions consult the engine
+   *  first — a matching handler scripts the answer, a miss answers the labeled stub with a
+   *  pointer to the miss. Twin-only scaffolding, never vendor surface. */
+  scenarioEngine?: FireworksScenarioEngine;
+};
+
+export type SseEvent = { data?: unknown; done?: boolean };
+export type SseSink = (event: SseEvent) => void;
+
+/** The handler response. `headers` (when present) are response headers the HTTP server should set. */
+export type FireworksResponseEnvelope = { status: number; body: unknown; headers?: Record<string, string> };
+
+// ── 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: string, extra: Record<string, unknown> = {}) {
+  return { error: { message, ...extra } };
+}
+function invalidRequest(message: string, extra: Record<string, unknown> = {}): FireworksResponseEnvelope {
+  return { status: 400, body: errBody(message, { code: 400, ...extra }) };
+}
+function notFound(message: string): FireworksResponseEnvelope {
+  return { status: 404, body: errBody(message, { code: 404 }) };
+}
+function authError(message: string): FireworksResponseEnvelope {
+  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: (string | number)[], msg: string, type: string): FireworksResponseEnvelope {
+  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: number, message: string): FireworksResponseEnvelope {
+  const code: FireworksGatewayCode =
+    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: FireworksRequest): FireworksResponseEnvelope | null {
+  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?: string): number {
+  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: Record<string, unknown>): boolean {
+  return r._deleted === true || r.deleted === true;
+}
+function rows(type: string, accountId: string | undefined, root?: string): Array<Record<string, unknown>> {
+  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: string, prefix: string, accountId: string | undefined, root?: string): string {
+  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: string, id: string, accountId: string | undefined, root?: string): Record<string, unknown> | undefined {
+  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: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  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?: string): Record<string, unknown> {
+  if (!body || !body.trim()) return {};
+  try {
+    const v = JSON.parse(body);
+    return v && typeof v === 'object' ? (v as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** A deterministic id suffix from the request (so ids are stable + assertable). */
+function stableSuffix(seedText: string): string {
+  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?: string): Set<string> {
+  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: string): FireworksResponseEnvelope {
+  return notFound(`Model id not found: ${model}`);
+}
+
+// ── chat completions: validate the request the way Fireworks does ───────────────────────
+const SERVICE_TIERS = ['auto', 'default', 'flex', 'priority'] as const;
+const CONTEXT_BEHAVIORS = ['error', 'truncate'] as const;
+
+/**
+ * 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: Array<{ field: string; kind: 'number'; min?: number; max?: number; integer?: boolean } | { field: string; kind: 'enum'; values: readonly string[] } | { field: string; kind: 'bool' }> = [
+  { 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: Record<string, unknown>): FireworksResponseEnvelope | null {
+  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'] as const;
+
+type ChatArgs = {
+  model: string;
+  messages: FireworksMessageParam[];
+  promptText: string;
+  tools?: unknown;
+  maxTokens?: number;
+  stop?: string[];
+  stream: boolean;
+  includeUsage: boolean;
+  serviceTier: string;
+  contextBehavior: 'error' | 'truncate';
+  responseFormat?: { type: string; schema?: unknown };
+  reasoningEffort?: string | number | boolean;
+};
+
+/**
+ * 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: Record<string, unknown>): { args: ChatArgs } | { error: FireworksResponseEnvelope } {
+  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 as FireworksMessageParam[];
+  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 as (typeof MESSAGE_ROLES)[number])) {
+      // 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: number | undefined;
+  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: string[] | undefined;
+  if (params.stop !== undefined && params.stop !== null) {
+    if (typeof params.stop === 'string') stop = [params.stop];
+    else if (Array.isArray(params.stop)) stop = params.stop as string[];
+    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 as (typeof SERVICE_TIERS)[number])) {
+      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: 'error' | 'truncate' = '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 as 'error' | 'truncate')) {
+      return { error: validationError(['body', 'context_length_exceeded_behavior'], "Input should be one of 'error', 'truncate'", 'enum') };
+    }
+    contextBehavior = params.context_length_exceeded_behavior as 'error' | 'truncate';
+  }
+  let responseFormat: { type: string; schema?: unknown } | undefined;
+  const rf = params.response_format as { type?: unknown; json_schema?: unknown } | undefined;
+  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 as { include_usage?: boolean } | undefined;
+  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 as string | number | boolean } : {}),
+    },
+  };
+}
+
+/** Build ONE deterministic stub chat completion. */
+function buildChatCompletion(args: ChatArgs, occurredAt?: string, decision?: ScenarioDecision): FireworksChatCompletion | FireworksResponseEnvelope {
+  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: ScriptedResult | null = null;
+  let missTeach = '';
+  if (decision) {
+    if (decision.kind === 'handler') {
+      scripted = realizeFireworksRespond(decision.respond as FireworksScenarioRespond);
+    } 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: FireworksChatMessage = { 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: FireworksChatMessage = { 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: string): string[] {
+  if (!text) return [];
+  const out: string[] = [];
+  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: ChatArgs, sink: SseSink, occurredAt?: string, decision?: ScenarioDecision): FireworksChatCompletion | FireworksResponseEnvelope {
+  const built = buildChatCompletion(args, occurredAt, decision);
+  if ('status' in built) return built;
+  const full = built;
+  const base = { id: full.id, object: 'chat.completion.chunk' as const, 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: FireworksCompletion, sink: SseSink, includeUsage: boolean): FireworksCompletion {
+  const base = { id: full.id, object: 'text_completion' as const, 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: Record<string, unknown>, occurredAt?: string, sink?: SseSink, root?: string): FireworksResponseEnvelope {
+  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 as unknown[]).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: number | undefined;
+  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: FireworksCompletion = {
+    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 as { include_usage?: unknown } | undefined;
+  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: Record<string, unknown>): Record<string, unknown> {
+  return { id: r.id, ...strip(r) };
+}
+
+async function createResponse(params: Record<string, unknown>, req: FireworksRequest): Promise<FireworksResponseEnvelope> {
+  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' as const,
+    id: `msg_twin_${stableSuffix(text)}`,
+    role: 'assistant' as const,
+    status: 'completed' as const,
+    content: [{ type: 'output_text' as const, text }],
+  };
+  const base: Record<string, unknown> = {
+    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: FireworksRequest): FireworksResponseEnvelope {
+  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: string, req: FireworksRequest): FireworksResponseEnvelope {
+  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: string, req: FireworksRequest): Promise<FireworksResponseEnvelope> {
+  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: number, type: FireworksAnthropicErrorType, message: string): FireworksResponseEnvelope {
+  return { status, body: { type: 'error', error: { type, message }, request_id: null } };
+}
+
+function validateAnthropicMessages(params: Record<string, unknown>): { ok: true } | { error: FireworksResponseEnvelope } {
+  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 as Array<Record<string, unknown>>) {
+    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: Record<string, unknown>, occurredAt?: string): FireworksResponseEnvelope {
+  const bad = validateAnthropicMessages(params);
+  if ('error' in bad) return bad.error;
+  const messages = params.messages as Array<{ role: string; content: unknown }>;
+  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 as { text?: unknown }).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: FireworksAnthropicMessage['stop_reason'] = 'end_turn';
+  if (maxTokens !== undefined && estimateTokens(text) > maxTokens) {
+    text = text.slice(0, maxTokens * 4);
+    stopReason = 'max_tokens';
+  }
+  const content: FireworksAnthropicContentBlock[] = [{ type: 'text', text, citations: null }];
+  const outputTokens = estimateTokens(text);
+  const body: FireworksAnthropicMessage = {
+    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: Record<string, unknown>, sink: SseSink, occurredAt?: string): FireworksResponseEnvelope {
+  const built = buildAnthropicMessage(params, occurredAt);
+  if (built.status !== 200) return built;
+  const full = built.body as FireworksAnthropicMessage;
+  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: Record<string, unknown>, root?: string): FireworksResponseEnvelope {
+  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 as unknown[]).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' as const,
+      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: Record<string, unknown>, root?: string): FireworksResponseEnvelope {
+  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 as unknown[]).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: Record<string, unknown>): Record<string, unknown> {
+  // 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: Array<Record<string, unknown>>, url: URL): { items: Array<Record<string, unknown>>; nextPageToken: string | null } {
+  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(): Record<string, unknown> {
+  return { code: 'OK', message: '' };
+}
+
+async function createControlResource(type: string, prefix: string, accountId: string, params: Record<string, unknown>, req: FireworksRequest, url: URL, buildFields: (params: Record<string, unknown>) => Record<string, unknown>): Promise<FireworksResponseEnvelope> {
+  // 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) as Record<string, unknown>;
+  const bodyId = typeof wrapped[`${type}Id`] === 'string' ? (wrapped[`${type}Id`] as string)
+    : typeof params[`${type}Id`] === 'string' ? (params[`${type}Id`] as string)
+    // 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() as string)
+    : 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: string, id: string, accountId: string, req: FireworksRequest): Promise<FireworksResponseEnvelope> {
+  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'] as const;
+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'] as const;
+const USER_STATES = ['STATE_UNSPECIFIED', 'CREATING', 'READY', 'UPDATING', 'DELETING'] as const;
+const USER_ROLES = ['admin', 'user', 'contributor', 'inference-user', 'custom'] as const;
+
+// ── public entry: cross-cutting protocol (auth) then route ──────────────────────────────
+export async function handleFireworksTwinRequest(req: FireworksRequest): Promise<FireworksResponseEnvelope> {
+  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: FireworksRequest, method: string): Promise<FireworksResponseEnvelope> {
+  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: string) => 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: ScenarioDecision | undefined;
+      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: Record<string, { plural: string; states: readonly string[]; stateKey: string }> = {
+      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: Record<string, string[]> = {
+      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: Record<string, unknown>): Record<string, unknown> => {
+        // 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) as Record<string, unknown>;
+        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' } as Record<string, unknown>;
+          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)}` } as Record<string, unknown>;
+          }
+          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' } as Record<string, unknown>;
+          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)}` } as Record<string, unknown>;
+          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' } as Record<string, unknown>;
+          if (!USER_ROLES.includes(inner.role as (typeof USER_ROLES)[number])) return { __error: `role must be one of ${USER_ROLES.join(', ')}` } as Record<string, unknown>;
+          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' } as Record<string, unknown>;
+          const shortName = String(inner.name).split('/').pop() as string;
+          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 as Record<string, unknown>) };
+        // 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 as Record<string, unknown>).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 as Record<string, unknown>).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) as Record<string, unknown>;
+        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 as Record<string, unknown>) };
+        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}.`);
+}