@volter/twin-openai 0.1.0

package/src/openai-capabilities.ts

@@ -0,0 +1,1556 @@
+// OpenAI capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored
+// top-down from what the OpenAI API actually does — NOT from what this twin has built. This is
+// the honest denominator: most entries start as `todo` and coverage reads LOW until the twin
+// truly reaches 100% of the API. `verify()` (required to count as done) is ground truth;
+// `expected:'done'` only on capabilities we genuinely claim, so a broken one shows as a
+// regression. Grow this toward the API's *full* surface every cycle.
+//
+// THE HONEST CARVE-OUTS: `openai.chat.inference` and `openai.embeddings.real_vectors` are the
+// out-of-scope entries — the twin returns a DETERMINISTIC STUB for model generation (no
+// weights) and DETERMINISTIC pseudo-vectors for embeddings, while the protocol envelope (shape/
+// streaming/tool_calls/usage) is faithful. `openai.images.real_pixels` and
+// `openai.files.real_bytes` carve out the binary content. Surfaced here + in README ## Coverage.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkCapabilities, type CapabilityReport, type CapabilitySpec, verifyBoundary, isInfrastructureError, harnessError } from '@volter/twin-tooling';
+import { handleOpenAITwinRequest, type OpenAIResponseEnvelope } from './openai-twin.ts';
+import { buildSignedOpenAIWebhook, verifyOpenAIWebhook, OpenAIWebhookVerificationError, computeOpenAIWebhookSignature } from './openai-webhooks.ts';
+import type { SseEvent } from './openai-types.ts';
+
+// (OpenAI is an API-first vendor with no meaningful product UI worth mirroring — ARCHITECTURE.md
+// C1b — so this pack ships no mirror, and there are no UI capabilities to verify.)
+
+// ── API verify: drive REAL requests against a fresh temp root, then assert status/shape ──
+type Step = { m: string; p: string; b?: unknown };
+type Body = Record<string, any>;
+
+/** Run a sequence of real OpenAI requests against an isolated root; return all responses. */
+async function withRoot(steps: (h: (s: Step) => Promise<OpenAIResponseEnvelope>) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'openai-cap-'));
+  const h = (s: Step) => handleOpenAITwinRequest({ method: s.m, path: s.p, body: s.b === undefined ? undefined : JSON.stringify(s.b), root });
+  try {
+    return await verifyBoundary('openai.withRoot', () => steps(h));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+/** Collect the streaming SSE events for a request against an isolated root. */
+function withStream(body: unknown, fn: (events: SseEvent[], final: OpenAIResponseEnvelope) => boolean): Promise<boolean> {
+  return new Promise<boolean>((resolve, reject) => {
+    const root = mkdtempSync(join(tmpdir(), 'openai-cap-'));
+    const events: SseEvent[] = [];
+    handleOpenAITwinRequest({ method: 'POST', path: bodyPath(body), body: JSON.stringify(body), root, sseSink: (e) => events.push(e) })
+      .then((final) => resolve(fn(events, final)))
+      .catch((err) => { if (isInfrastructureError(err)) reject(harnessError('openai.withStream', err)); else resolve(false); })
+      .finally(() => rmSync(root, { recursive: true, force: true }));
+  });
+}
+function bodyPath(body: unknown): string {
+  return body && typeof body === 'object' && 'input' in (body as Record<string, unknown>) ? '/v1/responses' : '/v1/chat/completions';
+}
+
+/** Like withRoot, but the request helper passes request HEADERS through (for auth/rate-limit/
+ *  idempotency, which the trusted no-headers withRoot helper deliberately never triggers). */
+type StepH = Step & { headers?: Record<string, string> };
+async function withRootH(steps: (h: (s: StepH) => Promise<OpenAIResponseEnvelope>) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'openai-cap-'));
+  const h = (s: StepH) => handleOpenAITwinRequest({ method: s.m, path: s.p, body: s.b === undefined ? undefined : JSON.stringify(s.b), root, ...(s.headers ? { headers: s.headers } : {}) });
+  try {
+    return await verifyBoundary('openai.withRootH', () => steps(h));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+const ok = (r: OpenAIResponseEnvelope) => r.status >= 200 && r.status < 300;
+const id = (r: OpenAIResponseEnvelope) => (r.body as Body)?.id as string;
+const field = (r: OpenAIResponseEnvelope, k: string) => (r.body as Body)?.[k];
+
+// ── shorthands (mirror the stripe/anthropic manifests) ──
+const done = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify']): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier']): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'todo' });
+const outOfScope = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], reason: string): CapabilitySpec => ({ id, area, title, dimension, tier, expected: 'todo', outOfScope: reason });
+
+const CHAT = (extra: Record<string, unknown> = {}) => ({ model: 'gpt-4o', messages: [{ role: 'user', content: 'hello twin' }], ...extra });
+
+export const OPENAI_CAPABILITIES: CapabilitySpec[] = [
+  // ── THE HONEST CARVE-OUTS ─────────────────────────────────────────────────────────────
+  outOfScope('openai.chat.inference', 'chat', 'Real model inference (generation from model weights)', 'api', 'core',
+    'Out of scope: the twin cannot run the model — chat/responses return a DETERMINISTIC STUB completion (clearly labeled), never real model output. The protocol envelope (shape/streaming/tool_calls/usage) is faithful; only the generated text is a stub.'),
+  outOfScope('openai.embeddings.real_vectors', 'embeddings', 'Real embedding vectors (semantic values)', 'api', 'core',
+    'Out of scope: the twin cannot run the embedding model — /v1/embeddings returns DETERMINISTIC pseudo-vectors seeded from the input hash. The shape, dimensions, and determinism are faithful; the values carry no semantic meaning.'),
+  outOfScope('openai.images.real_pixels', 'images', 'Real image pixels (generated image bytes)', 'api', 'common',
+    'Out of scope: the twin cannot run the image model — /v1/images/generations returns the faithful response shape with a placeholder URL/revised_prompt; no real pixels are produced.'),
+  outOfScope('openai.files.real_bytes', 'files', 'Real opaque file storage of arbitrary bytes', 'api', 'niche',
+    'Out of scope: the twin stores file metadata + supplied text content faithfully, but does not persist arbitrary binary blobs as a real object store would.'),
+
+  // ── Chat Completions (the protocol envelope — faithful) ────────────────────────────────
+  done('openai.chat.create', 'chat', 'Chat: create → faithful envelope (id/object/created/model/choices/usage)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+      if (!ok(r)) return false;
+      const b = r.body as Body;
+      if (b.object !== 'chat.completion' || b.model !== 'gpt-4o' || typeof b.created !== 'number') return false;
+      if (!String(b.id).startsWith('chatcmpl-')) return false;
+      const c = b.choices?.[0];
+      if (!c || c.message?.role !== 'assistant' || typeof c.message?.content !== 'string' || c.finish_reason !== 'stop') return false;
+      const u = b.usage;
+      return typeof u.prompt_tokens === 'number' && typeof u.completion_tokens === 'number' && u.total_tokens === u.prompt_tokens + u.completion_tokens;
+    }),
+  ),
+  done('openai.chat.stub_labeled', 'chat', 'Stub completion is clearly labeled as a twin stub (not real output)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+      const text = (r.body as Body).choices?.[0]?.message?.content as string;
+      return ok(r) && text.includes('[twin-stub') && text.includes('hello twin');
+    }),
+  ),
+  done('openai.chat.validation', 'chat', 'Chat validation (model required, non-empty messages, valid roles)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const noModel = await h({ m: 'POST', p: '/v1/chat/completions', b: { messages: [{ role: 'user', content: 'x' }] } });
+      const noMsg = await h({ m: 'POST', p: '/v1/chat/completions', b: { model: 'gpt-4o' } });
+      const empty = await h({ m: 'POST', p: '/v1/chat/completions', b: { model: 'gpt-4o', messages: [] } });
+      return noModel.status === 400 && noMsg.status === 400 && empty.status === 400 && (noModel.body as Body).error?.type === 'invalid_request_error';
+    }),
+  ),
+  done('openai.chat.n_choices', 'chat', 'Chat: n returns multiple choices (indexed)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ n: 3 }) });
+      const choices = (r.body as Body).choices as Body[];
+      return ok(r) && choices.length === 3 && choices[0]!.index === 0 && choices[2]!.index === 2;
+    }),
+  ),
+  done('openai.chat.max_tokens', 'chat', 'Chat: max_tokens/max_completion_tokens caps output (finish_reason length)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const a = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ max_tokens: 1, messages: [{ role: 'user', content: 'please produce a long answer that exceeds one token' }] }) });
+      const b = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ max_completion_tokens: 1, messages: [{ role: 'user', content: 'please produce a long answer that exceeds one token' }] }) });
+      return ok(a) && ok(b) && (a.body as Body).choices[0].finish_reason === 'length' && (b.body as Body).choices[0].finish_reason === 'length';
+    }),
+  ),
+  done('openai.chat.system_message', 'chat', 'Chat: system/developer messages count toward prompt_tokens', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const without = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+      const withSys = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ messages: [{ role: 'system', content: 'You are a careful, verbose assistant.' }, { role: 'user', content: 'hello twin' }] }) });
+      return ok(without) && ok(withSys) && (withSys.body as Body).usage.prompt_tokens > (without.body as Body).usage.prompt_tokens;
+    }),
+  ),
+  done('openai.chat.multi_turn', 'chat', 'Chat: multi-turn user/assistant history accepted', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ messages: [{ role: 'user', content: 'first' }, { role: 'assistant', content: 'reply' }, { role: 'user', content: 'second' }] }) });
+      return ok(r) && (r.body as Body).object === 'chat.completion';
+    }),
+  ),
+  done('openai.chat.content_parts', 'chat', 'Chat: content-part array input (text/image_url) accepted', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ messages: [{ role: 'user', content: [{ type: 'text', text: 'describe' }, { type: 'image_url', image_url: { url: 'data:image/png;base64,iVBORw0KGgo=' } }] }] }) });
+      return ok(r) && (r.body as Body).usage.prompt_tokens > 0;
+    }),
+  ),
+  done('openai.chat.stop', 'chat', 'Chat: stop sequence truncates the stub text', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ stop: ['Echoing'] }) });
+      const text = (r.body as Body).choices[0].message.content as string;
+      return ok(r) && !text.includes('Echoing');
+    }),
+  ),
+  done('openai.chat.temperature_accepted', 'chat', 'Chat: temperature/top_p accepted (ignored for the stub)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ temperature: 0.7, top_p: 0.9 }) });
+      return ok(r) && (r.body as Body).object === 'chat.completion';
+    }),
+  ),
+  done('openai.chat.deterministic_usage', 'chat', 'Chat: usage token counts deterministic for a fixed request', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const a = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+      const b = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+      if (!ok(a) || !ok(b)) return false;
+      const ua = (a.body as Body).usage as { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number } | undefined;
+      const ub = (b.body as Body).usage as { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number } | undefined;
+      // usage must be a REAL populated token-count object, not just "the same as each other" (undefined === undefined is trivially true).
+      if (!ua || typeof ua.prompt_tokens !== 'number' || ua.prompt_tokens <= 0) return false;
+      if (typeof ua.completion_tokens !== 'number' || ua.completion_tokens <= 0) return false;
+      if (ua.total_tokens !== ua.prompt_tokens + ua.completion_tokens) return false;
+      if (JSON.stringify(ua) !== JSON.stringify(ub)) return false;
+      // the id must be a real, well-formed, content-derived id (deterministic hash), not merely equal-because-both-undefined.
+      const ida = id(a);
+      const idb = id(b);
+      return typeof ida === 'string' && ida.startsWith('chatcmpl-') && ida === idb;
+    }),
+  ),
+  done('openai.chat.system_fingerprint', 'chat', 'Chat: response carries system_fingerprint', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+      return ok(r) && typeof (r.body as Body).system_fingerprint === 'string';
+    }),
+  ),
+  done('openai.chat.json_mode', 'chat', 'response_format json_object / json_schema → valid JSON content', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const obj = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ response_format: { type: 'json_object' } }) });
+      if (!ok(obj)) return false;
+      const objText = (obj.body as Body).choices[0].message.content as string;
+      let parsedObj: any; try { parsedObj = JSON.parse(objText); } catch (err) { if (isInfrastructureError(err)) throw harnessError('openai.chat.json_mode', err); return false; }
+      if (typeof parsedObj !== 'object') return false;
+      const schema = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ response_format: { type: 'json_schema', json_schema: { name: 'r', schema: { type: 'object', properties: { title: { type: 'string' }, count: { type: 'integer' }, ok: { type: 'boolean' } } } } } }) });
+      const schemaText = (schema.body as Body).choices[0].message.content as string;
+      let parsed: any; try { parsed = JSON.parse(schemaText); } catch (err) { if (isInfrastructureError(err)) throw harnessError('openai.chat.json_mode', err); return false; }
+      // every declared property is present + type-appropriate
+      return 'title' in parsed && typeof parsed.title === 'string' && parsed.count === 0 && parsed.ok === false;
+    }),
+  ),
+  done('openai.chat.logprobs', 'chat', 'logprobs + top_logprobs in choices (faithful per-token shape)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      // no logprobs param → choices[].logprobs is null
+      const off = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+      if (!ok(off) || (off.body as Body).choices[0].logprobs !== null) return false;
+      // logprobs:true → content[] with token/logprob/bytes; re-joining tokens reconstructs the text
+      const on = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ logprobs: true }) });
+      const lp = (on.body as Body).choices[0].logprobs;
+      if (!lp || !Array.isArray(lp.content) || lp.content.length === 0) return false;
+      const tok = lp.content[0];
+      if (typeof tok.token !== 'string' || typeof tok.logprob !== 'number' || tok.logprob > 0 || !Array.isArray(tok.bytes)) return false;
+      const joined = lp.content.map((t: Body) => t.token).join('');
+      if (joined !== (on.body as Body).choices[0].message.content) return false;
+      // top_logprobs:2 → each token carries up to 2 alternatives
+      const top = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ logprobs: true, top_logprobs: 2 }) });
+      const t0 = (top.body as Body).choices[0].logprobs.content[0];
+      if (t0.top_logprobs.length !== 2) return false;
+      // top_logprobs without logprobs:true → 400
+      const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ top_logprobs: 2 }) });
+      const oob = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ logprobs: true, top_logprobs: 99 }) });
+      return bad.status === 400 && oob.status === 400;
+    }),
+  ),
+  done('openai.chat.seed', 'chat', 'seed accepted + reflected (distinct seed → distinct id; same seed deterministic)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const a = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ seed: 42 }) });
+      const a2 = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ seed: 42 }) });
+      const b = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ seed: 7 }) });
+      if (!ok(a) || !ok(b)) return false;
+      // same seed → identical id (deterministic); different seed → different id
+      if (id(a) !== id(a2) || id(a) === id(b)) return false;
+      const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ seed: 1.5 }) });
+      return bad.status === 400 && (bad.body as Body).error?.param === 'seed';
+    }),
+  ),
+  done('openai.chat.logit_bias', 'chat', 'logit_bias accepted + validated (object of [-100,100] numbers)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const ok1 = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ logit_bias: { '50256': -100, '1734': 25 } }) });
+      if (!ok(ok1) || (ok1.body as Body).object !== 'chat.completion') return false;
+      const notObj = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ logit_bias: [1, 2] }) });
+      const oob = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ logit_bias: { '50256': 500 } }) });
+      return notObj.status === 400 && oob.status === 400 && (oob.body as Body).error?.param === 'logit_bias';
+    }),
+  ),
+  done('openai.chat.audio', 'chat', 'Audio input/output modalities (input_audio parts + audio output envelope; bytes are a labeled stub)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      // INPUT: an input_audio content part is accepted + counts toward prompt_tokens.
+      const withAudioIn = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ messages: [{ role: 'user', content: [{ type: 'input_audio', input_audio: { data: 'BASE64AUDIO', format: 'wav' } }] }] }) });
+      if (!ok(withAudioIn) || (withAudioIn.body as Body).usage.prompt_tokens <= 0) return false;
+      // OUTPUT: modalities:['text','audio'] + audio:{voice,format} → message.audio envelope.
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ modalities: ['text', 'audio'], audio: { voice: 'alloy', format: 'mp3' } }) });
+      if (!ok(r)) return false;
+      const msg = (r.body as Body).choices[0].message;
+      if (msg.content !== null || !msg.audio) return false;
+      const a = msg.audio;
+      if (typeof a.id !== 'string' || typeof a.data !== 'string' || typeof a.transcript !== 'string' || typeof a.expires_at !== 'number') return false;
+      // the bytes are a LABELED stub (decode the base64 and assert the twin-stub marker + no real synthesis claim)
+      const decoded = Buffer.from(a.data, 'base64').toString('utf8');
+      if (!decoded.includes('[twin-stub') || !decoded.includes('no real audio synthesis')) return false;
+      if (!a.transcript.includes('[twin-stub') || !a.transcript.includes('hello twin')) return false;
+      // modalities includes 'audio' but audio missing → 400
+      const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ modalities: ['text', 'audio'] }) });
+      return bad.status === 400 && (bad.body as Body).error?.param === 'audio';
+    }),
+  ),
+  done('openai.chat.prediction', 'chat', 'Predicted outputs (prediction param → echoed + accepted_prediction_tokens)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ prediction: { type: 'content', content: 'the predicted text body' } }) });
+      if (!ok(r)) return false;
+      const b = r.body as Body;
+      const text = b.choices[0].message.content as string;
+      if (!text.includes('the predicted text body') || !text.includes('[twin-stub')) return false;
+      const details = b.usage.completion_tokens_details;
+      if (!details || details.accepted_prediction_tokens <= 0 || details.rejected_prediction_tokens !== 0) return false;
+      const bad = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ prediction: { type: 'content' } }) });
+      return bad.status === 400 && (bad.body as Body).error?.param === 'prediction';
+    }),
+  ),
+  done('openai.chat.store_metadata', 'chat', 'store + metadata → stored completion retrieve / list / messages / delete', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      // store:false (default) → not retrievable
+      const ns = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+      const nsGet = await h({ m: 'GET', p: `/v1/chat/completions/${id(ns)}` });
+      if (nsGet.status !== 404) return false;
+      // store:true + metadata → retrievable; metadata reflected
+      const c = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ store: true, metadata: { tag: 'unit' } }) });
+      if (!ok(c) || (c.body as Body).metadata?.tag !== 'unit') return false;
+      const g = await h({ m: 'GET', p: `/v1/chat/completions/${id(c)}` });
+      if (!ok(g) || id(g) !== id(c) || (g.body as Body).object !== 'chat.completion') return false;
+      const list = await h({ m: 'GET', p: '/v1/chat/completions' });
+      if (!ok(list) || (list.body as Body).object !== 'list' || ((list.body as Body).data as Body[]).length !== 1) return false;
+      const msgs = await h({ m: 'GET', p: `/v1/chat/completions/${id(c)}/messages` });
+      if (!ok(msgs) || ((msgs.body as Body).data as Body[]).length < 1) return false;
+      const del = await h({ m: 'DELETE', p: `/v1/chat/completions/${id(c)}` });
+      if (!ok(del) || (del.body as Body).deleted !== true) return false;
+      const after = await h({ m: 'GET', p: `/v1/chat/completions/${id(c)}` });
+      return after.status === 404;
+    }),
+  ),
+  done('openai.chat.stream_options_usage', 'chat', 'stream_options.include_usage emits a final usage-only chunk', 'api', 'common', () =>
+    withStream(CHAT({ stream: true, stream_options: { include_usage: true } }), (events, final) => {
+      const usageChunk = events.filter((e) => !e.done).find((e) => e.data!.usage !== undefined && (e.data!.choices as Body[]).length === 0);
+      if (!usageChunk) return false;
+      const u = usageChunk.data!.usage as Body;
+      const fu = (final.body as Body).usage;
+      return u.total_tokens === fu.total_tokens && u.prompt_tokens === fu.prompt_tokens;
+    }),
+  ),
+
+  // ── Streaming ─────────────────────────────────────────────────────────────────────────
+  done('openai.streaming.chunks', 'streaming', 'Streaming chat.completion.chunk sequence ends with [DONE]', 'api', 'core', () =>
+    withStream(CHAT({ stream: true }), (events) => {
+      const data = events.filter((e) => !e.done);
+      const hasRole = data.some((e) => (e.data!.choices as Body[])[0]?.delta?.role === 'assistant');
+      const allChunks = data.every((e) => e.data!.object === 'chat.completion.chunk');
+      const doneLast = events.length > 0 && events[events.length - 1]!.done === true;
+      return hasRole && allChunks && doneLast;
+    }),
+  ),
+  done('openai.streaming.reconstruct', 'streaming', 'Streaming content deltas reconstruct the full message text', 'api', 'core', () =>
+    withStream(CHAT({ stream: true }), (events, final) => {
+      const text = events.filter((e) => !e.done).map((e) => (e.data!.choices as Body[])[0]?.delta?.content ?? '').join('');
+      const full = (final.body as Body).choices[0].message.content as string;
+      return text === full && text.includes('[twin-stub');
+    }),
+  ),
+  done('openai.streaming.finish_reason', 'streaming', 'Streaming final chunk carries finish_reason', 'api', 'common', () =>
+    withStream(CHAT({ stream: true }), (events) => {
+      const withFinish = events.filter((e) => !e.done).find((e) => (e.data!.choices as Body[])[0]?.finish_reason === 'stop');
+      return !!withFinish;
+    }),
+  ),
+  done('openai.streaming.tool_calls', 'streaming', 'Streaming a tool_call emits function name + arguments deltas', 'api', 'common', () =>
+    withStream(CHAT({ stream: true, tools: [{ type: 'function', function: { name: 'lookup', parameters: { type: 'object' } } }] }), (events) => {
+      const data = events.filter((e) => !e.done);
+      const nameDelta = data.find((e) => (e.data!.choices as Body[])[0]?.delta?.tool_calls?.[0]?.function?.name === 'lookup');
+      const finish = data.find((e) => (e.data!.choices as Body[])[0]?.finish_reason === 'tool_calls');
+      return !!nameDelta && !!finish;
+    }),
+  ),
+  done('openai.streaming.usage_chunk', 'streaming', 'No usage chunk without include_usage; present + last (before [DONE]) with it', 'api', 'common', async () => {
+    const without = await withStream(CHAT({ stream: true }), (events) =>
+      !events.filter((e) => !e.done).some((e) => e.data!.usage !== undefined));
+    const withU = await withStream(CHAT({ stream: true, stream_options: { include_usage: true } }), (events) => {
+      const idxUsage = events.findIndex((e) => !e.done && e.data!.usage !== undefined);
+      const idxDone = events.findIndex((e) => e.done === true);
+      return idxUsage >= 0 && idxDone === events.length - 1 && idxUsage === idxDone - 1;
+    });
+    return without && withU;
+  }),
+
+  // ── Tool / function calling ───────────────────────────────────────────────────────────
+  done('openai.tools.tool_calls', 'tools', 'Tools provided → tool_calls + finish_reason tool_calls', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools: [{ type: 'function', function: { name: 'get_weather', parameters: { type: 'object', properties: { city: { type: 'string' } } } } }] }) });
+      if (!ok(r)) return false;
+      const c = (r.body as Body).choices[0];
+      const call = c.message?.tool_calls?.[0];
+      return c.finish_reason === 'tool_calls' && c.message.content === null && call?.type === 'function' && call.function.name === 'get_weather' && String(call.id).startsWith('call_');
+    }),
+  ),
+  done('openai.tools.legacy_functions', 'tools', 'Legacy functions param → tool_call for the named function', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ functions: [{ name: 'legacy_fn', parameters: { type: 'object' } }] }) });
+      const call = (r.body as Body).choices[0]?.message?.tool_calls?.[0];
+      return ok(r) && call?.function?.name === 'legacy_fn';
+    }),
+  ),
+  done('openai.tools.no_tools_text', 'tools', 'No tools → plain text content + finish_reason stop', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+      const c = (r.body as Body).choices[0];
+      return ok(r) && typeof c.message.content === 'string' && c.finish_reason === 'stop' && !c.message.tool_calls;
+    }),
+  ),
+  done('openai.tools.tool_choice', 'tools', 'tool_choice none→text / required+named→that tool / parallel_tool_calls', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const tools = [
+        { type: 'function', function: { name: 'get_weather', parameters: { type: 'object', properties: { city: { type: 'string' } } } } },
+        { type: 'function', function: { name: 'get_time', parameters: { type: 'object', properties: { tz: { type: 'string' } } } } },
+      ];
+      // none → no tool_calls, plain text + finish_reason stop
+      const none = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools, tool_choice: 'none' }) });
+      const nc = (none.body as Body).choices[0];
+      if (!(nc.finish_reason === 'stop' && typeof nc.message.content === 'string' && !nc.message.tool_calls)) return false;
+      // named → exactly that tool
+      const named = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools, tool_choice: { type: 'function', function: { name: 'get_time' } } }) });
+      const calls = (named.body as Body).choices[0].message.tool_calls as Body[];
+      if (!(calls.length === 1 && calls[0]!.function.name === 'get_time')) return false;
+      // default (auto) + parallel_tool_calls true → one call per provided tool
+      const parallel = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools }) });
+      const pcalls = (parallel.body as Body).choices[0].message.tool_calls as Body[];
+      if (pcalls.length !== 2) return false;
+      // parallel_tool_calls false → collapse to a single call
+      const single = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tools, parallel_tool_calls: false }) });
+      return ((single.body as Body).choices[0].message.tool_calls as Body[]).length === 1;
+    }),
+  ),
+  done('openai.tools.strict', 'tools', 'Strict function schemas → arguments validate against the declared schema', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ tool_choice: { type: 'function', function: { name: 'set_user' } }, tools: [{ type: 'function', function: { name: 'set_user', strict: true, parameters: { type: 'object', properties: { name: { type: 'string' }, age: { type: 'integer' }, active: { type: 'boolean' }, role: { type: 'string', enum: ['admin', 'user'] } }, required: ['name', 'age', 'active', 'role'] } } }] }) });
+      const call = (r.body as Body).choices[0]?.message?.tool_calls?.[0];
+      if (!call) return false;
+      let args: any; try { args = JSON.parse(call.function.arguments); } catch (err) { if (isInfrastructureError(err)) throw harnessError('openai.tools.strict', err); return false; }
+      // every declared property is present with a schema-typed value (so a strict parse succeeds)
+      return typeof args.name === 'string' && args.age === 0 && args.active === false && args.role === 'admin';
+    }),
+  ),
+
+  // ── Responses API ─────────────────────────────────────────────────────────────────────
+  done('openai.responses.create', 'responses', 'Responses: create → faithful envelope (id/object/output/usage)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/responses', b: { model: 'gpt-4o', input: 'hello responses' } });
+      if (!ok(r)) return false;
+      const b = r.body as Body;
+      if (b.object !== 'response' || b.status !== 'completed' || !String(b.id).startsWith('resp-')) return false;
+      const item = b.output?.[0];
+      if (item?.type !== 'message' || item.content?.[0]?.type !== 'output_text') return false;
+      return typeof b.usage.input_tokens === 'number' && typeof b.usage.output_tokens === 'number';
+    }),
+  ),
+  done('openai.responses.stub_labeled', 'responses', 'Responses stub output is clearly labeled (not real output)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/responses', b: { model: 'gpt-4o', input: 'echo me responses' } });
+      const text = (r.body as Body).output_text as string;
+      return ok(r) && text.includes('[twin-stub') && text.includes('echo me responses');
+    }),
+  ),
+  done('openai.responses.input_items', 'responses', 'Responses accepts an array of input items (role/content)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/responses', b: { model: 'gpt-4o', input: [{ role: 'user', content: [{ type: 'input_text', text: 'structured input' }] }] } });
+      return ok(r) && (r.body as Body).output?.[0]?.type === 'message';
+    }),
+  ),
+  done('openai.responses.validation', 'responses', 'Responses validation (model + input required)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const noModel = await h({ m: 'POST', p: '/v1/responses', b: { input: 'x' } });
+      const noInput = await h({ m: 'POST', p: '/v1/responses', b: { model: 'gpt-4o' } });
+      return noModel.status === 400 && noInput.status === 400;
+    }),
+  ),
+  done('openai.responses.streaming', 'responses', 'Responses streaming events (created → output_text.delta → completed → [DONE])', 'api', 'common', () =>
+    withStream({ model: 'gpt-4o', input: 'stream responses', stream: true }, (events) => {
+      const types = events.filter((e) => !e.done).map((e) => e.data!.type);
+      const doneLast = events[events.length - 1]?.done === true;
+      return types.includes('response.created') && types.includes('response.output_text.delta') && types.includes('response.completed') && doneLast;
+    }),
+  ),
+  done('openai.responses.retrieve', 'responses', 'Responses: stored by default, retrieve + delete by id (+ 404)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/responses', b: { model: 'gpt-4o', input: 'store me' } });
+      if (!ok(c)) return false;
+      const g = await h({ m: 'GET', p: `/v1/responses/${id(c)}` });
+      if (!ok(g) || id(g) !== id(c) || (g.body as Body).object !== 'response' || (g.body as Body).output_text !== (c.body as Body).output_text) return false;
+      const del = await h({ m: 'DELETE', p: `/v1/responses/${id(c)}` });
+      if (!ok(del) || (del.body as Body).deleted !== true) return false;
+      const after = await h({ m: 'GET', p: `/v1/responses/${id(c)}` });
+      const missing = await h({ m: 'GET', p: '/v1/responses/resp-nope' });
+      // store:false must NOT be retrievable
+      const ns = await h({ m: 'POST', p: '/v1/responses', b: { model: 'gpt-4o', input: 'ephemeral', store: false } });
+      const nsGet = await h({ m: 'GET', p: `/v1/responses/${id(ns)}` });
+      return after.status === 404 && missing.status === 404 && nsGet.status === 404;
+    }),
+  ),
+  outOfScope('openai.responses.tools', 'responses', 'Responses built-in tools (web_search/file_search/computer_use)', 'api', 'niche',
+    'Out of scope: the hosted built-in tools (web_search, computer_use, code_interpreter) require live model+infrastructure side effects the twin cannot reproduce offline — faking a web_search result or a computer_use action would fabricate output and violate the honest-stub contract. (User-defined function tools ARE modeled via openai.tools.*.)'),
+  done('openai.responses.reasoning', 'responses', 'Responses reasoning items + reasoning.effort (faithful reasoning item shape; labeled stub summary)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      // no reasoning param → no reasoning item, no reasoning_tokens
+      const plain = await h({ m: 'POST', p: '/v1/responses', b: { model: 'o4-mini', input: 'think about this' } });
+      if (!ok(plain)) return false;
+      if ((plain.body as Body).output.some((o: Body) => o.type === 'reasoning')) return false;
+      if ((plain.body as Body).usage.output_tokens_details !== undefined) return false;
+      // reasoning.effort:'high' → a reasoning item (labeled stub) BEFORE the message item + reasoning_tokens
+      const r = await h({ m: 'POST', p: '/v1/responses', b: { model: 'o4-mini', input: 'think about this', reasoning: { effort: 'high' } } });
+      if (!ok(r)) return false;
+      const b = r.body as Body;
+      const items = b.output as Body[];
+      const reasoning = items.find((o) => o.type === 'reasoning');
+      const message = items.find((o) => o.type === 'message');
+      if (!reasoning || !message) return false;
+      // reasoning item is first; faithful shape (id/summary[]) with a labeled-stub summary
+      if (items[0]!.type !== 'reasoning' || !String(reasoning.id).startsWith('rs-twin-')) return false;
+      const summary = reasoning.summary?.[0];
+      if (summary?.type !== 'summary_text' || !String(summary.text).includes('[twin-stub') || !String(summary.text).includes('effort=high')) return false;
+      // usage.output_tokens_details.reasoning_tokens > 0 and folded into output_tokens
+      const rt = b.usage.output_tokens_details?.reasoning_tokens;
+      if (typeof rt !== 'number' || rt <= 0) return false;
+      if (b.reasoning?.effort !== 'high') return false;
+      // higher effort → more reasoning tokens (deterministic budget)
+      const low = await h({ m: 'POST', p: '/v1/responses', b: { model: 'o4-mini', input: 'think about this', reasoning: { effort: 'low' } } });
+      if ((low.body as Body).usage.output_tokens_details.reasoning_tokens >= rt) return false;
+      // invalid effort → 400
+      const bad = await h({ m: 'POST', p: '/v1/responses', b: { model: 'o4-mini', input: 'x', reasoning: { effort: 'turbo' } } });
+      return bad.status === 400 && (bad.body as Body).error?.param === 'reasoning.effort';
+    }),
+  ),
+  done('openai.responses.previous_response', 'responses', 'previous_response_id chaining (server-side state; 404 unknown)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const first = await h({ m: 'POST', p: '/v1/responses', b: { model: 'gpt-4o', input: 'first turn' } });
+      if (!ok(first)) return false;
+      const second = await h({ m: 'POST', p: '/v1/responses', b: { model: 'gpt-4o', input: 'second turn', previous_response_id: id(first) } });
+      if (!ok(second) || (second.body as Body).previous_response_id !== id(first)) return false;
+      // chaining folds the prior turn into the prompt → larger input_tokens than the same turn unchained
+      const unchained = await h({ m: 'POST', p: '/v1/responses', b: { model: 'gpt-4o', input: 'second turn' } });
+      if (!((second.body as Body).usage.input_tokens > (unchained.body as Body).usage.input_tokens)) return false;
+      const bad = await h({ m: 'POST', p: '/v1/responses', b: { model: 'gpt-4o', input: 'x', previous_response_id: 'resp-nope' } });
+      return bad.status === 404;
+    }),
+  ),
+  done('openai.responses.input_items_list', 'responses', 'List the input items of a stored response', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/responses', b: { model: 'gpt-4o', input: 'an input turn' } });
+      const items = await h({ m: 'GET', p: `/v1/responses/${id(c)}/input_items` });
+      const data = (items.body as Body).data as Body[];
+      const missing = await h({ m: 'GET', p: '/v1/responses/resp-nope/input_items' });
+      return ok(items) && (items.body as Body).object === 'list' && data.length >= 1 && data[0]!.type === 'message' && missing.status === 404;
+    }),
+  ),
+
+  // ── Embeddings ────────────────────────────────────────────────────────────────────────
+  done('openai.embeddings.create', 'embeddings', 'Embeddings: faithful list envelope + per-input embedding objects', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'text-embedding-3-small', input: 'embed me' } });
+      if (!ok(r)) return false;
+      const b = r.body as Body;
+      const e = b.data?.[0];
+      return b.object === 'list' && e?.object === 'embedding' && e.index === 0 && Array.isArray(e.embedding) && e.embedding.length === 1536 && typeof b.usage.prompt_tokens === 'number';
+    }),
+  ),
+  done('openai.embeddings.deterministic', 'embeddings', 'Embeddings: same input → identical pseudo-vector', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const a = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'text-embedding-3-small', input: 'same' } });
+      const b = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'text-embedding-3-small', input: 'same' } });
+      const va = (a.body as Body).data[0].embedding, vb = (b.body as Body).data[0].embedding;
+      const vc = (await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'text-embedding-3-small', input: 'different' } })).body as Body;
+      return JSON.stringify(va) === JSON.stringify(vb) && JSON.stringify(va) !== JSON.stringify(vc.data[0].embedding);
+    }),
+  ),
+  done('openai.embeddings.batch', 'embeddings', 'Embeddings: array input → one indexed embedding per item', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'text-embedding-3-small', input: ['one', 'two', 'three'] } });
+      const data = (r.body as Body).data as Body[];
+      return ok(r) && data.length === 3 && data[2]!.index === 2;
+    }),
+  ),
+  done('openai.embeddings.dimensions', 'embeddings', 'Embeddings: dimensions param controls vector length; large default 3072', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const custom = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'text-embedding-3-small', input: 'x', dimensions: 256 } });
+      const large = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'text-embedding-3-large', input: 'x' } });
+      return (custom.body as Body).data[0].embedding.length === 256 && (large.body as Body).data[0].embedding.length === 3072;
+    }),
+  ),
+  done('openai.embeddings.normalized', 'embeddings', 'Embeddings: pseudo-vectors are L2-normalized (unit length)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'text-embedding-3-small', input: 'normalize', dimensions: 64 } });
+      const v = (r.body as Body).data[0].embedding as number[];
+      const norm = Math.sqrt(v.reduce((s, x) => s + x * x, 0));
+      return Math.abs(norm - 1) < 1e-6;
+    }),
+  ),
+  done('openai.embeddings.validation', 'embeddings', 'Embeddings: model + input required (400 otherwise)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const noModel = await h({ m: 'POST', p: '/v1/embeddings', b: { input: 'x' } });
+      const noInput = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'text-embedding-3-small' } });
+      return noModel.status === 400 && noInput.status === 400;
+    }),
+  ),
+  done('openai.embeddings.base64', 'embeddings', 'encoding_format base64 → base64 Float32 string decoding to the float vector', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const flt = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'text-embedding-3-small', input: 'b64', dimensions: 8 } });
+      const b64 = await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'text-embedding-3-small', input: 'b64', dimensions: 8, encoding_format: 'base64' } });
+      if (!ok(flt) || !ok(b64)) return false;
+      const floats = (flt.body as Body).data[0].embedding as number[];
+      const encoded = (b64.body as Body).data[0].embedding;
+      if (typeof encoded !== 'string') return false; // base64 returns a STRING, not an array
+      // decode the base64 little-endian Float32 buffer and compare to the float vector
+      const bin = atob(encoded);
+      const buf = new ArrayBuffer(bin.length);
+      const bytes = new Uint8Array(buf);
+      for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+      const view = new DataView(buf);
+      if (bytes.length !== floats.length * 4) return false;
+      for (let i = 0; i < floats.length; i++) {
+        if (Math.abs(view.getFloat32(i * 4, true) - floats[i]!) > 1e-5) return false;
+      }
+      return true;
+    }),
+  ),
+
+  // ── Models ────────────────────────────────────────────────────────────────────────────
+  done('openai.models.list', 'models', 'Models: list (object:list, data array of model objects)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/v1/models' });
+      const b = r.body as Body;
+      return ok(r) && b.object === 'list' && Array.isArray(b.data) && b.data.length > 0 && b.data[0].object === 'model';
+    }),
+  ),
+  done('openai.models.retrieve', 'models', 'Models: retrieve by id (+ 404 model_not_found)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/v1/models/gpt-4o' });
+      if (!ok(r) || (r.body as Body).object !== 'model' || (r.body as Body).id !== 'gpt-4o') return false;
+      const missing = await h({ m: 'GET', p: '/v1/models/nope-9' });
+      return missing.status === 404 && (missing.body as Body).error?.code === 'model_not_found';
+    }),
+  ),
+  done('openai.models.delete', 'models', 'Delete a fine-tuned model (job output); base models refuse; 404 unknown', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const job = await h({ m: 'POST', p: '/v1/fine_tuning/jobs', b: { model: 'gpt-4o-mini', training_file: 'file-train' } });
+      const ftModel = (job.body as Body).fine_tuned_model as string;
+      // the minted fine-tuned model is retrievable + listed
+      const ret = await h({ m: 'GET', p: `/v1/models/${encodeURIComponent(ftModel)}` });
+      if (!ok(ret) || (ret.body as Body).id !== ftModel) return false;
+      const listed = ((await h({ m: 'GET', p: '/v1/models' })).body as Body).data as Body[];
+      if (!listed.some((m) => m.id === ftModel)) return false;
+      // delete it → deleted:true, then gone from retrieve + list
+      const del = await h({ m: 'DELETE', p: `/v1/models/${encodeURIComponent(ftModel)}` });
+      if (!ok(del) || (del.body as Body).deleted !== true) return false;
+      const after = await h({ m: 'GET', p: `/v1/models/${encodeURIComponent(ftModel)}` });
+      if (after.status !== 404) return false;
+      // base catalog model cannot be deleted; unknown → 404
+      const base = await h({ m: 'DELETE', p: '/v1/models/gpt-4o' });
+      const missing = await h({ m: 'DELETE', p: '/v1/models/ft:nope' });
+      return base.status === 400 && missing.status === 404;
+    }),
+  ),
+
+  // ── Moderations ───────────────────────────────────────────────────────────────────────
+  done('openai.moderations.create', 'moderations', 'Moderations: faithful results shape (categories/scores/flagged)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/moderations', b: { input: 'a harmless sentence' } });
+      if (!ok(r)) return false;
+      const res = (r.body as Body).results?.[0];
+      return String((r.body as Body).id).startsWith('modr-') && res && res.flagged === false && typeof res.categories === 'object' && typeof res.category_scores === 'object';
+    }),
+  ),
+  done('openai.moderations.flagging', 'moderations', 'Moderations: deterministic flagging on the keyword heuristic', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/moderations', b: { input: 'I will kill the process' } });
+      const res = (r.body as Body).results?.[0];
+      return ok(r) && res.flagged === true && res.categories.violence === true;
+    }),
+  ),
+  done('openai.moderations.batch', 'moderations', 'Moderations: array input → one result per item', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/moderations', b: { input: ['safe', 'hateful slur'] } });
+      const results = (r.body as Body).results as Body[];
+      return ok(r) && results.length === 2 && results[0]!.flagged === false && results[1]!.flagged === true;
+    }),
+  ),
+
+  // ── Files (stateful) ──────────────────────────────────────────────────────────────────
+  done('openai.files.upload', 'files', 'Files: upload (stateful) with purpose/filename/bytes/status', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/files', b: { purpose: 'fine-tune', filename: 'train.jsonl', content: '{"x":1}' } });
+      if (!ok(r) || (r.body as Body).object !== 'file' || !String(id(r)).startsWith('file-')) return false;
+      const b = r.body as Body;
+      return b.purpose === 'fine-tune' && b.filename === 'train.jsonl' && b.status === 'processed' && b.bytes > 0;
+    }),
+  ),
+  done('openai.files.retrieve', 'files', 'Files: retrieve by id (+ 404 unknown)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/files', b: { purpose: 'batch', filename: 'a.jsonl', content: '{}' } });
+      const g = await h({ m: 'GET', p: `/v1/files/${id(c)}` });
+      const missing = await h({ m: 'GET', p: '/v1/files/file-nope' });
+      return ok(g) && id(g) === id(c) && missing.status === 404;
+    }),
+  ),
+  done('openai.files.list', 'files', 'Files: list (object:list, newest first)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ m: 'POST', p: '/v1/files', b: { purpose: 'batch', filename: 'a.jsonl', content: '{}' } });
+      await h({ m: 'POST', p: '/v1/files', b: { purpose: 'batch', filename: 'b.jsonl', content: '{}' } });
+      const l = await h({ m: 'GET', p: '/v1/files' });
+      return ok(l) && (l.body as Body).object === 'list' && (l.body as Body).data.length === 2;
+    }),
+  ),
+  done('openai.files.content', 'files', 'Files: download content of an uploaded file', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/files', b: { purpose: 'batch', filename: 'a.jsonl', content: 'hello-bytes' } });
+      const content = await h({ m: 'GET', p: `/v1/files/${id(c)}/content` });
+      return ok(content) && content.body === 'hello-bytes';
+    }),
+  ),
+  done('openai.files.delete', 'files', 'Files: delete returns the deleted stub + removes from list', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/files', b: { purpose: 'batch', filename: 'a.jsonl', content: '{}' } });
+      const del = await h({ m: 'DELETE', p: `/v1/files/${id(c)}` });
+      if (!ok(del) || (del.body as Body).deleted !== true) return false;
+      const l = await h({ m: 'GET', p: '/v1/files' });
+      return (l.body as Body).data.length === 0;
+    }),
+  ),
+  done('openai.files.purpose_required', 'files', 'Files: purpose required (400 invalid_request_error)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/files', b: { filename: 'a.jsonl', content: '{}' } });
+      return r.status === 400 && (r.body as Body).error?.param === 'purpose';
+    }),
+  ),
+
+  // ── Batches (stateful) ────────────────────────────────────────────────────────────────
+  done('openai.batches.create', 'batches', 'Batches: create (stateful) with endpoint/input_file_id/status', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/batches', b: { input_file_id: 'file-x', endpoint: '/v1/chat/completions', completion_window: '24h' } });
+      if (!ok(r) || (r.body as Body).object !== 'batch' || !String(id(r)).startsWith('batch-')) return false;
+      const b = r.body as Body;
+      return b.endpoint === '/v1/chat/completions' && b.status === 'completed' && typeof b.output_file_id === 'string';
+    }),
+  ),
+  done('openai.batches.retrieve', 'batches', 'Batches: retrieve by id (+ 404 unknown)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/batches', b: { input_file_id: 'file-x', endpoint: '/v1/chat/completions', completion_window: '24h' } });
+      const g = await h({ m: 'GET', p: `/v1/batches/${id(c)}` });
+      const missing = await h({ m: 'GET', p: '/v1/batches/batch-nope' });
+      return ok(g) && id(g) === id(c) && missing.status === 404;
+    }),
+  ),
+  done('openai.batches.list', 'batches', 'Batches: list (object:list)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ m: 'POST', p: '/v1/batches', b: { input_file_id: 'file-x', endpoint: '/v1/chat/completions', completion_window: '24h' } });
+      const l = await h({ m: 'GET', p: '/v1/batches' });
+      return ok(l) && (l.body as Body).object === 'list' && (l.body as Body).data.length === 1;
+    }),
+  ),
+  done('openai.batches.cancel', 'batches', 'Batches: cancel sets status cancelled (404 unknown)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/batches', b: { input_file_id: 'file-x', endpoint: '/v1/chat/completions', completion_window: '24h' } });
+      const cancel = await h({ m: 'POST', p: `/v1/batches/${id(c)}/cancel` });
+      const missing = await h({ m: 'POST', p: '/v1/batches/batch-nope/cancel' });
+      return ok(cancel) && field(cancel, 'status') === 'cancelled' && missing.status === 404;
+    }),
+  ),
+  done('openai.batches.validation', 'batches', 'Batches: input_file_id/endpoint/completion_window required', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/batches', b: { endpoint: '/v1/chat/completions', completion_window: '24h' } });
+      return r.status === 400 && (r.body as Body).error?.param === 'input_file_id';
+    }),
+  ),
+  done('openai.batches.persistence', 'batches', 'Batches persist across requests (kernel-backed, not a side store)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/batches', b: { input_file_id: 'file-x', endpoint: '/v1/chat/completions', completion_window: '24h' } });
+      if (!ok(c)) return false;
+      const cid = id(c);
+      // a real, well-formed batch id + object/fields must exist — not merely "both sides undefined".
+      if (typeof cid !== 'string' || !cid.startsWith('batch-')) return false;
+      const cb = c.body as Body;
+      if (cb.object !== 'batch' || cb.input_file_id !== 'file-x' || cb.status !== 'completed') return false;
+      const g1 = await h({ m: 'GET', p: `/v1/batches/${cid}` });
+      const g2 = await h({ m: 'GET', p: `/v1/batches/${cid}` });
+      // the GET must actually round-trip the persisted resource's real fields (kernel-backed) —
+      // not merely a matching-because-undefined id.
+      const same = (r: OpenAIResponseEnvelope) => {
+        const rb = r.body as Body;
+        return rb.object === 'batch' && rb.input_file_id === cb.input_file_id && rb.endpoint === cb.endpoint &&
+          rb.status === cb.status && rb.output_file_id === cb.output_file_id;
+      };
+      return ok(g1) && ok(g2) && id(g1) === cid && id(g2) === cid && same(g1) && same(g2);
+    }),
+  ),
+
+  // ── Fine-tuning (stateful) ────────────────────────────────────────────────────────────
+  done('openai.fine_tuning.create', 'fine_tuning', 'Fine-tuning: create job (stateful) with model/training_file/status', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/fine_tuning/jobs', b: { model: 'gpt-4o-mini', training_file: 'file-train' } });
+      if (!ok(r) || (r.body as Body).object !== 'fine_tuning.job' || !String(id(r)).startsWith('ftjob-')) return false;
+      const b = r.body as Body;
+      return b.model === 'gpt-4o-mini' && b.status === 'succeeded' && String(b.fine_tuned_model).startsWith('ft:');
+    }),
+  ),
+  done('openai.fine_tuning.retrieve', 'fine_tuning', 'Fine-tuning: retrieve + list jobs', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/fine_tuning/jobs', b: { model: 'gpt-4o-mini', training_file: 'file-train' } });
+      const g = await h({ m: 'GET', p: `/v1/fine_tuning/jobs/${id(c)}` });
+      const l = await h({ m: 'GET', p: '/v1/fine_tuning/jobs' });
+      return ok(g) && id(g) === id(c) && (l.body as Body).data.length === 1;
+    }),
+  ),
+  done('openai.fine_tuning.events', 'fine_tuning', 'Fine-tuning: job events list', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/fine_tuning/jobs', b: { model: 'gpt-4o-mini', training_file: 'file-train' } });
+      const ev = await h({ m: 'GET', p: `/v1/fine_tuning/jobs/${id(c)}/events` });
+      const data = (ev.body as Body).data as Body[];
+      return ok(ev) && data.length > 0 && data[0]!.object === 'fine_tuning.job.event';
+    }),
+  ),
+  done('openai.fine_tuning.cancel', 'fine_tuning', 'Fine-tuning: cancel job (status cancelled)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/fine_tuning/jobs', b: { model: 'gpt-4o-mini', training_file: 'file-train' } });
+      const cancel = await h({ m: 'POST', p: `/v1/fine_tuning/jobs/${id(c)}/cancel` });
+      return ok(cancel) && field(cancel, 'status') === 'cancelled';
+    }),
+  ),
+  done('openai.fine_tuning.validation', 'fine_tuning', 'Fine-tuning: model + training_file required', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/fine_tuning/jobs', b: { model: 'gpt-4o-mini' } });
+      return r.status === 400 && (r.body as Body).error?.param === 'training_file';
+    }),
+  ),
+  done('openai.fine_tuning.checkpoints', 'fine_tuning', 'Fine-tuning checkpoints list (succeeded job → checkpoint; 404 unknown)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const job = await h({ m: 'POST', p: '/v1/fine_tuning/jobs', b: { model: 'gpt-4o-mini', training_file: 'file-train' } });
+      const ck = await h({ m: 'GET', p: `/v1/fine_tuning/jobs/${id(job)}/checkpoints` });
+      if (!ok(ck) || (ck.body as Body).object !== 'list') return false;
+      const data = (ck.body as Body).data as Body[];
+      if (data.length !== 1 || data[0]!.object !== 'fine_tuning.job.checkpoint' || data[0]!.fine_tuning_job_id !== id(job) || typeof data[0]!.step_number !== 'number') return false;
+      const missing = await h({ m: 'GET', p: '/v1/fine_tuning/jobs/ftjob-nope/checkpoints' });
+      return missing.status === 404;
+    }),
+  ),
+
+  // ── Vector stores (stateful) ──────────────────────────────────────────────────────────
+  done('openai.vector_stores.create', 'vector_stores', 'Vector stores: create (stateful) with name/status/file_counts', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/vector_stores', b: { name: 'docs' } });
+      if (!ok(r) || (r.body as Body).object !== 'vector_store' || !String(id(r)).startsWith('vs-')) return false;
+      const b = r.body as Body;
+      return b.name === 'docs' && b.status === 'completed' && typeof b.file_counts === 'object';
+    }),
+  ),
+  done('openai.vector_stores.crud', 'vector_stores', 'Vector stores: retrieve + list + delete', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/vector_stores', b: { name: 'docs' } });
+      const g = await h({ m: 'GET', p: `/v1/vector_stores/${id(c)}` });
+      const l = await h({ m: 'GET', p: '/v1/vector_stores' });
+      const del = await h({ m: 'DELETE', p: `/v1/vector_stores/${id(c)}` });
+      const after = await h({ m: 'GET', p: '/v1/vector_stores' });
+      return ok(g) && (l.body as Body).data.length === 1 && (del.body as Body).deleted === true && (after.body as Body).data.length === 0;
+    }),
+  ),
+  done('openai.vector_stores.files', 'vector_stores', 'Vector stores: attach + list files', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/vector_stores', b: { name: 'docs' } });
+      const add = await h({ m: 'POST', p: `/v1/vector_stores/${id(c)}/files`, b: { file_id: 'file-abc' } });
+      if (!ok(add) || (add.body as Body).file_id !== 'file-abc' || (add.body as Body).object !== 'vector_store.file') return false;
+      const l = await h({ m: 'GET', p: `/v1/vector_stores/${id(c)}/files` });
+      return ok(l) && (l.body as Body).data.length === 1 && (l.body as Body).data[0].file_id === 'file-abc';
+    }),
+  ),
+  done('openai.vector_stores.seed_files', 'vector_stores', 'Vector stores: create with file_ids seeds attached files', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/vector_stores', b: { name: 'docs', file_ids: ['file-a', 'file-b'] } });
+      const l = await h({ m: 'GET', p: `/v1/vector_stores/${id(c)}/files` });
+      return ok(c) && (l.body as Body).data.length === 2;
+    }),
+  ),
+  done('openai.vector_stores.search', 'vector_stores', 'Vector store search: deterministic ranked results page (+ query required, 404 store)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/vector_stores', b: { name: 'docs', file_ids: ['file-a', 'file-b', 'file-c'] } });
+      const s = await h({ m: 'POST', p: `/v1/vector_stores/${id(c)}/search`, b: { query: 'hello' } });
+      if (!ok(s) || (s.body as Body).object !== 'vector_store.search_results.page') return false;
+      const data = (s.body as Body).data as Body[];
+      if (data.length !== 3 || typeof data[0]!.score !== 'number') return false;
+      // ranked descending + deterministic across runs
+      if (!(data[0]!.score >= data[1]!.score && data[1]!.score >= data[2]!.score)) return false;
+      const s2 = await h({ m: 'POST', p: `/v1/vector_stores/${id(c)}/search`, b: { query: 'hello' } });
+      if (JSON.stringify((s2.body as Body).data) !== JSON.stringify(data)) return false;
+      const maxR = await h({ m: 'POST', p: `/v1/vector_stores/${id(c)}/search`, b: { query: 'hello', max_num_results: 1 } });
+      if (((maxR.body as Body).data as Body[]).length !== 1) return false;
+      const noQuery = await h({ m: 'POST', p: `/v1/vector_stores/${id(c)}/search`, b: {} });
+      const badStore = await h({ m: 'POST', p: '/v1/vector_stores/vs-nope/search', b: { query: 'x' } });
+      return noQuery.status === 400 && badStore.status === 404;
+    }),
+  ),
+  done('openai.vector_stores.file_batches', 'vector_stores', 'Vector store file batches: bulk attach → batch object + retrieve + list batch files', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const vs = await h({ m: 'POST', p: '/v1/vector_stores', b: { name: 'docs' } });
+      const batch = await h({ m: 'POST', p: `/v1/vector_stores/${id(vs)}/file_batches`, b: { file_ids: ['file-a', 'file-b', 'file-c'] } });
+      if (!ok(batch)) return false;
+      const bb = batch.body as Body;
+      if (bb.object !== 'vector_store.file_batch' || bb.status !== 'completed' || bb.file_counts?.total !== 3) return false;
+      // retrieve the batch
+      const get = await h({ m: 'GET', p: `/v1/vector_stores/${id(vs)}/file_batches/${bb.id}` });
+      if (!ok(get) || (get.body as Body).id !== bb.id) return false;
+      // list this batch's files
+      const files = await h({ m: 'GET', p: `/v1/vector_stores/${id(vs)}/file_batches/${bb.id}/files` });
+      if (!ok(files) || ((files.body as Body).data as Body[]).length !== 3) return false;
+      // the files are also attached to the store as a whole
+      const all = await h({ m: 'GET', p: `/v1/vector_stores/${id(vs)}/files` });
+      if (((all.body as Body).data as Body[]).length !== 3) return false;
+      // validation + 404 store + 404 batch
+      const noIds = await h({ m: 'POST', p: `/v1/vector_stores/${id(vs)}/file_batches`, b: {} });
+      const badStore = await h({ m: 'POST', p: '/v1/vector_stores/vs-nope/file_batches', b: { file_ids: ['x'] } });
+      const badBatch = await h({ m: 'GET', p: `/v1/vector_stores/${id(vs)}/file_batches/vsfb-nope` });
+      return noIds.status === 400 && badStore.status === 404 && badBatch.status === 404;
+    }),
+  ),
+
+  // ── Images ────────────────────────────────────────────────────────────────────────────
+  done('openai.images.generations_shape', 'images', 'Images: generations return the faithful response shape (placeholder URL)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/images/generations', b: { model: 'dall-e-3', prompt: 'a cat', n: 1 } });
+      if (!ok(r)) return false;
+      const d = (r.body as Body).data?.[0];
+      return typeof (r.body as Body).created === 'number' && typeof d?.url === 'string' && String(d.revised_prompt).includes('[twin-stub');
+    }),
+  ),
+  done('openai.images.validation', 'images', 'Images: prompt required (400)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/images/generations', b: { model: 'dall-e-3' } });
+      return r.status === 400 && (r.body as Body).error?.param === 'prompt';
+    }),
+  ),
+  done('openai.images.edits', 'images', 'Image edits (image+prompt) + variations (image) → faithful response shape', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const edit = await h({ m: 'POST', p: '/v1/images/edits', b: { image: 'base.png', prompt: 'add a hat' } });
+      if (!ok(edit) || typeof (edit.body as Body).created !== 'number' || typeof (edit.body as Body).data[0].url !== 'string') return false;
+      const varn = await h({ m: 'POST', p: '/v1/images/variations', b: { image: 'base.png', n: 2 } });
+      if (!ok(varn) || ((varn.body as Body).data as Body[]).length !== 2) return false;
+      // validation: edits require image AND prompt; variations require image
+      const noImg = await h({ m: 'POST', p: '/v1/images/edits', b: { prompt: 'x' } });
+      const noPrompt = await h({ m: 'POST', p: '/v1/images/edits', b: { image: 'base.png' } });
+      const varNoImg = await h({ m: 'POST', p: '/v1/images/variations', b: {} });
+      return noImg.status === 400 && noPrompt.status === 400 && varNoImg.status === 400;
+    }),
+  ),
+
+  // ── Audio ─────────────────────────────────────────────────────────────────────────────
+  done('openai.audio.transcriptions', 'audio', 'Audio transcriptions: labeled stub transcript, json + verbose_json + text shapes', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const j = await h({ m: 'POST', p: '/v1/audio/transcriptions', b: { file: 'speech.mp3', model: 'whisper-1' } });
+      if (!ok(j) || typeof (j.body as Body).text !== 'string' || !String((j.body as Body).text).includes('[twin-stub')) return false;
+      const v = await h({ m: 'POST', p: '/v1/audio/transcriptions', b: { file: 'speech.mp3', model: 'whisper-1', response_format: 'verbose_json' } });
+      if (!ok(v) || (v.body as Body).task !== 'transcription' || !Array.isArray((v.body as Body).segments)) return false;
+      const t = await h({ m: 'POST', p: '/v1/audio/transcriptions', b: { file: 'speech.mp3', model: 'whisper-1', response_format: 'text' } });
+      if (!ok(t) || typeof t.body !== 'string') return false;
+      const noFile = await h({ m: 'POST', p: '/v1/audio/transcriptions', b: { model: 'whisper-1' } });
+      const noModel = await h({ m: 'POST', p: '/v1/audio/transcriptions', b: { file: 'speech.mp3' } });
+      return noFile.status === 400 && (noFile.body as Body).error?.param === 'file' && noModel.status === 400;
+    }),
+  ),
+  done('openai.audio.translations', 'audio', 'Audio translations: labeled stub, task translation, english language', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const v = await h({ m: 'POST', p: '/v1/audio/translations', b: { file: 'foreign.mp3', model: 'whisper-1', response_format: 'verbose_json' } });
+      const noFile = await h({ m: 'POST', p: '/v1/audio/translations', b: { model: 'whisper-1' } });
+      return ok(v) && (v.body as Body).task === 'translation' && (v.body as Body).language === 'english' && noFile.status === 400;
+    }),
+  ),
+  done('openai.audio.speech', 'audio', 'Text-to-speech: deterministic labeled audio payload (+ model/input/voice required)', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/audio/speech', b: { model: 'tts-1', input: 'hello world', voice: 'alloy' } });
+      if (!ok(r) || (r.body as Body).object !== 'audio.speech' || typeof (r.body as Body).audio_base64 !== 'string') return false;
+      // deterministic: same input → same payload; decoded marker labels it a stub
+      const r2 = await h({ m: 'POST', p: '/v1/audio/speech', b: { model: 'tts-1', input: 'hello world', voice: 'alloy' } });
+      if ((r.body as Body).audio_base64 !== (r2.body as Body).audio_base64) return false;
+      if (!atob((r.body as Body).audio_base64 as string).includes('[twin-stub-audio]')) return false;
+      const noVoice = await h({ m: 'POST', p: '/v1/audio/speech', b: { model: 'tts-1', input: 'x' } });
+      const noInput = await h({ m: 'POST', p: '/v1/audio/speech', b: { model: 'tts-1', voice: 'alloy' } });
+      return noVoice.status === 400 && (noVoice.body as Body).error?.param === 'voice' && noInput.status === 400;
+    }),
+  ),
+  outOfScope('openai.audio.realtime', 'audio', 'Realtime API (websocket sessions)', 'api', 'niche',
+    'Out of scope: the Realtime API is a stateful bidirectional WebSocket carrying live audio to/from a running speech model — both the transport and the real-time model inference are irreproducible offline. The twin runs no model and the verify() harness is HTTP/offline, so a faithful realtime session cannot be modeled without fabrication.'),
+
+  // ── Assistants (beta) ─────────────────────────────────────────────────────────────────
+  done('openai.assistants.crud', 'assistants', 'Assistants: create/retrieve/update/list/delete (+ model required, 404)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const noModel = await h({ m: 'POST', p: '/v1/assistants', b: { name: 'a' } });
+      if (noModel.status !== 400) return false;
+      const c = await h({ m: 'POST', p: '/v1/assistants', b: { model: 'gpt-4o', name: 'Helper', instructions: 'be helpful', tools: [{ type: 'code_interpreter' }] } });
+      if (!ok(c) || !String(id(c)).startsWith('asst-') || (c.body as Body).object !== 'assistant' || (c.body as Body).name !== 'Helper') return false;
+      const g = await h({ m: 'GET', p: `/v1/assistants/${id(c)}` });
+      if (!ok(g) || id(g) !== id(c)) return false;
+      const upd = await h({ m: 'POST', p: `/v1/assistants/${id(c)}`, b: { name: 'Renamed' } });
+      if (!ok(upd) || (upd.body as Body).name !== 'Renamed' || (upd.body as Body).instructions !== 'be helpful') return false;
+      const l = await h({ m: 'GET', p: '/v1/assistants' });
+      if (!ok(l) || ((l.body as Body).data as Body[]).length !== 1) return false;
+      const del = await h({ m: 'DELETE', p: `/v1/assistants/${id(c)}` });
+      if (!ok(del) || (del.body as Body).deleted !== true) return false;
+      const after = await h({ m: 'GET', p: `/v1/assistants/${id(c)}` });
+      const missing = await h({ m: 'GET', p: '/v1/assistants/asst-nope' });
+      return after.status === 404 && missing.status === 404;
+    }),
+  ),
+  done('openai.threads.crud', 'assistants', 'Threads + messages: create/retrieve/update/delete + add/list/retrieve messages', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      // create a thread with an inline seed message
+      const t = await h({ m: 'POST', p: '/v1/threads', b: { messages: [{ role: 'user', content: 'seed turn' }], metadata: { k: 'v' } } });
+      if (!ok(t) || !String(id(t)).startsWith('thread-') || (t.body as Body).object !== 'thread') return false;
+      const g = await h({ m: 'GET', p: `/v1/threads/${id(t)}` });
+      if (!ok(g) || id(g) !== id(t)) return false;
+      // the seed message is present
+      const seeded = await h({ m: 'GET', p: `/v1/threads/${id(t)}/messages` });
+      if (((seeded.body as Body).data as Body[]).length !== 1) return false;
+      // add a message
+      const m = await h({ m: 'POST', p: `/v1/threads/${id(t)}/messages`, b: { role: 'user', content: 'another turn' } });
+      if (!ok(m) || (m.body as Body).object !== 'thread.message' || (m.body as Body).content[0].text.value !== 'another turn') return false;
+      const mg = await h({ m: 'GET', p: `/v1/threads/${id(t)}/messages/${id(m)}` });
+      if (!ok(mg) || id(mg) !== id(m)) return false;
+      const list = await h({ m: 'GET', p: `/v1/threads/${id(t)}/messages` });
+      if (((list.body as Body).data as Body[]).length !== 2) return false;
+      // content required
+      const noContent = await h({ m: 'POST', p: `/v1/threads/${id(t)}/messages`, b: { role: 'user' } });
+      if (noContent.status !== 400) return false;
+      // update thread metadata
+      const upd = await h({ m: 'POST', p: `/v1/threads/${id(t)}`, b: { metadata: { k: 'v2' } } });
+      if ((upd.body as Body).metadata?.k !== 'v2') return false;
+      // delete
+      const del = await h({ m: 'DELETE', p: `/v1/threads/${id(t)}` });
+      if (!ok(del) || (del.body as Body).deleted !== true) return false;
+      const after = await h({ m: 'GET', p: `/v1/threads/${id(t)}` });
+      const missingMsg = await h({ m: 'POST', p: '/v1/threads/thread-nope/messages', b: { role: 'user', content: 'x' } });
+      return after.status === 404 && missingMsg.status === 404;
+    }),
+  ),
+  done('openai.runs.crud', 'assistants', 'Runs + run steps: create (stub completion) / retrieve / list / steps / cancel', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const a = await h({ m: 'POST', p: '/v1/assistants', b: { model: 'gpt-4o', name: 'Runner' } });
+      const t = await h({ m: 'POST', p: '/v1/threads', b: { messages: [{ role: 'user', content: 'do a thing' }] } });
+      // assistant_id required + 404 unknown assistant
+      const noAsst = await h({ m: 'POST', p: `/v1/threads/${id(t)}/runs`, b: {} });
+      const badAsst = await h({ m: 'POST', p: `/v1/threads/${id(t)}/runs`, b: { assistant_id: 'asst-nope' } });
+      if (noAsst.status !== 400 || badAsst.status !== 404) return false;
+      // create a run → completed, stub assistant reply appended to the thread
+      const run = await h({ m: 'POST', p: `/v1/threads/${id(t)}/runs`, b: { assistant_id: id(a) } });
+      if (!ok(run) || !String(id(run)).startsWith('run-') || (run.body as Body).object !== 'thread.run' || (run.body as Body).status !== 'completed') return false;
+      if ((run.body as Body).assistant_id !== id(a) || (run.body as Body).thread_id !== id(t)) return false;
+      // the thread now has the user turn + the stub assistant reply
+      const msgs = ((await h({ m: 'GET', p: `/v1/threads/${id(t)}/messages` })).body as Body).data as Body[];
+      const assistantMsg = msgs.find((mm) => mm.role === 'assistant');
+      if (!assistantMsg || !String(assistantMsg.content[0].text.value).includes('[twin-stub')) return false;
+      // retrieve the run + list runs
+      const gr = await h({ m: 'GET', p: `/v1/threads/${id(t)}/runs/${id(run)}` });
+      if (!ok(gr) || id(gr) !== id(run)) return false;
+      const lr = await h({ m: 'GET', p: `/v1/threads/${id(t)}/runs` });
+      if (((lr.body as Body).data as Body[]).length !== 1) return false;
+      // run steps: a message_creation step pointing at the reply message
+      const steps = await h({ m: 'GET', p: `/v1/threads/${id(t)}/runs/${id(run)}/steps` });
+      const sd = (steps.body as Body).data as Body[];
+      if (sd.length !== 1 || sd[0]!.object !== 'thread.run.step' || sd[0]!.type !== 'message_creation') return false;
+      if (sd[0]!.step_details.message_creation.message_id !== assistantMsg.id) return false;
+      const gs = await h({ m: 'GET', p: `/v1/threads/${id(t)}/runs/${id(run)}/steps/${sd[0]!.id}` });
+      if (!ok(gs) || (gs.body as Body).id !== sd[0]!.id) return false;
+      // cancel
+      const cancel = await h({ m: 'POST', p: `/v1/threads/${id(t)}/runs/${id(run)}/cancel` });
+      if (!ok(cancel) || (cancel.body as Body).status !== 'cancelled') return false;
+      const badRun = await h({ m: 'GET', p: `/v1/threads/${id(t)}/runs/run-nope` });
+      return badRun.status === 404;
+    }),
+  ),
+
+  // ── Admin / org ───────────────────────────────────────────────────────────────────────
+  done('openai.uploads.multipart', 'uploads', 'Uploads API: create → add parts → complete assembles a File (+ cancel, validation)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      // create requires filename/purpose/bytes/mime_type
+      const noFn = await h({ m: 'POST', p: '/v1/uploads', b: { purpose: 'fine-tune', bytes: 10, mime_type: 'text/plain' } });
+      if (noFn.status !== 400) return false;
+      const up = await h({ m: 'POST', p: '/v1/uploads', b: { filename: 'big.jsonl', purpose: 'fine-tune', bytes: 6, mime_type: 'text/plain' } });
+      if (!ok(up) || (up.body as Body).object !== 'upload' || (up.body as Body).status !== 'pending' || !String(id(up)).startsWith('upload-')) return false;
+      const p1 = await h({ m: 'POST', p: `/v1/uploads/${id(up)}/parts`, b: { data: 'foo' } });
+      const p2 = await h({ m: 'POST', p: `/v1/uploads/${id(up)}/parts`, b: { data: 'bar' } });
+      if (!ok(p1) || !ok(p2) || (p1.body as Body).object !== 'upload.part') return false;
+      // complete in the given part order assembles 'foobar' into a real File
+      const done = await h({ m: 'POST', p: `/v1/uploads/${id(up)}/complete`, b: { part_ids: [(p1.body as Body).id, (p2.body as Body).id] } });
+      if (!ok(done) || (done.body as Body).status !== 'completed' || !(done.body as Body).file) return false;
+      const fileId = (done.body as Body).file.id as string;
+      const content = await h({ m: 'GET', p: `/v1/files/${fileId}/content` });
+      if (content.body !== 'foobar') return false;
+      // adding a part after completion fails; cancel a fresh upload
+      const lateP = await h({ m: 'POST', p: `/v1/uploads/${id(up)}/parts`, b: { data: 'x' } });
+      const up2 = await h({ m: 'POST', p: '/v1/uploads', b: { filename: 'c.jsonl', purpose: 'fine-tune', bytes: 1, mime_type: 'text/plain' } });
+      const cancel = await h({ m: 'POST', p: `/v1/uploads/${id(up2)}/cancel` });
+      return lateP.status === 404 && ok(cancel) && (cancel.body as Body).status === 'cancelled';
+    }),
+  ),
+  done('openai.admin.projects', 'admin', 'Admin: projects create/retrieve/modify/list/archive (+ archived hidden by default)', 'connector', 'niche', () =>
+    withRoot(async (h) => {
+      const noName = await h({ m: 'POST', p: '/v1/organization/projects', b: {} });
+      if (noName.status !== 400) return false;
+      const c = await h({ m: 'POST', p: '/v1/organization/projects', b: { name: 'Alpha' } });
+      if (!ok(c) || (c.body as Body).object !== 'organization.project' || !String(id(c)).startsWith('proj-') || (c.body as Body).status !== 'active') return false;
+      const g = await h({ m: 'GET', p: `/v1/organization/projects/${id(c)}` });
+      if (!ok(g) || id(g) !== id(c)) return false;
+      const upd = await h({ m: 'POST', p: `/v1/organization/projects/${id(c)}`, b: { name: 'Alpha2' } });
+      if ((upd.body as Body).name !== 'Alpha2') return false;
+      const arch = await h({ m: 'POST', p: `/v1/organization/projects/${id(c)}/archive` });
+      if (!ok(arch) || (arch.body as Body).status !== 'archived') return false;
+      // archived project hidden by default, visible with include_archived
+      const def = ((await h({ m: 'GET', p: '/v1/organization/projects' })).body as Body).data as Body[];
+      const withArch = ((await h({ m: 'GET', p: '/v1/organization/projects?include_archived=true' })).body as Body).data as Body[];
+      const missing = await h({ m: 'GET', p: '/v1/organization/projects/proj-nope' });
+      return def.length === 0 && withArch.length === 1 && missing.status === 404;
+    }),
+  ),
+  done('openai.admin.api_keys', 'admin', 'Admin: project API keys create (one-time secret) / list / retrieve (redacted) / delete', 'connector', 'niche', () =>
+    withRoot(async (h) => {
+      const proj = await h({ m: 'POST', p: '/v1/organization/projects', b: { name: 'Keys' } });
+      const pid = id(proj);
+      const key = await h({ m: 'POST', p: `/v1/organization/projects/${pid}/api_keys`, b: { name: 'CI key' } });
+      if (!ok(key)) return false;
+      const kb = key.body as Body;
+      // creation returns the one-time secret value (a synthetic twin key, not a real OpenAI key)
+      if (kb.object !== 'organization.project.api_key' || typeof kb.value !== 'string' || !String(kb.value).startsWith('sk-twin-')) return false;
+      // retrieve only shows the redacted value, never the secret
+      const g = await h({ m: 'GET', p: `/v1/organization/projects/${pid}/api_keys/${kb.id}` });
+      if (!ok(g) || (g.body as Body).value !== undefined || typeof (g.body as Body).redacted_value !== 'string') return false;
+      const list = await h({ m: 'GET', p: `/v1/organization/projects/${pid}/api_keys` });
+      if (((list.body as Body).data as Body[]).length !== 1) return false;
+      const del = await h({ m: 'DELETE', p: `/v1/organization/projects/${pid}/api_keys/${kb.id}` });
+      if (!ok(del) || (del.body as Body).deleted !== true) return false;
+      const after = await h({ m: 'GET', p: `/v1/organization/projects/${pid}/api_keys/${kb.id}` });
+      return after.status === 404;
+    }),
+  ),
+  done('openai.usage.costs', 'admin', 'Usage + costs reporting endpoints computed over REAL recorded usage', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      // with no traffic the report is genuinely EMPTY (nothing hardcoded)
+      const empty = await h({ m: 'GET', p: '/v1/organization/usage/completions' });
+      if (!ok(empty) || (empty.body as Body).object !== 'page' || ((empty.body as Body).data as Body[]).length !== 0) return false;
+      const emptyCosts = await h({ m: 'GET', p: '/v1/organization/costs' });
+      if (((emptyCosts.body as Body).data as Body[]).length !== 0) return false;
+      // generate real usage: two chat calls (gpt-4o) + one embeddings call
+      const c1 = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+      const c2 = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT({ messages: [{ role: 'user', content: 'another prompt entirely' }] }) });
+      await h({ m: 'POST', p: '/v1/embeddings', b: { model: 'text-embedding-3-small', input: 'embed me' } });
+      // completions usage aggregates the two chat calls under gpt-4o
+      const usage = await h({ m: 'GET', p: '/v1/organization/usage/completions' });
+      const buckets = (usage.body as Body).data as Body[];
+      if (buckets.length !== 1) return false;
+      const results = buckets[0]!.results as Body[];
+      const gpt4o = results.find((r) => r.model === 'gpt-4o');
+      if (!gpt4o || gpt4o.object !== 'organization.usage.completions.result' || gpt4o.num_model_requests !== 2) return false;
+      // the recorded input/output tokens equal the sum of the two completions' real usage
+      const expectedIn = (c1.body as Body).usage.prompt_tokens + (c2.body as Body).usage.prompt_tokens;
+      const expectedOut = (c1.body as Body).usage.completion_tokens + (c2.body as Body).usage.completion_tokens;
+      if (gpt4o.input_tokens !== expectedIn || gpt4o.output_tokens !== expectedOut) return false;
+      // embeddings usage is filtered out of the completions view, present under embeddings
+      if (results.some((r) => r.model.startsWith('text-embedding'))) return false;
+      const emb = await h({ m: 'GET', p: '/v1/organization/usage/embeddings' });
+      const embResults = ((emb.body as Body).data as Body[])[0]!.results as Body[];
+      if (!embResults.some((r) => r.model === 'text-embedding-3-small' && r.object === 'organization.usage.embeddings.result')) return false;
+      // costs: a non-zero amount computed from the recorded usage (not hardcoded)
+      const costs = await h({ m: 'GET', p: '/v1/organization/costs' });
+      const costResults = ((costs.body as Body).data as Body[])[0]!.results as Body[];
+      const completionsCost = costResults.find((r) => r.line_item === 'completions');
+      if (!completionsCost || completionsCost.object !== 'organization.costs.result' || completionsCost.amount.currency !== 'usd' || !(completionsCost.amount.value > 0)) return false;
+      // the cost matches the price-table computation over the recorded tokens (gpt-4o: $2.5/$10 per 1M)
+      const expectedCost = (expectedIn / 1e6) * 2.5 + (expectedOut / 1e6) * 10;
+      return Math.abs(completionsCost.amount.value - expectedCost) < 1e-9;
+    }),
+  ),
+
+  // ── Evals API (config → runs → output items) ──────────────────────────────────────────
+  done('openai.evals.api', 'evals', 'Evals API — create/run/list evals + eval runs + output items', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      // create an eval, read it back, assert values
+      const ev = await h({ m: 'POST', p: '/v1/evals', b: { name: 'qa-eval', data_source_config: { type: 'custom', item_schema: { type: 'object' } }, testing_criteria: [{ type: 'string_check', name: 'match', input: '{{item.x}}', reference: 'y', operation: 'eq' }] } });
+      if (!ok(ev) || field(ev, 'object') !== 'eval' || field(ev, 'name') !== 'qa-eval') return false;
+      const evalId = id(ev);
+      const got = await h({ m: 'GET', p: `/v1/evals/${evalId}` });
+      // the testing_criteria round-trips through the kernel byte-for-byte (not fabricated)
+      const tc = field(got, 'testing_criteria') as Body[];
+      if (!ok(got) || id(got) !== evalId || !Array.isArray(tc) || tc[0]?.name !== 'match' || tc[0]?.operation !== 'eq') return false;
+      const dsc = field(got, 'data_source_config') as Body;
+      if (dsc?.type !== 'custom') return false;
+      const list = await h({ m: 'GET', p: '/v1/evals' });
+      if (!ok(list) || !(list.body as Body).data.some((e: Body) => e.id === evalId)) return false;
+      // kick off a run; assert completed + result_counts + per_model_usage reflects the run model
+      const run = await h({ m: 'POST', p: `/v1/evals/${evalId}/runs`, b: { name: 'run-1', data_source: { type: 'completions', model: 'gpt-4.1', source: { type: 'file_content', content: [] } } } });
+      if (!ok(run) || field(run, 'object') !== 'eval.run' || field(run, 'status') !== 'completed') return false;
+      const rc = field(run, 'result_counts') as Body;
+      if (rc.passed !== 1 || rc.total !== 1 || field(run, 'eval_id') !== evalId) return false;
+      // the run echoes the model from the request data_source (not a hardcoded default)
+      if (field(run, 'model') !== 'gpt-4.1') return false;
+      const pmu = field(run, 'per_model_usage') as Body[];
+      if (!Array.isArray(pmu) || pmu[0]?.model_name !== 'gpt-4.1') return false;
+      const runId = id(run);
+      const runGet = await h({ m: 'GET', p: `/v1/evals/${evalId}/runs/${runId}` });
+      if (!ok(runGet) || id(runGet) !== runId) return false;
+      const runList = await h({ m: 'GET', p: `/v1/evals/${evalId}/runs` });
+      if (!ok(runList) || !(runList.body as Body).data.some((r: Body) => r.id === runId)) return false;
+      // output items
+      const items = await h({ m: 'GET', p: `/v1/evals/${evalId}/runs/${runId}/output_items` });
+      if (!ok(items)) return false;
+      const it = (items.body as Body).data?.[0] as Body;
+      if (!it || it.object !== 'eval.run.output_item' || it.status !== 'pass' || it.run_id !== runId) return false;
+      // negative: missing testing_criteria → 400; missing data_source_config → 400; unknown eval id → 404
+      const noCriteria = await h({ m: 'POST', p: '/v1/evals', b: { data_source_config: { type: 'custom' } } });
+      const noConfig = await h({ m: 'POST', p: '/v1/evals', b: { testing_criteria: [] } });
+      const missing = await h({ m: 'GET', p: '/v1/evals/eval-nope' });
+      const missingRun = await h({ m: 'POST', p: '/v1/evals/eval-nope/runs', b: { data_source: {} } });
+      return noCriteria.status === 400 && noConfig.status === 400 && missing.status === 404 && missingRun.status === 404;
+    }),
+  ),
+
+  // ── Containers API (code-interpreter sandboxes → container files) ──────────────────────
+  done('openai.containers.api', 'containers', 'Containers API — create/list/delete containers + container files (code-interpreter sandboxes)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const c = await h({ m: 'POST', p: '/v1/containers', b: { name: 'sandbox-1' } });
+      if (!ok(c) || field(c, 'object') !== 'container' || field(c, 'status') !== 'running' || field(c, 'name') !== 'sandbox-1') return false;
+      const cid = id(c);
+      const got = await h({ m: 'GET', p: `/v1/containers/${cid}` });
+      if (!ok(got) || id(got) !== cid) return false;
+      const list = await h({ m: 'GET', p: '/v1/containers' });
+      if (!ok(list) || !(list.body as Body).data.some((x: Body) => x.id === cid)) return false;
+      // container file with inline text content → read back metadata + content
+      const cf = await h({ m: 'POST', p: `/v1/containers/${cid}/files`, b: { path: '/mnt/data/a.txt', content: 'hello sandbox' } });
+      if (!ok(cf) || field(cf, 'object') !== 'container.file' || field(cf, 'container_id') !== cid || field(cf, 'bytes') !== 'hello sandbox'.length || field(cf, 'path') !== '/mnt/data/a.txt') return false;
+      const fid = id(cf);
+      const content = await h({ m: 'GET', p: `/v1/containers/${cid}/files/${fid}/content` });
+      if (!ok(content) || content.body !== 'hello sandbox') return false;
+      const fileGet = await h({ m: 'GET', p: `/v1/containers/${cid}/files/${fid}` });
+      if (!ok(fileGet) || id(fileGet) !== fid) return false;
+      const del = await h({ m: 'DELETE', p: `/v1/containers/${cid}/files/${fid}` });
+      if (!ok(del) || (del.body as Body).deleted !== true) return false;
+      const afterDel = await h({ m: 'GET', p: `/v1/containers/${cid}/files/${fid}` });
+      if (afterDel.status !== 404) return false;
+      // delete the container; subsequent GET → 404
+      const delC = await h({ m: 'DELETE', p: `/v1/containers/${cid}` });
+      const gone = await h({ m: 'GET', p: `/v1/containers/${cid}` });
+      // negative: create without name → 400; unknown container → 404
+      const bad = await h({ m: 'POST', p: '/v1/containers', b: {} });
+      const missing = await h({ m: 'GET', p: '/v1/containers/cntr-nope' });
+      return ok(delC) && gone.status === 404 && bad.status === 400 && missing.status === 404;
+    }),
+  ),
+
+  // ── Background responses (queued → poll → completed | cancel) ──────────────────────────
+  done('openai.responses.background', 'responses', 'Background responses (background:true → queued status + poll + cancel)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      // background:true → immediate queued response with no output yet
+      const bg = await h({ m: 'POST', p: '/v1/responses', b: { model: 'gpt-4o', input: 'background task A', background: true } });
+      if (!ok(bg) || field(bg, 'status') !== 'queued' || field(bg, 'background') !== true) return false;
+      if (field(bg, 'output_text') !== null || ((field(bg, 'output') as unknown[]) ?? []).length !== 0) return false;
+      const rid = id(bg);
+      // first poll → transitions to completed with the real stub output + usage
+      const poll = await h({ m: 'GET', p: `/v1/responses/${rid}` });
+      if (!ok(poll) || field(poll, 'status') !== 'completed') return false;
+      const text = field(poll, 'output_text');
+      if (typeof text !== 'string' || !text.includes('[twin-stub')) return false;
+      // usage must be coherent: total = input + output, and output > 0 (the stub produced text)
+      const usage = field(poll, 'usage') as Body;
+      if (!usage || typeof usage.output_tokens !== 'number' || usage.output_tokens <= 0) return false;
+      if (usage.total_tokens !== usage.input_tokens + usage.output_tokens) return false;
+      // the completion is billable: a usage_record was recorded → the usage report is non-empty
+      const report = await h({ m: 'GET', p: '/v1/organization/usage/responses' });
+      const buckets = (report.body as Body).data as Body[];
+      if (!ok(report) || buckets.length === 0) return false;
+      // a second poll stays completed (idempotent) with the same output text (no re-billing visible)
+      const poll2 = await h({ m: 'GET', p: `/v1/responses/${rid}` });
+      if (field(poll2, 'status') !== 'completed' || field(poll2, 'output_text') !== text) return false;
+      // cancel a still-queued background response → cancelled
+      const bg2 = await h({ m: 'POST', p: '/v1/responses', b: { model: 'gpt-4o', input: 'background task B', background: true } });
+      const rid2 = id(bg2);
+      const cancel = await h({ m: 'POST', p: `/v1/responses/${rid2}/cancel` });
+      if (!ok(cancel) || field(cancel, 'status') !== 'cancelled') return false;
+      // negative: cancel an already-completed response → 400; cancel unknown id → 404
+      const reCancel = await h({ m: 'POST', p: `/v1/responses/${rid}/cancel` });
+      const missing = await h({ m: 'POST', p: '/v1/responses/resp-nope/cancel' });
+      return reCancel.status === 400 && missing.status === 404;
+    }),
+  ),
+
+  // ── Fine-tuning pause / resume ─────────────────────────────────────────────────────────
+  done('openai.fine_tuning.pause_resume', 'fine_tuning', 'Fine-tuning job pause / resume — status transitions', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const job = await h({ m: 'POST', p: '/v1/fine_tuning/jobs', b: { model: 'gpt-4o-mini', training_file: 'file-twin-1' } });
+      if (!ok(job) || field(job, 'status') !== 'succeeded') return false;
+      const jid = id(job);
+      // pause → status 'paused'
+      const paused = await h({ m: 'POST', p: `/v1/fine_tuning/jobs/${jid}/pause` });
+      if (!ok(paused) || field(paused, 'status') !== 'paused') return false;
+      const readPaused = await h({ m: 'GET', p: `/v1/fine_tuning/jobs/${jid}` });
+      if (field(readPaused, 'status') !== 'paused') return false;
+      // resume → back to 'succeeded', and the persisted state round-trips
+      const resumed = await h({ m: 'POST', p: `/v1/fine_tuning/jobs/${jid}/resume` });
+      if (!ok(resumed) || field(resumed, 'status') !== 'succeeded') return false;
+      const readResumed = await h({ m: 'GET', p: `/v1/fine_tuning/jobs/${jid}` });
+      if (field(readResumed, 'status') !== 'succeeded') return false;
+      // negative: resuming the now-succeeded (non-paused) job → 400; pause unknown job → 404
+      const badResume = await h({ m: 'POST', p: `/v1/fine_tuning/jobs/${jid}/resume` });
+      const missing = await h({ m: 'POST', p: '/v1/fine_tuning/jobs/ftjob-nope/pause' });
+      return badResume.status === 400 && missing.status === 404;
+    }),
+  ),
+
+  // ── Webhook signature verification (REAL HMAC, Standard-Webhooks scheme) ────────────────
+  done('openai.webhooks.verify', 'webhooks', 'Webhook event signature verification (REAL signing-secret HMAC, Standard-Webhooks)', 'api', 'niche', async () => {
+    // a 32-byte base64 signing secret (whsec_<base64>), like the vendor mints.
+    const secret = 'whsec_' + Buffer.from('0123456789abcdef0123456789abcdef').toString('base64');
+    const signed = buildSignedOpenAIWebhook({ type: 'response.completed', resourceId: 'resp-twin-abc', secret, occurredAt: '2026-01-01T00:00:00Z', webhookId: 'wh-1' });
+    // a good delivery verifies and returns the parsed event with faithful shape
+    const ev = verifyOpenAIWebhook(signed.body, signed.headers, secret);
+    if (ev.object !== 'event' || ev.type !== 'response.completed' || ev.data.id !== 'resp-twin-abc') return false;
+    // the signature header is the Standard-Webhooks `v1,<base64>` form computed over id.ts.payload
+    const recomputed = computeOpenAIWebhookSignature('wh-1', Math.floor(Date.parse('2026-01-01T00:00:00Z') / 1000), signed.body, secret);
+    if (signed.headers['webhook-signature'] !== recomputed) return false;
+    // a TAMPERED payload must be rejected (the real verifier throws)
+    let tamperedRejected = false;
+    try { verifyOpenAIWebhook(signed.body + ' ', signed.headers, secret); } catch (e) { tamperedRejected = e instanceof OpenAIWebhookVerificationError; }
+    if (!tamperedRejected) return false;
+    // a wrong secret must be rejected
+    let wrongSecretRejected = false;
+    try { verifyOpenAIWebhook(signed.body, signed.headers, 'whsec_' + Buffer.from('ffffffffffffffffffffffffffffffff').toString('base64')); } catch (e) { wrongSecretRejected = e instanceof OpenAIWebhookVerificationError; }
+    if (!wrongSecretRejected) return false;
+    // missing headers must be rejected
+    let missingRejected = false;
+    try { verifyOpenAIWebhook(signed.body, {}, secret); } catch (e) { missingRejected = e instanceof OpenAIWebhookVerificationError; }
+    return missingRejected;
+  }),
+
+  // ── Genuinely-unmodeled real surfaces (honest todos — the API has these; the twin does not yet) ──
+  todo('openai.evals.run_cancel_delete', 'evals', 'Evals — cancel a run + delete an eval/run', 'api', 'niche'),
+  todo('openai.evals.update', 'evals', 'Evals — update an eval (name/metadata) via POST /v1/evals/:id', 'api', 'niche'),
+  todo('openai.responses.background_stream_resume', 'responses', 'Background responses — resume an in-progress stream via starting_after cursor', 'api', 'niche'),
+  todo('openai.fine_tuning.checkpoint_permissions', 'fine_tuning', 'Fine-tuning checkpoint permissions (per-project grant/list/revoke)', 'api', 'niche'),
+  todo('openai.admin.invites_and_users', 'admin', 'Admin API — organization invites + users (list/retrieve/modify/delete)', 'api', 'niche'),
+
+  // ── Errors / protocol ─────────────────────────────────────────────────────────────────
+  done('openai.errors.not_found', 'errors', 'Vendor-faithful 404 on unknown route', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'GET', p: '/v1/nonexistent' });
+      return r.status === 404 && typeof (r.body as Body).error === 'object' && (r.body as Body).error.type === 'invalid_request_error';
+    }),
+  ),
+  done('openai.errors.invalid_request', 'errors', 'Vendor-faithful 400 invalid_request_error envelope (error.message/type/param/code)', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ m: 'POST', p: '/v1/chat/completions', b: '{bad json' as any });
+      const e = (r.body as Body).error;
+      return r.status === 400 && e && typeof e.message === 'string' && e.type === 'invalid_request_error' && 'param' in e && 'code' in e;
+    }),
+  ),
+  done('openai.read_only_guard', 'errors', 'Read-only mode rejects mutations (405 vendor-shaped error)', 'api', 'common', () => {
+    const root = mkdtempSync(join(tmpdir(), 'openai-cap-'));
+    return handleOpenAITwinRequest({ method: 'POST', path: '/v1/chat/completions', body: JSON.stringify(CHAT()), root, readOnly: true })
+      .then((r) => r.status === 405 && (r.body as Body).error?.type === 'invalid_request_error')
+      .finally(() => rmSync(root, { recursive: true, force: true }));
+  }),
+  done('openai.auth.faked', 'errors', 'Auth is modeled but permissive — any non-empty key is accepted; trusted in-process calls pass', 'api', 'common', () =>
+    withRoot(async (h) => {
+      // trusted in-process calls (no headers/apiKey) are NOT auth-gated → succeed with a REAL model catalog.
+      const trusted = await h({ m: 'GET', p: '/v1/models' });
+      if (!ok(trusted)) return false;
+      const tb = trusted.body as Body;
+      if (tb.object !== 'list' || !Array.isArray(tb.data) || tb.data.length === 0) return false;
+      // a request that carries a valid bearer key is accepted (the twin can't validate real keys),
+      // and it must return the SAME real, non-empty catalog content — not just any 2xx status.
+      const withKey = await handleOpenAITwinRequest({ method: 'GET', path: '/v1/models', headers: { authorization: 'Bearer sk-anything' } });
+      if (!ok(withKey)) return false;
+      const wb = withKey.body as Body;
+      return wb.object === 'list' && Array.isArray(wb.data) && wb.data.length === tb.data.length && JSON.stringify(wb) === JSON.stringify(tb);
+    }),
+  ),
+  done('openai.errors.auth_401', 'errors', 'Authentication error (401) — modeled auth: missing/invalid credential on a request carrying an auth surface', 'api', 'niche', () =>
+    withRootH(async (h) => {
+      // a request carrying an auth surface (headers present) but no credential → 401
+      const missing = await h({ m: 'GET', p: '/v1/models', headers: {} });
+      if (missing.status !== 401) return false;
+      const me = (missing.body as Body).error;
+      if (me?.type !== 'invalid_request_error' || me?.code !== 'invalid_api_key') return false;
+      // an empty bearer is also missing
+      const emptyBearer = await h({ m: 'GET', p: '/v1/models', headers: { authorization: 'Bearer ' } });
+      if (emptyBearer.status !== 401) return false;
+      // the reserved sentinel exercises the invalid-key path deterministically → 401
+      const invalid = await h({ m: 'GET', p: '/v1/models', headers: { authorization: 'Bearer sk-invalid' } });
+      if (invalid.status !== 401) return false;
+      // a valid bearer passes; and a trusted call WITHOUT any auth surface is NOT gated
+      const valid = await h({ m: 'GET', p: '/v1/models', headers: { authorization: 'Bearer sk-twin-good' } });
+      const trusted = await handleOpenAITwinRequest({ method: 'GET', path: '/v1/models' });
+      return ok(valid) && ok(trusted);
+    }),
+  ),
+  done('openai.errors.rate_limit_429', 'errors', 'Rate limit (429) — deterministic opt-in trigger → vendor envelope + Retry-After + x-ratelimit-* headers', 'api', 'niche', () =>
+    withRootH(async (h) => {
+      const auth = { authorization: 'Bearer sk-twin-good' };
+      // no trigger → normal success
+      const normal = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT(), headers: auth });
+      if (!ok(normal)) return false;
+      // the deterministic trigger header → 429 with the vendor error envelope + rate-limit headers
+      const limited = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT(), headers: { ...auth, 'x-twin-force-rate-limit': '1' } });
+      if (limited.status !== 429) return false;
+      const e = (limited.body as Body).error;
+      if (e?.type !== 'rate_limit_exceeded' || e?.code !== 'rate_limit_exceeded') return false;
+      const hdrs = limited.headers;
+      if (!hdrs || hdrs['retry-after'] !== '1') return false;
+      return hdrs['x-ratelimit-remaining-requests'] === '0' && typeof hdrs['x-ratelimit-limit-tokens'] === 'string';
+    }),
+  ),
+  done('openai.protocol.idempotency', 'errors', 'Idempotency-Key header dedup — re-issue replays the same response; a new key → a new result', 'api', 'niche', () =>
+    withRootH(async (h) => {
+      const auth = { authorization: 'Bearer sk-twin-good' };
+      // a mutation (file create) with an Idempotency-Key → re-issue replays the SAME id (no double create)
+      const first = await h({ m: 'POST', p: '/v1/files', b: { purpose: 'batch', filename: 'a.jsonl', content: '{}' }, headers: { ...auth, 'idempotency-key': 'key-A' } });
+      if (!ok(first)) return false;
+      const id1 = (first.body as Body).id as string;
+      const replay = await h({ m: 'POST', p: '/v1/files', b: { purpose: 'batch', filename: 'a.jsonl', content: '{}' }, headers: { ...auth, 'idempotency-key': 'key-A' } });
+      if (!ok(replay) || (replay.body as Body).id !== id1) return false;
+      // the side effect happened ONCE: exactly one file exists
+      const listed = (await h({ m: 'GET', p: '/v1/files', headers: auth })).body as Body;
+      if ((listed.data as Body[]).length !== 1) return false;
+      // a DIFFERENT key → a new, distinct create
+      const second = await h({ m: 'POST', p: '/v1/files', b: { purpose: 'batch', filename: 'a.jsonl', content: '{}' }, headers: { ...auth, 'idempotency-key': 'key-B' } });
+      if (!ok(second) || (second.body as Body).id === id1) return false;
+      const listed2 = (await h({ m: 'GET', p: '/v1/files', headers: auth })).body as Body;
+      // even the replayed body is byte-identical to the first response (full envelope replay)
+      return (listed2.data as Body[]).length === 2 && JSON.stringify(replay.body) === JSON.stringify(first.body);
+    }),
+  ),
+  done('openai.protocol.pagination', 'errors', 'Cursor pagination: after/limit + has_more/first_id/last_id across list endpoints', 'api', 'common', () =>
+    withRoot(async (h) => {
+      // create 3 files; page with limit=2 → has_more + last_id; then after=last_id → final page
+      for (const f of ['a', 'b', 'c']) await h({ m: 'POST', p: '/v1/files', b: { purpose: 'batch', filename: `${f}.jsonl`, content: '{}' } });
+      const p1 = await h({ m: 'GET', p: '/v1/files?limit=2' });
+      const b1 = p1.body as Body;
+      if (!ok(p1) || b1.data.length !== 2 || b1.has_more !== true || b1.last_id !== b1.data[1].id || b1.first_id !== b1.data[0].id) return false;
+      const p2 = await h({ m: 'GET', p: `/v1/files?limit=2&after=${b1.last_id}` });
+      const b2 = p2.body as Body;
+      if (b2.data.length !== 1 || b2.has_more !== false) return false;
+      // the two pages partition the set (no overlap)
+      if (b2.data[0].id === b1.data[0].id || b2.data[0].id === b1.data[1].id) return false;
+      // an unknown cursor → empty page (vendor returns nothing past the end)
+      const empty = await h({ m: 'GET', p: '/v1/files?after=file-nope' });
+      return (empty.body as Body).data.length === 0;
+    }),
+  ),
+
+  // ── Connector (pull/push over an injected client) ─────────────────────────────────────
+  done('openai.connector.read_surface', 'connector', 'Connector read surface (models + files + batches in one pass)', 'connector', 'core', () =>
+    withRoot(async (h) => {
+      const models = await h({ m: 'GET', p: '/v1/models' });
+      const files = await h({ m: 'GET', p: '/v1/files' });
+      const batches = await h({ m: 'GET', p: '/v1/batches' });
+      return ok(models) && Array.isArray((models.body as Body).data) && ok(files) && ok(batches);
+    }),
+  ),
+  done('openai.connector.pull_map', 'connector', 'Connector pulls + maps real state into the twin (offline, injected client)', 'connector', 'core', async () => {
+    const { mapBatch, mapFile, syncOpenAIFromReal } = await import('./openai-connector.ts');
+    const { projectResources } = await import('@volter/twin');
+    const root = mkdtempSync(join(tmpdir(), 'openai-cap-'));
+    try {
+      const mappedFile = mapFile({ id: 'file-real', purpose: 'batch', bytes: 12, status: 'processed', created_at: 1 });
+      const mappedBatch = mapBatch({ id: 'batch-real', status: 'completed', created_at: 1, request_counts: { total: 1 } });
+      if (mappedFile.type !== 'file' || mappedBatch.fields.status !== 'completed') return false;
+      const fake = async (_m: 'GET' | 'POST' | 'DELETE', p: string) => {
+        if (p.startsWith('/v1/files')) return { data: [{ id: 'file-real', purpose: 'batch', bytes: 12, status: 'processed', created_at: 1 }] };
+        if (p.startsWith('/v1/batches')) return { data: [{ id: 'batch-real', status: 'completed', created_at: 1, request_counts: { total: 1 } }] };
+        return { data: [] };
+      };
+      const res = await syncOpenAIFromReal(fake, { root, occurredAt: '2026-06-15T00:00:00Z' });
+      if (res.deltasAppended < 1) return false;
+      const got = projectResources('openai', root).find((r) => r.id === 'file-real');
+      const again = await syncOpenAIFromReal(fake, { root, occurredAt: '2026-06-15T00:00:00Z' });
+      return !!got && got.status === 'processed' && again.deltasAppended === 0;
+    } catch (err) {
+      if (isInfrastructureError(err)) throw harnessError('openai.connector.pull_map', err);
+      return false;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('openai.connector.push_confirm', 'connector', 'Connector pushes pending local writes to real + confirms them (offline, injected client)', 'connector', 'core', async () => {
+    const { pushPendingOpenAIActions, openaiRequestForAction } = await import('./openai-connector.ts');
+    const { pendingActions } = await import('@volter/twin');
+    const root = mkdtempSync(join(tmpdir(), 'openai-cap-'));
+    try {
+      const created = await handleOpenAITwinRequest({ method: 'POST', path: '/v1/batches', body: JSON.stringify({ input_file_id: 'file-x', endpoint: '/v1/chat/completions', completion_window: '24h' }), root, occurredAt: '2026-06-15T00:00:00Z' });
+      if (created.status !== 200) return false;
+      if (pendingActions('openai', root).length === 0) return false;
+      const createReq = openaiRequestForAction({ operation: 'batch.create', subject: { type: 'batch', id: 'batch-twin-1' } });
+      const cancelReq = openaiRequestForAction({ operation: 'batch.cancel', subject: { type: 'batch', id: 'batch-twin-1' } });
+      const delReq = openaiRequestForAction({ operation: 'file.delete', subject: { type: 'file', id: 'file-twin-1' } });
+      if (createReq.path !== '/v1/batches' || cancelReq.path !== '/v1/batches/batch-twin-1/cancel' || delReq.method !== 'DELETE') return false;
+      const calls: string[] = [];
+      const fake = async (m: 'GET' | 'POST' | 'DELETE', p: string) => { calls.push(`${m} ${p}`); return { id: 'batch-real-1' }; };
+      const res = await pushPendingOpenAIActions(fake, { root, occurredAt: '2026-06-15T00:00:01Z' });
+      if (res.pushed < 1 || calls.length < 1) return false;
+      const after = await pushPendingOpenAIActions(fake, { root, occurredAt: '2026-06-15T00:00:02Z' });
+      return pendingActions('openai', root).length === 0 && after.pushed === 0;
+    } catch (err) {
+      if (isInfrastructureError(err)) throw harnessError('openai.connector.push_confirm', err);
+      return false;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('openai.connector.unsupported_op_fails', 'connector', 'Connector refuses to silently drop an unsupported push op', 'connector', 'common', async () => {
+    const { pushOpenAIAction } = await import('./openai-connector.ts');
+    try {
+      const fake = async () => ({ id: 'x' });
+      let threw = false;
+      try { await pushOpenAIAction(fake, { operation: 'batch.frobnicate', subject: { type: 'batch', id: 'batch-1' }, fields: {} }); } catch { threw = true; }
+      return threw;
+    } catch (err) {
+      if (isInfrastructureError(err)) throw harnessError('openai.connector.unsupported_op_fails', err);
+      return false;
+    }
+  }),
+  done('openai.connector.full_sync', 'connector', 'Connector full bi-directional sync: push pending then pull all collections (idempotent)', 'connector', 'common', async () => {
+    const { fullSyncOpenAI } = await import('./openai-connector.ts');
+    const { pendingActions } = await import('@volter/twin');
+    const root = mkdtempSync(join(tmpdir(), 'openai-cap-'));
+    try {
+      // a local write becomes a pending action
+      const created = await handleOpenAITwinRequest({ method: 'POST', path: '/v1/batches', body: JSON.stringify({ input_file_id: 'file-x', endpoint: '/v1/chat/completions', completion_window: '24h' }), root, occurredAt: '2026-06-15T00:00:00Z' });
+      if (created.status !== 200 || pendingActions('openai', root).length === 0) return false;
+      const calls: string[] = [];
+      const fake = async (m: 'GET' | 'POST' | 'DELETE', p: string) => {
+        calls.push(`${m} ${p}`);
+        if (m === 'GET' && p.startsWith('/v1/files')) return { data: [{ id: 'file-real', purpose: 'batch', bytes: 5, status: 'processed', created_at: 1 }] };
+        if (m === 'GET' && p.startsWith('/v1/batches')) return { data: [{ id: 'batch-real', status: 'completed', created_at: 1, request_counts: { total: 1 } }] };
+        if (m === 'GET') return { data: [] };
+        return { id: 'batch-real-pushed' };
+      };
+      const res = await fullSyncOpenAI(fake, { root, occurredAt: '2026-06-15T00:00:01Z' });
+      // pushed the pending write, observed real state, appended deltas, swept all 4 collections
+      if (res.pushed < 1 || res.deltasAppended < 1 || res.collections < 4) return false;
+      if (pendingActions('openai', root).length !== 0) return false;
+      // idempotent: a second run with no pending + identical real state changes nothing
+      const again = await fullSyncOpenAI(fake, { root, occurredAt: '2026-06-15T00:00:02Z' });
+      return again.pushed === 0 && again.deltasAppended === 0;
+    } catch (err) {
+      if (isInfrastructureError(err)) throw harnessError('openai.connector.full_sync', err);
+      return false;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+
+  // ── Conformance harness ───────────────────────────────────────────────────────────────
+  done('openai.conformance.envelopes', 'conformance', 'Offline conformance harness passes (envelope shapes across the surface)', 'connector', 'core', async () => {
+    const { checkOpenAIConformance } = await import('./openai-conformance.ts');
+    const report = await checkOpenAIConformance();
+    return report.ok && report.checksRun >= 6;
+  }),
+  // ── Pull-surface coverage audit gaps (TWIN-46 / G2) — filed as manifest todos, which is
+  // what the demand-ordered build list is drawn from. See pull-audit.json (repo root) for the
+  // per-pack pull-vs-read-surface evidence.
+  todo('openai.connector.pull_model', 'connector', 'Connector: pull the real model catalog (GET /v1/models) into the twin', 'connector', 'core'),
+  todo('openai.connector.pull_assistant', 'connector', 'Connector: pull assistants from the real account', 'connector', 'niche'),
+
+  // ── Missing-area sweep (TWIN-87 / F1) ────────────────────────────────────────────────────
+  // The legacy completions endpoint and org audit logs had NO manifest entry of any status —
+  // neither the twin nor the manifest modeled them, so they never surfaced as gaps. Filed as
+  // honest todos (both genuinely buildable). See OPENAI_AREAS below + openai-capabilities.
+  // test.ts's area-census meta-test, gate-wired so a future whole-area omission fails here.
+  todo('openai.completions_legacy.create', 'completions_legacy', 'Legacy POST /v1/completions (pre-chat text completions endpoint)', 'api', 'niche'),
+  todo('openai.completions_legacy.streaming', 'completions_legacy', 'Legacy completions streaming (text/event-stream deltas)', 'api', 'niche'),
+  todo('openai.admin.audit_logs.list', 'admin', 'Admin API — organization audit logs (GET /v1/organization/audit_logs, filterable)', 'api', 'niche'),
+  todo('openai.admin.audit_logs.get', 'admin', 'Admin API — retrieve a single audit log event by id', 'api', 'niche'),
+
+];
+
+// TWIN-87 committed area census — the vendor's top-level API product areas (docs nav /
+// OpenAPI tags), authored top-down independent of what a manifest entry happens to already
+// exist for. openai-capabilities.test.ts's area-census meta-test (assertAreaCensus) fails the
+// gate if a declared area has zero manifest entries and no named exclusion, OR if a manifest
+// entry's `area` drifts outside this list — so a whole missing area (legacy completions, org
+// audit logs were the concrete F1 leak) can never again hide invisibly.
+export const OPENAI_AREAS = [
+  'admin', 'assistants', 'audio', 'batches', 'chat', 'completions_legacy', 'conformance',
+  'connector', 'containers', 'embeddings', 'errors', 'evals', 'files', 'fine_tuning', 'images',
+  'models', 'moderations', 'responses', 'streaming', 'tools', 'uploads', 'vector_stores', 'webhooks',
+] as const;
+
+export function openaiCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('openai', OPENAI_CAPABILITIES);
+}