@volter/twin-openai 0.1.2 → 2.0.1

package/src/openai-twin.ts

@@ -1,38 +1,28 @@
-// OpenAI twin REQUEST HANDLER — the canonical OpenAI API surface for the twin.
-// Contract: handleOpenAITwinRequest({method, path, body}) -> {status, body}. It is the
-// faithful OpenAI API the real `openai` SDK (pointed at this baseURL) talks to UNMODIFIED.
-//
-// THE HONEST DESIGN: the twin cannot run the model, so `POST /v1/chat/completions` and
-// `POST /v1/responses` return a DETERMINISTIC STUB completion (openai-stub.ts) clearly labeled
-// a twin stub — it NEVER pretends to be real model output. `POST /v1/embeddings` returns
-// DETERMINISTIC pseudo-vectors (never real embedding values). But the ENTIRE PROTOCOL ENVELOPE
-// is vendor-faithful: response shapes, streaming SSE chunks, tool_calls, finish_reason,
-// deterministic usage. The genuinely stateful + static surface is real, not stubbed:
-//   • GET /v1/models (+ /:id)            — static catalog (openai-models.ts)
-//   • POST/GET/DELETE /v1/files          — stateful (kernel action log)
-//   • POST/GET /v1/batches (+ cancel)    — stateful
-//   • POST /v1/moderations               — deterministic classifier
-//   • Fine-tuning jobs (create/get/list/cancel/events) — stateful
-//   • Vector stores (+ files)            — stateful
-//   • POST /v1/images/generations        — response shape with a placeholder URL (real pixels
-//                                          are out of scope)
-//
-// State lives in the kernel action log (D1): all writes are local actions, reads are the
-// projection. No real OpenAI 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/twin';
-import { OPENAI_MODELS, findModel } from './openai-models.ts';
+// OpenAI twin: the pack's behaviour and its in-process door. `handleOpenAITwinRequest` answers one
+// request through the pack's fetch (openai-server.ts), which the derived dispatch owns: an operation
+// OpenAI's spec publishes is a semantics handler (semantics/), the derived core (manifest.ts), or
+// OpenAI's unknown-URL 404. What lives here is what those share:
+//   • the generative stubs: chat completions and responses (validation, the deterministic stub or a
+//     scripted scenario's turn, the streaming event sequences), embeddings (pseudo-vectors),
+//     moderations, images and audio (labeled placeholders); never a model's output;
+//   • the Responses API's atomic id allocation and background-poll completion;
+//   • the usage and costs reports over the recorded usage.
+// No real OpenAI is called from this path.
+import { applyTwinWriteAtomic, type ScenarioDecision } from '@volter/world-core';
 import {
   buildLogprobs,
   countPromptTokens,
   estimateTokens,
+  lastUserText,
   moderateText,
   pseudoEmbedding,
   stubAssistantText,
   stubJsonObject,
   stubToolCall,
 } from './openai-stub.ts';
-import { type OpenAIScenarioEngine, type OpenAIScenarioRespond, realizeOpenAIRespond, type ScriptedResult } from './openai-scenario.ts';
+import { DEFAULT_EFFORT, modelOf, reasons, unsupported } from './openai-models.ts';
+import { type OpenAIScenarioEngine, scenarioTurn, scriptedChoice } from './openai-scenario.ts';
+import { audioFormat, base64, imageFormat, partBytes, placeholderPng, pngSize, requestedSize, silentAac, silentFlac, silentMp3, silentOpus, silentPcm, silentWav, wavSeconds } from './openai-media.ts';
 import type {
   ChatChoice,
   ChatCompletion,
@@ -44,11 +34,14 @@ import type {
   OpenAIResponse,
   ResponseMessageItem,
   ResponseOutputItem,
+  ResponseFunctionCallItem,
   ResponseReasoningItem,
   ResponseUsage,
   SseSink,
 } from './openai-types.ts';
 
+import { createOpenAITwinFetch } from './openai-server.ts';
+
 const SERVICE = 'openai';
 
 export type OpenAIRequest = {
@@ -56,7 +49,8 @@ export type OpenAIRequest = {
   scenarioEngine?: OpenAIScenarioEngine;
   method: string;
   path: string;
-  body?: string;
+  /** JSON text, or a multipart form (an upload) */
+  body?: string | FormData;
   occurredAt?: string;
   root?: string;
   readOnly?: boolean;
@@ -66,8 +60,8 @@ export type OpenAIRequest = {
    *  (capability verify, connector) omit BOTH and are not auth-gated — the twin can't validate
    *  against real keys, so the modeled failure is the CHECKABLE missing/sentinel-invalid case. */
   apiKey?: string;
-  /** Lower-cased request headers (e.g. `authorization`, `idempotency-key`) the HTTP server passes
-   *  through so the handler can model auth (401), the rate-limit trigger (429), and idempotency. */
+  /** Lower-cased request headers (e.g. `authorization`) the HTTP server passes through so the
+   *  handler can model auth (401) and the rate-limit trigger (429). */
   headers?: Record<string, string>;
   /** When set on a streaming POST, chunks are written here (no sockets). */
   sseSink?: SseSink;
@@ -83,116 +77,10 @@ function errBody(type: string, message: string, code: string | null = null, para
 function invalidRequest(message: string, param: string | null = null, code: string | null = null): OpenAIResponseEnvelope {
   return { status: 400, body: errBody('invalid_request_error', message, code, param) };
 }
-function notFound(message: string, code: string | null = null): OpenAIResponseEnvelope {
-  return { status: 404, body: errBody('invalid_request_error', message, code) };
-}
-function authError(message: string, code = 'invalid_api_key'): OpenAIResponseEnvelope {
-  // Real OpenAI 401s carry error.type:'invalid_request_error' with a code like 'invalid_api_key'.
-  return { status: 401, body: errBody('invalid_request_error', message, code) };
-}
-
-// ── modeled authentication (401) ────────────────────────────────────────────────────────
-// Real OpenAI requires a bearer credential on every request and returns 401 when it is missing
-// or invalid. The twin can't validate against real keys, so it models the CHECKABLE failures: a
-// missing credential, and a reserved sentinel ('sk-invalid'/'invalid') for the invalid-key path.
-// Any other non-empty key is accepted. Trusted in-process calls (verify/connector) carry NEITHER
-// `headers` nor `apiKey` and are NOT auth-gated; the real `openai` SDK always sends a key → passes.
-function checkAuth(req: OpenAIRequest): OpenAIResponseEnvelope | 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) return authError('You didn\'t provide an API key. You need to provide your API key in an Authorization header using Bearer auth (i.e. Authorization: Bearer YOUR_KEY).', 'invalid_api_key');
-  if (key === 'sk-invalid' || key === 'invalid') return authError('Incorrect API key provided. You can find your API key at https://platform.openai.com/account/api-keys.', 'invalid_api_key');
-  return null;
-}
-
-// ── modeled rate limiting (429) ─────────────────────────────────────────────────────────
-// Rate limits are non-deterministic in production, so the twin exposes a DETERMINISTIC opt-in
-// trigger: a request carrying `x-twin-force-rate-limit: 1` (or `true`) returns the faithful 429
-// envelope (error.type:'rate_limit_exceeded') + Retry-After and the x-ratelimit-* header family.
-// (No real timing/quotas — the twin can't reproduce them; this is the checkable plumbing.)
-function rateLimitError(): OpenAIResponseEnvelope {
-  return {
-    status: 429,
-    body: errBody('rate_limit_exceeded', 'Rate limit reached for requests. Limit your request rate or retry after the indicated delay.', 'rate_limit_exceeded'),
-    headers: {
-      'retry-after': '1',
-      'x-ratelimit-limit-requests': '10000',
-      'x-ratelimit-remaining-requests': '0',
-      'x-ratelimit-reset-requests': '1s',
-      'x-ratelimit-limit-tokens': '2000000',
-      'x-ratelimit-remaining-tokens': '0',
-      'x-ratelimit-reset-tokens': '6ms',
-    },
-  };
-}
-function rateLimitTriggered(req: OpenAIRequest): boolean {
-  const v = req.headers?.['x-twin-force-rate-limit'];
-  return v === '1' || v === 'true';
-}
 
 function nowEpoch(occurredAt?: string): number {
   return Math.floor((occurredAt ? Date.parse(occurredAt) : 0) / 1000);
 }
-function nowIso(occurredAt?: string): string {
-  return occurredAt ? new Date(Date.parse(occurredAt)).toISOString() : '1970-01-01T00:00:00.000Z';
-}
-
-// ── kernel helpers ──────────────────────────────────────────────────────────────────────
-function rows(type: string, root?: string): Array<Record<string, unknown>> {
-  return projectResources(SERVICE, root).filter((r) => r.type === type);
-}
-function nextId(type: string, prefix: string, root?: string): string {
-  let max = 0;
-  for (const r of rows(type, root)) {
-    const m = new RegExp(`^${prefix}-twin-(\\d+)$`).exec(String(r.id));
-    if (m) max = Math.max(max, Number(m[1]));
-  }
-  return `${prefix}-twin-${max + 1}`;
-}
-function getRow(type: string, id: string, root?: string): Record<string, unknown> | undefined {
-  return rows(type, root).find((r) => r.id === id);
-}
-// The kernel reserves the field name `type` as its resource-type discriminator, so the stored
-// vendor `object` field survives projection but the kernel `type` shadows nothing — we strip
-// the kernel housekeeping fields and re-shape the served view per resource.
-function strip(r: Record<string, unknown>): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(r)) {
-    // drop the kernel housekeeping field + the twin's private underscore-prefixed fields.
-    if (k === 'type' || k === 'updatedAt' || k.startsWith('_')) continue;
-    out[k] = v;
-  }
-  return out;
-}
-
-// ── idempotency (Idempotency-Key header dedup) ───────────────────────────────────────────
-// A mutation carrying an Idempotency-Key is replayed verbatim on re-issue with the same key — the
-// vendor returns the original response (same id) and never re-applies the side effect. The twin
-// stores the serialized {status,body,headers} keyed by a hash of the key (type-prefixed id, so it
-// can't collide with another resource's numeric id — kernel (type,id) caveat).
-function idemId(key: string): string {
-  let h = 0x811c9dc5;
-  for (let i = 0; i < key.length; i++) { h ^= key.charCodeAt(i); h = Math.imul(h, 0x01000193); }
-  return `idem-${(h >>> 0).toString(36)}`;
-}
-function getIdempotentResult(key: string, root?: string): OpenAIResponseEnvelope | null {
-  const row = getRow('idempotency_record', idemId(key), root);
-  if (!row || typeof row._result !== 'string') return null;
-  try { return JSON.parse(row._result as string) as OpenAIResponseEnvelope; } catch { return null; }
-}
-async function storeIdempotentResult(key: string, result: OpenAIResponseEnvelope, req: OpenAIRequest): Promise<void> {
-  const id = idemId(key);
-  if (getRow('idempotency_record', id, req.root)) return; // a concurrent insert won
-  await applyTwinWrite(SERVICE, {
-    operation: 'idempotency_record.create',
-    subjectType: 'idempotency_record',
-    subjectId: id,
-    fields: { object: 'idempotency_record', _key: key, _result: JSON.stringify(result) },
-    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
-    actor: { kind: 'agent' },
-  }, req.root);
-}
 
 // ── usage ledger (real recorded usage → the usage/costs reporting endpoints) ──────────────
 // Every billable inference call appends a usage record (model + token counts + a synthetic cost
@@ -215,60 +103,121 @@ const MODEL_PRICES: Record<string, { input: number; output: number }> = {
 function modelPrice(model: string): { input: number; output: number } {
   return MODEL_PRICES[model] ?? { input: 0, output: 0 };
 }
-function usageCost(model: string, inputTokens: number, outputTokens: number): number {
+export function usageCost(model: string, inputTokens: number, outputTokens: number): number {
   const p = modelPrice(model);
   return (inputTokens / 1e6) * p.input + (outputTokens / 1e6) * p.output;
 }
-async function recordUsage(req: OpenAIRequest, kind: string, model: string, inputTokens: number, outputTokens: number): Promise<void> {
-  const id = nextId('usage_record', 'usage', req.root);
-  await applyTwinWrite(SERVICE, {
-    operation: 'usage_record.create',
-    subjectType: 'usage_record',
-    subjectId: id,
-    fields: {
-      object: 'usage_record',
-      kind,
-      model,
-      input_tokens: inputTokens,
-      output_tokens: outputTokens,
-      num_model_requests: 1,
-      cost_usd: usageCost(model, inputTokens, outputTokens),
-      created_at: nowEpoch(req.occurredAt),
-    },
-    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
-    actor: { kind: 'agent' },
-  }, req.root);
-}
 
-// ── cursor pagination (after/limit + has_more, vendor-faithful list envelope) ────────────
-// OpenAI list endpoints page by an opaque cursor: `after=<id>` returns items AFTER that id and
-// `limit` (default 20, capped 100) caps the page; the envelope carries has_more/first_id/last_id.
-function paginate(items: Array<Record<string, unknown>>, rawPath: string): Record<string, unknown> {
-  const qIdx = rawPath.indexOf('?');
-  const qs = new URLSearchParams(qIdx >= 0 ? rawPath.slice(qIdx + 1) : '');
-  const after = qs.get('after');
-  let limit = Number(qs.get('limit'));
-  if (!Number.isInteger(limit) || limit < 1) limit = 20;
-  if (limit > 100) limit = 100;
-  let start = 0;
-  if (after) {
-    const i = items.findIndex((it) => it.id === after);
-    start = i >= 0 ? i + 1 : items.length; // unknown cursor → empty page (vendor returns nothing after end)
-  }
-  const page = items.slice(start, start + limit);
-  const hasMore = start + limit < items.length;
-  return { object: 'list', data: page, has_more: hasMore, first_id: page[0]?.id ?? null, last_id: page[page.length - 1]?.id ?? null };
-}
+// ── Usage and costs (computed over the recorded usage rows) ─────────────────────────────
+// The vendor's Usage and Costs APIs return time buckets from `start_time` (to `end_time` or now), each
+// `bucket_width` wide (Costs: only `1d`), `limit` buckets a page (Usage `1d`: 7 by default, at most 31;
+// `1h`: 24, 168; `1m`: 60, 1440; Costs: 7, 180), with `next_page` when more remain; a bucket holds one
+// result over its window, or one per group when `group_by` names `model` (Usage) or `line_item` (Costs)
+// (https://platform.openai.com/docs/api-reference/usage/completions,
+// https://platform.openai.com/docs/api-reference/usage/costs). The twin records a usage row per billable
+// inference call (semantics/shared.ts recordUsage) and aggregates them here: nothing is hardcoded.
+/** The query a report answers: its window, bucket width, page size, where the page starts, and its groups. */
+export type ReportQuery = { start: number; end: number; width: number; limit: number; from: number; groupBy: string[] };
+
+const WIDTHS: Record<string, { seconds: number; limit: number; max: number }> = {
+  '1m': { seconds: 60, limit: 60, max: 1440 },
+  '1h': { seconds: 3600, limit: 24, max: 168 },
+  '1d': { seconds: 86400, limit: 7, max: 31 },
+};
 
-// ── 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 report's query from its parameters; Costs buckets by day only and pages up to 180 of them. */
+export function reportQuery(params: Record<string, unknown>, now: number, costs: boolean): ReportQuery {
+  const width = WIDTHS[String(params.bucket_width ?? '1d')] ?? WIDTHS['1d']!;
+  const max = costs ? 180 : width.max;
+  const asked = Number(params.limit);
+  const limit = Number.isInteger(asked) && asked >= 1 ? Math.min(asked, max) : width.limit;
+  const start = Number(params.start_time);
+  const end = params.end_time !== undefined ? Number(params.end_time) : now;
+  const page = /^page_(\d+)$/.exec(String(params.page ?? ''));
+  const groups = params.group_by;
+  return { start, end, width: width.seconds, limit, from: page ? Number(page[1]) : start, groupBy: (Array.isArray(groups) ? groups : groups === undefined ? [] : [groups]).map(String) };
+}
+
+/** Buckets of one page of the query, each holding `results(rows in its window)`. */
+export function bucketed(records: Array<Record<string, unknown>>, q: ReportQuery, results: (rows: Array<Record<string, unknown>>, at: number, until: number) => unknown[]): Record<string, unknown> {
+  const data: unknown[] = [];
+  let at = q.from;
+  while (at < q.end && data.length < q.limit) {
+    const until = Math.min(at + q.width, q.end);
+    data.push({ object: 'bucket', start_time: at, end_time: until, results: results(records.filter((r) => Number(r.created_at) >= at && Number(r.created_at) < until), at, until) });
+    at = until;
+  }
+  return { object: 'page', data, has_more: at < q.end, next_page: at < q.end ? `page_${at}` : null };
+}
+
+/** Rows grouped by `key` when grouping by it, else all in one group keyed null; none when there are no rows. */
+function grouped(rows: Array<Record<string, unknown>>, by: string | null): Array<[string | null, Array<Record<string, unknown>>]> {
+  const out = new Map<string | null, Array<Record<string, unknown>>>();
+  for (const r of rows) {
+    const k = by === null ? null : String(r[by]);
+    out.set(k, [...(out.get(k) ?? []), r]);
+  }
+  return [...out.entries()].sort((a, b) => (String(a[0]) < String(b[0]) ? -1 : 1));
+}
+
+/** What each usage kind's result counts, and the object it answers as (the spec's Usage*Result schemas;
+ *  https://platform.openai.com/docs/api-reference/usage). A result names the grouping it answers (model, and for images
+ *  their size and source) and null for the groupings not asked for. */
+const USAGE_RESULTS: Record<string, { object: string; count: (rows: Array<Record<string, unknown>>) => Record<string, unknown>; by?: string[] }> = {
+  completions: {
+    object: 'organization.usage.completions.result',
+    // the twin caches nothing and hears, sees and speaks nothing: every token is uncached text
+    count: (rs) => {
+      const input = sum(rs, 'input_tokens');
+      const output = sum(rs, 'output_tokens');
+      return { input_tokens: input, input_cached_tokens: 0, input_cache_write_tokens: 0, input_uncached_tokens: input, output_tokens: output, input_text_tokens: input, output_text_tokens: output, input_cached_text_tokens: 0, input_audio_tokens: 0, input_cached_audio_tokens: 0, output_audio_tokens: 0, input_image_tokens: 0, input_cached_image_tokens: 0, output_image_tokens: 0, num_model_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null, batch: null, service_tier: null };
+    },
+  },
+  embeddings: { object: 'organization.usage.embeddings.result', count: (rs) => ({ input_tokens: sum(rs, 'input_tokens'), num_model_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null }) },
+  moderations: { object: 'organization.usage.moderations.result', count: (rs) => ({ input_tokens: sum(rs, 'input_tokens'), num_model_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null }) },
+  audio_speeches: { object: 'organization.usage.audio_speeches.result', count: (rs) => ({ characters: sum(rs, 'characters'), num_model_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null }) },
+  audio_transcriptions: { object: 'organization.usage.audio_transcriptions.result', count: (rs) => ({ seconds: sum(rs, 'seconds'), num_model_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null }) },
+  images: { object: 'organization.usage.images.result', by: ['size', 'source'], count: (rs) => ({ images: sum(rs, 'images'), num_model_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null }) },
+  code_interpreter_sessions: { object: 'organization.usage.code_interpreter_sessions.result', count: (rs) => ({ num_sessions: sum(rs, 'num_sessions') }) },
+  file_search_calls: { object: 'organization.usage.file_searches.result', count: (rs) => ({ num_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null, vector_store_id: null }) },
+  web_search_calls: { object: 'organization.usage.web_searches.result', count: (rs) => ({ num_model_requests: sum(rs, 'num_model_requests'), num_requests: sum(rs, 'num_model_requests'), user_id: null, api_key_id: null, context_level: null }) },
+};
+const sum = (rows: Array<Record<string, unknown>>, k: string): number => rows.reduce((n, r) => n + Number(r[k] ?? 0), 0);
+/** The kinds whose results name a model. */
+const MODELLESS = new Set(['code_interpreter_sessions', 'file_search_calls']);
+
+/** The usage report over the recorded usage rows, for one kind ('completions', 'embeddings', …). */
+export function usageReport(records: Array<Record<string, unknown>>, kind: string | undefined, q: ReportQuery): Record<string, unknown> {
+  const spec = USAGE_RESULTS[kind ?? 'completions'] ?? USAGE_RESULTS.completions!;
+  const byModel = q.groupBy.includes('model') && !MODELLESS.has(kind ?? '');
+  const extra = (spec.by ?? []).filter((k) => q.groupBy.includes(k));
+  return bucketed(records.filter((r) => kind === undefined || r.kind === kind), q, (rows) => groupedBy(rows, [...(byModel ? ['model'] : []), ...extra]).map(([key, rs]) => ({
+    object: spec.object,
+    ...spec.count(rs),
+    project_id: null,
+    ...(MODELLESS.has(kind ?? '') ? {} : { model: byModel ? key.model : null }),
+    ...(spec.by ? Object.fromEntries(spec.by.map((k) => [k, extra.includes(k) ? key[k] : null])) : {}),
+  })));
+}
+
+/** Rows grouped by the values of `keys`, in key order; one group of all rows when no key; none when there are no rows. */
+function groupedBy(rows: Array<Record<string, unknown>>, keys: string[]): Array<[Record<string, unknown>, Array<Record<string, unknown>>]> {
+  const out = new Map<string, [Record<string, unknown>, Array<Record<string, unknown>>]>();
+  for (const r of rows) {
+    const key = Object.fromEntries(keys.map((k) => [k, r[k] === undefined ? null : String(r[k])]));
+    const id = JSON.stringify(key);
+    out.set(id, [key, [...(out.get(id)?.[1] ?? []), r]]);
+  }
+  return [...out.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1)).map(([, v]) => v);
+}
+/** The costs report: the recorded usage priced per model, per bucket, by line item (usage kind) when grouped so. */
+export function costsReport(records: Array<Record<string, unknown>>, q: ReportQuery): Record<string, unknown> {
+  const byLine = q.groupBy.includes('line_item');
+  return bucketed(records, q, (rows) => grouped(rows, byLine ? 'kind' : null).map(([line, rs]) => ({
+    object: 'organization.costs.result',
+    amount: { value: rs.reduce((n, r) => n + Number(r.cost_usd ?? 0), 0), currency: 'usd' },
+    line_item: line, project_id: null, api_key_id: null, quantity: null, quantity_unit: null,
+  })));
 }
 
 const SYSTEM_FINGERPRINT = 'fp_twin_stub';
@@ -294,118 +243,155 @@ type ChatArgs = {
   seed?: number;
   logitBias?: Record<string, number>;
   prediction?: string;
+  /** the reasoning effort a reasoning model spends (the request's `reasoning_effort`, else the default) */
+  reasoningEffort?: string;
   store: boolean;
   metadata?: Record<string, unknown>;
   /** modalities: ['text'] (default) or ['text','audio'] — audio asks for a spoken output. */
   audioOutput?: { voice: string; format: string };
 };
 
-function validateChat(params: Record<string, unknown>): { args: ChatArgs } | { error: OpenAIResponseEnvelope } {
+/** The roles a chat message may have (the spec's ChatCompletionRequestMessage variants). */
+const ROLES = new Set(['developer', 'system', 'user', 'assistant', 'tool', 'function']);
+
+/** OpenAI's refusal of a chat message whose role is not one of the request message types
+ *  (https://platform.openai.com/docs/api-reference/chat/create, `messages`). */
+function invalidRole(): { error: OpenAIResponseEnvelope } {
+  return { error: invalidRequest("each message must have a valid 'role'", 'messages') };
+}
+
+type ChatRefusal = { error: OpenAIResponseEnvelope };
+// The chat options below are OpenAI's (https://platform.openai.com/docs/api-reference/chat/create); each
+// parser answers the option's value or OpenAI's refusal of it.
+
+/** `n`: how many choices to generate, at least one. */
+function chatN(raw: unknown): number | ChatRefusal {
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 1 ? n : { error: invalidRequest("'n' must be an integer >= 1", 'n') };
+}
+
+/** `max_completion_tokens` (or the legacy `max_tokens`): a cap of at least one token. */
+function chatMaxTokens(raw: unknown): number | ChatRefusal {
+  const max = Number(raw);
+  return Number.isInteger(max) && max >= 1 ? max : { error: invalidRequest("'max_tokens' must be an integer >= 1", 'max_tokens') };
+}
+
+/** `stop`: one sequence or a list of them. */
+function chatStop(raw: unknown): string[] | ChatRefusal {
+  if (typeof raw === 'string') return [raw];
+  return Array.isArray(raw) ? (raw as string[]) : { error: invalidRequest("'stop' must be a string or array of strings", 'stop') };
+}
+
+/** `tool_choice`: 'auto' | 'none' | 'required' | { type:'function', function:{ name } }. */
+function chatToolChoice(raw: unknown): ToolChoice | ChatRefusal {
+  if (raw === 'auto' || raw === 'none' || raw === 'required') return raw;
+  if (!raw || typeof raw !== 'object') return { error: invalidRequest("'tool_choice' must be 'auto'/'none'/'required' or a named function", 'tool_choice') };
+  const fn = (raw as { function?: { name?: unknown } }).function;
+  return typeof fn?.name === 'string' ? { name: fn.name } : { error: invalidRequest("invalid 'tool_choice' — named choice requires function.name", 'tool_choice') };
+}
+
+/** OpenAI's refusal of a `response_format` whose type is none of text, json_object and json_schema. */
+function badResponseFormat(): ChatRefusal {
+  return { error: invalidRequest("'response_format.type' must be 'text', 'json_object', or 'json_schema'", 'response_format') };
+}
+
+/** `top_logprobs`: 0 to 20 alternatives per token, only with `logprobs: true`. */
+function chatTopLogprobs(raw: unknown, logprobs: boolean): number | ChatRefusal {
+  const top = Number(raw);
+  if (!Number.isInteger(top) || top < 0 || top > 20) return { error: invalidRequest("'top_logprobs' must be an integer between 0 and 20", 'top_logprobs') };
+  return logprobs ? top : { error: invalidRequest("'top_logprobs' requires 'logprobs' to be true", 'top_logprobs') };
+}
+
+/** `seed`: an integer for best-effort reproducible sampling. */
+function chatSeed(raw: unknown): number | ChatRefusal {
+  const seed = Number(raw);
+  return Number.isInteger(seed) ? seed : { error: invalidRequest("'seed' must be an integer", 'seed') };
+}
+
+/** `logit_bias`: token ids mapped to a bias from -100 to 100. */
+function chatLogitBias(raw: unknown): Record<string, number> | ChatRefusal {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { error: invalidRequest("'logit_bias' must be an object mapping token ids to bias values", 'logit_bias') };
+  const bias: Record<string, number> = {};
+  for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+    const num = Number(v);
+    if (!Number.isFinite(num) || num < -100 || num > 100) return { error: invalidRequest("each 'logit_bias' value must be a number between -100 and 100", 'logit_bias') };
+    bias[k] = num;
+  }
+  return bias;
+}
+
+/** `prediction`: predicted output, `{ type: 'content', content }`, its content a string or text parts. */
+function chatPrediction(raw: unknown): string | ChatRefusal {
+  const p = raw as { type?: unknown; content?: unknown } | undefined;
+  if (!p || typeof p !== 'object' || p.type !== 'content' || p.content === undefined) return { error: invalidRequest("'prediction' must be an object with type 'content' and a content field", 'prediction') };
+  if (typeof p.content === 'string') return p.content;
+  return Array.isArray(p.content) ? p.content.map((c) => (c && typeof c === 'object' ? String((c as { text?: unknown }).text ?? '') : String(c))).join('') : '';
+}
+
+/** `modalities` with `audio`: a spoken answer needs `audio: { voice, format }` (the vendor's rule). The twin
+ *  can't synthesize speech, so the returned bytes are a labeled stub; the envelope is faithful. */
+function chatAudio(modalities: unknown, audio: unknown): { voice: string; format: string } | ChatRefusal | undefined {
+  if (!Array.isArray(modalities)) return { error: invalidRequest("'modalities' must be an array", 'modalities') };
+  if (!(modalities as unknown[]).includes('audio')) return undefined;
+  const a = audio as { voice?: unknown; format?: unknown } | undefined;
+  if (!a || typeof a !== 'object' || typeof a.voice !== 'string' || typeof a.format !== 'string') return { error: invalidRequest("'audio' with a 'voice' and 'format' is required when 'modalities' includes 'audio'", 'audio') };
+  return { voice: a.voice, format: a.format };
+}
+
+export function validateChat(params: Record<string, unknown>): { args: ChatArgs } | { error: OpenAIResponseEnvelope } {
   if (params.model === undefined || params.model === '') return { error: invalidRequest("you must provide a model parameter", 'model') };
   if (typeof params.model !== 'string') return { error: invalidRequest("'model' must be a string", 'model') };
   if (!Array.isArray(params.messages)) return { error: invalidRequest("you must provide a messages parameter", 'messages') };
   if (params.messages.length === 0) return { error: invalidRequest("[] is too short - 'messages'", 'messages') };
   const messages = params.messages as ChatMessageParam[];
-  for (const m of messages) {
-    if (!m || typeof m !== 'object' || typeof m.role !== 'string') {
-      return { error: invalidRequest("each message must have a valid 'role'", 'messages') };
-    }
-  }
-  let n = 1;
-  if (params.n !== undefined) {
-    n = Number(params.n);
-    if (!Number.isInteger(n) || n < 1) return { error: invalidRequest("'n' must be an integer >= 1", 'n') };
-  }
+  if (messages.some((m) => !m || typeof m !== 'object' || !ROLES.has(String(m.role)))) return invalidRole();
+  // Each option the request may carry is parsed by its own function (below): a function returns the
+  // option's value, or OpenAI's refusal of it as `{ error }`.
+  const n = params.n === undefined ? 1 : chatN(params.n);
+  if (typeof n !== 'number') return n;
   // max_completion_tokens is the current name; max_tokens is the legacy alias.
   const maxRaw = params.max_completion_tokens ?? params.max_tokens;
-  let maxTokens: number | undefined;
-  if (maxRaw !== undefined) {
-    maxTokens = Number(maxRaw);
-    if (!Number.isInteger(maxTokens) || maxTokens < 1) return { error: invalidRequest("'max_tokens' must be an integer >= 1", 'max_tokens') };
-  }
-  const stopRaw = params.stop;
-  let stop: string[] | undefined;
-  if (stopRaw !== undefined) {
-    if (typeof stopRaw === 'string') stop = [stopRaw];
-    else if (Array.isArray(stopRaw)) stop = stopRaw as string[];
-    else return { error: invalidRequest("'stop' must be a string or array of strings", 'stop') };
-  }
-  // tool_choice: 'auto' | 'none' | 'required' | { type:'function', function:{ name } }.
-  let toolChoice: ToolChoice | undefined;
-  const tcRaw = params.tool_choice;
-  if (tcRaw !== undefined) {
-    if (tcRaw === 'auto' || tcRaw === 'none' || tcRaw === 'required') toolChoice = tcRaw;
-    else if (tcRaw && typeof tcRaw === 'object') {
-      const fn = (tcRaw as { function?: { name?: unknown } }).function;
-      if (typeof fn?.name === 'string') toolChoice = { name: fn.name };
-      else return { error: invalidRequest("invalid 'tool_choice' — named choice requires function.name", 'tool_choice') };
-    } else return { error: invalidRequest("'tool_choice' must be 'auto'/'none'/'required' or a named function", 'tool_choice') };
-  }
+  const maxTokens = maxRaw === undefined ? undefined : chatMaxTokens(maxRaw);
+  if (typeof maxTokens === 'object') return maxTokens;
+  const stop = params.stop === undefined ? undefined : chatStop(params.stop);
+  if (stop && !Array.isArray(stop)) return stop;
+  const toolChoice = params.tool_choice === undefined ? undefined : chatToolChoice(params.tool_choice);
+  if (toolChoice && typeof toolChoice === 'object' && 'error' in toolChoice) return toolChoice;
   // response_format: { type:'text' | 'json_object' | 'json_schema', json_schema? }.
   let responseFormat: ResponseFormat = { kind: 'text' };
   const rf = params.response_format;
   if (rf !== undefined) {
     if (!rf || typeof rf !== 'object') return { error: invalidRequest("'response_format' must be an object", 'response_format') };
-    const t = (rf as { type?: unknown }).type;
-    if (t === 'json_object') responseFormat = { kind: 'json_object' };
-    else if (t === 'json_schema') responseFormat = { kind: 'json_schema', schema: (rf as { json_schema?: unknown }).json_schema };
-    else if (t === 'text' || t === undefined) responseFormat = { kind: 'text' };
-    else return { error: invalidRequest("'response_format.type' must be 'text', 'json_object', or 'json_schema'", 'response_format') };
+    const t = (rf as { type?: unknown }).type ?? 'text';
+    const format: ResponseFormat | undefined = t === 'json_schema' ? { kind: 'json_schema', schema: (rf as { json_schema?: unknown }).json_schema } : t === 'json_object' || t === 'text' ? { kind: t } : undefined;
+    if (!format) return badResponseFormat();
+    responseFormat = format;
   }
   // stream_options.include_usage → emit a final usage-only chunk in the stream.
   const so = params.stream_options as { include_usage?: unknown } | undefined;
   const includeUsage = !!(so && typeof so === 'object' && so.include_usage === true);
   // logprobs (boolean) + top_logprobs (0..20, requires logprobs:true) → per-token logprob detail.
   const logprobs = params.logprobs === true;
-  let topLogprobs: number | undefined;
-  if (params.top_logprobs !== undefined) {
-    topLogprobs = Number(params.top_logprobs);
-    if (!Number.isInteger(topLogprobs) || topLogprobs < 0 || topLogprobs > 20) return { error: invalidRequest("'top_logprobs' must be an integer between 0 and 20", 'top_logprobs') };
-    if (!logprobs) return { error: invalidRequest("'top_logprobs' requires 'logprobs' to be true", 'top_logprobs') };
-  }
+  const topLogprobs = params.top_logprobs === undefined ? undefined : chatTopLogprobs(params.top_logprobs, logprobs);
+  if (typeof topLogprobs === 'object') return topLogprobs;
   // seed → reproducible sampling (the twin is already deterministic; we echo it via fingerprint).
-  let seed: number | undefined;
-  if (params.seed !== undefined) {
-    seed = Number(params.seed);
-    if (!Number.isInteger(seed)) return { error: invalidRequest("'seed' must be an integer", 'seed') };
-  }
-  // logit_bias → a map of token-id → bias in [-100, 100]; must be an object of numbers.
-  let logitBias: Record<string, number> | undefined;
-  if (params.logit_bias !== undefined) {
-    const lb = params.logit_bias;
-    if (!lb || typeof lb !== 'object' || Array.isArray(lb)) return { error: invalidRequest("'logit_bias' must be an object mapping token ids to bias values", 'logit_bias') };
-    logitBias = {};
-    for (const [k, v] of Object.entries(lb as Record<string, unknown>)) {
-      const num = Number(v);
-      if (!Number.isFinite(num) || num < -100 || num > 100) return { error: invalidRequest("each 'logit_bias' value must be a number between -100 and 100", 'logit_bias') };
-      logitBias[k] = num;
-    }
-  }
+  const seed = params.seed === undefined ? undefined : chatSeed(params.seed);
+  if (typeof seed === 'object') return seed;
+  // logit_bias → a map of token-id → bias in [-100, 100].
+  const logitBias = params.logit_bias === undefined ? undefined : chatLogitBias(params.logit_bias);
+  if (logitBias && 'error' in logitBias) return logitBias as { error: OpenAIResponseEnvelope };
   // prediction → predicted outputs ({ type:'content', content }); content may be a string or parts.
-  let prediction: string | undefined;
-  if (params.prediction !== undefined) {
-    const p = params.prediction as { type?: unknown; content?: unknown } | undefined;
-    if (!p || typeof p !== 'object' || p.type !== 'content' || p.content === undefined) return { error: invalidRequest("'prediction' must be an object with type 'content' and a content field", 'prediction') };
-    prediction = typeof p.content === 'string'
-      ? p.content
-      : Array.isArray(p.content) ? p.content.map((c) => (c && typeof c === 'object' ? String((c as { text?: unknown }).text ?? '') : String(c))).join('') : '';
-  }
-  // modalities + audio → audio output. modalities is ['text'] (default) or includes 'audio'; when
-  // it does, `audio: { voice, format }` is REQUIRED (vendor rule). The twin can't synthesize speech,
-  // so the returned bytes are a labeled stub — the envelope (message.audio shape) is faithful.
-  let audioOutput: { voice: string; format: string } | undefined;
-  const modalities = params.modalities;
-  if (modalities !== undefined) {
-    if (!Array.isArray(modalities)) return { error: invalidRequest("'modalities' must be an array", 'modalities') };
-    if ((modalities as unknown[]).includes('audio')) {
-      const a = params.audio as { voice?: unknown; format?: unknown } | undefined;
-      if (!a || typeof a !== 'object' || typeof a.voice !== 'string' || typeof a.format !== 'string') {
-        return { error: invalidRequest("'audio' with a 'voice' and 'format' is required when 'modalities' includes 'audio'", 'audio') };
-      }
-      audioOutput = { voice: a.voice, format: a.format };
-    }
-  }
+  const prediction = params.prediction === undefined ? undefined : chatPrediction(params.prediction);
+  if (typeof prediction === 'object') return prediction;
+  // modalities + audio → audio output.
+  const audioOutput = params.modalities === undefined ? undefined : chatAudio(params.modalities, params.audio);
+  if (audioOutput && 'error' in audioOutput) return audioOutput;
   // store + metadata → stored completions (retrievable later); metadata must be a flat object.
+  // a model refuses what its page says it does not take (openai-models.ts); a reasoning model reasons with the effort
+  // asked for, else the spec's default
+  const refused = unsupported(params.model, { effort: params.reasoning_effort, effortParam: 'reasoning_effort', temperature: params.temperature, top_p: params.top_p, logprobs: params.logprobs, chatTools: params.tools ?? params.functions });
+  if (refused) return { error: invalidRequest(refused.message, refused.param, 'unsupported_value') };
+  const reasoningEffort = typeof params.reasoning_effort === 'string' ? params.reasoning_effort : reasons(params.model) ? DEFAULT_EFFORT : undefined;
   const store = params.store === true;
   let metadata: Record<string, unknown> | undefined;
   if (params.metadata !== undefined) {
@@ -429,15 +415,51 @@ function validateChat(params: Record<string, unknown>): { args: ChatArgs } | { e
       logprobs,
       ...(topLogprobs !== undefined ? { topLogprobs } : {}),
       ...(seed !== undefined ? { seed } : {}),
-      ...(logitBias !== undefined ? { logitBias } : {}),
+      ...(logitBias !== undefined ? { logitBias: logitBias as Record<string, number> } : {}),
       ...(prediction !== undefined ? { prediction } : {}),
+      ...(reasoningEffort !== undefined ? { reasoningEffort } : {}),
       store,
       ...(metadata !== undefined ? { metadata } : {}),
-      ...(audioOutput !== undefined ? { audioOutput } : {}),
+      ...(audioOutput !== undefined ? { audioOutput: audioOutput as { voice: string; format: string } } : {}),
     },
   };
 }
 
+/** The text cut at the EARLIEST-occurring stop sequence across the whole `stop` list, not whichever is
+ *  listed first: the real vendor's "stop generation at the first hit", regardless of array order. */
+function stoppedAt(text: string, stops: string[]): string {
+  let stopAt = -1;
+  for (const s of stops) {
+    if (!s) continue;
+    const i = text.indexOf(s);
+    if (i >= 0 && (stopAt < 0 || i < stopAt)) stopAt = i;
+  }
+  return stopAt >= 0 ? text.slice(0, stopAt) : text;
+}
+
+/** The text cut to a `max_completion_tokens` cap (about four characters a token); the choice finishes `length`. */
+function cutAt(text: string, maxTokens: number): string {
+  return text.slice(0, maxTokens * 4);
+}
+
+/** modalities:['audio'] → the assistant replies with an audio object (content is null, the text lives in
+ *  audio.transcript). The twin can't synthesize speech, so `data` is a labeled-stub base64 string; the shape
+ *  (id/data/transcript/expires_at) is vendor-faithful. */
+function audioChoice(args: ChatArgs, idx: number, transcript: string, logprobs: ChatChoice['logprobs'], finish: ChatChoice['finish_reason']): { choice: ChatChoice; completionTokens: number } {
+  const voice = args.audioOutput!;
+  const stubBytes = `[twin-stub:${args.model}] no real audio synthesis — voice=${voice.voice} format=${voice.format}; transcript: ${transcript}`;
+  const audio = {
+    id: `audio-twin-${stableSuffix(args)}-${idx}`,
+    data: Buffer.from(stubBytes, 'utf8').toString('base64'),
+    transcript,
+    expires_at: nowEpoch() + 3600,
+  };
+  return {
+    choice: { index: idx, message: { role: 'assistant', content: null, refusal: null, audio }, logprobs, finish_reason: finish },
+    completionTokens: estimateTokens(transcript),
+  };
+}
+
 // Build ONE deterministic stub choice (index `idx`). Honors tools/functions (tool_calls +
 // finish_reason tool_calls), tool_choice (none/required/named), parallel_tool_calls,
 // response_format (json_object/json_schema), max_tokens, and stop sequences.
@@ -448,28 +470,21 @@ function buildChoice(args: ChatArgs, idx: number): { choice: ChatChoice; complet
   // forces it (even when the heuristic otherwise would not); 'auto'/default calls when tools exist.
   const forbidTools = args.toolChoice === 'none';
   const forcedName = typeof args.toolChoice === 'object' ? args.toolChoice.name : undefined;
-  const wantTool = hasTools && !forbidTools;
+  // a model answers a tool's result in words unless the caller insists on another call; one that always
+  // called a tool would never let an app's tool loop end
+  const answeringTool = ['tool', 'function'].includes(String(args.messages.at(-1)?.role));
+  const wantTool = hasTools && !forbidTools && (!answeringTool || forcedName !== undefined || args.toolChoice === 'required');
   if (wantTool) {
     // parallel_tool_calls (default true) → the stub may emit one call per provided tool; a named
     // choice or parallel:false collapses to a single call.
-    const list = Array.isArray(toolsSource) ? toolsSource : [];
-    const calls: ChatToolCall[] = [];
-    if (forcedName || args.parallelToolCalls === false) {
-      const tc = stubToolCall(toolsSource, idx + 1, forcedName);
-      if (tc) calls.push(tc);
-    } else {
-      for (let t = 0; t < list.length; t++) {
-        const tc = stubToolCall([list[t]], idx * 100 + t + 1);
-        if (tc) calls.push(tc);
-      }
-    }
-    if (calls.length) {
-      const completionTokens = estimateTokens(JSON.stringify(calls));
-      return {
-        choice: { index: idx, message: { role: 'assistant', content: null, tool_calls: calls, refusal: null }, logprobs: null, finish_reason: 'tool_calls' },
-        completionTokens,
-      };
-    }
+    // (the tools are there, so each call is made)
+    const calls: ChatToolCall[] = forcedName || args.parallelToolCalls === false
+      ? [stubToolCall(toolsSource, idx + 1, forcedName, lastUserText(args.messages))!]
+      : (toolsSource as unknown[]).map((tool, t) => stubToolCall([tool], idx * 100 + t + 1, undefined, lastUserText(args.messages))!);
+    return {
+      choice: { index: idx, message: { role: 'assistant', content: null, tool_calls: calls, refusal: null }, logprobs: null, finish_reason: 'tool_calls' },
+      completionTokens: estimateTokens(JSON.stringify(calls)),
+    };
   }
   // json_mode: when response_format requests json_object/json_schema, the content is valid JSON.
   // prediction (predicted outputs): a real model uses the prediction to speed decoding but still
@@ -482,78 +497,57 @@ function buildChoice(args: ChatArgs, idx: number): { choice: ChatChoice; complet
       : args.responseFormat.kind === 'json_schema'
         ? stubJsonObject(args.messages, args.model, args.responseFormat.schema)
         : stubAssistantText(args.messages, args.model);
-  let finish: ChatChoice['finish_reason'] = 'stop';
-  // Truncate at the EARLIEST-occurring stop sequence across the whole `stop` list — not
-  // whichever sequence happens to be listed first — so multi-element `stop` arrays match the
-  // real vendor's "stop generation at the first hit" semantics regardless of array order.
-  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);
-  if (args.maxTokens !== undefined && estimateTokens(text) > args.maxTokens) {
-    text = text.slice(0, args.maxTokens * 4);
-    finish = 'length';
-  }
+  if (args.stop) text = stoppedAt(text, args.stop);
+  const capped = args.maxTokens !== undefined && estimateTokens(text) > args.maxTokens;
+  if (capped) text = cutAt(text, args.maxTokens!);
+  const finish: ChatChoice['finish_reason'] = capped ? 'length' : 'stop';
   const logprobs = args.logprobs ? buildLogprobs(text, args.topLogprobs ?? 0) : null;
-  // modalities:['audio'] → the assistant replies with an audio object (content is null, the text
-  // lives in audio.transcript). The twin can't synthesize speech, so `data` is a labeled-stub
-  // base64 string; the shape (id/data/transcript/expires_at) is vendor-faithful.
-  if (args.audioOutput) {
-    const transcript = text;
-    const stubBytes = `[twin-stub:${args.model}] no real audio synthesis — voice=${args.audioOutput.voice} format=${args.audioOutput.format}; transcript: ${transcript}`;
-    const audio = {
-      id: `audio-twin-${stableSuffix(args)}-${idx}`,
-      data: Buffer.from(stubBytes, 'utf8').toString('base64'),
-      transcript,
-      expires_at: nowEpoch() + 3600,
-    };
-    return {
-      choice: { index: idx, message: { role: 'assistant', content: null, refusal: null, audio }, logprobs, finish_reason: finish },
-      completionTokens: estimateTokens(transcript),
-    };
-  }
+  if (args.audioOutput) return audioChoice(args, idx, text, logprobs, finish);
   return {
-    choice: { index: idx, message: { role: 'assistant', content: text, refusal: null }, logprobs, finish_reason: finish },
+    // a text answer carries its annotations (none: the twin cites no web source), as OpenAI's does
+    // (https://platform.openai.com/docs/api-reference/chat/object, `choices[].message.annotations`)
+    choice: { index: idx, message: { role: 'assistant', content: text, refusal: null, annotations: [] }, logprobs, finish_reason: finish },
     completionTokens: estimateTokens(text),
   };
 }
 
-function buildChatCompletion(args: ChatArgs, occurredAt?: string, scenarioEngine?: OpenAIScenarioEngine): ChatCompletion {
+/** Predicted-output accounting: the twin echoes the prediction, so every predicted token is "accepted". */
+function predictionUsage(prediction: string): Pick<NonNullable<ChatUsage['completion_tokens_details']>, 'accepted_prediction_tokens' | 'rejected_prediction_tokens'> {
+  return { accepted_prediction_tokens: estimateTokens(prediction), rejected_prediction_tokens: 0 };
+}
+
+export function buildChatCompletion(args: ChatArgs, occurredAt?: string, decision?: ScenarioDecision): ChatCompletion {
   const promptTokens = countPromptTokens(args.messages);
-  // Scenario handlers: a fired handler scripts the assistant turn; a miss teaches in the stub.
-  let scripted: ScriptedResult | null = null;
-  let missTeach = '';
-  if (scenarioEngine) {
-    const decision = scenarioEngine.next({ model: args.model, messages: args.messages, tools: args.tools, maxTokens: args.maxTokens });
-    if (decision.kind === 'handler') scripted = realizeOpenAIRespond(decision.respond as OpenAIScenarioRespond);
-    else missTeach = `\n[twin-scenario miss — no handler matched. Author one in the world dir's handlers/openai.json (GET /twin explains; GET /twin/scenario lists handlers + misses). Features seen: ${JSON.stringify(decision.miss.features)}]`;
-  }
+  // Scenario handlers: a fired handler scripts the assistant turn; a miss teaches in the stub. The
+  // decision was made (and any fault honored) by the request handler through the engine's serve(); this
+  // builder only realizes it — a status fault never reaches here.
+  const turn = decision && scenarioTurn(decision);
   const choices: ChatChoice[] = [];
   let completionTokens = 0;
   for (let i = 0; i < args.n; i++) {
-    if (scripted) {
-      const message = scripted.toolCalls.length
-        ? { role: 'assistant' as const, content: scripted.text, tool_calls: scripted.toolCalls, refusal: null }
-        : { role: 'assistant' as const, content: scripted.text ?? '', refusal: null };
-      const ct = estimateTokens(JSON.stringify(scripted.toolCalls.length ? scripted.toolCalls : scripted.text ?? ''));
-      choices.push({ index: i, message, logprobs: null, finish_reason: scripted.finishReason });
-      completionTokens += ct;
-      continue;
-    }
-    const { choice, completionTokens: ct } = buildChoice(args, i);
-    if (missTeach && typeof choice.message.content === 'string') choice.message.content += missTeach;
+    const { choice, completionTokens: ct } = turn?.scripted ? scriptedChoice(turn.scripted, i) : buildChoice(args, i);
+    if (turn?.missTeach && typeof choice.message.content === 'string') choice.message.content += turn.missTeach;
     choices.push(choice);
     completionTokens += ct;
   }
-  const usage: ChatUsage = { prompt_tokens: promptTokens, completion_tokens: completionTokens, total_tokens: promptTokens + completionTokens };
+  // usage breaks its counts down as OpenAI's does (https://platform.openai.com/docs/api-reference/chat/object,
+  // `usage.prompt_tokens_details`, `usage.completion_tokens_details`): the twin caches nothing and reasons and
+  // speaks nothing, so those are zero
+  const usage: ChatUsage = {
+    prompt_tokens: promptTokens, completion_tokens: completionTokens, total_tokens: promptTokens + completionTokens,
+    prompt_tokens_details: { cached_tokens: 0, audio_tokens: 0 },
+    completion_tokens_details: { reasoning_tokens: 0, audio_tokens: 0, accepted_prediction_tokens: 0, rejected_prediction_tokens: 0 },
+  };
   // prediction (predicted outputs): real responses report how many predicted tokens were accepted
   // vs rejected. The twin echoes the prediction, so all predicted tokens are "accepted".
-  if (args.prediction !== undefined) {
-    const accepted = estimateTokens(args.prediction);
-    usage.completion_tokens_details = { accepted_prediction_tokens: accepted, rejected_prediction_tokens: 0 };
+  if (args.prediction !== undefined) usage.completion_tokens_details = { ...usage.completion_tokens_details!, ...predictionUsage(args.prediction) };
+  // a reasoning model's reasoning tokens are billed as output tokens (https://developers.openai.com/api/docs/guides/reasoning:
+  // "they still occupy space in the model's context window and are billed as output tokens")
+  if (args.reasoningEffort !== undefined && reasons(args.model)) {
+    const spent = REASONING_BUDGET[args.reasoningEffort] ?? 0;
+    usage.completion_tokens += spent;
+    usage.total_tokens += spent;
+    usage.completion_tokens_details = { ...usage.completion_tokens_details!, reasoning_tokens: spent };
   }
   return {
     id: `chatcmpl-twin-${stableSuffix(args)}`,
@@ -563,27 +557,13 @@ function buildChatCompletion(args: ChatArgs, occurredAt?: string, scenarioEngine
     choices,
     usage,
     system_fingerprint: SYSTEM_FINGERPRINT,
+    // the tier that served the request: the standard one, which is what `auto` and `default` pick for a project
+    // not on Scale Tier (https://platform.openai.com/docs/api-reference/chat/object, `service_tier`)
+    service_tier: 'default',
     ...(args.metadata !== undefined ? { metadata: args.metadata } : {}),
   };
 }
 
-// Persist a stored chat completion (store:true) so it can be retrieved/listed/deleted later, and
-// keep the request messages for the /messages sub-resource (stored-completions input replay).
-async function storeChatCompletion(resp: ChatCompletion, args: ChatArgs, req: OpenAIRequest): Promise<void> {
-  const inputMessages = args.messages.map((m, i) => ({ id: `${resp.id}-msg-${i}`, role: m.role, content: typeof m.content === 'string' ? m.content : (m.content ?? null) }));
-  await applyTwinWrite(SERVICE, {
-    operation: 'chat_completion.create',
-    subjectType: 'chat_completion',
-    subjectId: resp.id,
-    fields: { ...resp, _stored: true, _input_messages: inputMessages },
-    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
-    actor: { kind: 'agent' },
-  }, req.root);
-}
-function storedChatView(r: Record<string, unknown>): Record<string, unknown> {
-  return { id: r.id, ...strip(r) };
-}
-
 // A deterministic id suffix from the request (so ids are stable + assertable, like the twin's
 // other deterministic outputs). Hash of the prompt text + model + seed (seed changes sampling,
 // so it changes the response id the way a real seed-distinct request does).
@@ -602,26 +582,30 @@ function chunkText(text: string): string[] {
   return out;
 }
 
+/** A streamed choice's tool calls: one tool_calls delta-pair per call, each carrying its own `index`
+ *  (parallel tool calls). */
+function streamToolCalls(calls: ChatToolCall[], idx: number, base: Record<string, unknown>, sink: SseSink): void {
+  calls.forEach((tc, tIdx) => {
+    sink({ data: { ...base, choices: [{ index: idx, delta: { tool_calls: [{ index: tIdx, id: tc.id, type: 'function', function: { name: tc.function.name, arguments: '' } }] }, logprobs: null, finish_reason: null }] } });
+    sink({ data: { ...base, choices: [{ index: idx, delta: { tool_calls: [{ index: tIdx, function: { arguments: tc.function.arguments } }] }, logprobs: null, finish_reason: null }] } });
+  });
+}
+
 /**
  * Emit the vendor-faithful Chat Completions streaming sequence into the injected sink (NO
  * sockets, NO setTimeout). Real order: a first chunk with `delta:{role:'assistant'}`, then
  * `delta:{content}` chunks (or tool_calls deltas), then a final chunk with `finish_reason`,
  * then `[DONE]`. Deterministic + synchronous so a collector can assert the full sequence.
  */
-export function streamChat(args: ChatArgs, sink: SseSink, occurredAt?: string, scenarioEngine?: OpenAIScenarioEngine): ChatCompletion {
-  const full = buildChatCompletion(args, occurredAt, scenarioEngine);
+export function streamChat(args: ChatArgs, sink: SseSink, occurredAt?: string, decision?: ScenarioDecision): ChatCompletion {
+  const full = buildChatCompletion(args, occurredAt, decision);
   const base = { id: full.id, object: 'chat.completion.chunk' as const, created: full.created, model: full.model, system_fingerprint: SYSTEM_FINGERPRINT };
   for (const choice of full.choices) {
     const idx = choice.index;
     // role chunk
     sink({ data: { ...base, choices: [{ index: idx, delta: { role: 'assistant', content: '' }, logprobs: null, finish_reason: null }] } });
-    if (choice.message.tool_calls && choice.message.tool_calls.length) {
-      // one tool_calls delta-pair per call, each carrying its own `index` (parallel tool calls).
-      choice.message.tool_calls.forEach((tc, tIdx) => {
-        sink({ data: { ...base, choices: [{ index: idx, delta: { tool_calls: [{ index: tIdx, id: tc.id, type: 'function', function: { name: tc.function.name, arguments: '' } }] }, logprobs: null, finish_reason: null }] } });
-        sink({ data: { ...base, choices: [{ index: idx, delta: { tool_calls: [{ index: tIdx, function: { arguments: tc.function.arguments } }] }, logprobs: null, finish_reason: null }] } });
-      });
-    } else {
+    if (choice.message.tool_calls && choice.message.tool_calls.length) streamToolCalls(choice.message.tool_calls, idx, base, sink);
+    else {
       for (const piece of chunkText(choice.message.content ?? '')) {
         sink({ data: { ...base, choices: [{ index: idx, delta: { content: piece }, logprobs: null, finish_reason: null }] } });
       }
@@ -637,7 +621,9 @@ export function streamChat(args: ChatArgs, sink: SseSink, occurredAt?: string, s
 }
 
 // ── Responses API ───────────────────────────────────────────────────────────────────────
-type ResponsesArgs = {
+export type ResponsesArgs = {
+  inputItems: Record<string, unknown>[];
+  instructions?: string;
   model: string;
   inputText: string;
   messages: ChatMessageParam[];
@@ -648,31 +634,61 @@ type ResponsesArgs = {
   reasoningEffort?: string;
   /** background:true → the response is created `queued` and processed asynchronously (poll + cancel). */
   background: boolean;
+  /** The caller's tools, as sent (Responses shape `{type:'function', name, parameters}`); the scenario reads their names. */
+  tools?: unknown;
+  /** max_output_tokens, when sent — the output cap a scenario handler may key on. */
+  maxTokens?: number;
+  /** the request's settings a response answers back as sent, or OpenAI's defaults */
+  echo: { metadata: unknown; temperature: unknown; top_p: unknown; parallel_tool_calls: unknown; tool_choice: unknown; text: unknown; truncation: unknown; user: unknown; max_tool_calls: unknown; top_logprobs: unknown; service_tier: unknown };
+  /** reasoning.summary, when sent: a reasoning item carries a summary only when one is asked for */
+  reasoningSummary?: string;
 };
-const REASONING_EFFORTS = new Set(['minimal', 'low', 'medium', 'high']);
 
-function validateResponses(params: Record<string, unknown>): { args: ResponsesArgs } | { error: OpenAIResponseEnvelope } {
+export function responseMessages(items: Record<string, unknown>[], instructions?: string): ChatMessageParam[] {
+  const messages: ChatMessageParam[] = instructions ? [{ role: 'system', content: instructions }] : [];
+  const partsText = (content: unknown): string => typeof content === 'string' ? content : Array.isArray(content) ? content.map((c) => c && typeof c === 'object' ? String(c.text ?? JSON.stringify(c)) : String(c)).join('\n') : '';
+  for (const item of items) {
+    if (item.type === 'function_call') {
+      messages.push({ role: 'assistant', content: '', tool_calls: [{ id: String(item.call_id ?? item.id ?? ''), type: 'function', function: { name: String(item.name ?? ''), arguments: typeof item.arguments === 'string' ? item.arguments : JSON.stringify(item.arguments ?? {}) } }] });
+    } else if (item.type === 'function_call_output') {
+      messages.push({ role: 'tool', content: partsText(item.output), tool_call_id: String(item.call_id ?? '') });
+    } else if (item.type === 'message' || item.type === undefined) {
+      messages.push({ role: (item.role ?? 'user') as ChatMessageParam['role'], content: partsText(item.content) });
+    }
+    // Reasoning and other typed items remain in state, without inventing user turns.
+  }
+  return messages;
+}
+
+/** OpenAI's refusal of an `input` list holding something other than input items (objects)
+ *  (https://platform.openai.com/docs/api-reference/responses/create, `input`). */
+function itemsNotObjects(): { error: OpenAIResponseEnvelope } {
+  return { error: invalidRequest("'input' items must be objects", 'input') };
+}
+
+export function validateResponses(params: Record<string, unknown>): { args: ResponsesArgs } | { error: OpenAIResponseEnvelope } {
   if (params.model === undefined || params.model === '') return { error: invalidRequest("you must provide a model parameter", 'model') };
   if (typeof params.model !== 'string') return { error: invalidRequest("'model' must be a string", 'model') };
   if (params.input === undefined) return { error: invalidRequest("you must provide an input parameter", 'input') };
-  // input may be a string OR an array of input items (role/content). Reduce to plain text +
-  // a messages-shaped view for token counting.
-  let inputText = '';
-  const messages: ChatMessageParam[] = [];
+  // Keep vendor items as state; the messages view is only a projection for the scenario.
+  let inputItems: Record<string, unknown>[];
   if (typeof params.input === 'string') {
-    inputText = params.input;
-    messages.push({ role: 'user', content: params.input });
+    inputItems = [{ type: 'message', role: 'user', content: [{ type: 'input_text', text: params.input }] }];
   } else if (Array.isArray(params.input)) {
-    for (const item of params.input as Array<Record<string, unknown>>) {
-      const role = (typeof item?.role === 'string' ? item.role : 'user') as ChatMessageParam['role'];
-      const content = item?.content;
-      const text = typeof content === 'string' ? content : Array.isArray(content) ? content.map((c) => (c && typeof c === 'object' ? String((c as { text?: unknown }).text ?? JSON.stringify(c)) : String(c))).join('\n') : '';
-      inputText += (inputText ? '\n' : '') + text;
-      messages.push({ role, content: text });
-    }
+    if (params.input.some((item) => !item || typeof item !== 'object' || Array.isArray(item))) return itemsNotObjects();
+    inputItems = params.input.map((item: Record<string, unknown>) => {
+      if (item.type !== undefined && item.type !== 'message') return { ...item };
+      return { ...item, type: 'message', role: item.role ?? 'user', content: typeof item.content === 'string' ? [{ type: item.role === 'assistant' ? 'output_text' : 'input_text', text: item.content }] : item.content };
+    });
   } else {
     return { error: invalidRequest("'input' must be a string or an array of input items", 'input') };
   }
+  const instructions = typeof params.instructions === 'string' ? params.instructions : undefined;
+  const messages = responseMessages(inputItems, instructions);
+  const inputText = responseMessages(inputItems).map((m) => m.content).filter(Boolean).join('\n');
+  if (params.tools !== undefined && !Array.isArray(params.tools)) return { error: invalidRequest("'tools' must be an array", 'tools') };
+  const maxOut = params.max_output_tokens;
+  if (maxOut !== undefined && (typeof maxOut !== 'number' || !Number.isInteger(maxOut) || maxOut < 1)) return { error: invalidRequest("'max_output_tokens' must be a positive integer", 'max_output_tokens') };
   const prev = params.previous_response_id;
   if (prev !== undefined && (typeof prev !== 'string' || !prev)) return { error: invalidRequest("'previous_response_id' must be a string", 'previous_response_id') };
   // reasoning.effort → the model spends a (stubbed) reasoning budget; the item shape is faithful.
@@ -681,14 +697,19 @@ function validateResponses(params: Record<string, unknown>): { args: ResponsesAr
     const r = params.reasoning;
     if (!r || typeof r !== 'object' || Array.isArray(r)) return { error: invalidRequest("'reasoning' must be an object", 'reasoning') };
     const effort = (r as { effort?: unknown }).effort;
-    if (effort !== undefined) {
-      if (typeof effort !== 'string' || !REASONING_EFFORTS.has(effort)) return { error: invalidRequest("'reasoning.effort' must be one of 'minimal', 'low', 'medium', 'high'", 'reasoning.effort') };
-      reasoningEffort = effort;
-    }
-  }
+    if (effort !== undefined && effort !== null) reasoningEffort = effort as string;
+  }
+  // a model refuses what its page says it does not take (openai-models.ts); a reasoning model reasons with the effort
+  // asked for, else the spec's default
+  const refused = unsupported(params.model, { effort: reasoningEffort, effortParam: 'reasoning.effort', temperature: params.temperature, top_p: params.top_p });
+  if (refused) return { error: invalidRequest(refused.message, refused.param, 'unsupported_value') };
+  if (reasoningEffort === undefined && reasons(params.model)) reasoningEffort = DEFAULT_EFFORT;
+  const reasoningSummary = params.reasoning && typeof (params.reasoning as { summary?: unknown }).summary === 'string' ? String((params.reasoning as { summary: string }).summary) : undefined;
   return {
     args: {
       model: params.model,
+      inputItems,
+      instructions,
       inputText,
       messages,
       stream: params.stream === true,
@@ -696,143 +717,205 @@ function validateResponses(params: Record<string, unknown>): { args: ResponsesAr
       background: params.background === true,
       ...(typeof prev === 'string' ? { previousResponseId: prev } : {}),
       ...(reasoningEffort !== undefined ? { reasoningEffort } : {}),
+      ...(Array.isArray(params.tools) ? { tools: params.tools } : {}),
+      ...(typeof maxOut === 'number' ? { maxTokens: maxOut } : {}),
+      ...(reasoningSummary !== undefined ? { reasoningSummary } : {}),
+      // OpenAI's defaults for what was not sent (the Response schema's): temperature and top_p 1, tools in parallel, auto;
+      // plain text out, no truncation, no end user, no tool-call cap, no alternative tokens, the default tier
+      // (https://platform.openai.com/docs/api-reference/responses/object)
+      echo: {
+        metadata: params.metadata ?? {}, temperature: params.temperature ?? 1, top_p: params.top_p ?? 1, parallel_tool_calls: params.parallel_tool_calls ?? true, tool_choice: params.tool_choice ?? 'auto',
+        text: params.text ?? { format: { type: 'text' } }, truncation: params.truncation ?? 'disabled', user: params.user ?? null, max_tool_calls: params.max_tool_calls ?? null,
+        top_logprobs: params.top_logprobs ?? 0, service_tier: ['flex', 'priority', 'scale'].includes(String(params.service_tier)) ? params.service_tier : 'default',
+      },
     },
   };
 }
 
-// A deterministic reasoning-token budget per effort level (more effort → more reasoning tokens).
-const REASONING_BUDGET: Record<string, number> = { minimal: 8, low: 16, medium: 48, high: 128 };
+/** A tool as a response answers it: as sent, with what OpenAI fills in for what was not. A web search preview searches
+ *  with `medium` context from the United States unless told otherwise (the spec's WebSearchPreviewTool: "`medium` is
+ *  the default"; `user_location` "If omitted or null, defaults to the United States"); a function tool sent without
+ *  `strict` answers strict, as the reference's Functions example answers the tool it sends; a file search tool, its
+ *  default filter and ranking
+ *  (https://platform.openai.com/docs/api-reference/responses/create). */
+const TOOL_DEFAULTS: Record<string, (t: Record<string, unknown>) => Record<string, unknown>> = {
+  function: (t) => ({ ...t, strict: t.strict ?? true }),
+  // a file search sent without filters or ranking answers no filter and the automatic ranker with no threshold, as the
+  // reference's File search example answers the tool it sends
+  file_search: (t) => ({ ...t, filters: t.filters ?? null, ranking_options: t.ranking_options ?? { ranker: 'auto', score_threshold: 0 } }),
+  // and the domains it is limited to, none unless sent, as the reference's Web search example answers `"domains": []`
+  web_search_preview: (t) => ({ ...t, domains: t.domains ?? [], search_context_size: t.search_context_size ?? 'medium', user_location: t.user_location ?? { type: 'approximate', city: null, country: 'US', region: null, timezone: null } }),
+};
+TOOL_DEFAULTS.web_search_preview_2025_03_11 = TOOL_DEFAULTS.web_search_preview!;
+function answeredTool(tool: unknown): unknown {
+  const t = (tool && typeof tool === 'object' ? tool : {}) as Record<string, unknown>;
+  return TOOL_DEFAULTS[String(t.type)]?.(t) ?? tool;
+}
+
+/** The built-in tool calls a response makes: a web search for a web search tool, a file search over the named stores for a
+ *  file search tool, each querying the input's text (its results are not included unless asked for: `results` null). */
+function builtInCalls(args: ResponsesArgs, suffix: string): ResponseOutputItem[] {
+  const query = args.inputText.slice(0, 200);
+  const out: ResponseOutputItem[] = [];
+  for (const [i, tool] of (Array.isArray(args.tools) ? (args.tools as Array<{ type?: unknown }>) : []).entries()) {
+    const type = String(tool?.type ?? '');
+    if (/^web_search/.test(type)) out.push({ type: 'web_search_call', id: `ws-twin-${suffix}-${i}`, status: 'completed', action: { type: 'search', query } });
+    if (type === 'file_search') out.push({ type: 'file_search_call', id: `fs-twin-${suffix}-${i}`, status: 'completed', queries: [query], results: null });
+  }
+  return out;
+}
 
-function buildResponse(args: ResponsesArgs, occurredAt?: string, idSuffix?: string): OpenAIResponse {
-  const text = stubAssistantText(args.messages, args.model);
-  const inputTokens = countPromptTokens(args.messages);
-  const messageTokens = estimateTokens(text);
+/** What every response answers besides its output: the request's settings as sent (or OpenAI's defaults), no error,
+ *  no program access (https://platform.openai.com/docs/api-reference/responses/object). */
+const responseSettings = (args: ResponsesArgs): Record<string, unknown> => ({
+  instructions: args.instructions ?? null, tools: Array.isArray(args.tools) ? args.tools.map(answeredTool) : [], ...args.echo,
+  access_programs: null, error: null, incomplete_details: null,
+  // whether it is kept: the spec's own Response example answers `"store": true` (spec/patches.json)
+  background: args.background, store: args.store, max_output_tokens: args.maxTokens ?? null,
+  previous_response_id: args.previousResponseId ?? null,
+  reasoning: { effort: args.reasoningEffort ?? null, summary: args.reasoningSummary ?? null },
+});
+
+// A deterministic reasoning-token budget per effort level (more effort → more reasoning tokens).
+const REASONING_BUDGET: Record<string, number> = { none: 0, minimal: 8, low: 16, medium: 48, high: 128, xhigh: 256, max: 512 };
+
+/** The function call an unscripted response makes: when the caller requires one or names one, or on
+ *  `auto` unless the input ends with a tool's result, which a model answers in words. */
+function responseToolCall(args: ResponsesArgs): ChatToolCall | null {
+  const choice = args.echo.tool_choice;
+  const named = choice && typeof choice === 'object' ? String((choice as { name?: unknown }).name ?? '') : undefined;
+  const answering = args.inputItems.at(-1)?.type === 'function_call_output';
+  const functions = (Array.isArray(args.tools) ? args.tools : []).filter((t) => (t as { type?: unknown }).type === 'function');
+  if (!functions.length || choice === 'none' || (answering && !named && choice !== 'required')) return null;
+  return stubToolCall(functions, 1, named, lastUserText(args.messages));
+}
+
+export function buildResponse(args: ResponsesArgs, occurredAt?: string, idSuffix?: string, decision?: ScenarioDecision): OpenAIResponse {
+  // The scenario decides the turn exactly as it does for chat completions: a fired handler scripts the
+  // text and the tool calls; a miss answers the labeled stub and teaches. The request handler has
+  // already honored a fault; only a content decision reaches here.
   const suffix = idSuffix ?? String(nowEpoch(occurredAt));
+  const turn = decision && scenarioTurn(decision, `call-twin-${suffix}`);
+  const scripted = turn?.scripted;
+  let text = scripted ? (scripted.text ?? '') : stubAssistantText(args.messages, args.model) + (turn?.missTeach ?? '');
+  const inputTokens = countPromptTokens(args.messages);
   const messageItem: ResponseMessageItem = {
     type: 'message',
     id: `msg-twin-${suffix}`,
     status: 'completed',
     role: 'assistant',
-    content: [{ type: 'output_text', text, annotations: [] }],
+    // no log probabilities unless asked for (`include: ["message.output_text.logprobs"]`): an empty list
+    content: [{ type: 'output_text', text, annotations: [], logprobs: [] }],
   };
+  // unscripted, the stub calls a function tool as the chat stub does (buildChoice)
+  const stubbed = scripted ? null : responseToolCall(args);
+  if (stubbed) text = '';
+  const calls: ResponseFunctionCallItem[] = (scripted?.toolCalls ?? (stubbed ? [stubbed] : [])).map((tc, i) => ({ type: 'function_call', id: `fc-twin-${suffix}-${i}`, status: 'completed', call_id: tc.id, name: tc.function.name, arguments: tc.function.arguments }));
+  const messageTokens = estimateTokens(text) + estimateTokens(calls.map((c) => c.arguments).join(''));
   const output: ResponseOutputItem[] = [];
-  const usage: ResponseUsage = { input_tokens: inputTokens, output_tokens: messageTokens, total_tokens: inputTokens + messageTokens };
+  // usage breaks its counts down as OpenAI's does (https://platform.openai.com/docs/api-reference/responses/object, `usage`):
+  // the twin caches nothing, so no input token was read from or written to a cache
+  const usage: ResponseUsage = { input_tokens: inputTokens, input_tokens_details: { cached_tokens: 0, cache_write_tokens: 0 }, output_tokens: messageTokens, output_tokens_details: { reasoning_tokens: 0 }, total_tokens: inputTokens + messageTokens };
   // reasoning.effort → a faithful reasoning item (labeled-stub summary) BEFORE the message item,
   // plus output_tokens_details.reasoning_tokens in usage (counted into output_tokens, like the vendor).
   if (args.reasoningEffort) {
     const reasoningTokens = REASONING_BUDGET[args.reasoningEffort] ?? 16;
+    // a summary only when one was asked for (`reasoning.summary`); without, OpenAI answers the item's summary empty
+    // (https://platform.openai.com/docs/guides/reasoning#reasoning-summaries)
     const reasoningItem: ResponseReasoningItem = {
       type: 'reasoning',
       id: `rs-twin-${suffix}`,
-      summary: [{ type: 'summary_text', text: `[twin-stub] reasoning summary (effort=${args.reasoningEffort}); the twin cannot run the model, so the chain-of-thought is not real.` }],
+      summary: args.reasoningSummary ? [{ type: 'summary_text', text: `[twin-stub] reasoning summary (effort=${args.reasoningEffort}); the twin cannot run the model, so the chain-of-thought is not real.` }] : [],
     };
-    output.push(reasoningItem);
+    // only a model that reasons lists its reasoning item (openai-models.ts)
+    if (reasons(args.model)) output.push(reasoningItem);
     usage.output_tokens += reasoningTokens;
     usage.total_tokens += reasoningTokens;
     usage.output_tokens_details = { reasoning_tokens: reasoningTokens };
   }
-  output.push(messageItem);
+  // the built-in tools the request offers, which OpenAI runs itself before answering: the placeholder model searches
+  // with each one offered, on the input's text, unless `tool_choice` is `none` (the reference's Web search and File search
+  // examples answer a `web_search_call` / `file_search_call` item before the message:
+  // https://platform.openai.com/docs/guides/tools-web-search, https://platform.openai.com/docs/guides/tools-file-search)
+  if (!scripted && args.echo.tool_choice !== 'none') output.push(...builtInCalls(args, suffix));
+  // A scripted turn with tool calls and no words carries the calls alone, as the vendor does.
+  if (text || !calls.length) output.push(messageItem);
+  output.push(...calls);
   return {
     id: `resp-twin-${suffix}`,
     object: 'response',
     created_at: nowEpoch(occurredAt),
     status: 'completed',
+    // answered whole at once: completed the instant it was created
+    completed_at: nowEpoch(occurredAt),
     model: args.model,
+    // no `output_text`: the spec's is an "SDK-only convenience property" the SDKs compute from `output`
     output,
-    output_text: text,
     usage,
-    ...(args.reasoningEffort ? { reasoning: { effort: args.reasoningEffort, summary: null } } : {}),
-    ...(args.previousResponseId ? { previous_response_id: args.previousResponseId } : {}),
+    ...responseSettings(args),
   };
 }
 
-// A deterministic id suffix for a stored response (hash of model + input + chain) so retrieval
-// is stable + assertable, like the twin's other deterministic outputs.
-function responseSuffix(args: ResponsesArgs): string {
+// Unstored responses have no state to overwrite. Stored identities are allocated atomically below.
+export function responseSuffix(args: ResponsesArgs): string {
   let h = 0x811c9dc5;
-  const s = args.model + '|' + args.inputText + '|' + (args.previousResponseId ?? '');
+  const s = JSON.stringify([args.model, args.inputItems ?? args.messages, args.previousResponseId, args.instructions]);
   for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193); }
   return (h >>> 0).toString(36);
 }
 
-// Persist a stored Response so it can be retrieved/deleted later (Responses server-side state).
-async function storeResponse(resp: OpenAIResponse, args: ResponsesArgs, req: OpenAIRequest): Promise<void> {
-  const inputItems = args.messages.map((m, i) => ({ id: `msg-in-${i}`, type: 'message', role: m.role, content: [{ type: 'input_text', text: typeof m.content === 'string' ? m.content : '' }] }));
-  await applyTwinWrite(SERVICE, {
-    operation: 'response.create',
-    subjectType: 'response',
-    subjectId: resp.id,
-    fields: { ...resp, _stored: true, _input_items: inputItems },
-    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
-    actor: { kind: 'agent' },
+// Allocate and create under the kernel's cross-process lock. Repeated requests are occurrences;
+// a content hash alone would overwrite an earlier response (and its queued scenario decision).
+export async function createStoredResponse(args: ResponsesArgs, req: OpenAIRequest, decision?: ScenarioDecision): Promise<OpenAIResponse | Record<string, unknown>> {
+  const { value } = await applyTwinWriteAtomic<OpenAIResponse | Record<string, unknown>>(SERVICE, (resources) => {
+    let ordinal = 0;
+    for (const row of resources) {
+      if (row.type !== 'response') continue;
+      const match = /^resp-twin-(\d+)$/.exec(String(row.id));
+      if (match) ordinal = Math.max(ordinal, Number(match[1]));
+    }
+    const suffix = String(ordinal + 1);
+    const inputItems = args.inputItems.map((item, i) => ({ ...item, id: item.id ?? `item-in-${suffix}-${i}` }));
+    const resp = args.background ? {
+      id: `resp-twin-${suffix}`, object: 'response', created_at: nowEpoch(req.occurredAt),
+      status: 'queued', completed_at: null, model: args.model, output: [],
+      usage: null, ...responseSettings(args),
+    } : buildResponse(args, req.occurredAt, suffix, decision);
+    return { kind: 'write', value: resp, write: {
+      operation: 'response.create', subjectType: 'response', subjectId: resp.id,
+      fields: { ...resp, _stored: true, _input_items: inputItems,
+        ...(args.background ? { _bg_args: JSON.stringify(args), _bg_suffix: suffix, _bg_decision: decision ? JSON.stringify(decision) : null } : {}),
+      },
+      ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+    } };
   }, req.root);
-}
-function responseView(r: Record<string, unknown>): Record<string, unknown> {
-  return { id: r.id, ...strip(r) };
-}
-
-// ── background responses (background:true → queued → poll → completed | cancel) ───────────
-// Persist a `queued` background response: the faithful queued envelope (no output yet) plus the
-// stashed args so the first poll can compute the real stub output. background implies store.
-async function storeQueuedResponse(args: ResponsesArgs, req: OpenAIRequest, suffix: string): Promise<Record<string, unknown>> {
-  const id = `resp-twin-${suffix}`;
-  const inputItems = args.messages.map((m, i) => ({ id: `msg-in-${i}`, type: 'message', role: m.role, content: [{ type: 'input_text', text: typeof m.content === 'string' ? m.content : '' }] }));
-  const fields = {
-    id,
-    object: 'response',
-    created_at: nowEpoch(req.occurredAt),
-    status: 'queued',
-    background: true,
-    model: args.model,
-    output: [],
-    output_text: null,
-    usage: null,
-    error: null,
-    incomplete_details: null,
-    ...(args.previousResponseId ? { previous_response_id: args.previousResponseId } : {}),
-    _stored: true,
-    _input_items: inputItems,
-    _bg_args: JSON.stringify(args),
-    _bg_suffix: suffix,
-  };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'response.create', subjectType: 'response', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return resource;
-}
-// First poll of a queued background response: compute the real stub output + usage, flip the
-// persisted row to `completed`, and record the (now billable) usage exactly once.
-async function completeQueuedResponse(r: Record<string, unknown>, req: OpenAIRequest): Promise<Record<string, unknown>> {
-  const args = JSON.parse(String(r._bg_args ?? '{}')) as ResponsesArgs;
-  const suffix = String(r._bg_suffix ?? responseSuffix(args));
-  const resp = buildResponse(args, req.occurredAt, suffix);
-  const fields = { ...resp, background: true, status: 'completed', _bg_args: undefined };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'response.update', subjectType: 'response', subjectId: String(r.id), fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  await recordUsage(req, 'responses', resp.model, resp.usage.input_tokens, resp.usage.output_tokens);
-  return resource;
+  return value;
 }
 
-/** Emit the faithful Responses API streaming events (response.created → output_text.delta* →
- *  response.completed → [DONE]) into the injected sink. */
-export function streamResponse(args: ResponsesArgs, sink: SseSink, occurredAt?: string, idSuffix?: string): OpenAIResponse {
-  const resp = buildResponse(args, occurredAt, idSuffix);
-  sink({ data: { type: 'response.created', response: { ...resp, output: [], output_text: '' } } });
-  // Emit each output item in order; the message item carries the text deltas at its own index.
-  const msgIndex = resp.output.findIndex((o) => o.type === 'message');
+export function emitResponse(resp: OpenAIResponse, sink: SseSink): OpenAIResponse {
+  sink({ data: { type: 'response.created', response: { ...resp, output: [] } } });
+  // Emit each output item in order, as the vendor streams them: a reasoning item whole, the message
+  // item's text as deltas at its own index, a function call's arguments as one delta then done.
   resp.output.forEach((item, i) => {
-    sink({ data: { type: 'response.output_item.added', output_index: i, item } });
-    if (item.type === 'reasoning') sink({ data: { type: 'response.output_item.done', output_index: i, item } });
+    sink({ data: { type: 'response.output_item.added', output_index: i, item: item.type === 'function_call' ? { ...item, arguments: '' } : item } });
+    if (item.type === 'message') {
+      const text = item.content[0]?.text ?? '';
+      for (const piece of chunkText(text)) sink({ data: { type: 'response.output_text.delta', output_index: i, content_index: 0, delta: piece } });
+      sink({ data: { type: 'response.output_text.done', output_index: i, content_index: 0, text } });
+    }
+    if (item.type === 'function_call') {
+      sink({ data: { type: 'response.function_call_arguments.delta', output_index: i, item_id: item.id, delta: item.arguments } });
+      sink({ data: { type: 'response.function_call_arguments.done', output_index: i, item_id: item.id, arguments: item.arguments } });
+    }
+    sink({ data: { type: 'response.output_item.done', output_index: i, item } });
   });
-  const text = resp.output_text ?? '';
-  for (const piece of chunkText(text)) {
-    sink({ data: { type: 'response.output_text.delta', output_index: msgIndex, content_index: 0, delta: piece } });
-  }
-  sink({ data: { type: 'response.output_text.done', output_index: msgIndex, content_index: 0, text } });
   sink({ data: { type: 'response.completed', response: resp } });
   sink({ done: true });
   return resp;
 }
 
 // ── Embeddings (deterministic pseudo-vectors) ───────────────────────────────────────────
-function handleEmbeddings(params: Record<string, unknown>): OpenAIResponseEnvelope {
+export function handleEmbeddings(params: Record<string, unknown>): OpenAIResponseEnvelope {
   if (params.model === undefined || params.model === '') return invalidRequest("you must provide a model parameter", 'model');
   if (params.input === undefined) return invalidRequest("you must provide an input parameter", 'input');
   const model = String(params.model);
@@ -872,1229 +955,241 @@ function floatsToBase64(vec: number[]): string {
   return btoa(bin);
 }
 
-// ── Files (stateful) ────────────────────────────────────────────────────────────────────
-async function createFile(params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  // The SDK sends multipart/form-data; the twin's JSON contract accepts { purpose, filename,
-  // bytes } (the server adapts multipart → this shape). purpose is required like the vendor.
-  const purpose = params.purpose;
-  if (purpose === undefined || purpose === '') return invalidRequest("you must provide a purpose parameter", 'purpose');
-  const id = nextId('file', 'file', req.root);
-  const filename = typeof params.filename === 'string' && params.filename ? params.filename : 'upload.jsonl';
-  const bytes = Number(params.bytes ?? (typeof params.content === 'string' ? params.content.length : 0));
-  const fields = {
-    object: 'file',
-    bytes: Number.isFinite(bytes) ? bytes : 0,
-    created_at: nowEpoch(req.occurredAt),
-    filename,
-    purpose: String(purpose),
-    status: 'processed',
-    // The raw bytes are carved out (openai.files.real_bytes); we keep the supplied content for
-    // the /content endpoint when present so round-trips are faithful.
-    _content: typeof params.content === 'string' ? params.content : '',
-  };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'file.create', subjectType: 'file', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return { status: 200, body: fileView(resource) };
-}
-function fileView(r: Record<string, unknown>): Record<string, unknown> {
-  const { _content: _c, ...rest } = strip(r);
-  return { id: r.id, ...rest };
-}
-
-// ── Batches (stateful) ──────────────────────────────────────────────────────────────────
-async function createBatch(params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  if (params.input_file_id === undefined || params.input_file_id === '') return invalidRequest("you must provide an input_file_id parameter", 'input_file_id');
-  if (params.endpoint === undefined || params.endpoint === '') return invalidRequest("you must provide an endpoint parameter", 'endpoint');
-  if (params.completion_window === undefined) return invalidRequest("you must provide a completion_window parameter", 'completion_window');
-  const id = nextId('batch', 'batch', req.root);
-  const created = nowEpoch(req.occurredAt);
-  // The twin has nothing to process asynchronously, so a batch completes immediately. The
-  // results file id is a deterministic synthetic id.
-  const fields = {
-    object: 'batch',
-    endpoint: String(params.endpoint),
-    input_file_id: String(params.input_file_id),
-    completion_window: String(params.completion_window),
-    status: 'completed',
-    output_file_id: `file-twin-batchout-${id}`,
-    error_file_id: null,
-    created_at: created,
-    in_progress_at: created,
-    completed_at: created,
-    request_counts: { total: 0, completed: 0, failed: 0 },
-    metadata: (params.metadata && typeof params.metadata === 'object') ? params.metadata : null,
-  };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'batch.create', subjectType: 'batch', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return { status: 200, body: batchView(resource) };
-}
-function batchView(r: Record<string, unknown>): Record<string, unknown> {
-  return { id: r.id, ...strip(r) };
-}
-
 // ── Moderations (deterministic) ─────────────────────────────────────────────────────────
-function handleModerations(params: Record<string, unknown>, occurredAt?: string): OpenAIResponseEnvelope {
+export function handleModerations(params: Record<string, unknown>, occurredAt?: string): OpenAIResponseEnvelope {
   if (params.input === undefined) return invalidRequest("you must provide an input parameter", 'input');
-  const inputs: string[] = typeof params.input === 'string'
-    ? [params.input]
-    : Array.isArray(params.input)
-      ? (params.input as unknown[]).map((x) => (typeof x === 'string' ? x : JSON.stringify(x)))
-      : [];
+  // an array of strings is several inputs, one result each; an array of text and image parts is ONE multimodal input,
+  // one result (https://platform.openai.com/docs/api-reference/moderations/create, `input`)
+  const list = Array.isArray(params.input) ? (params.input as unknown[]) : [];
+  const parts = list.length > 0 && list.every((x) => x && typeof x === 'object' && !Array.isArray(x));
+  const inputs: Array<{ text: string; image: boolean }> = typeof params.input === 'string'
+    ? [{ text: params.input, image: false }]
+    : parts
+      ? [{ text: (list as Array<{ type?: unknown; text?: unknown }>).filter((x) => x.type === 'text').map((x) => String(x.text ?? '')).join('\n'), image: (list as Array<{ type?: unknown }>).some((x) => x.type === 'image_url') }]
+      : list.map((x) => ({ text: typeof x === 'string' ? x : JSON.stringify(x), image: false }));
   if (inputs.length === 0) return invalidRequest("'input' must be a non-empty string or array", 'input');
-  const model = typeof params.model === 'string' && params.model ? params.model : 'omni-moderation-latest';
-  const results = inputs.map((t) => moderateText(t));
+  const model = modelOf('createModeration', params)!;
+  const results = inputs.map((t) => moderateText(t.text, t.image));
   return { status: 200, body: { id: `modr-twin-${nowEpoch(occurredAt)}`, model, results } };
 }
 
-// ── Fine-tuning jobs (stateful) ─────────────────────────────────────────────────────────
-async function createFineTune(params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  if (params.model === undefined || params.model === '') return invalidRequest("you must provide a model parameter", 'model');
-  if (params.training_file === undefined || params.training_file === '') return invalidRequest("you must provide a training_file parameter", 'training_file');
-  const id = nextId('ftjob', 'ftjob', req.root);
-  const created = nowEpoch(req.occurredAt);
-  // The twin cannot train a model, so the job completes immediately with a synthetic
-  // fine-tuned model id (the lifecycle/shape is faithful; the trained model is a stub).
-  const fields = {
-    object: 'fine_tuning.job',
-    model: String(params.model),
-    created_at: created,
-    finished_at: created,
-    fine_tuned_model: `ft:${String(params.model)}:twin::${id}`,
-    organization_id: 'org-twin',
-    status: 'succeeded',
-    training_file: String(params.training_file),
-    validation_file: params.validation_file ?? null,
-    hyperparameters: (params.hyperparameters && typeof params.hyperparameters === 'object') ? params.hyperparameters : { n_epochs: 'auto' },
-    result_files: [],
-    trained_tokens: 0,
-    error: null,
-    seed: Number(params.seed ?? 0),
-  };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'fine_tuning_job.create', subjectType: 'fine_tuning_job', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return { status: 200, body: ftView(resource) };
-}
-function ftView(r: Record<string, unknown>): Record<string, unknown> {
-  return { id: r.id, ...strip(r) };
-}
-/** The fine-tuned model objects minted by succeeded fine-tuning jobs (deletable, owned by the
- *  user), minus any that have been deleted via DELETE /v1/models/:id. */
-function fineTunedModels(root?: string): Array<{ id: string; object: 'model'; created: number; owned_by: string }> {
-  const deleted = new Set(rows('model', root).filter((r) => r._deleted).map((r) => String(r.id)));
-  const out: Array<{ id: string; object: 'model'; created: number; owned_by: string }> = [];
-  for (const j of rows('fine_tuning_job', root)) {
-    const ftm = (j as { fine_tuned_model?: unknown }).fine_tuned_model;
-    if (typeof ftm === 'string' && ftm && !deleted.has(ftm)) {
-      out.push({ id: ftm, object: 'model', created: Number(j.created_at ?? 0), owned_by: 'org-twin' });
-    }
-  }
-  return out;
-}
-
-// ── Vector stores (stateful) ────────────────────────────────────────────────────────────
-async function createVectorStore(params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  const id = nextId('vector_store', 'vs', req.root);
-  const created = nowEpoch(req.occurredAt);
-  const fileIds = Array.isArray(params.file_ids) ? (params.file_ids as unknown[]) : [];
-  const fields = {
-    object: 'vector_store',
-    created_at: created,
-    name: typeof params.name === 'string' ? params.name : null,
-    usage_bytes: 0,
-    status: 'completed',
-    file_counts: { in_progress: 0, completed: fileIds.length, failed: 0, cancelled: 0, total: fileIds.length },
-    metadata: (params.metadata && typeof params.metadata === 'object') ? params.metadata : {},
-    last_active_at: created,
-  };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'vector_store.create', subjectType: 'vector_store', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  // Seed any provided file_ids as vector_store_file children.
-  for (const fid of fileIds) {
-    await addVectorStoreFile(id, String(fid), req);
-  }
-  return { status: 200, body: vsView(resource) };
-}
-function vsView(r: Record<string, unknown>): Record<string, unknown> {
-  return { id: r.id, ...strip(r) };
-}
-async function addVectorStoreFile(storeId: string, fileId: string, req: OpenAIRequest, batchId?: string): Promise<Record<string, unknown>> {
-  const created = nowEpoch(req.occurredAt);
-  const childId = `${storeId}::${fileId}`;
-  const fields = { object: 'vector_store.file', vector_store_id: storeId, file_id: fileId, created_at: created, status: 'completed', usage_bytes: 0, ...(batchId ? { _batch_id: batchId } : {}) };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'vector_store_file.create', subjectType: 'vector_store_file', subjectId: childId, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return vsFileView(resource);
-}
-function vsFileView(r: Record<string, unknown>): Record<string, unknown> {
-  const s = strip(r);
-  return { id: String(r.id).split('::')[1] ?? r.id, object: 'vector_store.file', file_id: s.file_id, vector_store_id: s.vector_store_id, created_at: s.created_at, status: s.status, usage_bytes: s.usage_bytes ?? 0 };
-}
-function vsBatchView(r: Record<string, unknown>): Record<string, unknown> {
-  const { _file_ids: _f, ...rest } = strip(r);
-  return { id: r.id, ...rest };
-}
+// ── Images (a real placeholder image, no model: ./openai-media.ts) ─────────────────────────────────
+const gptImage = (model: string): boolean => /^(gpt-image|chatgpt-image)/.test(model);
 
-// ── Admin / org API (stateful) ──────────────────────────────────────────────────────────
-// The Admin API (under /v1/organization, authed with an admin key) manages organization
-// projects and their API keys. The twin models projects (create/list/retrieve/modify/archive)
-// and project API keys (create/list/retrieve/delete) statefully. Keys are SYNTHETIC twin keys —
-// never real OpenAI credentials.
-async function createProject(params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  if (params.name === undefined || params.name === '') return invalidRequest("you must provide a name parameter", 'name');
-  const id = nextId('project', 'proj', req.root);
-  const created = nowEpoch(req.occurredAt);
-  const fields = { object: 'organization.project', name: String(params.name), created_at: created, archived_at: null, status: 'active' };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'project.create', subjectType: 'project', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return { status: 200, body: idView(resource) };
+/** One answered image: the GPT image models give the image itself as base64, always; `dall-e-2` and `dall-e-3` a URL
+ *  unless `response_format` is `b64_json`, and `dall-e-3` its revised prompt (developers.openai.com/api/reference/
+ *  resources/images/methods/generate, `response_format`; the Image object's `b64_json`, `url`, `revised_prompt`). */
+function imageData(params: Record<string, unknown>, model: string, size: { width: number; height: number }, seed: string, kind: string, i: number, occurredAt?: string): Record<string, unknown> {
+  return gptImage(model) || params.response_format === 'b64_json' ? { b64_json: base64(placeholderPng(size, `${seed} #${i + 1}`)) } : dalleUrl(model, seed, kind, i, occurredAt);
 }
-async function createProjectApiKey(projectId: string, params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  if (params.name === undefined || params.name === '') return invalidRequest("you must provide a name parameter", 'name');
-  const seq = rows('api_key', req.root).filter((r) => r.project_id === projectId).length + 1;
-  const id = `key_twin_${projectId}_${seq}`;
-  const created = nowEpoch(req.occurredAt);
-  // a SYNTHETIC twin secret — clearly not a real OpenAI key (only shown at creation, like the vendor).
-  const secret = `sk-twin-proj-${projectId}-${seq}`;
-  const fields = { object: 'organization.project.api_key', name: String(params.name), created_at: created, project_id: projectId, redacted_value: `sk-twin-...${seq}`, _secret: secret };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'api_key.create', subjectType: 'api_key', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  // creation echoes the one-time secret `value`; subsequent reads only show redacted_value.
-  return { status: 200, body: { ...apiKeyView(resource), value: secret } };
+/** A DALL·E image as its URL, the default for `dall-e-2` and `dall-e-3`. */
+function dalleUrl(model: string, seed: string, kind: string, i: number, occurredAt?: string): Record<string, unknown> {
+  return { url: `https://twin.invalid/openai-${kind}-stub/${nowEpoch(occurredAt)}-${i}.png`, ...(model === 'dall-e-3' ? { revised_prompt: `[twin-stub] ${seed}` } : {}) };
 }
-function apiKeyView(r: Record<string, unknown>): Record<string, unknown> {
-  const { _secret: _s, ...rest } = strip(r);
-  return { id: r.id, ...rest };
-}
-
-// ── Uploads API (multipart large-file parts, stateful) ──────────────────────────────────
-// The Uploads API lets a client stream a large file in parts: create an upload, POST each part,
-// then complete (which assembles the parts into a real File object). The twin models the full
-// lifecycle and assembles the concatenated part contents into a File (faithful, stateful).
-async function createUpload(params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  for (const k of ['filename', 'purpose', 'bytes', 'mime_type']) {
-    if (params[k] === undefined || params[k] === '') return invalidRequest(`you must provide a ${k} parameter`, k);
-  }
-  const id = nextId('upload', 'upload', req.root);
-  const created = nowEpoch(req.occurredAt);
-  const fields = {
-    object: 'upload', created_at: created, filename: String(params.filename), bytes: Number(params.bytes),
-    purpose: String(params.purpose), mime_type: String(params.mime_type), status: 'pending',
-    expires_at: created + 3600, file: null,
-  };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'upload.create', subjectType: 'upload', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return { status: 200, body: uploadView(resource) };
-}
-function uploadView(r: Record<string, unknown>): Record<string, unknown> {
-  const { _parts: _p, ...rest } = strip(r);
-  return { id: r.id, ...rest };
-}
-async function addUploadPart(uploadId: string, params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  const up = getRow('upload', uploadId, req.root);
-  if (!up || up.status !== 'pending') return notFound(`No such Upload object: ${uploadId}`);
-  if (params.data === undefined) return invalidRequest("you must provide a data parameter", 'data');
-  const parts = Array.isArray((up as { _parts?: unknown })._parts) ? [...((up as { _parts: unknown[] })._parts)] : [];
-  const partId = `part-twin-${uploadId}-${parts.length + 1}`;
-  parts.push({ id: partId, data: String(params.data) });
-  await applyTwinWrite(SERVICE, { operation: 'upload.update', subjectType: 'upload', subjectId: uploadId, fields: { _parts: parts }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return { status: 200, body: { id: partId, object: 'upload.part', created_at: nowEpoch(req.occurredAt), upload_id: uploadId } };
-}
-async function completeUpload(uploadId: string, params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  const up = getRow('upload', uploadId, req.root);
-  if (!up || up.status !== 'pending') return notFound(`No such Upload object: ${uploadId}`);
-  if (!Array.isArray(params.part_ids) || params.part_ids.length === 0) return invalidRequest("you must provide a part_ids array", 'part_ids');
-  const parts = Array.isArray((up as { _parts?: unknown })._parts) ? (up as { _parts: Array<{ id: string; data: string }> })._parts : [];
-  const byId = new Map(parts.map((p) => [p.id, p.data]));
-  // assemble the file content from the parts in the caller-specified order.
-  let content = '';
-  for (const pid of params.part_ids as string[]) {
-    if (!byId.has(String(pid))) return invalidRequest(`unknown part_id '${pid}'`, 'part_ids');
-    content += byId.get(String(pid));
-  }
-  // mint a real File object from the assembled content.
-  const fileId = nextId('file', 'file', req.root);
-  const created = nowEpoch(req.occurredAt);
-  const fileFields = {
-    object: 'file', bytes: Number(up.bytes ?? content.length), created_at: created,
-    filename: String(up.filename), purpose: String(up.purpose), status: 'processed', _content: content,
-  };
-  await applyTwinWrite(SERVICE, { operation: 'file.create', subjectType: 'file', subjectId: fileId, fields: fileFields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  const fileObj = fileView({ id: fileId, ...fileFields });
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'upload.update', subjectType: 'upload', subjectId: uploadId, fields: { status: 'completed', file: fileObj }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return { status: 200, body: uploadView(resource) };
-}
-
-// ── Assistants / Threads / Runs (beta, stateful) ────────────────────────────────────────
-// The Assistants API is fully stateful CRUD over assistants, threads (+ messages), and runs
-// (+ run steps). The twin models the OBJECTS + lifecycle faithfully; a run cannot invoke a real
-// model, so a run completes immediately and any assistant reply message is a clearly-labeled stub.
-async function createAssistant(params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  if (params.model === undefined || params.model === '') return invalidRequest("you must provide a model parameter", 'model');
-  const id = nextId('assistant', 'asst', req.root);
-  const created = nowEpoch(req.occurredAt);
-  const fields = {
-    object: 'assistant', created_at: created,
-    name: params.name ?? null, description: params.description ?? null,
-    model: String(params.model), instructions: params.instructions ?? null,
-    tools: Array.isArray(params.tools) ? params.tools : [],
-    metadata: (params.metadata && typeof params.metadata === 'object') ? params.metadata : {},
-    temperature: params.temperature ?? null, top_p: params.top_p ?? null,
-    response_format: params.response_format ?? 'auto',
-  };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'assistant.create', subjectType: 'assistant', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return { status: 200, body: idView(resource) };
-}
-function idView(r: Record<string, unknown>): Record<string, unknown> {
-  return { id: r.id, ...strip(r) };
-}
-/** Pick the updatable fields present in an update body (vendor PATCH-via-POST semantics). */
-function pickUpdate(params: Record<string, unknown>, keys: string[]): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  for (const k of keys) if (params[k] !== undefined) out[k] = params[k];
-  return out;
-}
-async function createThread(params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  const id = nextId('thread', 'thread', req.root);
-  const created = nowEpoch(req.occurredAt);
-  const fields = { object: 'thread', created_at: created, metadata: (params.metadata && typeof params.metadata === 'object') ? params.metadata : {}, tool_resources: params.tool_resources ?? null };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'thread.create', subjectType: 'thread', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  // Seed any inline messages provided at thread creation.
-  if (Array.isArray(params.messages)) {
-    for (const m of params.messages as Array<Record<string, unknown>>) await addThreadMessage(id, m, req);
-  }
-  return { status: 200, body: idView(resource) };
-}
-async function addThreadMessage(threadId: string, params: Record<string, unknown>, req: OpenAIRequest): Promise<Record<string, unknown>> {
-  const seq = rows('message', req.root).filter((r) => r.thread_id === threadId).length + 1;
-  const id = `msg-twin-${threadId}-${seq}`;
-  const created = nowEpoch(req.occurredAt);
-  const role = typeof params.role === 'string' ? params.role : 'user';
-  const text = typeof params.content === 'string' ? params.content : Array.isArray(params.content) ? (params.content as Array<Record<string, unknown>>).map((p) => String((p as { text?: { value?: unknown } }).text?.value ?? (p as { text?: unknown }).text ?? '')).join('') : '';
-  const fields = {
-    object: 'thread.message', created_at: created, thread_id: threadId, role,
-    content: [{ type: 'text', text: { value: text, annotations: [] } }],
-    assistant_id: params.assistant_id ?? null, run_id: params.run_id ?? null,
-    attachments: Array.isArray(params.attachments) ? params.attachments : [],
-    metadata: (params.metadata && typeof params.metadata === 'object') ? params.metadata : {},
-    _seq: seq,
-  };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'message.create', subjectType: 'message', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return msgView(resource);
-}
-function msgView(r: Record<string, unknown>): Record<string, unknown> {
-  const { _seq: _s, ...rest } = strip(r);
-  return { id: r.id, ...rest };
-}
-// A run completes immediately (the twin can't invoke the model): it appends a clearly-labeled
-// stub assistant message to the thread and records two run steps (message creation lifecycle).
-async function createRun(threadId: string, params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  if (params.assistant_id === undefined || params.assistant_id === '') return invalidRequest("you must provide an assistant_id parameter", 'assistant_id');
-  const assistantId = String(params.assistant_id);
-  const assistant = getRow('assistant', assistantId, req.root);
-  if (!assistant || assistant._deleted) return notFound(`No assistant found with id '${assistantId}'.`);
-  const id = nextId('run', 'run', req.root);
-  const created = nowEpoch(req.occurredAt);
-  const model = typeof params.model === 'string' && params.model ? params.model : String(assistant.model);
-  // append the stub assistant reply to the thread.
-  const replyText = `[twin-stub:${model}] deterministic assistant run output (no model weights are run)`;
-  const reply = await addThreadMessage(threadId, { role: 'assistant', content: replyText, assistant_id: assistantId, run_id: id }, req);
-  const fields = {
-    object: 'thread.run', created_at: created, thread_id: threadId, assistant_id: assistantId,
-    status: 'completed', model, instructions: params.instructions ?? assistant.instructions ?? null,
-    tools: Array.isArray(params.tools) ? params.tools : (assistant.tools ?? []),
-    started_at: created, completed_at: created, expires_at: null, cancelled_at: null, failed_at: null,
-    required_action: null, last_error: null,
-    usage: { prompt_tokens: 0, completion_tokens: estimateTokens(replyText), total_tokens: estimateTokens(replyText) },
-    metadata: (params.metadata && typeof params.metadata === 'object') ? params.metadata : {},
-    _reply_msg: reply.id,
+function imageCount(params: Record<string, unknown>): number {
+  const n = Number(params.n ?? 1);
+  return Number.isInteger(n) && n > 0 ? n : 1;
+}
+/** An image answer, and its events when streamed. */
+export type ImageAnswer = OpenAIResponseEnvelope & { events?: Array<{ event: string; data: unknown }> };
+
+/** A GPT image model's answer: the images with the tokens they cost (the image generation guide's 1024x1024
+ *  medium-quality image is 1056 output tokens, scaled here by area; the twin reads no pixels, so it counts no input image
+ *  tokens: https://platform.openai.com/docs/guides/image-generation#cost-and-latency), or, with `stream`, the
+ *  `partial_images` asked (none by default: "When set to 0, the response will be a single image sent in one streaming
+ *  event") then the completed image (https://platform.openai.com/docs/api-reference/images-streaming). */
+function gptImageAnswer(params: Record<string, unknown>, size: { width: number; height: number }, data: Array<Record<string, unknown>>, kind: 'image_generation' | 'image_edit', occurredAt?: string): ImageAnswer {
+  const text = estimateTokens(String(params.prompt ?? ''));
+  const output = Math.ceil((1056 * size.width * size.height) / (1024 * 1024)) * data.length;
+  const usage = { total_tokens: text + output, input_tokens: text, output_tokens: output, input_tokens_details: { text_tokens: text, image_tokens: 0 } };
+  const created = nowEpoch(occurredAt);
+  if (params.stream !== true && params.stream !== 'true') return { status: 200, body: { created, data, usage } };
+  const settings = {
+    created_at: created, size: `${size.width}x${size.height}`,
+    // what `auto` settles on for a placeholder: an opaque PNG of medium quality
+    quality: params.quality && params.quality !== 'auto' ? params.quality : 'medium',
+    background: params.background && params.background !== 'auto' ? params.background : 'opaque',
+    output_format: params.output_format ?? 'png',
   };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'run.create', subjectType: 'run', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return { status: 200, body: runView(resource) };
-}
-function runView(r: Record<string, unknown>): Record<string, unknown> {
-  const { _reply_msg: _m, ...rest } = strip(r);
-  return { id: r.id, ...rest };
-}
-function runSteps(run: Record<string, unknown>): Array<Record<string, unknown>> {
-  const created = Number(run.created_at ?? 0);
-  const replyMsg = String((run as { _reply_msg?: unknown })._reply_msg ?? '');
-  return [{
-    id: `step-${run.id}-1`, object: 'thread.run.step', created_at: created,
-    run_id: String(run.id), assistant_id: String(run.assistant_id), thread_id: String(run.thread_id),
-    type: 'message_creation', status: 'completed', completed_at: created,
-    step_details: { type: 'message_creation', message_creation: { message_id: replyMsg } },
-    usage: run.usage ?? null,
-  }];
+  const partials = Math.min(3, Math.max(0, Number(params.partial_images ?? 0) || 0));
+  const b64 = String(data[0]?.b64_json ?? '');
+  const events = [
+    ...Array.from({ length: partials }, (_, i) => ({ event: `${kind}.partial_image`, data: { type: `${kind}.partial_image`, b64_json: b64, ...settings, partial_image_index: i } })),
+    { event: `${kind}.completed`, data: { type: `${kind}.completed`, b64_json: b64, ...settings, usage } },
+  ];
+  return { status: 200, body: { created, data, usage }, events };
 }
 
-// ── Images (response shape; real pixels out of scope) ───────────────────────────────────
-function handleImages(params: Record<string, unknown>, occurredAt?: string): OpenAIResponseEnvelope {
+export function handleImages(params: Record<string, unknown>, occurredAt?: string): ImageAnswer {
   if (params.prompt === undefined || params.prompt === '') return invalidRequest("you must provide a prompt parameter", 'prompt');
-  const n = Number(params.n ?? 1);
-  const count = Number.isInteger(n) && n > 0 ? n : 1;
-  const data = Array.from({ length: count }, (_, i) => ({
-    url: `https://twin.invalid/openai-image-stub/${nowEpoch(occurredAt)}-${i}.png`,
-    revised_prompt: `[twin-stub] ${String(params.prompt)}`,
-  }));
+  const model = modelOf('createImage', params)!;
+  const size = requestedSize(params.size);
+  const data = Array.from({ length: imageCount(params) }, (_, i) => imageData(params, model, size, String(params.prompt), 'image', i, occurredAt));
+  if (gptImage(model)) return gptImageAnswer(params, size, data, 'image_generation', occurredAt);
   return { status: 200, body: { created: nowEpoch(occurredAt), data } };
 }
-// Image EDITS (require image + prompt) and VARIATIONS (require image, no prompt). Real pixels are
-// out of scope, so the twin returns the faithful response shape with a placeholder URL.
-function handleImageEdit(params: Record<string, unknown>, occurredAt?: string): OpenAIResponseEnvelope {
-  if (params.image === undefined || params.image === '') return invalidRequest("you must provide an image to edit", 'image');
+/** OpenAI's refusal of an upload that is not an image the model takes. */
+const badImage = (formats: string): OpenAIResponseEnvelope => invalidRequest(`Invalid image file: 'image' must be ${formats}.`, 'image', 'invalid_image_format');
+
+// An EDIT takes an image file and a prompt; a VARIATION (dall-e-2 only) a square PNG. Each is told by its bytes.
+export function handleImageEdit(params: Record<string, unknown>, occurredAt?: string): ImageAnswer {
+  // a GPT image model edits several images sent as `image[]` (the form keeps the last one named so)
+  const image = params.image ?? params['image[]'];
+  if (image === undefined || image === '') return invalidRequest("you must provide an image to edit", 'image');
   if (params.prompt === undefined || params.prompt === '') return invalidRequest("you must provide a prompt parameter", 'prompt');
-  const n = Number(params.n ?? 1);
-  const count = Number.isInteger(n) && n > 0 ? n : 1;
-  const data = Array.from({ length: count }, (_, i) => ({ url: `https://twin.invalid/openai-image-edit-stub/${nowEpoch(occurredAt)}-${i}.png` }));
+  const model = modelOf('createImageEdit', params)!;
+  const bytes = partBytes(image);
+  const format = bytes && imageFormat(bytes);
+  if (gptImage(model) ? !format : format !== 'png' || !square(bytes!)) return badImage(gptImage(model) ? 'a png, webp, or jpg file' : 'a square png file');
+  const size = requestedSize(params.size, format === 'png' ? pngSize(bytes!) : undefined);
+  const data = Array.from({ length: imageCount(params) }, (_, i) => imageData(params, model, size, String(params.prompt), 'image-edit', i, occurredAt));
+  if (gptImage(model)) return gptImageAnswer(params, size, data, 'image_edit', occurredAt);
   return { status: 200, body: { created: nowEpoch(occurredAt), data } };
 }
-function handleImageVariation(params: Record<string, unknown>, occurredAt?: string): OpenAIResponseEnvelope {
+const square = (png: Uint8Array): boolean => { const s = pngSize(png); return s.width === s.height; };
+export function handleImageVariation(params: Record<string, unknown>, occurredAt?: string): OpenAIResponseEnvelope {
   if (params.image === undefined || params.image === '') return invalidRequest("you must provide an image", 'image');
-  const n = Number(params.n ?? 1);
-  const count = Number.isInteger(n) && n > 0 ? n : 1;
-  const data = Array.from({ length: count }, (_, i) => ({ url: `https://twin.invalid/openai-image-variation-stub/${nowEpoch(occurredAt)}-${i}.png` }));
+  const bytes = partBytes(params.image);
+  if (!bytes || imageFormat(bytes) !== 'png' || !square(bytes)) return badImage('a valid square png file');
+  const size = requestedSize(params.size);
+  const data = Array.from({ length: imageCount(params) }, (_, i) => imageData(params, modelOf('createImageVariation', params)!, size, 'variation', 'image-variation', i, occurredAt));
   return { status: 200, body: { created: nowEpoch(occurredAt), data } };
 }
 
-// ── Audio (deterministic stubs; real model output is out of scope) ──────────────────────
+// ── Audio (deterministic stubs; the twin runs no model) ──────────────────────
 // Transcription/translation cannot run a real speech model, so the twin returns a clearly
-// labeled deterministic transcript derived from the supplied filename/text. The response SHAPE
+// labeled deterministic transcript naming the uploaded file. It takes the audio file itself, in a
+// format OpenAI transcribes (./openai-media.ts), never a file's name. The response SHAPE
 // (json / verbose_json / text) is vendor-faithful.
-function handleTranscription(params: Record<string, unknown>, translate: boolean): OpenAIResponseEnvelope {
-  // The server adapts multipart → JSON { file (filename), model, response_format, language }.
+/** A multipart list field (`include[]`, `timestamp_granularities[]`), however the form named it. */
+function formList(params: Record<string, unknown>, name: string): string[] {
+  const v = params[name] ?? params[`${name}[]`];
+  return (Array.isArray(v) ? v : v === undefined ? [] : [v]).map(String);
+}
+
+/** What a transcription is billed on: the GPT-4o transcribe models by tokens, whisper-1 and the diarizing model by the
+ *  audio's seconds (https://platform.openai.com/docs/api-reference/audio/json-object, `usage`). The twin counts ten
+ *  audio tokens a second and its transcript's text tokens; neither is a model's count. */
+function transcriptionUsage(model: string, seconds: number, text: string): Record<string, unknown> {
+  if (model.startsWith('whisper') || model.includes('diarize')) return { type: 'duration', seconds: Math.ceil(seconds) };
+  const audio = Math.ceil(seconds * 10);
+  const out = estimateTokens(text);
+  return { type: 'tokens', input_tokens: audio, input_token_details: { text_tokens: 0, audio_tokens: audio }, output_tokens: out, total_tokens: audio + out };
+}
+
+/** The transcript's words spread evenly over the audio: the twin hears nothing, so its timings are the file's length
+ *  shared out, not a model's alignment. */
+function words(text: string, seconds: number): Array<{ word: string; start: number; end: number }> {
+  const all = text.split(/\s+/).filter(Boolean);
+  const each = seconds / Math.max(1, all.length);
+  return all.map((word, i) => ({ word, start: i * each, end: (i + 1) * each }));
+}
+
+export type Transcription = { status: 200; body: unknown; seconds: number; events?: Array<{ data: unknown }> } | OpenAIResponseEnvelope;
+
+/** A transcription (or translation) of the uploaded audio: a labeled transcript naming the file, in the response
+ *  format asked (json, text, verbose_json with the word or segment timestamps asked, or diarized_json), with the
+ *  token log probabilities when `include[]=logprobs`, and as `transcript.text.delta` events then
+ *  `transcript.text.done` when `stream=true` on a model that streams (https://platform.openai.com/docs/api-reference/audio/createTranscription). */
+export function handleTranscription(params: Record<string, unknown>, translate: boolean): Transcription {
   if (params.file === undefined || params.file === '') return invalidRequest("you must provide a file parameter", 'file');
   if (params.model === undefined || params.model === '') return invalidRequest("you must provide a model parameter", 'model');
-  const filename = String(params.file);
+  const bytes = partBytes(params.file);
+  if (!bytes || !audioFormat(bytes)) return invalidRequest("Invalid file format. Supported formats: ['flac', 'm4a', 'mp3', 'mp4', 'mpeg', 'mpga', 'oga', 'ogg', 'wav', 'webm']", 'file', 'invalid_value');
+  const filename = String((params.file as { name?: string }).name || 'upload');
+  const model = String(params.model);
   const verb = translate ? 'translation' : 'transcription';
   const text = `[twin-stub] deterministic ${verb} of ${filename} (no speech model is run)`;
   const format = typeof params.response_format === 'string' ? params.response_format : 'json';
-  if (format === 'text') return { status: 200, body: text };
+  // the file's own length where the twin can read it (a WAV's header), else a labeled second
+  const duration = wavSeconds(bytes) ?? 1.0;
+  if (format === 'text') return { status: 200, body: text, seconds: duration };
+  if (translate) return { status: 200, seconds: duration, body: format === 'verbose_json' ? { task: 'translation', language: 'english', duration, text, segments: [{ id: 0, start: 0, end: duration, text }] } : { text } };
+  const usage = transcriptionUsage(model, duration, text);
+  if (format === 'diarized_json') {
+    // one speaker the twin cannot tell apart: the first name the caller knows, else OpenAI's first label
+    const speaker = formList(params, 'known_speaker_names')[0] ?? 'A';
+    return { status: 200, seconds: duration, body: { task: 'transcribe', duration, text, segments: [{ type: 'transcript.text.segment', id: 'seg_001', start: 0, end: duration, text, speaker }], usage } };
+  }
   if (format === 'verbose_json') {
-    return { status: 200, body: { task: verb, language: translate ? 'english' : (typeof params.language === 'string' ? params.language : 'english'), duration: 1.0, text, segments: [{ id: 0, start: 0, end: 1, text }] } };
+    const granularities = formList(params, 'timestamp_granularities');
+    const segment = { id: 0, seek: 0, start: 0, end: duration, text, tokens: [], temperature: 0, avg_logprob: 0, compression_ratio: 1, no_speech_prob: 0 };
+    return {
+      status: 200,
+      seconds: duration,
+      body: {
+        task: 'transcribe', language: typeof params.language === 'string' ? params.language : 'english', duration, text,
+        ...(granularities.includes('word') ? { words: words(text, duration) } : {}),
+        ...(!granularities.length || granularities.includes('segment') ? { segments: [segment] } : {}),
+        usage,
+      },
+    };
   }
-  return { status: 200, body: { text } };
-}
-// Text-to-speech: cannot synthesize real audio (out of scope), but the endpoint returns audio
-// bytes deterministically derived from the input so the round-trip shape is faithful.
-function handleSpeech(params: Record<string, unknown>): OpenAIResponseEnvelope {
+  const logprobs = formList(params, 'include').includes('logprobs') ? buildLogprobs(text, 0).content.map(({ token, logprob, bytes: b }) => ({ token, logprob, bytes: b })) : undefined;
+  const body = { text, ...(logprobs ? { logprobs } : {}), usage };
+  // whisper-1 does not stream ("Streaming is not supported for the whisper-1 model and will be ignored")
+  if (String(params.stream) === 'true' && !model.startsWith('whisper')) {
+    const pieces = text.match(/\s*\S+/g) ?? [];
+    const events = pieces.map((delta) => ({ data: { type: 'transcript.text.delta', delta, ...(logprobs ? { logprobs: buildLogprobs(delta, 0).content.map(({ token, logprob, bytes: b }) => ({ token, logprob, bytes: b })) } : {}) } }));
+    events.push({ data: { type: 'transcript.text.done', text, ...(logprobs ? { logprobs } : {}), usage } as never });
+    return { status: 200, body, seconds: duration, events };
+  }
+  return { status: 200, body, seconds: duration };
+}
+// Text-to-speech: runs no speech model, but answers the audio file itself in the requested format, as OpenAI does
+// (a second of silence: ./openai-media.ts), with that format's Content-Type.
+const SPEECH: Record<string, { type: string; file: () => Uint8Array }> = {
+  mp3: { type: 'audio/mpeg', file: silentMp3 },
+  opus: { type: 'audio/opus', file: silentOpus },
+  aac: { type: 'audio/aac', file: silentAac },
+  flac: { type: 'audio/flac', file: silentFlac },
+  wav: { type: 'audio/wav', file: silentWav },
+  pcm: { type: 'audio/pcm', file: silentPcm },
+};
+export function handleSpeech(params: Record<string, unknown>): OpenAIResponseEnvelope | { status: 200; audio: Uint8Array; type: string } {
   if (params.model === undefined || params.model === '') return invalidRequest("you must provide a model parameter", 'model');
   if (params.input === undefined || params.input === '') return invalidRequest("you must provide an input parameter", 'input');
   if (params.voice === undefined || params.voice === '') return invalidRequest("you must provide a voice parameter", 'voice');
-  // Deterministic placeholder "audio" payload (base64 of a labeled stub), never real audio.
-  const marker = `[twin-stub-audio] voice=${String(params.voice)} format=${String(params.response_format ?? 'mp3')} text=${String(params.input)}`;
-  return { status: 200, body: { object: 'audio.speech', audio_base64: btoa(marker), format: String(params.response_format ?? 'mp3') } };
-}
-
-// ── Vector store search (deterministic ranking over attached files) ──────────────────────
-// The twin can't run a real similarity search (no embeddings of file content), so it returns
-// the attached files ranked by a deterministic pseudo-score seeded from (query, file_id). The
-// response SHAPE (object:vector_store.search_results.page, data[].score/file_id/content) is faithful.
-function searchScore(query: string, fileId: string): number {
-  let h = 0x811c9dc5;
-  const s = query + '|' + fileId;
-  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193); }
-  return (h >>> 0) / 0xffffffff;
-}
-
-// ── Evals API (stateful: eval config → runs → output items) ──────────────────────────────
-// The Evals API systematically evaluates model output. The twin cannot run a real grader, so a
-// run completes immediately with a deterministic synthetic result + one output item per datasource
-// item (passed, since the twin's stub output is graded by a deterministic stub grader). The eval/
-// run/output-item SHAPES are vendor-faithful; the grading values are clearly-deterministic stubs.
-async function createEval(params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  if (params.data_source_config === undefined) return invalidRequest("you must provide a data_source_config parameter", 'data_source_config');
-  if (params.testing_criteria === undefined || !Array.isArray(params.testing_criteria)) return invalidRequest("you must provide a testing_criteria parameter (array)", 'testing_criteria');
-  const id = nextId('eval', 'eval', req.root);
-  const fields = {
-    object: 'eval',
-    name: typeof params.name === 'string' ? params.name : `eval-${id}`,
-    created_at: nowEpoch(req.occurredAt),
-    data_source_config: params.data_source_config,
-    testing_criteria: params.testing_criteria,
-    metadata: (params.metadata && typeof params.metadata === 'object') ? params.metadata : {},
-  };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'eval.create', subjectType: 'eval', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return { status: 200, body: idView(resource) };
-}
-function evalView(r: Record<string, unknown>): Record<string, unknown> {
-  return { id: r.id, ...strip(r) };
-}
-// A run records a synthetic per-model usage + a result_counts of passed items. The twin grades a
-// fixed single datasource item (the twin cannot fetch a real dataset) → 1 passed item.
-async function createEvalRun(evalId: string, params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  if (params.data_source === undefined) return invalidRequest("you must provide a data_source parameter", 'data_source');
-  const id = nextId('evalrun', 'evalrun', req.root);
-  const created = nowEpoch(req.occurredAt);
-  const model = typeof (params.data_source as { model?: unknown })?.model === 'string' ? String((params.data_source as { model?: unknown }).model) : 'gpt-4o';
-  const fields = {
-    object: 'eval.run',
-    eval_id: evalId,
-    name: typeof params.name === 'string' ? params.name : `run-${id}`,
-    created_at: created,
-    status: 'completed',
-    model,
-    data_source: params.data_source,
-    result_counts: { total: 1, errored: 0, failed: 0, passed: 1 },
-    per_model_usage: [{ model_name: model, invocation_count: 1, prompt_tokens: 0, completion_tokens: 0, total_tokens: 0, cached_tokens: 0 }],
-    per_testing_criteria_results: [{ testing_criteria: 'twin-stub-grader', passed: 1, failed: 0 }],
-    report_url: `https://twin.invalid/evals/${evalId}/runs/${id}`,
-    metadata: (params.metadata && typeof params.metadata === 'object') ? params.metadata : {},
-    error: null,
-  };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'eval_run.create', subjectType: 'eval_run', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return { status: 200, body: evalRunView(resource) };
-}
-function evalRunView(r: Record<string, unknown>): Record<string, unknown> {
-  return { id: r.id, ...strip(r) };
-}
-// The output items for a completed run: a single deterministic passed item (the twin's stub
-// output graded by a deterministic stub grader). Shape: object:'eval.run.output_item'.
-function evalRunOutputItems(run: Record<string, unknown>): Array<Record<string, unknown>> {
-  const created = Number(run.created_at ?? 0);
-  return [{
-    id: `evalitem-${run.id}-1`,
-    object: 'eval.run.output_item',
-    created_at: created,
-    run_id: String(run.id),
-    eval_id: String(run.eval_id),
-    status: 'pass',
-    datasource_item_id: 0,
-    datasource_item: { item: { input: '[twin-stub] datasource item' } },
-    results: [{ name: 'twin-stub-grader', passed: true, score: 1.0 }],
-    sample: { input: [], output: [{ role: 'assistant', content: '[twin-stub] eval sample output (no real model run)' }], finish_reason: 'stop', model: String(run.model ?? 'gpt-4o'), usage: { total_tokens: 0, completion_tokens: 0, prompt_tokens: 0, cached_tokens: 0 }, error: null },
-  }];
-}
-
-// ── Containers API (code-interpreter sandboxes: container → container files) ──────────────
-// A container is an isolated sandbox for the code_interpreter tool. The twin cannot run a real
-// sandbox, so a container is created `running` and its files are stored faithfully (metadata +
-// supplied text content, like the Files API). The SHAPES are vendor-faithful.
-async function createContainer(params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  if (params.name === undefined || params.name === '') return invalidRequest("you must provide a name parameter", 'name');
-  const id = nextId('container', 'cntr', req.root);
-  const created = nowEpoch(req.occurredAt);
-  const fields = {
-    object: 'container',
-    name: String(params.name),
-    created_at: created,
-    status: 'running',
-    last_active_at: created,
-    expires_after: (params.expires_after && typeof params.expires_after === 'object') ? params.expires_after : { anchor: 'last_active_at', minutes: 20 },
-  };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'container.create', subjectType: 'container', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return { status: 200, body: containerView(resource) };
-}
-function containerView(r: Record<string, unknown>): Record<string, unknown> {
-  return { id: r.id, ...strip(r) };
-}
-async function createContainerFile(containerId: string, params: Record<string, unknown>, req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
-  // The server adapts a multipart upload (or a JSON { file_id } reference) into JSON; the twin
-  // accepts either an inline `content`+`path` (text) or a `file_id` referencing a stored File.
-  const seq = rows('container_file', req.root).filter((r) => r.container_id === containerId).length + 1;
-  const id = `cfile-twin-${containerId}-${seq}`;
-  const created = nowEpoch(req.occurredAt);
-  let content = '';
-  let source = 'user';
-  if (typeof params.file_id === 'string' && params.file_id) {
-    const f = getRow('file', params.file_id, req.root);
-    if (!f || f._deleted) return notFound(`No such File object: ${String(params.file_id)}`);
-    content = String(f._content ?? '');
-    source = 'file_id';
-  } else if (typeof params.content === 'string') {
-    content = params.content;
-  }
-  const path = typeof params.path === 'string' && params.path ? params.path : `/mnt/data/${id}`;
-  const fields = {
-    object: 'container.file',
-    container_id: containerId,
-    created_at: created,
-    bytes: content.length,
-    path,
-    source,
-    _content: content,
-  };
-  const { resource } = await applyTwinWrite(SERVICE, { operation: 'container_file.create', subjectType: 'container_file', subjectId: id, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-  return { status: 200, body: containerFileView(resource) };
-}
-function containerFileView(r: Record<string, unknown>): Record<string, unknown> {
-  return { id: r.id, ...strip(r) };
-}
-
-// ── public entry: cross-cutting protocol (auth / rate-limit / idempotency) then route ─────
-// The HTTP server passes request headers, so on the live wire every call is auth/rate-limit/
-// idempotency-checked; in-process trusted calls (capability verify, connector) omit `headers`/
-// `apiKey` and are NOT gated. Idempotency-Key dedup wraps the WHOLE request so any successful
-// mutation is replayed verbatim on a re-issue with the same key.
+  const format = SPEECH[String(params.response_format ?? 'mp3')];
+  if (!format) return invalidRequest("'response_format' must be one of 'mp3', 'opus', 'aac', 'flac', 'wav', 'pcm'", 'response_format');
+  return { status: 200, audio: format.file(), type: format.type };
+}
+
+// ── public entry: cross-cutting protocol (auth / rate-limit) then route ─────────────────────
+// The HTTP server passes request headers, so on the live wire every call is auth/rate-limit-
+// checked; in-process trusted calls (capability verify, connector) omit `headers`/`apiKey` and are
+// NOT gated.
+/** OpenAI's API as one call: the request goes through the pack's own dispatch (the derived dispatch over its
+ *  semantics, its derived core and the hand-written routes below), so a caller that holds no HTTP
+ *  server reaches exactly what an SDK does. A caller that presents no credential is a trusted
+ *  in-process caller and is not held to the auth rule; `sseSink` receives a stream's events. */
 export async function handleOpenAITwinRequest(req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
+  const twin = createOpenAITwinFetch({
+    ...(req.root !== undefined ? { root: req.root } : {}),
+    readOnly: req.readOnly ?? false,
+    ...(req.scenarioEngine ? { scenarioEngine: req.scenarioEngine } : {}),
+    ...(req.occurredAt ? { clock: () => req.occurredAt! } : {}),
+  });
+  const headers: Record<string, string> = { ...(req.headers ?? {}) };
+  if (req.apiKey !== undefined) headers.authorization = `Bearer ${req.apiKey}`;
+  else if (req.headers === undefined) headers.authorization = 'Bearer sk-twin-in-process';
   const method = req.method.toUpperCase();
-
-  // Modeled authentication (401). Gated only when the request carries an auth surface.
-  if (req.headers !== undefined || req.apiKey !== undefined) {
-    const authErr = checkAuth(req);
-    if (authErr) return authErr;
-  }
-  // Modeled rate limiting (429) — deterministic opt-in trigger header.
-  if (rateLimitTriggered(req)) return rateLimitError();
-
-  // Idempotency-Key: a re-issue with the same key replays the prior response byte-for-byte. Only
-  // mutations (non-GET) are keyed (matching the vendor), and only 2xx results are cached.
-  const idemKey = method !== 'GET' ? req.headers?.['idempotency-key'] : undefined;
-  if (idemKey) {
-    const cached = getIdempotentResult(idemKey, req.root);
-    if (cached) return cached;
-    const result = await routeOpenAI(req, method);
-    if (result.status >= 200 && result.status < 300) await storeIdempotentResult(idemKey, result, req);
-    return result;
-  }
-  return routeOpenAI(req, method);
-}
-
-// ── router ──────────────────────────────────────────────────────────────────────────────
-async function routeOpenAI(req: OpenAIRequest, method: string): Promise<OpenAIResponseEnvelope> {
-  const path = (req.path.split('?')[0] ?? '/').replace(/\/+$/, '') || '/';
-  const seg = path.replace(/^\/+/, '').split('/'); // ["v1","chat","completions",...]
-  const params = parseJson(req.body);
-  const dec = (s: string) => decodeURIComponent(s);
-
-  // D3: a read-only twin rejects any mutation with a vendor-shaped error.
-  if (req.readOnly && method !== 'GET') {
-    return { status: 405, body: errBody('invalid_request_error', 'twin is read-only; omit readOnly to accept writes', 'method_not_allowed') };
-  }
-
-  // ---- models (static catalog + fine-tuned models minted by fine-tuning jobs) ----
-  if (path === '/v1/models' && method === 'GET') {
-    // List the static catalog plus every (non-deleted) fine-tuned model produced by a job.
-    return { status: 200, body: { object: 'list', data: [...OPENAI_MODELS, ...fineTunedModels(req.root)] } };
-  }
-  if (seg[1] === 'models' && seg.length === 3 && method === 'GET') {
-    const mid = dec(seg[2]!);
-    const m = findModel(mid) ?? fineTunedModels(req.root).find((fm) => fm.id === mid);
-    return m ? { status: 200, body: m } : notFound(`The model '${mid}' does not exist`, 'model_not_found');
-  }
-  // Delete a fine-tuned model (only models you own — base catalog models can't be deleted).
-  if (seg[1] === 'models' && seg.length === 3 && method === 'DELETE') {
-    const mid = dec(seg[2]!);
-    if (findModel(mid)) return invalidRequest(`The model '${mid}' cannot be deleted`, 'model', 'model_not_deletable');
-    const ft = fineTunedModels(req.root).find((fm) => fm.id === mid);
-    if (!ft) return notFound(`The model '${mid}' does not exist`, 'model_not_found');
-    await applyTwinWrite(SERVICE, { operation: 'model.delete', subjectType: 'model', subjectId: mid, fields: { _deleted: true, object: 'model' }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: { id: mid, object: 'model', deleted: true } };
-  }
-
-  // ---- stored chat completions (store:true) — retrieve / list / messages / delete ----
-  // (must precede the generic create route below; these are GET/DELETE on the same prefix.)
-  if (path === '/v1/chat/completions' && method === 'GET') {
-    const items = rows('chat_completion', req.root).filter((r) => !r._deleted).map(storedChatView).sort((a, b) => Number(b.created) - Number(a.created));
-    return { status: 200, body: paginate(items, req.path) };
-  }
-  if (seg[1] === 'chat' && seg[2] === 'completions' && seg.length === 4 && method === 'GET') {
-    const c = getRow('chat_completion', dec(seg[3]!), req.root);
-    return c && !c._deleted ? { status: 200, body: storedChatView(c) } : notFound(`No chat completion found with id '${dec(seg[3]!)}'.`);
-  }
-  if (seg[1] === 'chat' && seg[2] === 'completions' && seg.length === 5 && seg[4] === 'messages' && method === 'GET') {
-    const c = getRow('chat_completion', dec(seg[3]!), req.root);
-    if (!c || c._deleted) return notFound(`No chat completion found with id '${dec(seg[3]!)}'.`);
-    const msgs = ((c as { _input_messages?: unknown })._input_messages as unknown[]) ?? [];
-    return { status: 200, body: paginate(msgs as Array<Record<string, unknown>>, req.path) };
-  }
-  if (seg[1] === 'chat' && seg[2] === 'completions' && seg.length === 4 && method === 'DELETE') {
-    const cid = dec(seg[3]!);
-    const c = getRow('chat_completion', cid, req.root);
-    if (!c || c._deleted) return notFound(`No chat completion found with id '${cid}'.`);
-    await applyTwinWrite(SERVICE, { operation: 'chat_completion.delete', subjectType: 'chat_completion', subjectId: cid, fields: { _deleted: true }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: { id: cid, object: 'chat.completion.deleted', deleted: true } };
-  }
-
-  // ---- chat completions (the generative stub; envelope is faithful) ----
-  if (path === '/v1/chat/completions' && method === 'POST') {
-    const validated = validateChat(params);
-    if ('error' in validated) return validated.error;
-    const args = validated.args;
-    let result: ChatCompletion;
-    if (args.stream && req.sseSink) result = streamChat(args, req.sseSink, req.occurredAt, req.scenarioEngine);
-    else result = buildChatCompletion(args, req.occurredAt, req.scenarioEngine);
-    // store:true → persist the completion so it can be retrieved/listed later (stored completions).
-    if (args.store) await storeChatCompletion(result, args, req);
-    await recordUsage(req, 'completions', result.model, result.usage.prompt_tokens, result.usage.completion_tokens);
-    return { status: 200, body: result };
-  }
-
-  // ---- responses API ----
-  if (path === '/v1/responses' && method === 'POST') {
-    const validated = validateResponses(params);
-    if ('error' in validated) return validated.error;
-    const args = validated.args;
-    // previous_response_id chaining: the referenced response must exist; its assistant output is
-    // folded into the prompt context (so usage reflects the chained history — server-side state).
-    if (args.previousResponseId) {
-      const prior = getRow('response', args.previousResponseId, req.root);
-      if (!prior || prior._deleted) return notFound(`Response with id '${args.previousResponseId}' not found.`);
-      const priorText = String((prior as { output_text?: unknown }).output_text ?? '');
-      args.messages = [{ role: 'assistant', content: priorText }, ...args.messages];
-    }
-    // Deterministic stored-response id (hash of model+input+chain) so retrieval is assertable.
-    const suffix = responseSuffix(args);
-    // background:true → the response is created `queued` and processed asynchronously. The twin has
-    // nothing to run in the background, so it persists a queued response that the FIRST poll
-    // (GET /v1/responses/:id) transitions to `completed` (computing the real stub output then). The
-    // queued envelope carries no output yet; background implies store (so it can be polled/cancelled).
-    if (args.background) {
-      const queued = await storeQueuedResponse(args, req, suffix);
-      return { status: 200, body: responseView(queued) };
-    }
-    if (args.stream) {
-      const resp = req.sseSink ? streamResponse(args, req.sseSink, req.occurredAt, suffix) : buildResponse(args, req.occurredAt, suffix);
-      if (args.store) await storeResponse(resp, args, req);
-      await recordUsage(req, 'responses', resp.model, resp.usage.input_tokens, resp.usage.output_tokens);
-      return { status: 200, body: resp };
-    }
-    const resp = buildResponse(args, req.occurredAt, suffix);
-    if (args.store) await storeResponse(resp, args, req);
-    await recordUsage(req, 'responses', resp.model, resp.usage.input_tokens, resp.usage.output_tokens);
-    return { status: 200, body: resp };
-  }
-  // Responses: retrieve / delete a stored response by id.
-  if (seg[1] === 'responses' && seg.length === 3 && method === 'GET') {
-    const r = getRow('response', dec(seg[2]!), req.root);
-    if (!r || r._deleted) return notFound(`Response with id '${dec(seg[2]!)}' not found.`);
-    // A queued background response is processed on first poll: transition queued → completed,
-    // computing the real stub output + usage at that point (then record billable usage once).
-    if (r.status === 'queued') {
-      const completed = await completeQueuedResponse(r, req);
-      return { status: 200, body: responseView(completed) };
-    }
-    return { status: 200, body: responseView(r) };
-  }
-  // Responses: cancel a background response (only a queued/in_progress one can be cancelled).
-  if (seg[1] === 'responses' && seg.length === 4 && seg[3] === 'cancel' && method === 'POST') {
-    const rid = dec(seg[2]!);
-    const r = getRow('response', rid, req.root);
-    if (!r || r._deleted) return notFound(`Response with id '${rid}' not found.`);
-    if (r.status !== 'queued' && r.status !== 'in_progress') {
-      return invalidRequest(`Cannot cancel a response with status '${String(r.status)}'.`, null, 'invalid_status');
-    }
-    const { resource } = await applyTwinWrite(SERVICE, { operation: 'response.cancel', subjectType: 'response', subjectId: rid, fields: { status: 'cancelled' }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: responseView(resource) };
-  }
-  if (seg[1] === 'responses' && seg.length === 3 && method === 'DELETE') {
-    const rid = dec(seg[2]!);
-    const r = getRow('response', rid, req.root);
-    if (!r || r._deleted) return notFound(`Response with id '${rid}' not found.`);
-    await applyTwinWrite(SERVICE, { operation: 'response.delete', subjectType: 'response', subjectId: rid, fields: { _deleted: true }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: { id: rid, object: 'response.deleted', deleted: true } };
-  }
-  // Responses: list the input items of a stored response (the user turns folded into it).
-  if (seg[1] === 'responses' && seg.length === 4 && seg[3] === 'input_items' && method === 'GET') {
-    const r = getRow('response', dec(seg[2]!), req.root);
-    if (!r || r._deleted) return notFound(`Response with id '${dec(seg[2]!)}' not found.`);
-    const items = ((r as { _input_items?: unknown })._input_items as unknown[]) ?? [];
-    return { status: 200, body: { object: 'list', data: items, has_more: false } };
-  }
-
-  // ---- embeddings ----
-  if (path === '/v1/embeddings' && method === 'POST') {
-    const res = handleEmbeddings(params);
-    if (res.status === 200) {
-      const b = res.body as EmbeddingResponse;
-      await recordUsage(req, 'embeddings', b.model, b.usage.prompt_tokens, 0);
-    }
-    return res;
-  }
-
-  // ---- moderations ----
-  if (path === '/v1/moderations' && method === 'POST') {
-    return handleModerations(params, req.occurredAt);
-  }
-
-  // ---- images ----
-  if (path === '/v1/images/generations' && method === 'POST') {
-    return handleImages(params, req.occurredAt);
-  }
-  if (path === '/v1/images/edits' && method === 'POST') return handleImageEdit(params, req.occurredAt);
-  if (path === '/v1/images/variations' && method === 'POST') return handleImageVariation(params, req.occurredAt);
-
-  // ---- audio ----
-  if (path === '/v1/audio/transcriptions' && method === 'POST') return handleTranscription(params, false);
-  if (path === '/v1/audio/translations' && method === 'POST') return handleTranscription(params, true);
-  if (path === '/v1/audio/speech' && method === 'POST') return handleSpeech(params);
-
-  // ---- files (stateful) ----
-  if (path === '/v1/files' && method === 'POST') return createFile(params, req);
-  if (path === '/v1/files' && method === 'GET') {
-    const items = rows('file', req.root).filter((r) => !r._deleted).map(fileView).sort((a, b) => Number(b.created_at) - Number(a.created_at));
-    return { status: 200, body: paginate(items, req.path) };
-  }
-  if (seg[1] === 'files' && seg.length === 3 && method === 'GET') {
-    const f = getRow('file', dec(seg[2]!), req.root);
-    return f && !f._deleted ? { status: 200, body: fileView(f) } : notFound(`No such File object: ${dec(seg[2]!)}`);
-  }
-  if (seg[1] === 'files' && seg.length === 4 && seg[3] === 'content' && method === 'GET') {
-    const f = getRow('file', dec(seg[2]!), req.root);
-    if (!f || f._deleted) return notFound(`No such File object: ${dec(seg[2]!)}`);
-    return { status: 200, body: (f._content as string) ?? '' };
-  }
-  if (seg[1] === 'files' && seg.length === 3 && method === 'DELETE') {
-    const id = dec(seg[2]!);
-    const f = getRow('file', id, req.root);
-    if (!f) return notFound(`No such File object: ${id}`);
-    await applyTwinWrite(SERVICE, { operation: 'file.delete', subjectType: 'file', subjectId: id, fields: { _deleted: true }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: { id, object: 'file', deleted: true } };
-  }
-
-  // ---- uploads (multipart large-file parts, stateful) ----
-  if (path === '/v1/uploads' && method === 'POST') return createUpload(params, req);
-  if (seg[1] === 'uploads' && seg.length === 4 && seg[3] === 'parts' && method === 'POST') return addUploadPart(dec(seg[2]!), params, req);
-  if (seg[1] === 'uploads' && seg.length === 4 && seg[3] === 'complete' && method === 'POST') return completeUpload(dec(seg[2]!), params, req);
-  if (seg[1] === 'uploads' && seg.length === 4 && seg[3] === 'cancel' && method === 'POST') {
-    const uid = dec(seg[2]!);
-    const up = getRow('upload', uid, req.root);
-    if (!up || up.status !== 'pending') return notFound(`No such Upload object: ${uid}`);
-    const { resource } = await applyTwinWrite(SERVICE, { operation: 'upload.cancel', subjectType: 'upload', subjectId: uid, fields: { status: 'cancelled' }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: uploadView(resource) };
-  }
-
-  // ---- batches (stateful) ----
-  if (path === '/v1/batches' && method === 'POST') return createBatch(params, req);
-  if (path === '/v1/batches' && method === 'GET') {
-    const items = rows('batch', req.root).map(batchView).sort((a, b) => Number(b.created_at) - Number(a.created_at));
-    return { status: 200, body: paginate(items, req.path) };
-  }
-  if (seg[1] === 'batches' && seg.length === 3 && method === 'GET') {
-    const b = getRow('batch', dec(seg[2]!), req.root);
-    return b ? { status: 200, body: batchView(b) } : notFound(`No such Batch object: ${dec(seg[2]!)}`);
-  }
-  if (seg[1] === 'batches' && seg.length === 4 && seg[3] === 'cancel' && method === 'POST') {
-    const id = dec(seg[2]!);
-    const b = getRow('batch', id, req.root);
-    if (!b) return notFound(`No such Batch object: ${id}`);
-    const { resource } = await applyTwinWrite(SERVICE, { operation: 'batch.cancel', subjectType: 'batch', subjectId: id, fields: { status: 'cancelled', cancelled_at: nowEpoch(req.occurredAt) }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: batchView(resource) };
-  }
-
-  // ---- moderations handled above ----
-
-  // ---- fine-tuning jobs (stateful) ----
-  if (path === '/v1/fine_tuning/jobs' && method === 'POST') return createFineTune(params, req);
-  if (path === '/v1/fine_tuning/jobs' && method === 'GET') {
-    const items = rows('fine_tuning_job', req.root).map(ftView).sort((a, b) => Number(b.created_at) - Number(a.created_at));
-    return { status: 200, body: paginate(items, req.path) };
-  }
-  if (seg[1] === 'fine_tuning' && seg[2] === 'jobs' && seg.length === 4 && method === 'GET') {
-    const j = getRow('fine_tuning_job', dec(seg[3]!), req.root);
-    return j ? { status: 200, body: ftView(j) } : notFound(`No such fine-tuning job: ${dec(seg[3]!)}`);
-  }
-  if (seg[1] === 'fine_tuning' && seg[2] === 'jobs' && seg.length === 5 && seg[4] === 'events' && method === 'GET') {
-    const j = getRow('fine_tuning_job', dec(seg[3]!), req.root);
-    if (!j) return notFound(`No such fine-tuning job: ${dec(seg[3]!)}`);
-    // Deterministic synthetic event stream for a completed twin job.
-    const created = Number(j.created_at ?? 0);
-    const events = [
-      { object: 'fine_tuning.job.event', id: `ftevent-${j.id}-1`, created_at: created, level: 'info', message: 'Created fine-tuning job', type: 'message' },
-      { object: 'fine_tuning.job.event', id: `ftevent-${j.id}-2`, created_at: created, level: 'info', message: 'Fine-tuning job successfully completed (twin stub)', type: 'message' },
-    ];
-    return { status: 200, body: { object: 'list', data: events, has_more: false } };
-  }
-  // Fine-tuning checkpoints: a completed job exposes its training checkpoints (one per epoch). The
-  // twin synthesizes a deterministic checkpoint per succeeded job (shape faithful; metrics are stubs).
-  if (seg[1] === 'fine_tuning' && seg[2] === 'jobs' && seg.length === 5 && seg[4] === 'checkpoints' && method === 'GET') {
-    const j = getRow('fine_tuning_job', dec(seg[3]!), req.root);
-    if (!j) return notFound(`No such fine-tuning job: ${dec(seg[3]!)}`);
-    const created = Number(j.created_at ?? 0);
-    // succeeded jobs have a final checkpoint pointing at the fine-tuned model; cancelled jobs have none.
-    const checkpoints = j.status === 'succeeded'
-      ? [{
-          object: 'fine_tuning.job.checkpoint',
-          id: `ftckpt-${j.id}-1`,
-          created_at: created,
-          fine_tuned_model_checkpoint: String(j.fine_tuned_model ?? `ft:twin::${j.id}:ckpt-step-1`),
-          fine_tuning_job_id: String(j.id),
-          metrics: { step: 1, train_loss: 0, train_mean_token_accuracy: 1, full_valid_loss: 0, full_valid_mean_token_accuracy: 1 },
-          step_number: 1,
-        }]
-      : [];
-    return { status: 200, body: { object: 'list', data: checkpoints, has_more: false, first_id: checkpoints[0]?.id ?? null, last_id: checkpoints[0]?.id ?? null } };
-  }
-  if (seg[1] === 'fine_tuning' && seg[2] === 'jobs' && seg.length === 5 && seg[4] === 'cancel' && method === 'POST') {
-    const id = dec(seg[3]!);
-    const j = getRow('fine_tuning_job', id, req.root);
-    if (!j) return notFound(`No such fine-tuning job: ${id}`);
-    const { resource } = await applyTwinWrite(SERVICE, { operation: 'fine_tuning_job.cancel', subjectType: 'fine_tuning_job', subjectId: id, fields: { status: 'cancelled' }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: ftView(resource) };
-  }
-  // Pause a fine-tuning job → status 'paused' (a deployable checkpoint is preserved). Only a
-  // running/queued/succeeded job can be paused; a cancelled job can't (vendor 400).
-  if (seg[1] === 'fine_tuning' && seg[2] === 'jobs' && seg.length === 5 && seg[4] === 'pause' && method === 'POST') {
-    const id = dec(seg[3]!);
-    const j = getRow('fine_tuning_job', id, req.root);
-    if (!j) return notFound(`No such fine-tuning job: ${id}`);
-    if (j.status === 'cancelled' || j.status === 'failed') return invalidRequest(`Cannot pause a job with status '${String(j.status)}'.`, null, 'invalid_status');
-    const { resource } = await applyTwinWrite(SERVICE, { operation: 'fine_tuning_job.pause', subjectType: 'fine_tuning_job', subjectId: id, fields: { status: 'paused' }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: ftView(resource) };
-  }
-  // Resume a paused fine-tuning job → status back to 'succeeded' (the twin's terminal state, since
-  // it cannot actually train). Only a paused job can be resumed (vendor 400 otherwise).
-  if (seg[1] === 'fine_tuning' && seg[2] === 'jobs' && seg.length === 5 && seg[4] === 'resume' && method === 'POST') {
-    const id = dec(seg[3]!);
-    const j = getRow('fine_tuning_job', id, req.root);
-    if (!j) return notFound(`No such fine-tuning job: ${id}`);
-    if (j.status !== 'paused') return invalidRequest(`Cannot resume a job with status '${String(j.status)}'.`, null, 'invalid_status');
-    const { resource } = await applyTwinWrite(SERVICE, { operation: 'fine_tuning_job.resume', subjectType: 'fine_tuning_job', subjectId: id, fields: { status: 'succeeded' }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: ftView(resource) };
-  }
-
-  // ---- vector stores (stateful) ----
-  if (path === '/v1/vector_stores' && method === 'POST') return createVectorStore(params, req);
-  if (path === '/v1/vector_stores' && method === 'GET') {
-    const items = rows('vector_store', req.root).filter((r) => !r._deleted).map(vsView).sort((a, b) => Number(b.created_at) - Number(a.created_at));
-    return { status: 200, body: paginate(items, req.path) };
-  }
-  if (seg[1] === 'vector_stores' && seg.length === 3 && method === 'GET') {
-    const v = getRow('vector_store', dec(seg[2]!), req.root);
-    return v && !v._deleted ? { status: 200, body: vsView(v) } : notFound(`No such vector store: ${dec(seg[2]!)}`);
-  }
-  if (seg[1] === 'vector_stores' && seg.length === 3 && method === 'DELETE') {
-    const id = dec(seg[2]!);
-    const v = getRow('vector_store', id, req.root);
-    if (!v) return notFound(`No such vector store: ${id}`);
-    await applyTwinWrite(SERVICE, { operation: 'vector_store.delete', subjectType: 'vector_store', subjectId: id, fields: { _deleted: true }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: { id, object: 'vector_store.deleted', deleted: true } };
-  }
-  if (seg[1] === 'vector_stores' && seg.length === 4 && seg[3] === 'files' && method === 'POST') {
-    const storeId = dec(seg[2]!);
-    if (!getRow('vector_store', storeId, req.root)) return notFound(`No such vector store: ${storeId}`);
-    if (params.file_id === undefined || params.file_id === '') return invalidRequest("you must provide a file_id parameter", 'file_id');
-    const view = await addVectorStoreFile(storeId, String(params.file_id), req);
-    return { status: 200, body: view };
-  }
-  if (seg[1] === 'vector_stores' && seg.length === 4 && seg[3] === 'files' && method === 'GET') {
-    const storeId = dec(seg[2]!);
-    if (!getRow('vector_store', storeId, req.root)) return notFound(`No such vector store: ${storeId}`);
-    const all = rows('vector_store_file', req.root).filter((r) => r.vector_store_id === storeId && !r._deleted).map(vsFileView);
-    return { status: 200, body: paginate(all, req.path) };
-  }
-  // Vector store FILE BATCHES: bulk-attach a list of file_ids to a store in one call. The twin
-  // attaches each file as a vector_store.file child, then returns a batch object (status completed,
-  // since the twin has nothing to process async). Retrieve + list-files re-read the batch.
-  if (seg[1] === 'vector_stores' && seg.length === 4 && seg[3] === 'file_batches' && method === 'POST') {
-    const storeId = dec(seg[2]!);
-    if (!getRow('vector_store', storeId, req.root)) return notFound(`No such vector store: ${storeId}`);
-    if (!Array.isArray(params.file_ids) || params.file_ids.length === 0) return invalidRequest("you must provide a non-empty file_ids array", 'file_ids');
-    const fileIds = (params.file_ids as unknown[]).map(String);
-    const batchId = nextId('vector_store_file_batch', 'vsfb', req.root);
-    for (const fid of fileIds) await addVectorStoreFile(storeId, fid, req, batchId);
-    const created = nowEpoch(req.occurredAt);
-    const fields = {
-      object: 'vector_store.file_batch',
-      vector_store_id: storeId,
-      created_at: created,
-      status: 'completed',
-      file_counts: { in_progress: 0, completed: fileIds.length, failed: 0, cancelled: 0, total: fileIds.length },
-      _file_ids: fileIds,
-    };
-    const { resource } = await applyTwinWrite(SERVICE, { operation: 'vector_store_file_batch.create', subjectType: 'vector_store_file_batch', subjectId: batchId, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: vsBatchView(resource) };
-  }
-  if (seg[1] === 'vector_stores' && seg.length === 5 && seg[3] === 'file_batches' && method === 'GET') {
-    const storeId = dec(seg[2]!);
-    if (!getRow('vector_store', storeId, req.root)) return notFound(`No such vector store: ${storeId}`);
-    const b = getRow('vector_store_file_batch', dec(seg[4]!), req.root);
-    return b && b.vector_store_id === storeId ? { status: 200, body: vsBatchView(b) } : notFound(`No such file batch: ${dec(seg[4]!)}`);
-  }
-  if (seg[1] === 'vector_stores' && seg.length === 6 && seg[3] === 'file_batches' && seg[5] === 'files' && method === 'GET') {
-    const storeId = dec(seg[2]!);
-    if (!getRow('vector_store', storeId, req.root)) return notFound(`No such vector store: ${storeId}`);
-    const batchId = dec(seg[4]!);
-    if (!getRow('vector_store_file_batch', batchId, req.root)) return notFound(`No such file batch: ${batchId}`);
-    const all = rows('vector_store_file', req.root).filter((r) => r.vector_store_id === storeId && r._batch_id === batchId && !r._deleted).map(vsFileView);
-    return { status: 200, body: paginate(all, req.path) };
-  }
-
-  // Vector store search: deterministic ranked results over the store's attached files.
-  if (seg[1] === 'vector_stores' && seg.length === 4 && seg[3] === 'search' && method === 'POST') {
-    const storeId = dec(seg[2]!);
-    if (!getRow('vector_store', storeId, req.root)) return notFound(`No such vector store: ${storeId}`);
-    if (params.query === undefined || params.query === '') return invalidRequest("you must provide a query parameter", 'query');
-    const query = typeof params.query === 'string' ? params.query : JSON.stringify(params.query);
-    const files = rows('vector_store_file', req.root).filter((r) => r.vector_store_id === storeId && !r._deleted);
-    const maxResults = Number.isInteger(Number(params.max_num_results)) ? Number(params.max_num_results) : 10;
-    const ranked = files
-      .map((f) => ({ file_id: String((f as { file_id?: unknown }).file_id ?? ''), score: searchScore(query, String((f as { file_id?: unknown }).file_id ?? '')) }))
-      .sort((a, b) => b.score - a.score)
-      .slice(0, Math.max(1, maxResults))
-      .map((r) => ({ file_id: r.file_id, filename: r.file_id, score: r.score, attributes: {}, content: [{ type: 'text', text: `[twin-stub] deterministic pseudo-match for "${query}" in ${r.file_id} (no real semantic search)` }] }));
-    return { status: 200, body: { object: 'vector_store.search_results.page', search_query: query, data: ranked, has_more: false, next_page: null } };
-  }
-
-  // ---- assistants (beta, stateful) ----
-  if (path === '/v1/assistants' && method === 'POST') return createAssistant(params, req);
-  if (path === '/v1/assistants' && method === 'GET') {
-    const items = rows('assistant', req.root).filter((r) => !r._deleted).map(idView).sort((a, b) => Number(b.created_at) - Number(a.created_at));
-    return { status: 200, body: paginate(items, req.path) };
-  }
-  if (seg[1] === 'assistants' && seg.length === 3 && method === 'GET') {
-    const a = getRow('assistant', dec(seg[2]!), req.root);
-    return a && !a._deleted ? { status: 200, body: idView(a) } : notFound(`No assistant found with id '${dec(seg[2]!)}'.`);
-  }
-  if (seg[1] === 'assistants' && seg.length === 3 && method === 'POST') {
-    const aid = dec(seg[2]!);
-    const a = getRow('assistant', aid, req.root);
-    if (!a || a._deleted) return notFound(`No assistant found with id '${aid}'.`);
-    const fields = pickUpdate(params, ['name', 'description', 'model', 'instructions', 'tools', 'metadata', 'temperature', 'top_p', 'response_format']);
-    const { resource } = await applyTwinWrite(SERVICE, { operation: 'assistant.update', subjectType: 'assistant', subjectId: aid, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: idView(resource) };
-  }
-  if (seg[1] === 'assistants' && seg.length === 3 && method === 'DELETE') {
-    const aid = dec(seg[2]!);
-    const a = getRow('assistant', aid, req.root);
-    if (!a || a._deleted) return notFound(`No assistant found with id '${aid}'.`);
-    await applyTwinWrite(SERVICE, { operation: 'assistant.delete', subjectType: 'assistant', subjectId: aid, fields: { _deleted: true }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: { id: aid, object: 'assistant.deleted', deleted: true } };
-  }
-
-  // ---- threads (+ messages) (beta, stateful) ----
-  if (path === '/v1/threads' && method === 'POST') return createThread(params, req);
-  if (seg[1] === 'threads' && seg.length === 3 && method === 'GET') {
-    const t = getRow('thread', dec(seg[2]!), req.root);
-    return t && !t._deleted ? { status: 200, body: idView(t) } : notFound(`No thread found with id '${dec(seg[2]!)}'.`);
-  }
-  if (seg[1] === 'threads' && seg.length === 3 && method === 'POST') {
-    const tid = dec(seg[2]!);
-    const t = getRow('thread', tid, req.root);
-    if (!t || t._deleted) return notFound(`No thread found with id '${tid}'.`);
-    const fields = pickUpdate(params, ['metadata', 'tool_resources']);
-    const { resource } = await applyTwinWrite(SERVICE, { operation: 'thread.update', subjectType: 'thread', subjectId: tid, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: idView(resource) };
-  }
-  if (seg[1] === 'threads' && seg.length === 3 && method === 'DELETE') {
-    const tid = dec(seg[2]!);
-    const t = getRow('thread', tid, req.root);
-    if (!t || t._deleted) return notFound(`No thread found with id '${tid}'.`);
-    await applyTwinWrite(SERVICE, { operation: 'thread.delete', subjectType: 'thread', subjectId: tid, fields: { _deleted: true }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: { id: tid, object: 'thread.deleted', deleted: true } };
-  }
-  if (seg[1] === 'threads' && seg.length === 4 && seg[3] === 'messages' && method === 'POST') {
-    const tid = dec(seg[2]!);
-    if (!getRow('thread', tid, req.root)) return notFound(`No thread found with id '${tid}'.`);
-    if (params.content === undefined) return invalidRequest("you must provide a content parameter", 'content');
-    const view = await addThreadMessage(tid, params, req);
-    return { status: 200, body: view };
-  }
-  if (seg[1] === 'threads' && seg.length === 4 && seg[3] === 'messages' && method === 'GET') {
-    const tid = dec(seg[2]!);
-    if (!getRow('thread', tid, req.root)) return notFound(`No thread found with id '${tid}'.`);
-    const all = rows('message', req.root).filter((r) => r.thread_id === tid && !r._deleted).map(msgView).sort((a, b) => Number(b.created_at) - Number(a.created_at) || String(b.id).localeCompare(String(a.id)));
-    return { status: 200, body: paginate(all, req.path) };
-  }
-  if (seg[1] === 'threads' && seg.length === 5 && seg[3] === 'messages' && method === 'GET') {
-    const tid = dec(seg[2]!);
-    if (!getRow('thread', tid, req.root)) return notFound(`No thread found with id '${tid}'.`);
-    const m = getRow('message', dec(seg[4]!), req.root);
-    return m && m.thread_id === tid && !m._deleted ? { status: 200, body: msgView(m) } : notFound(`No message found with id '${dec(seg[4]!)}'.`);
-  }
-
-  // ---- runs (+ run steps) (beta, stateful) ----
-  if (seg[1] === 'threads' && seg.length === 4 && seg[3] === 'runs' && method === 'POST') {
-    const tid = dec(seg[2]!);
-    if (!getRow('thread', tid, req.root)) return notFound(`No thread found with id '${tid}'.`);
-    return createRun(tid, params, req);
-  }
-  if (seg[1] === 'threads' && seg.length === 4 && seg[3] === 'runs' && method === 'GET') {
-    const tid = dec(seg[2]!);
-    if (!getRow('thread', tid, req.root)) return notFound(`No thread found with id '${tid}'.`);
-    const all = rows('run', req.root).filter((r) => r.thread_id === tid && !r._deleted).map(runView).sort((a, b) => Number(b.created_at) - Number(a.created_at));
-    return { status: 200, body: paginate(all, req.path) };
-  }
-  if (seg[1] === 'threads' && seg.length === 6 && seg[3] === 'runs' && seg[5] === 'steps' && method === 'GET') {
-    const tid = dec(seg[2]!);
-    const r = getRow('run', dec(seg[4]!), req.root);
-    if (!r || r.thread_id !== tid || r._deleted) return notFound(`No run found with id '${dec(seg[4]!)}'.`);
-    return { status: 200, body: { object: 'list', data: runSteps(r), has_more: false, first_id: `step-${r.id}-1`, last_id: `step-${r.id}-1` } };
-  }
-  if (seg[1] === 'threads' && seg.length === 7 && seg[3] === 'runs' && seg[5] === 'steps' && method === 'GET') {
-    const tid = dec(seg[2]!);
-    const r = getRow('run', dec(seg[4]!), req.root);
-    if (!r || r.thread_id !== tid || r._deleted) return notFound(`No run found with id '${dec(seg[4]!)}'.`);
-    const step = runSteps(r).find((s) => s.id === dec(seg[6]!));
-    return step ? { status: 200, body: step } : notFound(`No run step found with id '${dec(seg[6]!)}'.`);
-  }
-  if (seg[1] === 'threads' && seg.length === 5 && seg[3] === 'runs' && method === 'GET') {
-    const tid = dec(seg[2]!);
-    const r = getRow('run', dec(seg[4]!), req.root);
-    return r && r.thread_id === tid && !r._deleted ? { status: 200, body: runView(r) } : notFound(`No run found with id '${dec(seg[4]!)}'.`);
-  }
-  if (seg[1] === 'threads' && seg.length === 6 && seg[3] === 'runs' && seg[5] === 'cancel' && method === 'POST') {
-    const tid = dec(seg[2]!);
-    const r = getRow('run', dec(seg[4]!), req.root);
-    if (!r || r.thread_id !== tid || r._deleted) return notFound(`No run found with id '${dec(seg[4]!)}'.`);
-    const { resource } = await applyTwinWrite(SERVICE, { operation: 'run.cancel', subjectType: 'run', subjectId: dec(seg[4]!), fields: { status: 'cancelled', cancelled_at: nowEpoch(req.occurredAt) }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: runView(resource) };
-  }
-
-  // ---- admin: usage + costs reporting (computed over REAL recorded usage rows) ----
-  // The vendor's Usage/Costs API returns time-bucketed aggregates. The twin records a usage row per
-  // billable inference call (recordUsage) and aggregates them here — nothing is hardcoded; with no
-  // traffic the report is genuinely empty. A single bucket covers [0, now] (the twin is offline +
-  // time-frozen), grouped by model, faithful to the vendor's bucket/result shape.
-  if (seg[1] === 'organization' && seg[2] === 'usage' && (seg.length === 3 || seg.length === 4) && method === 'GET') {
-    const kindFilter = seg.length === 4 ? dec(seg[3]!) : undefined; // 'completions' | 'embeddings' | undefined (all)
-    const all = rows('usage_record', req.root).filter((r) => kindFilter === undefined || r.kind === kindFilter);
-    // group by model → one result object per model
-    const byModel = new Map<string, { input: number; output: number; requests: number }>();
-    for (const r of all) {
-      const m = String(r.model);
-      const agg = byModel.get(m) ?? { input: 0, output: 0, requests: 0 };
-      agg.input += Number(r.input_tokens ?? 0);
-      agg.output += Number(r.output_tokens ?? 0);
-      agg.requests += Number(r.num_model_requests ?? 0);
-      byModel.set(m, agg);
+  if (typeof req.body === 'string' && method !== 'GET' && method !== 'HEAD' && !headers['content-type']) headers['content-type'] = 'application/json';
+  const path = req.path.startsWith('/') ? req.path : `/${req.path}`;
+  const response = await twin(new Request(`https://api.openai.com${path}`, { method, headers, ...(req.body !== undefined && method !== 'GET' && method !== 'HEAD' ? { body: req.body } : {}) }));
+  const answerHeaders: Record<string, string> = {};
+  response.headers.forEach((v, k) => { if (k !== 'content-type') answerHeaders[k] = v; });
+  const type = response.headers.get('content-type') ?? '';
+  const text = await response.text();
+  if (type.includes('text/event-stream')) {
+    // the frames back into events, for a caller that collects them
+    for (const frame of text.split('\n\n')) {
+      const data = frame.split('\n').filter((l) => l.startsWith('data: ')).map((l) => l.slice(6)).join('\n');
+      if (!data) continue;
+      req.sseSink?.(data === '[DONE]' ? { done: true } : { data: JSON.parse(data) as Record<string, unknown> });
     }
-    const resultObject = kindFilter === 'embeddings' ? 'organization.usage.embeddings.result' : 'organization.usage.completions.result';
-    const results = [...byModel.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1)).map(([model, agg]) => ({
-      object: resultObject,
-      input_tokens: agg.input,
-      output_tokens: agg.output,
-      num_model_requests: agg.requests,
-      model,
-      project_id: null,
-    }));
-    const buckets = results.length === 0 ? [] : [{ object: 'bucket', start_time: 0, end_time: nowEpoch(req.occurredAt), results }];
-    return { status: 200, body: { object: 'page', data: buckets, has_more: false, next_page: null } };
-  }
-  if (path === '/v1/organization/costs' && method === 'GET') {
-    const all = rows('usage_record', req.root);
-    // group cost by line_item (the usage kind, vendor-style) → one result per line item
-    const byLine = new Map<string, number>();
-    for (const r of all) {
-      const line = String(r.kind);
-      byLine.set(line, (byLine.get(line) ?? 0) + Number(r.cost_usd ?? 0));
-    }
-    const results = [...byLine.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1)).map(([line, amount]) => ({
-      object: 'organization.costs.result',
-      amount: { value: amount, currency: 'usd' },
-      line_item: line,
-      project_id: null,
-    }));
-    const buckets = results.length === 0 ? [] : [{ object: 'bucket', start_time: 0, end_time: nowEpoch(req.occurredAt), results }];
-    return { status: 200, body: { object: 'page', data: buckets, has_more: false, next_page: null } };
-  }
-
-  // ---- admin: organization projects (stateful) ----
-  if (path === '/v1/organization/projects' && method === 'POST') return createProject(params, req);
-  if (path === '/v1/organization/projects' && method === 'GET') {
-    const includeArchived = new URLSearchParams(req.path.split('?')[1] ?? '').get('include_archived') === 'true';
-    const items = rows('project', req.root).filter((r) => includeArchived || r.status !== 'archived').map(idView).sort((a, b) => Number(b.created_at) - Number(a.created_at));
-    return { status: 200, body: paginate(items, req.path) };
-  }
-  if (seg[1] === 'organization' && seg[2] === 'projects' && seg.length === 4 && method === 'GET') {
-    const p = getRow('project', dec(seg[3]!), req.root);
-    return p ? { status: 200, body: idView(p) } : notFound(`Project ${dec(seg[3]!)} not found`);
-  }
-  if (seg[1] === 'organization' && seg[2] === 'projects' && seg.length === 4 && method === 'POST') {
-    const pid = dec(seg[3]!);
-    if (!getRow('project', pid, req.root)) return notFound(`Project ${pid} not found`);
-    const fields = pickUpdate(params, ['name']);
-    const { resource } = await applyTwinWrite(SERVICE, { operation: 'project.update', subjectType: 'project', subjectId: pid, fields, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: idView(resource) };
+    return { status: response.status, body: null, headers: answerHeaders };
   }
-  if (seg[1] === 'organization' && seg[2] === 'projects' && seg.length === 5 && seg[4] === 'archive' && method === 'POST') {
-    const pid = dec(seg[3]!);
-    if (!getRow('project', pid, req.root)) return notFound(`Project ${pid} not found`);
-    const { resource } = await applyTwinWrite(SERVICE, { operation: 'project.archive', subjectType: 'project', subjectId: pid, fields: { status: 'archived', archived_at: nowEpoch(req.occurredAt) }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: idView(resource) };
-  }
-  // ---- admin: project API keys (stateful; synthetic twin keys) ----
-  if (seg[1] === 'organization' && seg[2] === 'projects' && seg.length === 5 && seg[4] === 'api_keys' && method === 'POST') {
-    const pid = dec(seg[3]!);
-    if (!getRow('project', pid, req.root)) return notFound(`Project ${pid} not found`);
-    return createProjectApiKey(pid, params, req);
-  }
-  if (seg[1] === 'organization' && seg[2] === 'projects' && seg.length === 5 && seg[4] === 'api_keys' && method === 'GET') {
-    const pid = dec(seg[3]!);
-    if (!getRow('project', pid, req.root)) return notFound(`Project ${pid} not found`);
-    const items = rows('api_key', req.root).filter((r) => r.project_id === pid && !r._deleted).map(apiKeyView).sort((a, b) => Number(b.created_at) - Number(a.created_at));
-    return { status: 200, body: paginate(items, req.path) };
-  }
-  if (seg[1] === 'organization' && seg[2] === 'projects' && seg.length === 6 && seg[4] === 'api_keys' && method === 'GET') {
-    const k = getRow('api_key', dec(seg[5]!), req.root);
-    return k && k.project_id === dec(seg[3]!) && !k._deleted ? { status: 200, body: apiKeyView(k) } : notFound(`API key ${dec(seg[5]!)} not found`);
-  }
-  if (seg[1] === 'organization' && seg[2] === 'projects' && seg.length === 6 && seg[4] === 'api_keys' && method === 'DELETE') {
-    const kid = dec(seg[5]!);
-    const k = getRow('api_key', kid, req.root);
-    if (!k || k.project_id !== dec(seg[3]!) || k._deleted) return notFound(`API key ${kid} not found`);
-    await applyTwinWrite(SERVICE, { operation: 'api_key.delete', subjectType: 'api_key', subjectId: kid, fields: { _deleted: true }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: { id: kid, object: 'organization.project.api_key.deleted', deleted: true } };
-  }
-
-  // ---- evals (stateful: eval config → runs → output items) ----
-  if (path === '/v1/evals' && method === 'POST') return createEval(params, req);
-  if (path === '/v1/evals' && method === 'GET') {
-    const items = rows('eval', req.root).map(evalView).sort((a, b) => Number(b.created_at) - Number(a.created_at));
-    return { status: 200, body: paginate(items, req.path) };
-  }
-  if (seg[1] === 'evals' && seg.length === 3 && method === 'GET') {
-    const e = getRow('eval', dec(seg[2]!), req.root);
-    return e ? { status: 200, body: evalView(e) } : notFound(`Eval ${dec(seg[2]!)} not found`);
-  }
-  if (seg[1] === 'evals' && seg.length === 4 && seg[3] === 'runs' && method === 'POST') {
-    const evalId = dec(seg[2]!);
-    if (!getRow('eval', evalId, req.root)) return notFound(`Eval ${evalId} not found`);
-    return createEvalRun(evalId, params, req);
-  }
-  if (seg[1] === 'evals' && seg.length === 4 && seg[3] === 'runs' && method === 'GET') {
-    const evalId = dec(seg[2]!);
-    if (!getRow('eval', evalId, req.root)) return notFound(`Eval ${evalId} not found`);
-    const items = rows('eval_run', req.root).filter((r) => r.eval_id === evalId).map(evalRunView).sort((a, b) => Number(b.created_at) - Number(a.created_at));
-    return { status: 200, body: paginate(items, req.path) };
-  }
-  if (seg[1] === 'evals' && seg.length === 5 && seg[3] === 'runs' && method === 'GET') {
-    const run = getRow('eval_run', dec(seg[4]!), req.root);
-    return run && run.eval_id === dec(seg[2]!) ? { status: 200, body: evalRunView(run) } : notFound(`Eval run ${dec(seg[4]!)} not found`);
-  }
-  if (seg[1] === 'evals' && seg.length === 6 && seg[3] === 'runs' && seg[5] === 'output_items' && method === 'GET') {
-    const run = getRow('eval_run', dec(seg[4]!), req.root);
-    if (!run || run.eval_id !== dec(seg[2]!)) return notFound(`Eval run ${dec(seg[4]!)} not found`);
-    return { status: 200, body: paginate(evalRunOutputItems(run), req.path) };
-  }
-
-  // ---- containers (code-interpreter sandboxes) → container files ----
-  if (path === '/v1/containers' && method === 'POST') return createContainer(params, req);
-  if (path === '/v1/containers' && method === 'GET') {
-    const items = rows('container', req.root).filter((r) => !r._deleted).map(containerView).sort((a, b) => Number(b.created_at) - Number(a.created_at));
-    return { status: 200, body: paginate(items, req.path) };
-  }
-  if (seg[1] === 'containers' && seg.length === 3 && method === 'GET') {
-    const c = getRow('container', dec(seg[2]!), req.root);
-    return c && !c._deleted ? { status: 200, body: containerView(c) } : notFound(`Container ${dec(seg[2]!)} not found`);
-  }
-  if (seg[1] === 'containers' && seg.length === 3 && method === 'DELETE') {
-    const cid = dec(seg[2]!);
-    const c = getRow('container', cid, req.root);
-    if (!c || c._deleted) return notFound(`Container ${cid} not found`);
-    await applyTwinWrite(SERVICE, { operation: 'container.delete', subjectType: 'container', subjectId: cid, fields: { _deleted: true, status: 'deleted' }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: { id: cid, object: 'container.deleted', deleted: true } };
-  }
-  if (seg[1] === 'containers' && seg.length === 4 && seg[3] === 'files' && method === 'POST') {
-    const cid = dec(seg[2]!);
-    const c = getRow('container', cid, req.root);
-    if (!c || c._deleted) return notFound(`Container ${cid} not found`);
-    return createContainerFile(cid, params, req);
-  }
-  if (seg[1] === 'containers' && seg.length === 4 && seg[3] === 'files' && method === 'GET') {
-    const cid = dec(seg[2]!);
-    if (!getRow('container', cid, req.root)) return notFound(`Container ${cid} not found`);
-    const items = rows('container_file', req.root).filter((r) => r.container_id === cid && !r._deleted).map(containerFileView).sort((a, b) => Number(b.created_at) - Number(a.created_at));
-    return { status: 200, body: paginate(items, req.path) };
-  }
-  if (seg[1] === 'containers' && seg.length === 5 && seg[3] === 'files' && method === 'GET') {
-    const cf = getRow('container_file', dec(seg[4]!), req.root);
-    return cf && cf.container_id === dec(seg[2]!) && !cf._deleted ? { status: 200, body: containerFileView(cf) } : notFound(`Container file ${dec(seg[4]!)} not found`);
-  }
-  if (seg[1] === 'containers' && seg.length === 6 && seg[3] === 'files' && seg[5] === 'content' && method === 'GET') {
-    const cf = getRow('container_file', dec(seg[4]!), req.root);
-    if (!cf || cf.container_id !== dec(seg[2]!) || cf._deleted) return notFound(`Container file ${dec(seg[4]!)} not found`);
-    return { status: 200, body: (cf._content as string) ?? '' };
-  }
-  if (seg[1] === 'containers' && seg.length === 5 && seg[3] === 'files' && method === 'DELETE') {
-    const fid = dec(seg[4]!);
-    const cf = getRow('container_file', fid, req.root);
-    if (!cf || cf.container_id !== dec(seg[2]!) || cf._deleted) return notFound(`Container file ${fid} not found`);
-    await applyTwinWrite(SERVICE, { operation: 'container_file.delete', subjectType: 'container_file', subjectId: fid, fields: { _deleted: true }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' } }, req.root);
-    return { status: 200, body: { id: fid, object: 'container.file.deleted', deleted: true } };
-  }
-
-  // Unknown route → vendor-faithful 404 (never a fabricated success — D2).
-  return notFound(`Unknown request URL: ${method} ${path}. Please check the URL for typos.`);
+  const body = type.includes('json') ? (text ? JSON.parse(text) : null) : text;
+  return { status: response.status, body, headers: answerHeaders };
 }