@volter/twin-openai 0.1.0

package/src/openai-twin.ts

@@ -0,0 +1,2100 @@
+// 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';
+import {
+  buildLogprobs,
+  countPromptTokens,
+  estimateTokens,
+  moderateText,
+  pseudoEmbedding,
+  stubAssistantText,
+  stubJsonObject,
+  stubToolCall,
+} from './openai-stub.ts';
+import { type OpenAIScenarioEngine, type OpenAIScenarioRespond, realizeOpenAIRespond, type ScriptedResult } from './openai-scenario.ts';
+import type {
+  ChatChoice,
+  ChatCompletion,
+  ChatMessageParam,
+  ChatToolCall,
+  ChatUsage,
+  Embedding,
+  EmbeddingResponse,
+  OpenAIResponse,
+  ResponseMessageItem,
+  ResponseOutputItem,
+  ResponseReasoningItem,
+  ResponseUsage,
+  SseSink,
+} from './openai-types.ts';
+
+const SERVICE = 'openai';
+
+export type OpenAIRequest = {
+  /** The scenario engine (kernel grammar + this pack's vocabulary) — scripts chat turns. */
+  scenarioEngine?: OpenAIScenarioEngine;
+  method: string;
+  path: string;
+  body?: string;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+  /** The credential the caller presents (the SDK's bearer `Authorization` header). When a request
+   *  carries an auth SURFACE (this field set, or `headers` present), the twin holds it to the real
+   *  vendor rule: a credential is required → 401 on missing/invalid. In-process trusted calls
+   *  (capability verify, connector) omit BOTH and are not auth-gated — 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. */
+  headers?: Record<string, string>;
+  /** When set on a streaming POST, chunks are written here (no sockets). */
+  sseSink?: SseSink;
+};
+/** The handler response. `headers` (when present) are response headers the HTTP server should set
+ *  — e.g. `Retry-After` + the `x-ratelimit-*` family on a modeled 429. */
+export type OpenAIResponseEnvelope = { status: number; body: unknown; headers?: Record<string, string> };
+
+// ── vendor-shaped errors ──────────────────────────────────────────────────────────────
+function errBody(type: string, message: string, code: string | null = null, param: string | null = null) {
+  return { error: { message, type, param, code } };
+}
+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
+// computed from a per-model price table). The /v1/organization/usage|costs endpoints aggregate
+// these REAL recorded rows — nothing is hardcoded; with no traffic the report is genuinely empty.
+// Per-model USD price per 1M tokens (a faithful slice of the published price sheet; deterministic).
+const MODEL_PRICES: Record<string, { input: number; output: number }> = {
+  'gpt-4o': { input: 2.5, output: 10 },
+  'gpt-4o-mini': { input: 0.15, output: 0.6 },
+  'gpt-4.1': { input: 2, output: 8 },
+  'gpt-4.1-mini': { input: 0.4, output: 1.6 },
+  'gpt-4-turbo': { input: 10, output: 30 },
+  'o3': { input: 2, output: 8 },
+  'o4-mini': { input: 1.1, output: 4.4 },
+  'gpt-3.5-turbo': { input: 0.5, output: 1.5 },
+  'text-embedding-3-small': { input: 0.02, output: 0 },
+  'text-embedding-3-large': { input: 0.13, output: 0 },
+  'text-embedding-ada-002': { input: 0.1, output: 0 },
+};
+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 {
+  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 };
+}
+
+// ── 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 {};
+  }
+}
+
+const SYSTEM_FINGERPRINT = 'fp_twin_stub';
+
+// ── chat completions: validate the request the same way the vendor does ──────────────────
+type ToolChoice = 'auto' | 'none' | 'required' | { name: string };
+type ResponseFormat = { kind: 'text' } | { kind: 'json_object' } | { kind: 'json_schema'; schema: unknown };
+type ChatArgs = {
+  model: string;
+  messages: ChatMessageParam[];
+  tools?: unknown;
+  functions?: unknown;
+  n: number;
+  maxTokens?: number;
+  stop?: string[];
+  stream: boolean;
+  toolChoice?: ToolChoice;
+  parallelToolCalls: boolean;
+  responseFormat: ResponseFormat;
+  includeUsage: boolean;
+  logprobs: boolean;
+  topLogprobs?: number;
+  seed?: number;
+  logitBias?: Record<string, number>;
+  prediction?: 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 } {
+  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') };
+  }
+  // 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') };
+  }
+  // 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') };
+  }
+  // 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') };
+  }
+  // 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;
+    }
+  }
+  // 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 };
+    }
+  }
+  // store + metadata → stored completions (retrievable later); metadata must be a flat object.
+  const store = params.store === true;
+  let metadata: Record<string, unknown> | undefined;
+  if (params.metadata !== undefined) {
+    if (!params.metadata || typeof params.metadata !== 'object' || Array.isArray(params.metadata)) return { error: invalidRequest("'metadata' must be an object", 'metadata') };
+    metadata = params.metadata as Record<string, unknown>;
+  }
+  return {
+    args: {
+      model: params.model,
+      messages,
+      tools: params.tools,
+      functions: params.functions,
+      n,
+      ...(maxTokens !== undefined ? { maxTokens } : {}),
+      ...(stop !== undefined ? { stop } : {}),
+      stream: params.stream === true,
+      ...(toolChoice !== undefined ? { toolChoice } : {}),
+      parallelToolCalls: params.parallel_tool_calls !== false,
+      responseFormat,
+      includeUsage,
+      logprobs,
+      ...(topLogprobs !== undefined ? { topLogprobs } : {}),
+      ...(seed !== undefined ? { seed } : {}),
+      ...(logitBias !== undefined ? { logitBias } : {}),
+      ...(prediction !== undefined ? { prediction } : {}),
+      store,
+      ...(metadata !== undefined ? { metadata } : {}),
+      ...(audioOutput !== undefined ? { audioOutput } : {}),
+    },
+  };
+}
+
+// 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.
+function buildChoice(args: ChatArgs, idx: number): { choice: ChatChoice; completionTokens: number } {
+  const toolsSource = args.tools ?? args.functions;
+  const hasTools = Array.isArray(toolsSource) && toolsSource.length > 0;
+  // tool_choice gates whether the stub calls a tool: 'none' forbids it; a named/required choice
+  // 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;
+  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,
+      };
+    }
+  }
+  // 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
+  // returns its own generation — the twin echoes the predicted content (clearly still a stub) so
+  // the prediction round-trips, then reports accepted/rejected prediction tokens in usage.
+  let text = args.prediction !== undefined
+    ? `[twin-stub:${args.model}] predicted-output echo: ${args.prediction}`
+    : args.responseFormat.kind === 'json_object'
+      ? stubJsonObject(args.messages, args.model)
+      : 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';
+  }
+  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),
+    };
+  }
+  return {
+    choice: { index: idx, message: { role: 'assistant', content: text, refusal: null }, logprobs, finish_reason: finish },
+    completionTokens: estimateTokens(text),
+  };
+}
+
+function buildChatCompletion(args: ChatArgs, occurredAt?: string, scenarioEngine?: OpenAIScenarioEngine): 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)}]`;
+  }
+  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;
+    choices.push(choice);
+    completionTokens += ct;
+  }
+  const usage: ChatUsage = { prompt_tokens: promptTokens, completion_tokens: completionTokens, total_tokens: promptTokens + completionTokens };
+  // 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 };
+  }
+  return {
+    id: `chatcmpl-twin-${stableSuffix(args)}`,
+    object: 'chat.completion',
+    created: nowEpoch(occurredAt),
+    model: args.model,
+    choices,
+    usage,
+    system_fingerprint: SYSTEM_FINGERPRINT,
+    ...(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).
+function stableSuffix(args: ChatArgs): string {
+  let h = 0x811c9dc5;
+  const s = JSON.stringify(args.messages) + args.model + (args.seed !== undefined ? `|seed=${args.seed}` : '');
+  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193); }
+  return (h >>> 0).toString(36);
+}
+
+// Split text into deterministic streaming chunks (≤ ~20 chars each), preserving order.
+function chunkText(text: string): string[] {
+  if (!text) return [];
+  const out: string[] = [];
+  for (let i = 0; i < text.length; i += 20) out.push(text.slice(i, i + 20));
+  return out;
+}
+
+/**
+ * Emit the vendor-faithful 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);
+  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 {
+      for (const piece of chunkText(choice.message.content ?? '')) {
+        sink({ data: { ...base, choices: [{ index: idx, delta: { content: piece }, logprobs: null, finish_reason: null }] } });
+      }
+    }
+    sink({ data: { ...base, choices: [{ index: idx, delta: {}, logprobs: null, finish_reason: choice.finish_reason }] } });
+  }
+  // stream_options.include_usage → a final chunk with an empty choices array carrying `usage`.
+  if (args.includeUsage) {
+    sink({ data: { ...base, choices: [], usage: full.usage } });
+  }
+  sink({ done: true });
+  return full;
+}
+
+// ── Responses API ───────────────────────────────────────────────────────────────────────
+type ResponsesArgs = {
+  model: string;
+  inputText: string;
+  messages: ChatMessageParam[];
+  stream: boolean;
+  store: boolean;
+  previousResponseId?: string;
+  /** reasoning.effort ('minimal'|'low'|'medium'|'high') → emit a reasoning item + reasoning_tokens. */
+  reasoningEffort?: string;
+  /** background:true → the response is created `queued` and processed asynchronously (poll + cancel). */
+  background: boolean;
+};
+const REASONING_EFFORTS = new Set(['minimal', 'low', 'medium', 'high']);
+
+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[] = [];
+  if (typeof params.input === 'string') {
+    inputText = params.input;
+    messages.push({ role: 'user', content: 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 });
+    }
+  } else {
+    return { error: invalidRequest("'input' must be a string or an array of input items", 'input') };
+  }
+  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.
+  let reasoningEffort: string | undefined;
+  if (params.reasoning !== undefined) {
+    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;
+    }
+  }
+  return {
+    args: {
+      model: params.model,
+      inputText,
+      messages,
+      stream: params.stream === true,
+      store: params.store !== false, // OpenAI defaults store=true (stored & retrievable)
+      background: params.background === true,
+      ...(typeof prev === 'string' ? { previousResponseId: prev } : {}),
+      ...(reasoningEffort !== undefined ? { reasoningEffort } : {}),
+    },
+  };
+}
+
+// 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 };
+
+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);
+  const suffix = idSuffix ?? String(nowEpoch(occurredAt));
+  const messageItem: ResponseMessageItem = {
+    type: 'message',
+    id: `msg-twin-${suffix}`,
+    status: 'completed',
+    role: 'assistant',
+    content: [{ type: 'output_text', text, annotations: [] }],
+  };
+  const output: ResponseOutputItem[] = [];
+  const usage: ResponseUsage = { input_tokens: inputTokens, output_tokens: messageTokens, 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;
+    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.` }],
+    };
+    output.push(reasoningItem);
+    usage.output_tokens += reasoningTokens;
+    usage.total_tokens += reasoningTokens;
+    usage.output_tokens_details = { reasoning_tokens: reasoningTokens };
+  }
+  output.push(messageItem);
+  return {
+    id: `resp-twin-${suffix}`,
+    object: 'response',
+    created_at: nowEpoch(occurredAt),
+    status: 'completed',
+    model: args.model,
+    output,
+    output_text: text,
+    usage,
+    ...(args.reasoningEffort ? { reasoning: { effort: args.reasoningEffort, summary: null } } : {}),
+    ...(args.previousResponseId ? { previous_response_id: args.previousResponseId } : {}),
+  };
+}
+
+// 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 {
+  let h = 0x811c9dc5;
+  const s = args.model + '|' + args.inputText + '|' + (args.previousResponseId ?? '');
+  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' },
+  }, 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;
+}
+
+/** 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');
+  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 } });
+  });
+  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 {
+  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);
+  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)))
+      : [];
+  if (inputs.length === 0) return invalidRequest("'input' must be a non-empty string or array", 'input');
+  const dimensions = params.dimensions !== undefined ? Number(params.dimensions) : defaultDims(model);
+  if (!Number.isInteger(dimensions) || dimensions < 1) return invalidRequest("'dimensions' must be a positive integer", 'dimensions');
+  // The `openai` SDK defaults to encoding_format:'base64' and decodes a base64 Float32 buffer
+  // back into numbers client-side. Honor both formats faithfully.
+  const asBase64 = params.encoding_format === 'base64';
+  let promptTokens = 0;
+  const data: Embedding[] = inputs.map((text, index) => {
+    promptTokens += estimateTokens(text);
+    const vec = pseudoEmbedding(text, dimensions);
+    return { object: 'embedding', index, embedding: (asBase64 ? floatsToBase64(vec) : vec) as unknown as number[] };
+  });
+  const out: EmbeddingResponse = { object: 'list', data, model, usage: { prompt_tokens: promptTokens, total_tokens: promptTokens } };
+  return { status: 200, body: out };
+}
+function defaultDims(model: string): number {
+  if (model.includes('large')) return 3072;
+  return 1536; // small + ada-002
+}
+/** Encode a float vector as a base64 little-endian Float32 buffer (the SDK's base64 format). */
+function floatsToBase64(vec: number[]): string {
+  const buf = new ArrayBuffer(vec.length * 4);
+  const view = new DataView(buf);
+  for (let i = 0; i < vec.length; i++) view.setFloat32(i * 4, vec[i]!, true);
+  // btoa over the raw bytes (available in Bun/browser).
+  let bin = '';
+  const bytes = new Uint8Array(buf);
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]!);
+  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 {
+  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)))
+      : [];
+  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));
+  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 };
+}
+
+// ── 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) };
+}
+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 } };
+}
+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,
+  };
+  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,
+  }];
+}
+
+// ── Images (response shape; real pixels out of scope) ───────────────────────────────────
+function handleImages(params: Record<string, unknown>, occurredAt?: string): OpenAIResponseEnvelope {
+  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)}`,
+  }));
+  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');
+  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` }));
+  return { status: 200, body: { created: nowEpoch(occurredAt), data } };
+}
+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` }));
+  return { status: 200, body: { created: nowEpoch(occurredAt), data } };
+}
+
+// ── Audio (deterministic stubs; real model output is out of scope) ──────────────────────
+// 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
+// (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 }.
+  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 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 };
+  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 }] } };
+  }
+  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 {
+  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.
+export async function handleOpenAITwinRequest(req: OpenAIRequest): Promise<OpenAIResponseEnvelope> {
+  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);
+    }
+    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) };
+  }
+  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.`);
+}