@volter/twin-deepseek 0.1.0

package/src/deepseek-conformance.ts

@@ -0,0 +1,512 @@
+// DeepSeek twin conformance — an offline check with REAL TEETH: delete a handler branch and it goes
+// RED. DeepSeek publishes no OpenAPI document, so the harness does not compare two constants (the
+// false-green ADDING_A_TWIN.md §6 documents). Instead it runs FIVE passes:
+//
+//   1. PROBES — one real request per CLAIMED endpoint, graded on the OUTCOME a live handler
+//      produces: an expected status set PLUS a predicate over the body. A handler that returned
+//      `{}`, or whose branch was deleted (so the router falls through to its not-found), fails.
+//   2. BIJECTION — the probe table and the claimed-endpoint snapshot must match two ways, so a
+//      claim with no probe and a probe with no claim are both RED.
+//   3. ROUTER_SURFACE — a HAND-AUTHORED census of every method/path pair `routeDeepSeek` branches
+//      on, each with a LIVE request that must actually reach that branch.
+//   4. MUST_NOT_SERVE — the paths DeepSeek does not serve (above all the OpenAI-shaped `/v1/...`
+//      prefix, which this vendor genuinely does not have) and the ones this twin does not model
+//      yet must answer the vendor-shaped not-found envelope. This closes the served-but-unclaimed
+//      direction that probe⇄claim alone is blind to.
+//   5. REJECTIONS — the pass that matters most on an OpenAI-COMPATIBLE vendor. What distinguishes
+//      DeepSeek is what it REFUSES, so every documented refusal gets a live request asserting the
+//      exact status DeepSeek's own error table publishes: 422 for a bad parameter (NOT OpenAI's
+//      400), 400 for a body-format problem, 402 for a drained balance. Its mirror image is checked
+//      too — the parameters DeepSeek explicitly DEPRECATES but still accepts must NOT error, or the
+//      twin would be refusing surface the vendor has.
+//
+// Fully offline + deterministic (drives the local handler against a temp root) so it runs without
+// an API key. Honest scope: it checks the protocol envelope, NOT model output (a deterministic stub
+// by design).
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleDeepSeekTwinRequest, type DeepSeekResponseEnvelope } from './deepseek-twin.ts';
+import type { SseEvent } from './deepseek-types.ts';
+
+export type ConformanceViolation = { check: string; detail: string };
+export type DeepSeekConformanceReport = {
+  ok: boolean;
+  checksRun: number;
+  probes: number;
+  violations: ConformanceViolation[];
+};
+
+type Body = Record<string, any>;
+const isObj = (v: unknown): v is Body => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * THE CLAIMED SURFACE. Every entry is a real request plus the OUTCOME a live handler produces.
+ * The expected values are LITERALS here, never imported from the handler — an assertion against
+ * the module's own constant is a tautology that cannot catch the value drifting.
+ */
+type Probe = {
+  /** `"<METHOD> <path>"` — the claim key, and the bijection key. */
+  key: string;
+  method: string;
+  path: string;
+  body?: unknown;
+  /** Which statuses a live handler may answer with. */
+  statuses: number[];
+  /** What a live handler's body must look like. */
+  ok: (body: unknown, status: number) => boolean;
+  /** Seed the root before probing (returns nothing; failures surface as probe failures). */
+  seed?: (h: (m: string, p: string, b?: unknown) => Promise<DeepSeekResponseEnvelope>) => Promise<void>;
+};
+
+const CHAT = { model: 'deepseek-v4-flash', messages: [{ role: 'user', content: 'hi' }] };
+/** The image upload the Files API accepts (a real DeepSeek upload is multipart; the server maps it
+ *  into this JSON contract). */
+const UPLOAD = { purpose: 'user_data', filename: 'shot.png', media_type: 'image/png', content: 'AAA=', bytes: 3 };
+/** The twin's first locally-minted file id (`nextFileId`). */
+const FILE_1 = 'file-api-twin000000000001';
+
+const PROBES: Probe[] = [
+  {
+    key: 'POST /chat/completions',
+    method: 'POST', path: '/chat/completions', body: CHAT, statuses: [200],
+    ok: (b) => isObj(b) && b.object === 'chat.completion' && Array.isArray(b.choices)
+      && (b.choices as Body[])[0]?.message?.role === 'assistant'
+      && typeof (b.choices as Body[])[0]?.message?.content === 'string'
+      // Thinking is ON by default on every V4 model, so a real turn carries reasoning_content.
+      && typeof (b.choices as Body[])[0]?.message?.reasoning_content === 'string'
+      && isObj(b.usage)
+      // DeepSeek's KV-cache split — the field pair OpenAI does not have, and the invariant its own
+      // docs state (hit + miss === prompt_tokens).
+      && typeof b.usage.prompt_cache_hit_tokens === 'number'
+      && typeof b.usage.prompt_cache_miss_tokens === 'number'
+      && b.usage.prompt_cache_hit_tokens + b.usage.prompt_cache_miss_tokens === b.usage.prompt_tokens
+      && typeof b.system_fingerprint === 'string',
+  },
+  {
+    key: 'POST /beta/chat/completions',
+    method: 'POST', path: '/beta/chat/completions', statuses: [200],
+    // The beta base URL is what unlocks assistant-prefix completion: DeepSeek CONTINUES the final
+    // assistant message rather than starting a new turn.
+    body: { model: 'deepseek-v4-flash', messages: [{ role: 'user', content: 'the sky is' }, { role: 'assistant', content: 'The sky is', prefix: true }] },
+    ok: (b) => isObj(b) && b.object === 'chat.completion'
+      && String((b.choices as Body[])[0]?.message?.content ?? '').startsWith('The sky is'),
+  },
+  {
+    key: 'POST /beta/completions',
+    method: 'POST', path: '/beta/completions', body: { model: 'deepseek-v4-pro', prompt: 'def fib(', suffix: '\n    return n' }, statuses: [200],
+    ok: (b) => isObj(b) && b.object === 'text_completion'
+      && typeof (b.choices as Body[])[0]?.text === 'string'
+      && String((b.choices as Body[])[0]!.text).includes('[twin-stub:deepseek-v4-pro]')
+      && (b.choices as Body[])[0]?.finish_reason === 'stop',
+  },
+  {
+    key: 'GET /models',
+    method: 'GET', path: '/models', statuses: [200],
+    // Three keys and no more: DeepSeek's row has no `created` (OpenAI's does).
+    ok: (b) => isObj(b) && b.object === 'list' && Array.isArray(b.data)
+      && (b.data as Body[]).some((m) => m.id === 'deepseek-v4-flash' && m.object === 'model' && m.owned_by === 'deepseek')
+      && (b.data as Body[]).every((m) => Object.keys(m).sort().join(',') === 'id,object,owned_by'),
+  },
+  {
+    key: 'GET /user/balance',
+    method: 'GET', path: '/user/balance', statuses: [200],
+    ok: (b) => isObj(b) && b.is_available === true && Array.isArray(b.balance_infos)
+      // Balances are STRINGS on this vendor, not numbers.
+      && typeof (b.balance_infos as Body[])[0]?.total_balance === 'string'
+      && ['CNY', 'USD'].includes(String((b.balance_infos as Body[])[0]?.currency)),
+  },
+  {
+    key: 'POST /files',
+    method: 'POST', path: '/files', body: UPLOAD, statuses: [200],
+    ok: (b) => isObj(b) && b.object === 'file' && b.purpose === 'user_data' && b.filename === 'shot.png'
+      && String(b.id).startsWith('file-api-twin'),
+  },
+  {
+    key: 'GET /files',
+    method: 'GET', path: '/files', statuses: [200],
+    seed: async (h) => { await h('POST', '/files', { ...UPLOAD, filename: 'seed.webp', media_type: 'image/webp' }); },
+    ok: (b) => isObj(b) && b.object === 'list' && (b.data as Body[]).some((f) => f.filename === 'seed.webp') && b.has_more === false,
+  },
+  {
+    key: 'GET /files/{file_id}',
+    method: 'GET', path: `/files/${FILE_1}`, statuses: [200],
+    seed: async (h) => { await h('POST', '/files', { ...UPLOAD, filename: 'one.jpg', media_type: 'image/jpeg' }); },
+    ok: (b) => isObj(b) && b.id === FILE_1 && b.filename === 'one.jpg' && b.purpose === 'user_data',
+  },
+  {
+    key: 'DELETE /files/{file_id}',
+    method: 'DELETE', path: `/files/${FILE_1}`, statuses: [200],
+    seed: async (h) => { await h('POST', '/files', UPLOAD); },
+    ok: (b) => isObj(b) && b.deleted === true && b.id === FILE_1 && b.object === 'file',
+  },
+  {
+    // A REAL DeepSeek surface this twin does not model. Probed because "unmodeled ops fail like the
+    // vendor" is a testable property, and because the branch that says so is a real router branch.
+    key: 'POST /anthropic/v1/messages',
+    method: 'POST', path: '/anthropic/v1/messages', body: { model: 'claude-3-5-sonnet', messages: [] }, statuses: [404],
+    ok: (b) => isObj(b) && isObj(b.error) && String(b.error.message).includes('Anthropic-compatible'),
+  },
+  {
+    // FIM exists ONLY under /beta. On the standard base URL it must fail, not quietly work.
+    key: 'POST /completions',
+    method: 'POST', path: '/completions', body: { model: 'deepseek-v4-pro', prompt: 'x' }, statuses: [404],
+    ok: (b) => isObj(b) && isObj(b.error) && String(b.error.message).includes('beta base URL'),
+  },
+];
+
+/**
+ * THE ROUTER CENSUS — hand-authored by READING every dispatch branch in `routeDeepSeek`, paired
+ * with a live request AND ITS OWN EXPECTED OUTCOME.
+ *
+ * §9 ROUND ONE, SHOULD-FIX 7: the first version was a character-for-character copy of the probe
+ * keys, compared against a second copy of those same keys — two hand-written constants in the same
+ * file asserting about each other, which is §6's named false-green. Worse, the run-time half graded
+ * only "not the router's own miss", which is exactly tinybird's REPLACEMENT defect: teeth at the
+ * dispatch and nowhere deeper, so a branch could lose its body and stay green.
+ *
+ * Each entry now carries `expect`, a predicate over (status, body) written INDEPENDENTLY of the
+ * probe table. Deleting a branch reddens its census row by name whether or not its probe exists,
+ * and adding a branch nobody claimed is caught by the router-miss check plus the claim bijection.
+ */
+type CensusEntry = {
+  key: string; method: string; path: string; body?: unknown;
+  /** What reaching this branch looks like — NOT merely "did not fall through". */
+  expect: (status: number, b: Body) => boolean;
+};
+const isErr = (b: Body) => isObj(b) && isObj(b.error) && typeof b.error.message === 'string';
+
+const ROUTER_SURFACE: CensusEntry[] = [
+  { key: 'POST /chat/completions', method: 'POST', path: '/chat/completions', body: CHAT,
+    expect: (st, b) => st === 200 && b.object === 'chat.completion' && typeof (b.choices as Body[])[0]?.message?.content === 'string' },
+  // BETA-ONLY expectation, deliberately: `/chat/completions` and `/beta/chat/completions` are the
+  // SAME router branch, so a row whose predicate any chat response satisfies grades nothing the
+  // previous row already did (§9 round two, NIT 3). Prefix continuation is reachable ONLY under
+  // /beta, so this row dies if the beta gate stops being computed.
+  { key: 'POST /beta/chat/completions', method: 'POST', path: '/beta/chat/completions',
+    body: { model: 'deepseek-v4-flash', messages: [{ role: 'user', content: 'the sky' }, { role: 'assistant', content: 'The sky is', prefix: true }] },
+    expect: (st, b) => st === 200 && b.object === 'chat.completion'
+      && String((b.choices as Body[])[0]?.message?.content ?? '').startsWith('The sky is') },
+  { key: 'POST /beta/completions', method: 'POST', path: '/beta/completions', body: { model: 'deepseek-v4-pro', prompt: 'x' },
+    expect: (st, b) => st === 200 && b.object === 'text_completion' && typeof (b.choices as Body[])[0]?.text === 'string' },
+  { key: 'POST /completions', method: 'POST', path: '/completions', body: { model: 'deepseek-v4-pro', prompt: 'x' },
+    // The non-beta FIM branch exists to REFUSE, and it must say why.
+    expect: (st, b) => st >= 400 && st < 500 && isErr(b) && String(b.error.message).includes('beta base URL') },
+  { key: 'GET /models', method: 'GET', path: '/models',
+    expect: (st, b) => st === 200 && b.object === 'list' && (b.data as Body[]).some((m) => m.id === 'deepseek-v4-flash') },
+  { key: 'GET /user/balance', method: 'GET', path: '/user/balance',
+    expect: (st, b) => st === 200 && typeof b.is_available === 'boolean' && Array.isArray(b.balance_infos) },
+  { key: 'POST /files', method: 'POST', path: '/files', body: UPLOAD,
+    expect: (st, b) => st === 200 && b.object === 'file' && String(b.id).startsWith('file-api-') },
+  { key: 'GET /files', method: 'GET', path: '/files',
+    expect: (st, b) => st === 200 && b.object === 'list' && Array.isArray(b.data) && b.has_more === false },
+  { key: 'GET /files/{file_id}', method: 'GET', path: `/files/${FILE_1}`,
+    // No file exists in this cell's fresh root, so reaching the branch means its OWN not-found —
+    // which is a different message from the router's, and that difference is the tooth.
+    expect: (st, b) => st >= 400 && st < 500 && isErr(b) && String(b.error.message).includes('No such File object') },
+  { key: 'DELETE /files/{file_id}', method: 'DELETE', path: `/files/${FILE_1}`,
+    expect: (st, b) => st >= 400 && st < 500 && isErr(b) && String(b.error.message).includes('No such File object') },
+  { key: 'POST /anthropic/v1/messages', method: 'POST', path: '/anthropic/v1/messages', body: {},
+    expect: (st, b) => st >= 400 && st < 500 && isErr(b) && String(b.error.message).includes('Anthropic-compatible') },
+];
+
+/** The literal the router falls through to when NO branch matched. A census entry answering this
+ *  means its branch is gone. Kept as a LITERAL — importing the handler's string would be a
+ *  tautology that could not catch the message drifting. */
+const ROUTER_MISS = 'Unknown request URL';
+
+/**
+ * Surface the twin must NOT serve. The first three entries are the headline OpenAI-divergence:
+ * DeepSeek's base_url has NO version segment, so a twin answering on `/v1/...` would be asserting a
+ * route the vendor does not have. The rest are OpenAI endpoints DeepSeek genuinely lacks.
+ */
+const MUST_NOT_SERVE: Array<{ method: string; path: string; why: string }> = [
+  // NOTE what is deliberately NOT in this list: `/responses` and `/anthropic/*`. Those are REAL
+  // DeepSeek surface this twin has not modeled yet — they belong in the manifest as todos and in
+  // the unmodeled-ops capability, not in a table whose whole claim is "the vendor does not have
+  // this". Putting them here would assert a vendor fact that is false.
+  { method: 'POST', path: '/v1/chat/completions', why: "the OpenAI-shaped `/v1` prefix — DeepSeek's own base_url carries no version segment" },
+  { method: 'GET', path: '/v1/models', why: 'same: there is no /v1 segment on this vendor' },
+  { method: 'GET', path: '/v1/user/balance', why: 'same: there is no /v1 segment on this vendor' },
+  { method: 'POST', path: '/embeddings', why: 'OpenAI has embeddings; DeepSeek does not — @ai-sdk/deepseek throws NoSuchModelError for embeddingModel' },
+  { method: 'POST', path: '/images/generations', why: 'OpenAI has image generation; DeepSeek does not — the SDK throws NoSuchModelError for imageModel' },
+  { method: 'POST', path: '/audio/transcriptions', why: 'OpenAI has audio; DeepSeek publishes no audio endpoints at all' },
+  { method: 'POST', path: '/moderations', why: 'OpenAI has this endpoint; DeepSeek does not' },
+  { method: 'POST', path: '/batches', why: 'OpenAI has a Batch API; DeepSeek does not, and its Files API accepts images only' },
+  { method: 'GET', path: '/models/deepseek-v4-flash', why: 'DeepSeek documents only the LIST models endpoint; there is no per-model retrieve' },
+];
+
+/**
+ * THE REJECTION TABLE — the fidelity surface of an OpenAI-compatible vendor.
+ *
+ * Each row is a live request that must be REFUSED with the exact status DeepSeek's own error table
+ * publishes (api-docs.deepseek.com/quick_start/error_codes: 400 Invalid Format, 422 Invalid
+ * Parameters). The statuses are LITERALS, and the split between them is the point: OpenAI answers
+ * 400 for everything here, so a twin copied from an OpenAI-shaped exemplar would pass a 400-only
+ * check while being wrong on every single row.
+ */
+const REJECTIONS: Array<{ name: string; method: string; path: string; body: unknown; status: number; why: string }> = [
+  // ── parameters DeepSeek's closed table does not declare (OpenAI's do) ──
+  { name: 'n', method: 'POST', path: '/chat/completions', body: { ...CHAT, n: 2 }, status: 422, why: "'n' is not a DeepSeek parameter" },
+  { name: 'seed', method: 'POST', path: '/chat/completions', body: { ...CHAT, seed: 42 }, status: 422, why: "'seed' is not a DeepSeek parameter" },
+  { name: 'logit_bias', method: 'POST', path: '/chat/completions', body: { ...CHAT, logit_bias: { '1': 1 } }, status: 422, why: "'logit_bias' is not a DeepSeek parameter" },
+  { name: 'top_k', method: 'POST', path: '/chat/completions', body: { ...CHAT, top_k: 5 }, status: 422, why: "'top_k' is not a DeepSeek parameter" },
+  { name: 'user', method: 'POST', path: '/chat/completions', body: { ...CHAT, user: 'u1' }, status: 422, why: "DeepSeek's end-user identifier is 'user_id', not OpenAI's 'user'" },
+  { name: 'max_completion_tokens', method: 'POST', path: '/chat/completions', body: { ...CHAT, max_completion_tokens: 10 }, status: 422, why: "DeepSeek declares 'max_tokens' only" },
+  { name: 'service_tier', method: 'POST', path: '/chat/completions', body: { ...CHAT, service_tier: 'flex' }, status: 422, why: 'DeepSeek has no service tiers' },
+  { name: 'parallel_tool_calls', method: 'POST', path: '/chat/completions', body: { ...CHAT, parallel_tool_calls: false }, status: 422, why: 'not in DeepSeek\'s parameter table' },
+  { name: 'functions', method: 'POST', path: '/chat/completions', body: { ...CHAT, functions: [{ name: 'f' }] }, status: 422, why: "OpenAI's deprecated 'functions' has no DeepSeek counterpart" },
+  // ── closed value sets ──
+  { name: 'response_format json_schema', method: 'POST', path: '/chat/completions', body: { ...CHAT, response_format: { type: 'json_schema', json_schema: { name: 'x', schema: {} } } }, status: 422, why: "DeepSeek's response_format accepts 'text' and 'json_object' only" },
+  { name: 'thinking.type', method: 'POST', path: '/chat/completions', body: { ...CHAT, thinking: { type: 'adaptive' } }, status: 422, why: "thinking.type is 'enabled' | 'disabled'" },
+  { name: 'reasoning_effort', method: 'POST', path: '/chat/completions', body: { ...CHAT, reasoning_effort: 'ultra' }, status: 422, why: "reasoning_effort is 'low' | 'high' | 'max'" },
+  { name: 'tool_choice', method: 'POST', path: '/chat/completions', body: { ...CHAT, tool_choice: 'any' }, status: 422, why: "tool_choice is 'none' | 'auto' | 'required' or a named function" },
+  { name: 'retired model', method: 'POST', path: '/chat/completions', body: { ...CHAT, model: 'deepseek-chat' }, status: 422, why: 'deepseek-chat was retired on 2026-07-24' },
+  { name: 'unknown model', method: 'POST', path: '/chat/completions', body: { ...CHAT, model: 'gpt-4o' }, status: 422, why: 'not a DeepSeek model' },
+  // ── documented numeric bounds ──
+  { name: 'top_logprobs range', method: 'POST', path: '/chat/completions', body: { ...CHAT, logprobs: true, top_logprobs: 21 }, status: 422, why: 'top_logprobs is 0..20' },
+  { name: 'top_logprobs without logprobs', method: 'POST', path: '/chat/completions', body: { ...CHAT, top_logprobs: 5 }, status: 422, why: 'top_logprobs requires logprobs: true' },
+  { name: 'temperature range', method: 'POST', path: '/chat/completions', body: { ...CHAT, temperature: 3 }, status: 422, why: 'temperature is 0..2' },
+  { name: 'stop count', method: 'POST', path: '/chat/completions', body: { ...CHAT, stop: Array.from({ length: 17 }, (_, i) => `s${i}`) }, status: 422, why: 'up to 16 stop sequences' },
+  { name: 'user_id charset', method: 'POST', path: '/chat/completions', body: { ...CHAT, user_id: 'a b' }, status: 422, why: 'user_id must match /^[a-zA-Z0-9_-]+$/' },
+  { name: 'user_id length', method: 'POST', path: '/chat/completions', body: { ...CHAT, user_id: 'a'.repeat(513) }, status: 422, why: 'user_id is at most 512 characters' },
+  // ── beta-only features refused on the standard base URL ──
+  { name: 'strict tools off beta', method: 'POST', path: '/chat/completions', body: { ...CHAT, tools: [{ type: 'function', function: { name: 'f', strict: true, parameters: {} } }], messages: [{ role: 'user', content: 'x' }] }, status: 422, why: 'strict tool calls require the /beta base URL' },
+  { name: 'prefix off beta', method: 'POST', path: '/chat/completions', body: { model: 'deepseek-v4-flash', messages: [{ role: 'user', content: 'x' }, { role: 'assistant', content: 'y', prefix: true }] }, status: 422, why: 'prefix completion requires the /beta base URL' },
+  { name: 'prefix not final', method: 'POST', path: '/beta/chat/completions', body: { model: 'deepseek-v4-flash', messages: [{ role: 'assistant', content: 'y', prefix: true }, { role: 'user', content: 'x' }] }, status: 422, why: 'the prefixed message must be the final message' },
+  { name: 'mixed strict tools', method: 'POST', path: '/beta/chat/completions', body: { ...CHAT, tools: [{ type: 'function', function: { name: 'a', strict: true, parameters: {} } }, { type: 'function', function: { name: 'b', parameters: {} } }], messages: [{ role: 'user', content: 'x' }] }, status: 422, why: 'strict mode is all-or-nothing' },
+  // ── the reasoning_content hand-back rule: a documented 400, NOT a 422 ──
+  {
+    name: 'tools without reasoning_content', method: 'POST', path: '/chat/completions', status: 400,
+    body: {
+      model: 'deepseek-v4-flash',
+      messages: [{ role: 'user', content: 'x' }, { role: 'assistant', content: 'y' }, { role: 'user', content: 'z' }],
+      tools: [{ type: 'function', function: { name: 'f', parameters: {} } }],
+    },
+    why: 'with tools set, previous assistant turns must carry back reasoning_content (documented 400)',
+  },
+  // ── FIM's own closed set, and its logprobs TYPE divergence from chat ──
+  { name: 'fim model', method: 'POST', path: '/beta/completions', body: { model: 'deepseek-v4-flash', prompt: 'x' }, status: 422, why: 'FIM accepts deepseek-v4-pro only' },
+  { name: 'fim logprobs is an integer', method: 'POST', path: '/beta/completions', body: { model: 'deepseek-v4-pro', prompt: 'x', logprobs: true }, status: 422, why: "the FIM endpoint's logprobs is an integer, unlike chat's boolean" },
+  { name: 'fim messages', method: 'POST', path: '/beta/completions', body: { model: 'deepseek-v4-pro', messages: [] }, status: 422, why: 'FIM takes prompt/suffix, not messages' },
+  // ── the Files API is IMAGE-ONLY ──
+  { name: 'file purpose', method: 'POST', path: '/files', body: { ...UPLOAD, purpose: 'batch' }, status: 422, why: "purpose must be 'user_data'" },
+  { name: 'file type', method: 'POST', path: '/files', body: { purpose: 'user_data', filename: 'in.jsonl', media_type: 'application/jsonl', content: 'x', bytes: 1 }, status: 422, why: 'DeepSeek file uploads support JPEG, PNG, GIF and WebP only' },
+  { name: 'file expiry range', method: 'POST', path: '/files', body: { ...UPLOAD, 'expires_after[anchor]': 'created_at', 'expires_after[seconds]': 60 }, status: 422, why: 'expires_after[seconds] is 3600..2592000' },
+  { name: 'file list limit', method: 'GET', path: '/files?limit=5000', body: undefined, status: 422, why: 'limit is 1..1000' },
+];
+
+/**
+ * THE MIRROR IMAGE of the rejection table, and just as load-bearing: parameters DeepSeek documents
+ * as DEPRECATED-but-accepted, or as ignored while thinking is enabled, MUST NOT error. "Setting
+ * these parameters will not trigger an error but will also have no effect"
+ * (api-docs.deepseek.com/guides/thinking_mode). A twin that 4xx'd them would be refusing surface the
+ * vendor has — the same infidelity as serving surface it does not, pointing the other way.
+ */
+const MUST_ACCEPT: Array<{ name: string; body: unknown }> = [
+  { name: 'frequency_penalty (deprecated, no effect)', body: { ...CHAT, frequency_penalty: 1.5 } },
+  { name: 'presence_penalty (deprecated, no effect)', body: { ...CHAT, presence_penalty: 1.5 } },
+  { name: 'temperature while thinking is enabled (ignored, not refused)', body: { ...CHAT, temperature: 0.7 } },
+  { name: 'top_p while thinking is enabled (ignored, not refused)', body: { ...CHAT, top_p: 0.9 } },
+  { name: 'thinking.reasoning_effort placement (the API reference\'s form)', body: { ...CHAT, thinking: { type: 'enabled', reasoning_effort: 'max' } } },
+  { name: 'top-level reasoning_effort (the form @ai-sdk/deepseek sends)', body: { ...CHAT, reasoning_effort: 'low' } },
+  { name: 'legacy reasoning_effort medium (documented as mapped to high)', body: { ...CHAT, reasoning_effort: 'medium' } },
+  { name: 'message name on a system turn', body: { model: 'deepseek-v4-flash', messages: [{ role: 'system', content: 's', name: 'planner' }, { role: 'user', content: 'x' }] } },
+];
+
+/** Run the offline conformance checks against a fresh temp root. */
+export async function checkDeepSeekConformance(opts: { root?: string } = {}): Promise<DeepSeekConformanceReport> {
+  const violations: ConformanceViolation[] = [];
+  let checksRun = 0;
+  const fail = (check: string, detail: string) => violations.push({ check, detail });
+  const freshRoot = () => mkdtempSync(join(opts.root ?? tmpdir(), 'deepseek-conf-'));
+
+  // ── 1. PROBES: each in its OWN throwaway root, so a probe's seed can't leak into another. ──
+  for (const probe of PROBES) {
+    checksRun++;
+    // A FRESH root per probe, always. `opts.root` is the PARENT directory, never a shared root:
+    // sharing it would let `nextFileId` ratchet across probes, so the `/files/{id}` probe would read
+    // an id an earlier probe minted and report a false violation.
+    const root = freshRoot();
+    const h = (method: string, path: string, body?: unknown) =>
+      handleDeepSeekTwinRequest({ method, path, ...(body === undefined ? {} : { body: JSON.stringify(body) }), root });
+    try {
+      if (probe.seed) await probe.seed(h);
+      const res = await h(probe.method, probe.path, probe.body);
+      if (!probe.statuses.includes(res.status)) {
+        fail(`probe:${probe.key}`, `status ${res.status} (expected one of ${probe.statuses.join('/')}) body=${JSON.stringify(res.body).slice(0, 200)}`);
+      } else if (!probe.ok(res.body, res.status)) {
+        fail(`probe:${probe.key}`, `body did not satisfy the live-handler predicate: ${JSON.stringify(res.body).slice(0, 300)}`);
+      }
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }
+
+  // ── 2. BIJECTION: probe table ⇄ router census, both directions. ──
+  checksRun++;
+  // The bijection is between the CLAIMED endpoints (probes) and the branches the router actually
+  // dispatches on (the census) — two independently authored tables, not one table compared with a
+  // copy of itself. A census row with no probe is unclaimed surface; a probe with no census row is
+  // a claim about a branch nobody enumerated.
+  const probeKeys = new Set(PROBES.map((p) => p.key));
+  const censusKeys = new Set(ROUTER_SURFACE.map((e) => e.key));
+  for (const key of censusKeys) if (!probeKeys.has(key)) fail('bijection', `router branch "${key}" has no probe`);
+  for (const key of probeKeys) if (!censusKeys.has(key)) fail('bijection', `probe "${key}" is not in the hand-authored router census`);
+  if (PROBES.length !== probeKeys.size) fail('bijection', 'duplicate probe key');
+  if (ROUTER_SURFACE.length !== censusKeys.size) fail('bijection', 'duplicate router census key');
+
+  // ── 3. THE CENSUS HAS TEETH: every declared branch must actually be REACHED. A branch whose
+  //       handler was deleted falls through to the router's own not-found, which is what this
+  //       catches — independently of that endpoint's own probe.
+  for (const entry of ROUTER_SURFACE) {
+    checksRun++;
+    const root = freshRoot();
+    try {
+      const res = await handleDeepSeekTwinRequest({ method: entry.method, path: entry.path, ...(entry.body === undefined ? {} : { body: JSON.stringify(entry.body) }), root });
+      const message = String(((res.body as Body)?.error as Body)?.message ?? '');
+      if (message.includes(ROUTER_MISS)) {
+        fail('router_surface', `${entry.key} fell through to the router's not-found — the branch is gone (answered ${res.status}: ${message})`);
+      } else if (!entry.expect(res.status, res.body as Body)) {
+        // The tooth that reaches PAST the dispatch: a branch whose body was emptied still avoids
+        // the router's miss, so "not the miss" alone is not proof it works.
+        fail('router_surface', `${entry.key} reached its branch but the outcome is wrong: ${res.status} ${JSON.stringify(res.body).slice(0, 200)}`);
+      }
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }
+
+  {
+    // §9 ROUND ONE, SHOULD-FIX 9: `opts.root` used to mean two incompatible things — a PARENT
+    // directory for the per-probe temp roots above, and the state root itself here (which was then
+    // never cleaned up when supplied). It now has exactly ONE meaning, the parent directory, and
+    // every state root is a temp dir this function creates and removes.
+    const root = freshRoot();
+    try {
+      // ── 4. The twin must not serve surface the vendor does not have. ──
+      for (const entry of MUST_NOT_SERVE) {
+        checksRun++;
+        const res = await handleDeepSeekTwinRequest({ method: entry.method, path: entry.path, body: JSON.stringify(CHAT), root });
+        if (res.status !== 404) fail('must_not_serve', `${entry.method} ${entry.path} answered ${res.status}, not 404 — ${entry.why}`);
+        else if (!isObj(res.body) || !isObj((res.body as Body).error)) fail('must_not_serve', `${entry.method} ${entry.path} 404 body is not the vendor error envelope`);
+      }
+
+      // ── 5. THE REJECTIONS — the fidelity surface. Status is asserted EXACTLY, because the whole
+      //      point is DeepSeek's 422 where OpenAI answers 400.
+      for (const r of REJECTIONS) {
+        checksRun++;
+        const res = await handleDeepSeekTwinRequest({ method: r.method, path: r.path, ...(r.body === undefined ? {} : { body: JSON.stringify(r.body) }), root });
+        if (res.status !== r.status) {
+          fail('rejections', `${r.name}: answered ${res.status}, expected ${r.status} — ${r.why} (body=${JSON.stringify(res.body).slice(0, 160)})`);
+        } else if (!isObj(res.body) || typeof ((res.body as Body).error as Body)?.message !== 'string') {
+          fail('rejections', `${r.name}: refusal body is not DeepSeek's { error: { message } } envelope`);
+        }
+      }
+
+      // ── 5b. …and its mirror image: what DeepSeek deprecates but still ACCEPTS must not error. ──
+      for (const a of MUST_ACCEPT) {
+        checksRun++;
+        const res = await handleDeepSeekTwinRequest({ method: 'POST', path: '/chat/completions', body: JSON.stringify(a.body), root });
+        if (res.status !== 200) fail('must_accept', `${a.name}: answered ${res.status}, but DeepSeek accepts this (deprecated/ignored, not an error)`);
+      }
+
+      // ── 6. Body-format 400 is DISTINCT from parameter 422 on this vendor. ──
+      checksRun++;
+      const malformed = await handleDeepSeekTwinRequest({ method: 'POST', path: '/chat/completions', body: '{not json', root });
+      if (malformed.status !== 400) fail('error.status_split', `a malformed body answered ${malformed.status}, not DeepSeek's 400 "Invalid request body format"`);
+      checksRun++;
+      const missingParam = await handleDeepSeekTwinRequest({ method: 'POST', path: '/chat/completions', body: JSON.stringify({ model: 'deepseek-v4-flash' }), root });
+      if (missingParam.status !== 422) fail('error.status_split', `a MISSING required parameter answered ${missingParam.status}, not 422 — a missing parameter is the same class as a bad one and must not be reported two ways`);
+      checksRun++;
+      const badParam = await handleDeepSeekTwinRequest({ method: 'POST', path: '/chat/completions', body: JSON.stringify({ ...CHAT, model: 'nope' }), root });
+      if (badParam.status !== 422) fail('error.status_split', `a bad parameter answered ${badParam.status}, not DeepSeek's 422 "Invalid Parameters"`);
+
+      // ── 7. The error envelope carries only keys `@ai-sdk/deepseek`'s decoder declares. The key
+      //      list is a LITERAL here — asserting against the handler's own constant would be a
+      //      tautology that could not catch it drifting.
+      checksRun++;
+      const ERROR_KEYS = new Set(['message', 'type', 'param', 'code']);
+      const eb = badParam.body as Body;
+      if (!isObj(eb?.error)) {
+        fail('error.envelope', 'a refusal did not carry an error envelope');
+      } else {
+        const undeclared = Object.keys(eb.error).filter((k) => !ERROR_KEYS.has(k));
+        if (undeclared.length) fail('error.envelope', `error object carries key(s) deepSeekErrorSchema does not declare: ${undeclared.join(', ')}`);
+        if (typeof eb.error.message !== 'string' || !eb.error.message) fail('error.envelope', 'error.message is not a non-empty string');
+      }
+
+      // ── 8. 402 Insufficient Balance — DeepSeek's own status, with no OpenAI counterpart, and
+      //      STATE-DRIVEN: a drained account refuses completions. Asserted here rather than only in
+      //      the manifest because it is the one refusal that depends on the projection.
+      checksRun++;
+      const drained = freshRoot();
+      try {
+        const { applyTwinWrite } = await import('@volter/world-core');
+        await applyTwinWrite('deepseek', {
+          operation: 'balance.update', subjectType: 'balance', subjectId: 'account',
+          fields: { is_available: false, balance_infos: [{ currency: 'CNY', total_balance: '0.00', granted_balance: '0.00', topped_up_balance: '0.00' }] },
+          occurredAt: '2026-08-31T00:00:00.000Z', actor: { kind: 'agent' },
+        }, drained);
+        const res = await handleDeepSeekTwinRequest({ method: 'POST', path: '/chat/completions', body: JSON.stringify(CHAT), root: drained });
+        if (res.status !== 402) fail('balance.402', `a drained account answered ${res.status}, not DeepSeek's 402 "You have run out of balance"`);
+        else if (!String(((res.body as Body).error as Body)?.message ?? '').includes('run out of balance')) fail('balance.402', '402 message is not the documented cause');
+      } finally {
+        rmSync(drained, { recursive: true, force: true });
+      }
+
+      // ── 9. The streaming chunk sequence, including DeepSeek's OPT-IN usage tail chunk. ──
+      checksRun++;
+      const events: SseEvent[] = [];
+      await handleDeepSeekTwinRequest({
+        method: 'POST', path: '/chat/completions', root,
+        body: JSON.stringify({ ...CHAT, stream: true, stream_options: { include_usage: true } }),
+        sseSink: (e) => events.push(e),
+      });
+      const hasRole = events.some((e) => !e.done && ((e.data!.choices as Body[])?.[0]?.delta as Body)?.role === 'assistant');
+      const hasReasoningDelta = events.some((e) => !e.done && typeof ((e.data!.choices as Body[])?.[0]?.delta as Body)?.reasoning_content === 'string');
+      const done = events.length > 0 && events[events.length - 1]!.done === true;
+      const firstObj = events[0]?.data?.object;
+      const tail = events[events.length - 2]?.data as Body | undefined;
+      if (!hasRole) fail('chat.stream', 'no role delta chunk');
+      if (!hasReasoningDelta) fail('chat.stream', 'no reasoning_content delta — a V4 turn thinks by default');
+      if (!done) fail('chat.stream', 'stream did not end with [DONE]');
+      if (firstObj !== 'chat.completion.chunk') fail('chat.stream', `first chunk object is ${String(firstObj)}`);
+      if (!tail || !Array.isArray(tail.choices) || tail.choices.length !== 0 || !isObj(tail.usage)) {
+        fail('chat.stream', "final chunk is not DeepSeek's empty-choices usage tail");
+      }
+      // …and the tail is OPT-IN: without stream_options.include_usage there must be no usage chunk.
+      checksRun++;
+      const noUsage: SseEvent[] = [];
+      await handleDeepSeekTwinRequest({
+        method: 'POST', path: '/chat/completions', root,
+        body: JSON.stringify({ ...CHAT, stream: true }), sseSink: (e) => noUsage.push(e),
+      });
+      if (noUsage.some((e) => !e.done && isObj((e.data as Body)?.usage))) {
+        fail('chat.stream', 'a usage chunk was emitted without stream_options.include_usage');
+      }
+
+      // ── 10. tool_calls envelope when tools are provided. ──
+      checksRun++;
+      const tool = await handleDeepSeekTwinRequest({
+        method: 'POST', path: '/chat/completions', root,
+        body: JSON.stringify({
+          model: 'deepseek-v4-flash',
+          messages: [{ role: 'user', content: 'weather?' }],
+          tools: [{ type: 'function', function: { name: 'get_weather', parameters: { type: 'object', properties: { city: { type: 'string' } } } } }],
+        }),
+      });
+      const choice = ((tool.body as Body).choices as Body[])?.[0];
+      if (choice?.finish_reason !== 'tool_calls') fail('chat.tool_calls', `finish_reason is ${String(choice?.finish_reason)}, not tool_calls`);
+      const calls = choice?.message?.tool_calls as Body[];
+      if (!Array.isArray(calls) || calls[0]?.type !== 'function' || calls[0]?.function?.name !== 'get_weather') fail('chat.tool_calls', 'no get_weather function tool_call');
+      // DeepSeek's assistant message has NO `refusal` field (OpenAI's does) — serving one would be
+      // the inverse false-green.
+      if (choice && 'refusal' in (choice.message as Body)) fail('chat.message_shape', "assistant message carries a `refusal` field deepseekChatResponseSchema does not define");
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }
+
+  return { ok: violations.length === 0, checksRun, probes: PROBES.length, violations };
+}