@volter/twin-deepseek 0.1.0

package/src/deepseek-capabilities.ts

@@ -0,0 +1,1443 @@
+// DeepSeek capability manifest — the EXPECTED REAL-PRODUCT SURFACE (the target), authored top-down
+// from what the DeepSeek Platform API actually does — NOT from what this twin has built. The
+// denominator was enumerated from TWO first-party sources, both read on 2026-08-31:
+//   • api-docs.deepseek.com, walked as a docs NAV: quick_start/{error_codes,rate_limit,pricing},
+//     api/{create-chat-completion,create-completion,list-models,get-user-balance}, and
+//     guides/{kv_cache,thinking_mode,files_api,anthropic_api,chat_prefix_completion};
+//   • `@ai-sdk/deepseek@3.0.37` — the only first-party npm client of this surface — read as SOURCE:
+//     the zod schemas it encodes/decodes with (deepseek-chat-api-types.ts, files/deepseek-files-api.ts),
+//     the request it builds (deepseek-chat-language-model.ts), the refusals it raises locally
+//     (deepseek-prepare-tools.ts, convert-to-deepseek-chat-messages.ts), and the provider doc page
+//     shipped inside its tarball (docs/30-deepseek.mdx).
+// DeepSeek publishes no OpenAPI document, so where those two conflict the SDK's generated schema
+// wins over a rendered docs example (ADDING_A_TWIN.md §6, the precedence order), and where only
+// prose exists the manifest says so rather than asserting a closed set.
+//
+// ═══ THE DENOMINATOR IS DELIBERATELY WEIGHTED TOWARD REFUSALS ═══
+// DeepSeek is OPENAI-COMPATIBLE. Its response shapes are the easy half; what makes a DeepSeek twin
+// a DeepSeek twin rather than a relabelled OpenAI twin is what it REFUSES — 422 where OpenAI 400s,
+// 402 for a drained balance, no `/v1` segment, no `json_schema`/`n`/`seed`/`logit_bias`/`user`,
+// beta-only prefix completion and strict tools, and a documented 400 when `tools` is sent without
+// prior-turn `reasoning_content`. Those are first-class capabilities here, each with a failable
+// negative verify, because ADDING_A_TWIN.md §0 records that inherited PERMISSIVENESS is how the
+// nearest sibling pack shipped two false-greens.
+//
+// There are NO carve-outs: every entry here is done or todo. The twin returns DETERMINISTIC labeled
+// stubs where the vendor runs a model — those stubs ARE its answer — while the protocol envelope is
+// faithful, and it does not simulate properties of the vendor's own serving fleet (concurrency
+// ceilings). `deepseek.usage.real_tokenizer` and `deepseek.cache.expiry` are honest todos: a BPE
+// tokenizer is an offline data file and the kernel's world clock is deterministic, so both are work
+// not yet done rather than anything unreachable.
+//
+// TIERING (§6 rule 3): `core` = "first-week-of-every-integration". The overwhelming majority of
+// week-one DeepSeek integrations are chat completions and nothing else, so `core` is the
+// chat/streaming/tools/reasoning/errors/auth spine plus the conformance and connector-pull
+// backbone. The Files API (images only, and only usable by one vision model), the beta FIM
+// endpoint, the beta prefix/strict features and the Anthropic-compatible surface are specialist and
+// are tiered `common` or `niche`.
+//
+// (DeepSeek is an API-first vendor — platform.deepseek.com is a keys/billing/usage console, not
+// where the work happens — so this pack ships NO mirror and has NO UI capabilities.)
+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/world-tooling';
+import { applyTwinWrite, pendingActions, projectResources } from '@volter/world-core';
+import { handleDeepSeekTwinRequest, type DeepSeekResponseEnvelope } from './deepseek-twin.ts';
+import {
+  fullSyncDeepSeek,
+  deepseekRequestForAction,
+  externalIdFor,
+  liveDeepSeekExecute,
+  pullDeepSeekState,
+  pushPendingDeepSeekActions,
+  syncDeepSeekFromReal,
+  unpushableReason,
+  type DeepSeekExecute,
+} from './deepseek-connector.ts';
+import { createDeepSeekScenarioEngine } from './deepseek-scenario.ts';
+import type { SseEvent } from './deepseek-types.ts';
+
+// ── 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 DeepSeek requests against an isolated root; return all responses. */
+async function withRoot(steps: (h: (s: Step) => Promise<DeepSeekResponseEnvelope>, root: string) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'deepseek-cap-'));
+  const h = (s: Step) => handleDeepSeekTwinRequest({ method: s.m, path: s.p, body: s.b === undefined ? undefined : JSON.stringify(s.b), root, occurredAt: OCCURRED_AT });
+  try {
+    // `root` is handed to the steps too, so a verify can inspect the LOG (projectResources /
+    // pendingActions) and not merely the responses — the difference between proving "the reply did
+    // not change" and proving "nothing was written".
+    return await verifyBoundary('deepseek.withRoot', () => steps(h, root));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+/** Like withRoot, but the request helper passes request HEADERS through (for auth and the
+ *  deterministic 429 trigger, which the trusted no-headers helper never fires). */
+type StepH = Step & { headers?: Record<string, string> };
+async function withRootH(steps: (h: (s: StepH) => Promise<DeepSeekResponseEnvelope>) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'deepseek-cap-'));
+  const h = (s: StepH) => handleDeepSeekTwinRequest({ method: s.m, path: s.p, body: s.b === undefined ? undefined : JSON.stringify(s.b), root, occurredAt: OCCURRED_AT, ...(s.headers ? { headers: s.headers } : {}) });
+  try {
+    return await verifyBoundary('deepseek.withRootH', () => steps(h));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+/** Collect the streaming SSE events for a chat request against an isolated root. */
+function withStream(body: unknown, fn: (events: SseEvent[], final: DeepSeekResponseEnvelope) => boolean, path = CHAT_PATH): Promise<boolean> {
+  return new Promise<boolean>((resolve, reject) => {
+    const root = mkdtempSync(join(tmpdir(), 'deepseek-cap-'));
+    const events: SseEvent[] = [];
+    handleDeepSeekTwinRequest({ method: 'POST', path, body: JSON.stringify(body), root, occurredAt: OCCURRED_AT, sseSink: (e) => events.push(e) })
+      .then((final) => resolve(fn(events, final)))
+      .catch((err) => { if (isInfrastructureError(err)) reject(harnessError('deepseek.withStream', err)); else resolve(false); })
+      .finally(() => rmSync(root, { recursive: true, force: true }));
+  });
+}
+
+/** A connector verify against an isolated root, with the injected fake executor the verify builds. */
+async function withConnectorRoot(id: string, fn: (root: string) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'deepseek-cap-'));
+  try {
+    return await fn(root);
+  } catch (err) {
+    if (isInfrastructureError(err)) throw harnessError(id, err);
+    return false;
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+const ok = (r: DeepSeekResponseEnvelope) => r.status >= 200 && r.status < 300;
+/** Refused as a CLIENT error with the vendor's envelope. Used wherever the twin's exact status is
+ *  its own unverified choice — DeepSeek's published error table has no 404 at all — so asserting a
+ *  specific code would claim a vendor fact this pack states it does not have (§9 round one). */
+const refused = (r: DeepSeekResponseEnvelope) => r.status >= 400 && r.status < 500 && typeof (r.body as Body)?.error?.message === 'string';
+const body = (r: DeepSeekResponseEnvelope) => r.body as Body;
+const msg = (r: DeepSeekResponseEnvelope) => String((r.body as Body)?.error?.message ?? '');
+const choice0 = (r: DeepSeekResponseEnvelope) => ((r.body as Body)?.choices as Body[])?.[0];
+const text0 = (r: DeepSeekResponseEnvelope) => String(choice0(r)?.message?.content ?? '');
+
+// ── shorthands ──
+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' });
+
+// DeepSeek's real paths. NOTE the absence of `/v1` — that is not an omission, it is the vendor's
+// own base_url shape and `deepseek.chat.no_v1_prefix` asserts a twin serving `/v1` would be wrong.
+const CHAT_PATH = '/chat/completions';
+const BETA_CHAT = '/beta/chat/completions';
+const FIM_PATH = '/beta/completions';
+const FILES = '/files';
+const MODELS = '/models';
+const BALANCE = '/user/balance';
+
+/** A pinned timestamp so ids, `created` and cache-ledger writes are deterministic. Where a verify
+ *  REPEATS an identical transition it pins a DIFFERENT value deliberately (the kernel dedupes by
+ *  content + millisecond — ADDING_A_TWIN.md §6). */
+const OCCURRED_AT = '2026-08-31T12:00:00.000Z';
+
+const MODEL = 'deepseek-v4-flash';
+const PRO = 'deepseek-v4-pro';
+const CHAT = (extra: Record<string, unknown> = {}) => ({ model: MODEL, messages: [{ role: 'user', content: 'hello twin' }], ...extra });
+const WEATHER_TOOL = { type: 'function', function: { name: 'get_weather', parameters: { type: 'object', properties: { city: { type: 'string' }, days: { type: 'integer' } } } } };
+const TIME_TOOL = { type: 'function', function: { name: 'get_time', parameters: { type: 'object', properties: { tz: { type: 'string' } } } } };
+/** A valid PNG upload as the server's multipart adapter hands it to the handler. */
+const UPLOAD = (extra: Record<string, unknown> = {}) => ({ purpose: 'user_data', filename: 'shot.png', media_type: 'image/png', content: 'AAA=', bytes: 3, ...extra });
+const FILE_1 = 'file-api-twin000000000001';
+const FILE_2 = 'file-api-twin000000000002';
+
+/** A fake live executor over an in-memory account. Records every (method, path) so a connector
+ *  verify can assert WHICH calls went out, not merely that something did. */
+function fakeExecute(account: {
+  models?: Body[]; files?: Body[]; balance?: Body; fail?: string;
+}, calls: Array<{ method: string; path: string; body?: unknown }> = []): DeepSeekExecute {
+  return async (method, path, reqBody) => {
+    calls.push({ method, path, ...(reqBody === undefined ? {} : { body: reqBody }) });
+    if (account.fail === path) return { error: { message: 'Authentication fails due to the wrong API key' } };
+    if (path === '/models') return { object: 'list', data: account.models ?? [] };
+    if (path === '/files') return { object: 'list', data: account.files ?? [] };
+    if (path === '/user/balance') return (account.balance ?? { is_available: true, balance_infos: [] }) as Body;
+    if (method === 'DELETE' && path.startsWith('/files/')) return { id: path.slice('/files/'.length), object: 'file', deleted: true };
+    return {};
+  };
+}
+
+export const DEEPSEEK_CAPABILITIES: CapabilitySpec[] = [
+  // ══ chat completions ═════════════════════════════════════════════════════════════════════
+  done('deepseek.chat.completion', 'chat', 'POST /chat/completions returns a faithful chat.completion envelope', 'api', 'core', () => withRoot(async (h) => {
+    const r = await h({ m: 'POST', p: CHAT_PATH, b: CHAT() });
+    if (!ok(r)) return false;
+    const b = body(r);
+    return b.object === 'chat.completion' && b.model === MODEL && typeof b.id === 'string' && b.id.startsWith('chatcmpl-')
+      && typeof b.system_fingerprint === 'string' && b.system_fingerprint.startsWith('fp_')
+      && Array.isArray(b.choices) && b.choices.length === 1
+      && choice0(r).index === 0 && choice0(r).message.role === 'assistant'
+      && text0(r).includes('[twin-stub:deepseek-v4-flash]') && text0(r).includes('hello twin')
+      && choice0(r).finish_reason === 'stop'
+      // …and DeepSeek's assistant message has NO `refusal` (OpenAI's does). Serving one would be
+      // the inverse false-green.
+      && !('refusal' in choice0(r).message);
+  })),
+
+  done('deepseek.chat.system_and_multi_turn', 'chat', 'System messages and multi-turn history are accepted and echoed from the last user turn', 'api', 'core', () => withRoot(async (h) => {
+    const r = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [
+      { role: 'system', content: 'be terse' },
+      { role: 'user', content: 'first question' },
+      { role: 'assistant', content: 'first answer', reasoning_content: '' },
+      { role: 'user', content: 'second question' },
+    ] } });
+    if (!ok(r)) return false;
+    // The echo proves the twin read the LAST user turn, not the first — a handler returning a
+    // fixed string would fail this.
+    if (!text0(r).includes('second question') || text0(r).includes('first question')) return false;
+    // Negative: an empty message list is refused with DeepSeek's parameter status.
+    const empty = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [] } });
+    // Negative: an unknown role is refused too.
+    const badRole = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [{ role: 'developer', content: 'x' }] } });
+    return empty.status === 422 && badRole.status === 422;
+  })),
+
+  done('deepseek.chat.max_tokens_truncation', 'chat', "max_tokens truncates and reports finish_reason 'length'", 'api', 'core', () => withRoot(async (h) => {
+    const full = await h({ m: 'POST', p: CHAT_PATH, b: CHAT() });
+    const cut = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ max_tokens: 4 }) });
+    if (!ok(full) || !ok(cut)) return false;
+    if (choice0(cut).finish_reason !== 'length' || choice0(full).finish_reason !== 'stop') return false;
+    if (text0(cut).length >= text0(full).length) return false;
+    // Negative: DeepSeek's documented bound is an integer >= 1.
+    const bad = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ max_tokens: 0 }) });
+    return bad.status === 422;
+  })),
+
+  done('deepseek.chat.stop_sequences', 'chat', 'stop truncates at the earliest match; more than 16 sequences is refused', 'api', 'common', () => withRoot(async (h) => {
+    const r = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ stop: ['DeepSeek twin', 'deterministic'] }) });
+    if (!ok(r)) return false;
+    // 'deterministic' occurs EARLIER in the stub text than 'DeepSeek twin', so truncation must
+    // happen there — an implementation that took `stop[0]` would keep 'deterministic' and fail here.
+    if (!text0(r).includes('This is a ') || text0(r).includes('deterministic') || text0(r).includes('DeepSeek twin')) return false;
+    const many = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ stop: Array.from({ length: 17 }, (_, i) => `s${i}`) }) });
+    const sixteen = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ stop: Array.from({ length: 16 }, (_, i) => `s${i}`) }) });
+    return many.status === 422 && ok(sixteen);
+  })),
+
+  done('deepseek.chat.rejects_openai_only_params', 'chat', "The OpenAI parameters DeepSeek's closed table does not declare (n, seed, logit_bias, top_k, user, max_completion_tokens, service_tier, parallel_tool_calls, functions) are refused BY NAME with 422", 'api', 'core', () => withRoot(async (h) => {
+    // THE flagship OpenAI-divergence check. A twin copied from an OpenAI-shaped exemplar serves
+    // every one of these happily, which is the inherited-permissiveness false-green
+    // ADDING_A_TWIN.md §0 names. Each must be 422 — DeepSeek's "Invalid Parameters" — not 400.
+    for (const [key, value] of [
+      ['n', 2], ['seed', 42], ['logit_bias', { '1': 1 }], ['top_k', 5], ['user', 'u1'],
+      ['max_completion_tokens', 32], ['service_tier', 'flex'], ['parallel_tool_calls', false],
+      ['functions', [{ name: 'f' }]], ['store', true], ['metadata', { a: 'b' }],
+    ] as Array<[string, unknown]>) {
+      const r = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ [key]: value }) });
+      if (r.status !== 422) return false;
+      // The refusal must NAME the offending key, so a caller can act on it.
+      if (!msg(r).includes(`'${key}'`)) return false;
+    }
+    return true;
+  })),
+
+  done('deepseek.chat.no_v1_prefix', 'chat', "DeepSeek's base_url carries no version segment: /v1/... is not served", 'api', 'core', () => withRoot(async (h) => {
+    // api-docs.deepseek.com's own quick start uses base_url = https://api.deepseek.com with the
+    // endpoint at /chat/completions. A twin answering on the OpenAI-shaped /v1 prefix would be
+    // asserting a route the vendor does not have.
+    const served = await h({ m: 'POST', p: CHAT_PATH, b: CHAT() });
+    const v1chat = await h({ m: 'POST', p: '/v1/chat/completions', b: CHAT() });
+    const v1models = await h({ m: 'GET', p: '/v1/models' });
+    // The claim is that the route is REFUSED, not that the code is exactly 404: DeepSeek's
+    // published error table is {400,401,402,422,429,500,503} and contains no 404 at all, so the
+    // twin's choice of status for an unrouted path is unverified against any first-party source
+    // (filed as `deepseek.errors.unknown_route_envelope`). Asserting 404 exactly would be claiming
+    // a vendor fact this pack explicitly says it does not have (§9 round one, NIT 11).
+    return ok(served) && refused(v1chat) && refused(v1models)
+      && msg(v1chat).includes('Unknown request URL');
+  })),
+
+  done('deepseek.chat.deprecated_params_accepted', 'chat', 'frequency_penalty / presence_penalty are DEPRECATED but accepted with no effect — never an error', 'api', 'common', () => withRoot(async (h) => {
+    // The mirror image of the rejection surface, and just as load-bearing: DeepSeek documents these
+    // as having "no effect", not as errors. A twin that 4xx'd them would be refusing surface the
+    // vendor has. "No effect" is asserted, not assumed: the content must be byte-identical.
+    const plain = await h({ m: 'POST', p: CHAT_PATH, b: CHAT() });
+    const penalised = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ frequency_penalty: 1.5, presence_penalty: -1.2 }) });
+    if (!ok(plain) || !ok(penalised)) return false;
+    // MUTATION-GATE FINDING: "the two answers are equal" is satisfied by a dead twin answering
+    // {} twice. The equality only means something once each side is proven to be a REAL completion,
+    // so the content is asserted absolutely before it is compared.
+    if (!text0(penalised).includes('[twin-stub:deepseek-v4-flash]') || !text0(penalised).includes('hello twin')) return false;
+    if (body(penalised).object !== 'chat.completion' || choice0(penalised).finish_reason !== 'stop') return false;
+    return text0(plain) === text0(penalised);
+  })),
+
+  done('deepseek.chat.temperature_ignored_while_thinking', 'chat', 'temperature / top_p are ignored (not refused) while thinking is enabled, and bounded when checked', 'api', 'common', () => withRoot(async (h) => {
+    // "setting these parameters will not trigger an error but will also have no effect"
+    // (api-docs.deepseek.com/guides/thinking_mode). Thinking is on by default for every V4 model.
+    const plain = await h({ m: 'POST', p: CHAT_PATH, b: CHAT() });
+    const hot = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ temperature: 1.9, top_p: 0.1 }) });
+    if (!ok(plain) || !ok(hot)) return false;
+    // Same shape as the deprecated-params cell: prove each side is a real completion before the
+    // equality is allowed to mean anything (a dead twin answers {} twice, and {} === {}).
+    if (!text0(hot).includes('[twin-stub:deepseek-v4-flash]') || body(hot).object !== 'chat.completion') return false;
+    if (text0(plain) !== text0(hot)) return false;
+    // …but the documented RANGES are still enforced: temperature 0–2, top_p in (0, 1].
+    const tooHot = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ temperature: 2.5 }) });
+    const badP = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ top_p: 1.5 }) });
+    return tooHot.status === 422 && badP.status === 422;
+  })),
+
+  done('deepseek.chat.user_id', 'chat', "user_id (not OpenAI's `user`) is accepted, charset-checked and length-capped at 512", 'api', 'common', () => withRoot(async (h) => {
+    const good = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ user_id: 'tenant_123-user' }) });
+    const bad = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ user_id: 'tenant 123' }) });
+    const long = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ user_id: 'a'.repeat(513) }) });
+    const atCap = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ user_id: 'a'.repeat(512) }) });
+    return ok(good) && bad.status === 422 && long.status === 422 && ok(atCap);
+  })),
+
+  done('deepseek.chat.message_name', 'chat', 'Participant `name` is accepted on system/user/assistant turns and counted into prompt tokens', 'api', 'niche', () => withRoot(async (h) => {
+    const named = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [{ role: 'user', content: 'hi', name: 'customer_alpha' }] } });
+    const plain = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [{ role: 'user', content: 'hi' }] } });
+    if (!ok(named) || !ok(plain)) return false;
+    // A name is real payload, so it must move the prompt-token count — a handler that dropped the
+    // field entirely would report the same number.
+    if (body(named).usage.prompt_tokens <= body(plain).usage.prompt_tokens) return false;
+    // …and a NON-STRING name is a 422, not a 200. §9 round two, SHOULD-FIX 2: it used to reach
+    // `estimateTokens`, produce NaN and serialise as `null`, so the twin answered 200 with
+    // `prompt_tokens: null` — breaking the cache invariant its own capability asserts and handing
+    // the SDK a body its usage schema cannot decode. The revert matrix showed this cell was HOLLOW
+    // without the assertion.
+    const badName = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [{ role: 'user', content: 'hi', name: 12345 }] } });
+    if (badName.status !== 422) return false;
+    const badReasoning = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [{ role: 'assistant', content: 'x', reasoning_content: 7 }] } });
+    // …and a non-array tool_calls is a 422 too, not the retryable 500 a TypeError used to produce.
+    const badCalls = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [{ role: 'assistant', content: 'x', tool_calls: 5 }] } });
+    return badReasoning.status === 422 && badCalls.status === 422;
+  })),
+
+  done('deepseek.chat.logprobs_envelope', 'chat', "logprobs returns DeepSeek's TWO-channel block (content + reasoning_content); top_logprobs is bounded and requires logprobs", 'api', 'niche', () => withRoot(async (h) => {
+    const off = await h({ m: 'POST', p: CHAT_PATH, b: CHAT() });
+    if (!ok(off) || choice0(off).logprobs !== null) return false;
+    const on = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ logprobs: true, top_logprobs: 3 }) });
+    if (!ok(on)) return false;
+    const lp = choice0(on).logprobs as Body;
+    if (!lp || !Array.isArray(lp.content) || lp.content.length === 0) return false;
+    if (typeof lp.content[0].token !== 'string' || typeof lp.content[0].logprob !== 'number') return false;
+    if (lp.content[0].top_logprobs.length !== 3) return false;
+    // The reasoning channel is the DeepSeek-specific half — OpenAI's logprobs has no such key.
+    if (!Array.isArray(lp.reasoning_content) || lp.reasoning_content.length === 0) return false;
+    const tooMany = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ logprobs: true, top_logprobs: 21 }) });
+    const orphan = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ top_logprobs: 2 }) });
+    return tooMany.status === 422 && orphan.status === 422;
+  })),
+
+  todo('deepseek.chat.content_filter_finish', 'chat', "finish_reason 'content_filter' when DeepSeek's safety layer stops a generation", 'api', 'common'),
+  todo('deepseek.chat.insufficient_system_resource_finish', 'chat', "finish_reason 'insufficient_system_resource' — DeepSeek's own value, mapped by the SDK to the unified `error` reason", 'api', 'niche'),
+  todo('deepseek.chat.name_on_tool_message', 'chat', "How DeepSeek answers a `name` on a role:tool turn — it supports names on system/user/assistant only, and @ai-sdk/deepseek strips it client-side with a warning, so the server's own behaviour is unobserved", 'api', 'niche'),
+  // CORE, not common: every integration that grows a conversation hits the context ceiling in its
+  // first week, and the vendor's refusal is what a client must handle (§9 round one, NIT 16 — a
+  // manifest with ZERO core todos is a tiering smell, not an achievement).
+  todo('deepseek.chat.context_length_exceeded', 'chat', 'A prompt beyond the model context window is refused with the vendor-documented error', 'api', 'core'),
+
+  // ══ FIM completions (beta) ═══════════════════════════════════════════════════════════════
+  done('deepseek.completions.fim', 'completions', 'POST /beta/completions returns a faithful text_completion envelope', 'api', 'common', () => withRoot(async (h) => {
+    const r = await h({ m: 'POST', p: FIM_PATH, b: { model: PRO, prompt: 'def fib(n):\n    ' } });
+    if (!ok(r)) return false;
+    const b = body(r);
+    return b.object === 'text_completion' && b.model === PRO && String(b.id).startsWith('cmpl-')
+      && Array.isArray(b.choices) && typeof b.choices[0].text === 'string'
+      && b.choices[0].text.includes('[twin-stub:deepseek-v4-pro]')
+      && b.choices[0].finish_reason === 'stop' && b.choices[0].logprobs === null
+      // FIM's response carries the same KV-cache usage split as chat.
+      && typeof b.usage.prompt_cache_miss_tokens === 'number';
+  })),
+
+  done('deepseek.completions.suffix_and_echo', 'completions', 'suffix is honoured and echo prepends the prompt to the returned text', 'api', 'common', () => withRoot(async (h) => {
+    const withSuffix = await h({ m: 'POST', p: FIM_PATH, b: { model: PRO, prompt: 'a=', suffix: 'return a' } });
+    const noSuffix = await h({ m: 'POST', p: FIM_PATH, b: { model: PRO, prompt: 'a=' } });
+    if (!ok(withSuffix) || !ok(noSuffix)) return false;
+    if (!String(body(withSuffix).choices[0].text).includes('return a')) return false;
+    if (String(noSuffix.body && body(noSuffix).choices[0].text).includes('return a')) return false;
+    const echoed = await h({ m: 'POST', p: FIM_PATH, b: { model: PRO, prompt: 'PROMPT_HEAD', echo: true } });
+    const plain = await h({ m: 'POST', p: FIM_PATH, b: { model: PRO, prompt: 'PROMPT_HEAD' } });
+    return ok(echoed) && String(body(echoed).choices[0].text).startsWith('PROMPT_HEAD')
+      && !String(body(plain).choices[0].text).startsWith('PROMPT_HEAD');
+  })),
+
+  done('deepseek.completions.beta_only_and_closed_model', 'completions', 'FIM lives only under /beta and accepts only deepseek-v4-pro', 'api', 'common', () => withRoot(async (h) => {
+    const offBeta = await h({ m: 'POST', p: '/completions', b: { model: PRO, prompt: 'x' } });
+    const wrongModel = await h({ m: 'POST', p: FIM_PATH, b: { model: MODEL, prompt: 'x' } });
+    const noPrompt = await h({ m: 'POST', p: FIM_PATH, b: { model: PRO } });
+    return refused(offBeta) && msg(offBeta).includes('beta base URL')
+      && wrongModel.status === 422 && noPrompt.status === 422;
+  })),
+
+  done('deepseek.completions.logprobs_is_an_integer', 'completions', "The FIM endpoint's `logprobs` is an INTEGER (0..20), unlike the chat endpoint's boolean of the same name", 'api', 'niche', () => withRoot(async (h) => {
+    // Same key name, different type, on the same vendor. An OpenAI-shaped twin that shared one
+    // validator across both endpoints would accept the wrong type on one of them.
+    const good = await h({ m: 'POST', p: FIM_PATH, b: { model: PRO, prompt: 'x', logprobs: 5 } });
+    const boolean = await h({ m: 'POST', p: FIM_PATH, b: { model: PRO, prompt: 'x', logprobs: true } });
+    const tooMany = await h({ m: 'POST', p: FIM_PATH, b: { model: PRO, prompt: 'x', logprobs: 21 } });
+    // …and the chat endpoint is the exact inverse.
+    const chatBool = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ logprobs: true }) });
+    const chatInt = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ logprobs: 5 }) });
+    return ok(good) && boolean.status === 422 && tooMany.status === 422 && ok(chatBool) && chatInt.status === 422;
+  })),
+
+  done('deepseek.completions.refuses_unmodeled_streaming', 'completions', 'A FIM request asking to stream is REFUSED by name rather than answered with a unary body', 'api', 'common', () => withRoot(async (h) => {
+    // The endpoint really does declare `stream`, so serving a unary text_completion to a caller who
+    // asked for SSE would be a fake success — the exact failure mode "unmodeled ops fail like the
+    // vendor" exists to prevent. The refusal names the filed gap so the message is actionable.
+    const streamed = await h({ m: 'POST', p: FIM_PATH, b: { model: PRO, prompt: 'x', stream: true } });
+    if (streamed.status !== 422 || !msg(streamed).includes('deepseek.completions.streaming')) return false;
+    // …and the non-streaming path is unaffected, or the refusal would just be a broken endpoint.
+    const unary = await h({ m: 'POST', p: FIM_PATH, b: { model: PRO, prompt: 'x', stream: false } });
+    return ok(unary) && body(unary).object === 'text_completion';
+  })),
+  todo('deepseek.completions.cache_accounting', 'completions', 'FIM requests report prompt_cache_hit_tokens as a hard zero and record no prefix unit — the field is served in the faithful shape but is not measured on this endpoint the way it is on /chat/completions (§9 round one, NIT 18)', 'api', 'niche'),
+  todo('deepseek.completions.streaming', 'completions', 'FIM completion streaming (stream + stream_options.include_usage on /beta/completions) — currently refused by name rather than modeled', 'api', 'niche'),
+
+  // ══ models ═══════════════════════════════════════════════════════════════════════════════
+  done('deepseek.models.list', 'models', 'GET /models lists the published catalog', 'api', 'core', () => withRoot(async (h) => {
+    const r = await h({ m: 'GET', p: MODELS });
+    if (!ok(r)) return false;
+    const b = body(r);
+    const ids = (b.data as Body[]).map((m) => m.id);
+    return b.object === 'list' && ids.includes('deepseek-v4-flash') && ids.includes('deepseek-v4-pro')
+      && ids.includes('deepseek-v4-flash-vision-exp')
+      // The retired aliases must NOT be listed.
+      && !ids.includes('deepseek-chat') && !ids.includes('deepseek-reasoner');
+  })),
+
+  done('deepseek.models.row_shape', 'models', "A model row is exactly {id, object, owned_by} — DeepSeek's row has no `created` (OpenAI's does)", 'api', 'common', () => withRoot(async (h) => {
+    const r = await h({ m: 'GET', p: MODELS });
+    if (!ok(r)) return false;
+    // A LITERAL expected key set, licensed by §6 because DeepSeek's own list-models example
+    // response is a closed three-key object. Inventing `created` to look OpenAI-shaped is exactly
+    // the inverse false-green.
+    return (body(r).data as Body[]).every((m) => Object.keys(m).sort().join(',') === 'id,object,owned_by' && m.object === 'model' && m.owned_by === 'deepseek');
+  })),
+
+  done('deepseek.models.retired_and_unknown_ids', 'models', 'A retired alias is refused BY NAME with its retirement date; an unknown id is refused too', 'api', 'core', () => withRoot(async (h) => {
+    for (const retired of ['deepseek-chat', 'deepseek-reasoner']) {
+      const r = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ model: retired }) });
+      if (r.status !== 422 || !msg(r).includes('2026-07-24')) return false;
+    }
+    const unknown = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ model: 'gpt-4o' }) });
+    return unknown.status === 422 && msg(unknown).includes('does not exist');
+  })),
+
+  done('deepseek.models.pulled_rows_are_served', 'models', "A model observed by a connector pull is served by GET /models, not merely folded into the log", 'api', 'niche', () => withConnectorRoot('deepseek.models.pulled_rows_are_served', async (root) => {
+    const execute = fakeExecute({ models: [{ id: 'deepseek-v4-preview-internal', object: 'model', owned_by: 'deepseek' }] });
+    await syncDeepSeekFromReal(execute, { root, occurredAt: OCCURRED_AT });
+    const r = await handleDeepSeekTwinRequest({ method: 'GET', path: MODELS, root });
+    const ids = (body(r).data as Body[]).map((m) => m.id);
+    // Both the pulled row AND the published catalog must survive: an override that dropped either
+    // side makes the twin disagree with itself.
+    return ok(r) && ids.includes('deepseek-v4-preview-internal') && ids.includes('deepseek-v4-flash');
+  })),
+
+  todo('deepseek.models.per_model_metadata', 'models', 'Per-model metadata (context window, pricing tier, concurrency) — DeepSeek publishes these on its pricing page but not on the API row', 'api', 'niche'),
+
+  // ══ user balance ═════════════════════════════════════════════════════════════════════════
+  done('deepseek.balance.get', 'balance', 'GET /user/balance returns is_available plus per-currency balance_infos with STRING amounts', 'api', 'common', () => withRoot(async (h) => {
+    const r = await h({ m: 'GET', p: BALANCE });
+    if (!ok(r)) return false;
+    const b = body(r);
+    const info = (b.balance_infos as Body[])[0];
+    return b.is_available === true && Array.isArray(b.balance_infos) && b.balance_infos.length > 0
+      && ['CNY', 'USD'].includes(info.currency)
+      // Amounts are STRINGS on this vendor. A twin that emitted numbers would break any client
+      // decoding them as the documented type.
+      && typeof info.total_balance === 'string' && typeof info.granted_balance === 'string' && typeof info.topped_up_balance === 'string';
+  })),
+
+  done('deepseek.balance.insufficient_402', 'balance', 'A drained account refuses completions with 402 "You have run out of balance" — a status OpenAI does not have', 'api', 'core', () => withRoot(async (h, root) => {
+    const before = await h({ m: 'POST', p: CHAT_PATH, b: CHAT() });
+    if (!ok(before)) return false;
+    // STATE-DRIVEN, not a header trick: the refusal reads `is_available` off the same projection
+    // `GET /user/balance` serves, so it is a fact about the twin's state.
+    await applyTwinWrite('deepseek', {
+      operation: 'balance.update', subjectType: 'balance', subjectId: 'account',
+      fields: { is_available: false, balance_infos: [{ currency: 'USD', total_balance: '0.00', granted_balance: '0.00', topped_up_balance: '0.00' }] },
+      occurredAt: OCCURRED_AT, actor: { kind: 'agent' },
+    }, root);
+    const after = await h({ m: 'POST', p: CHAT_PATH, b: CHAT() });
+    const fim = await h({ m: 'POST', p: FIM_PATH, b: { model: PRO, prompt: 'x' } });
+    const balance = await h({ m: 'GET', p: BALANCE });
+    return after.status === 402 && msg(after).includes('run out of balance')
+      && fim.status === 402
+      // Reads still work on a drained account — only generation is refused.
+      && ok(balance) && body(balance).is_available === false;
+  })),
+
+  todo('deepseek.balance.multi_currency', 'balance', 'An account holding both CNY and USD balances reports both rows', 'api', 'niche'),
+
+  // ══ context cache (KV cache) ═════════════════════════════════════════════════════════════
+  done('deepseek.cache.hit_miss_split', 'cache', 'usage carries prompt_cache_hit_tokens + prompt_cache_miss_tokens, summing exactly to prompt_tokens', 'api', 'core', () => withRoot(async (h) => {
+    const r = await h({ m: 'POST', p: CHAT_PATH, b: CHAT() });
+    if (!ok(r)) return false;
+    const u = body(r).usage as Body;
+    return typeof u.prompt_cache_hit_tokens === 'number' && typeof u.prompt_cache_miss_tokens === 'number'
+      && u.prompt_cache_hit_tokens + u.prompt_cache_miss_tokens === u.prompt_tokens
+      // …and the OpenAI-shaped mirror field agrees with the hit count, because the SDK's usage
+      // schema declares both and its `cacheRead` reads the DeepSeek one.
+      && (u.prompt_tokens_details as Body).cached_tokens === u.prompt_cache_hit_tokens;
+  })),
+
+  done('deepseek.cache.prefix_hit_on_continuation', 'cache', "A follow-up turn genuinely HITS the cache: the twin keeps a prefix-unit ledger rather than fabricating a split", 'api', 'core', () => withRoot(async (h) => {
+    const first = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [{ role: 'user', content: 'a long opening question about caching behaviour' }] } });
+    if (!ok(first)) return false;
+    // A brand-new conversation can hit nothing.
+    if ((body(first).usage as Body).prompt_cache_hit_tokens !== 0) return false;
+    const answer = text0(first);
+    const second = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [
+      { role: 'user', content: 'a long opening question about caching behaviour' },
+      { role: 'assistant', content: answer, reasoning_content: '' },
+      { role: 'user', content: 'and a follow-up' },
+    ] } });
+    if (!ok(second)) return false;
+    const u = body(second).usage as Body;
+    // The continuation's recorded prefix (opening + answer) is reported as a hit and the NEW turn
+    // as a miss. `miss > 0` is the assertion that matters: an implementation measuring the hit off
+    // the stored prefix text instead of this request's own messages over-counts, the clamp in
+    // `buildUsage` rescues the invariant, and the follow-up reports a 100% cache with the new turn
+    // silently absent from the accounting. That was a real defect this cell caught.
+    return u.prompt_cache_hit_tokens > 0 && u.prompt_cache_miss_tokens > 0
+      && u.prompt_cache_hit_tokens + u.prompt_cache_miss_tokens === u.prompt_tokens;
+  })),
+
+  done('deepseek.cache.unrelated_prompt_misses', 'cache', 'An unrelated conversation reports a full miss even after the ledger has entries', 'api', 'common', () => withRoot(async (h) => {
+    // The other direction, and the one a fabricated split would fail: having served one
+    // conversation, a DIFFERENT one must still be 100% miss. A twin that reported a fixed
+    // hit ratio would pass the hit test and fail this one.
+    await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [{ role: 'user', content: 'topic one' }] } });
+    const other = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [{ role: 'user', content: 'a completely different topic' }] } });
+    if (!ok(other)) return false;
+    const u = body(other).usage as Body;
+    return u.prompt_cache_hit_tokens === 0 && u.prompt_cache_miss_tokens === u.prompt_tokens && u.prompt_tokens > 0;
+  })),
+
+  done('deepseek.cache.identical_replay_hits', 'cache', 'A byte-identical repeat of a request FULLY MATCHES the user-input-end prefix unit the first call recorded, and reports a full cache hit', 'api', 'common', () => withRoot(async (h) => {
+    // The canonical KV-cache demonstration, and the one the twin used to get wrong: it stopped its
+    // prefix search one message short, so an identical replay reported 0 hit tokens. The vendor's
+    // rule is that a request hits when it "fully matches a cache prefix unit", and units form at
+    // "the end position of the user input" (api-docs.deepseek.com/guides/kv_cache).
+    const req = { model: MODEL, messages: [{ role: 'user', content: 'a repeatable single-turn question' }] };
+    const first = await h({ m: 'POST', p: CHAT_PATH, b: req });
+    if (!ok(first) || (body(first).usage as Body).prompt_cache_hit_tokens !== 0) return false;
+    const second = await h({ m: 'POST', p: CHAT_PATH, b: req });
+    if (!ok(second)) return false;
+    const u = body(second).usage as Body;
+    // A FULL match: every prompt token is a hit, and none is a miss.
+    if (u.prompt_cache_hit_tokens !== u.prompt_tokens || u.prompt_cache_miss_tokens !== 0 || u.prompt_tokens === 0) return false;
+    // …and this is not a "second call always hits" rule: a DIFFERENT request in the same warmed
+    // root still misses completely.
+    const other = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [{ role: 'user', content: 'an entirely different question' }] } });
+    return ok(other) && (body(other).usage as Body).prompt_cache_hit_tokens === 0;
+  })),
+
+  done('deepseek.cache.key_covers_every_charged_field', 'cache', 'A turn carrying a different reasoning_content, name or tool_call is a MISS — the prefix key covers EVERY field the token count charges for', 'api', 'common', () => withRoot(async (h) => {
+    // §9 round one, NIT 15: the key dropped `name` and `reasoning_content` while `messageTokens`
+    // counted them, so a caller could attach an arbitrarily large reasoning_content to a matching
+    // turn and have those tokens billed as a hit.
+    const opening = { model: MODEL, messages: [{ role: 'user', content: 'opening' }] };
+    const seeded = await h({ m: 'POST', p: CHAT_PATH, b: opening });
+    if (!ok(seeded)) return false;
+    const answer = text0(seeded);
+    const cont = (assistant: Record<string, unknown>) => ({ model: MODEL, messages: [{ role: 'user', content: 'opening' }, assistant, { role: 'user', content: 'next' }] });
+    // A SECOND recorded shape whose assistant turn carries a tool call. Without it the padded-id
+    // case below differs from every recorded unit in TWO ways (it has tool_calls at all, and the id
+    // is long), so its miss would be explained by the first difference and the cell would stay green
+    // with the id dropped from the key — which is exactly how the first version of this pin came out
+    // HOLLOW on the revert matrix. This baseline makes the id the ONLY difference.
+    const TOOL_TURN = { role: 'assistant', content: answer, tool_calls: [{ id: 'call_twin_1', type: 'function', function: { name: 'f', arguments: '{}' } }] };
+    const toolBaseline = await h({ m: 'POST', p: CHAT_PATH, b: cont(TOOL_TURN) });
+    if (!ok(toolBaseline) || (body(toolBaseline).usage as Body).prompt_cache_miss_tokens > 200) return false;
+    // An absent reasoning_content and an empty one are the SAME key — that is the shape
+    // @ai-sdk/deepseek produces, so a stricter key would make every real SDK continuation a miss.
+    const plain = await h({ m: 'POST', p: CHAT_PATH, b: cont({ role: 'assistant', content: answer }) });
+    const empty = await h({ m: 'POST', p: CHAT_PATH, b: cont({ role: 'assistant', content: answer, reasoning_content: '' }) });
+    if (!ok(plain) || !ok(empty)) return false;
+    if ((body(plain).usage as Body).prompt_cache_hit_tokens === 0) return false;
+    // `empty` runs AFTER `plain` in the same root, so if the two canonicalize identically it fully
+    // matches the 3-message unit `plain` just recorded — a zero miss. If they canonicalized
+    // differently it would have to fall back to the shorter prefix and report a miss, which is
+    // exactly what a key that ignored `reasoning_content` inconsistently would produce.
+    if ((body(empty).usage as Body).prompt_cache_miss_tokens !== 0) return false;
+    // …but a turn carrying a LARGE payload in ANY field the token count charges for is a different
+    // conversation, and must not be billed as a hit against the unit recorded for the plain one.
+    // THREE fields, one per charged term in `messageTokens` — §9 round two, BLOCKER 1: the first
+    // version varied only `reasoning_content`, so `tool_calls[].id` (which `messageTokens` charges
+    // through `JSON.stringify(tc)`) slipped through and 999 tokens of caller padding were billed as
+    // a hit. A cell that proves one charged field says nothing about the others.
+    const fatCases: Array<[string, Record<string, unknown>]> = [
+      ['reasoning_content', { role: 'assistant', content: answer, reasoning_content: 'x'.repeat(4000) }],
+      ['name', { role: 'assistant', content: answer, name: 'n'.repeat(4000) }],
+      // Identical to TOOL_TURN except for the id — so a key that omitted the id would FULLY match
+      // the unit `toolBaseline` just recorded and bill all 4000 characters as a hit.
+      ['tool_calls[].id', { ...TOOL_TURN, tool_calls: [{ id: `call_${'z'.repeat(4000)}`, type: 'function', function: { name: 'f', arguments: '{}' } }] }],
+    ];
+    for (const [, assistant] of fatCases) {
+      const fat = await h({ m: 'POST', p: CHAT_PATH, b: cont(assistant) });
+      if (!ok(fat)) return false;
+      const fu = body(fat).usage as Body;
+      if (fu.prompt_cache_hit_tokens >= (body(toolBaseline).usage as Body).prompt_tokens + 10) return false;
+      if (fu.prompt_cache_miss_tokens <= 900) return false;
+      if (fu.prompt_cache_hit_tokens + fu.prompt_cache_miss_tokens !== fu.prompt_tokens) return false;
+    }
+    return true;
+  })),
+
+  todo('deepseek.cache.interval_units', 'cache', 'Cache prefix units cut at "fixed token intervals" inside long inputs — DeepSeek publishes no interval, so the twin does not invent one', 'api', 'niche'),
+  todo('deepseek.cache.expiry', 'cache', 'Cache entries auto-clearing "within hours to days": the kernel\'s world clock is deterministic by construction and is explicitly the seam TTL/expiry logic reads at serve time, so this is unbuilt rather than impossible (§9 round one, SHOULD-FIX 5)', 'api', 'niche'),
+
+  // ══ reasoning / thinking mode ════════════════════════════════════════════════════════════
+  done('deepseek.reasoning.enabled_by_default', 'reasoning', 'V4 models think by default: the assistant turn carries reasoning_content and reasoning_tokens', 'api', 'core', () => withRoot(async (h) => {
+    const r = await h({ m: 'POST', p: CHAT_PATH, b: CHAT() });
+    if (!ok(r)) return false;
+    const rc = choice0(r).message.reasoning_content;
+    return typeof rc === 'string' && rc.includes('[twin-stub:') && rc.includes('reasoning_effort=high')
+      && (body(r).usage.completion_tokens_details as Body)?.reasoning_tokens > 0;
+  })),
+
+  done('deepseek.reasoning.disabled', 'reasoning', "thinking.type 'disabled' removes reasoning_content and its token accounting", 'api', 'core', () => withRoot(async (h) => {
+    const off = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ thinking: { type: 'disabled' } }) });
+    if (!ok(off)) return false;
+    if (choice0(off).message.reasoning_content !== undefined) return false;
+    if (body(off).usage.completion_tokens_details !== undefined) return false;
+    // …and the closed set is enforced: `adaptive` is a legacy SDK-side value the API does not take.
+    const bad = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ thinking: { type: 'adaptive' } }) });
+    return bad.status === 422;
+  })),
+
+  done('deepseek.reasoning.effort', 'reasoning', "reasoning_effort is the closed set low|high|max, accepted at BOTH documented placements, with medium/xhigh mapped as the vendor documents", 'api', 'common', () => withRoot(async (h) => {
+    // Two first-party sources disagree on placement — the API reference puts it at
+    // `thinking.reasoning_effort`, `@ai-sdk/deepseek` sends a top-level `reasoning_effort`. The twin
+    // accepts BOTH rather than rejecting a shape a first-party client demonstrably sends.
+    const top = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ reasoning_effort: 'max' }) });
+    const nested = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ thinking: { type: 'enabled', reasoning_effort: 'max' } }) });
+    if (!ok(top) || !ok(nested)) return false;
+    // The effort must reach the turn — a handler that parsed and dropped it would serve `high`.
+    if (!String(choice0(top).message.reasoning_content).includes('reasoning_effort=max')) return false;
+    if (String(choice0(nested).message.reasoning_content) !== String(choice0(top).message.reasoning_content)) return false;
+    // Legacy values the vendor documents as MAPPED to high, not refused.
+    const legacy = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ reasoning_effort: 'medium' }) });
+    if (!ok(legacy) || !String(choice0(legacy).message.reasoning_content).includes('reasoning_effort=high')) return false;
+    const bad = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ reasoning_effort: 'ultra' }) });
+    return bad.status === 422;
+  })),
+
+  done('deepseek.reasoning.tools_require_handback', 'reasoning', 'With `tools` set, a previous assistant turn missing reasoning_content is a documented 400 — not a 422 and not a silent success', 'api', 'core', () => withRoot(async (h) => {
+    // "If the request carries the tools parameter: the reasoning_content of all previous turns
+    // should be passed back … the API will return a 400 error"
+    // (api-docs.deepseek.com/guides/thinking_mode). This is the one refusal on this vendor that is
+    // a 400 rather than a 422, and no OpenAI-shaped twin has it at all.
+    const history = [{ role: 'user', content: 'q' }, { role: 'assistant', content: 'a' }, { role: 'user', content: 'q2' }];
+    const missing = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: history, tools: [WEATHER_TOOL] } });
+    if (missing.status !== 400) return false;
+    // An EMPTY STRING counts as passed back — that is literally what @ai-sdk/deepseek sends for a
+    // turn with no reasoning, so a stricter check would refuse the real SDK.
+    const empty = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, tools: [WEATHER_TOOL], messages: [
+      { role: 'user', content: 'q' }, { role: 'assistant', content: 'a', reasoning_content: '' }, { role: 'user', content: 'q2' },
+    ] } });
+    // …and WITHOUT tools the same history is fine: the rule is scoped to tool requests.
+    const noTools = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: history } });
+    return ok(empty) && ok(noTools);
+  })),
+
+
+  // ══ streaming ════════════════════════════════════════════════════════════════════════════
+  done('deepseek.streaming.chat', 'streaming', 'Streaming emits the vendor chunk sequence and terminates with [DONE]', 'api', 'core', () => withStream({ ...CHAT(), stream: true }, (events) => {
+    const data = events.filter((e) => !e.done).map((e) => e.data as Body);
+    if (!events.length || events[events.length - 1]!.done !== true) return false;
+    if (data[0]?.object !== 'chat.completion.chunk') return false;
+    if ((data[0]!.choices as Body[])[0].delta.role !== 'assistant') return false;
+    const text = data.map((d) => (d.choices as Body[])[0]?.delta?.content ?? '').join('');
+    const finish = data.find((d) => (d.choices as Body[])[0]?.finish_reason != null);
+    return text.includes('[twin-stub:deepseek-v4-flash]') && text.includes('hello twin')
+      && (finish!.choices as Body[])[0].finish_reason === 'stop';
+  })),
+
+  done('deepseek.streaming.reasoning_before_text', 'streaming', 'reasoning_content deltas arrive BEFORE the first content delta and never interleave', 'api', 'core', () => withStream({ ...CHAT(), stream: true }, (events) => {
+    const data = events.filter((e) => !e.done).map((e) => e.data as Body);
+    const kinds = data.map((d) => {
+      const delta = (d.choices as Body[])[0]?.delta as Body | undefined;
+      if (typeof delta?.reasoning_content === 'string') return 'r';
+      if (typeof delta?.content === 'string' && delta.content !== '') return 'c';
+      return '.';
+    }).join('');
+    const lastR = kinds.lastIndexOf('r');
+    const firstC = kinds.indexOf('c');
+    // The SDK's transform closes its reasoning part the moment the first content delta arrives, so
+    // interleaving would produce a different part sequence than the vendor's.
+    return lastR >= 0 && firstC >= 0 && lastR < firstC;
+  })),
+
+  done('deepseek.streaming.usage_tail_is_opt_in', 'streaming', 'The empty-choices usage tail chunk is emitted only when stream_options.include_usage is set', 'api', 'core', async () => {
+    const withUsage = await withStream({ ...CHAT(), stream: true, stream_options: { include_usage: true } }, (events) => {
+      const tail = events[events.length - 2]?.data as Body | undefined;
+      return !!tail && Array.isArray(tail.choices) && tail.choices.length === 0
+        && typeof (tail.usage as Body)?.prompt_cache_miss_tokens === 'number'
+        && (tail.usage as Body).total_tokens > 0;
+    });
+    if (!withUsage) return false;
+    // The negative half: without the option there must be NO usage chunk at all. A twin that always
+    // emitted it would look right to the SDK (which always asks for it) and be wrong for everyone else.
+    return withStream({ ...CHAT(), stream: true }, (events) => !events.some((e) => !e.done && (e.data as Body)?.usage !== undefined));
+  }),
+
+  done('deepseek.streaming.tool_call_deltas', 'streaming', 'Tool calls stream as indexed name-then-arguments deltas', 'api', 'common', () => withStream({ ...CHAT(), tools: [WEATHER_TOOL], stream: true }, (events) => {
+    const data = events.filter((e) => !e.done).map((e) => e.data as Body);
+    const deltas = data.flatMap((d) => ((d.choices as Body[])[0]?.delta?.tool_calls ?? []) as Body[]);
+    if (deltas.length < 2) return false;
+    const named = deltas.find((t) => t.function?.name === 'get_weather');
+    const args = deltas.filter((t) => typeof t.function?.arguments === 'string' && t.function.arguments !== '');
+    const finish = data.find((d) => (d.choices as Body[])[0]?.finish_reason != null);
+    return !!named && named.index === 0 && typeof named.id === 'string' && named.type === 'function'
+      && args.length > 0 && JSON.parse(args[args.length - 1]!.function.arguments).city === ''
+      && (finish!.choices as Body[])[0].finish_reason === 'tool_calls';
+  })),
+
+  todo('deepseek.streaming.stream_options_without_stream', 'streaming', "How DeepSeek answers `stream_options` on a NON-streaming request — the reference table says only 'set when stream: true', which is guidance rather than a documented refusal, so the twin accepts and ignores it rather than inventing a 422 (§9 round one, NIT 13)", 'api', 'niche'),
+
+  done('deepseek.streaming.never_degrades_to_a_unary_body', 'streaming', 'A `stream: true` request is never answered with a unary JSON body — not through a repeated-slash path spelling, and not when a caller supplies no sink', 'api', 'core', async () => {
+    // §9 ROUND TWO, SHOULD-FIX 1. Two independent holes, both fake successes of exactly the kind
+    // `deepseek.completions.refuses_unmodeled_streaming` forbids on the FIM endpoint:
+    //   • the handler fell through to the unary builder whenever an sseSink was absent;
+    //   • the SERVER's STREAMABLE lookup collapsed only a TRAILING slash while the router collapsed
+    //     REPEATED ones, so `/beta//chat/completions` reached the streaming route, missed the
+    //     streaming response path, and answered `application/json` to a client reading SSE.
+    const root = mkdtempSync(join(tmpdir(), 'deepseek-cap-'));
+    const { createDeepSeekTwinServer } = await import('./deepseek-server.ts');
+    const server = await createDeepSeekTwinServer({ root });
+    try {
+      return await verifyBoundary('deepseek.streaming.never_degrades_to_a_unary_body', async () => {
+        // The handler half: a streaming request with no sink is refused, not downgraded.
+        const noSink = await handleDeepSeekTwinRequest({ method: 'POST', path: CHAT_PATH, body: JSON.stringify({ ...CHAT(), stream: true }), root, occurredAt: OCCURRED_AT });
+        if (noSink.status !== 422 || (body(noSink) as Body).object === 'chat.completion') return false;
+        // The server half: every spelling that REACHES the streaming route must stream.
+        const base = `http://127.0.0.1:${server.port}`;
+        for (const path of ['/chat/completions', '//chat/completions', '/beta/chat/completions', '/beta//chat/completions']) {
+          const res = await fetch(`${base}${path}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: 'Bearer sk-x' },
+            body: JSON.stringify({ ...CHAT(), stream: true }),
+          });
+          const ct = res.headers.get('content-type') ?? '';
+          const text = await res.text();
+          if (!ct.includes('text/event-stream')) return false;
+          if (!text.trimEnd().endsWith('data: [DONE]')) return false;
+        }
+        return true;
+      });
+    } finally { server.stop(); rmSync(root, { recursive: true, force: true }); }
+  }),
+
+  todo('deepseek.streaming.error_chunk', 'streaming', 'A mid-stream failure emits DeepSeek\'s error envelope as an SSE data event with the retryable metadata the SDK discriminates on', 'api', 'niche'),
+
+  // ══ tools / function calling ═════════════════════════════════════════════════════════════
+  done('deepseek.tools.function_calling', 'tools', 'Providing tools yields tool_calls with schema-shaped arguments and finish_reason tool_calls', 'api', 'core', () => withRoot(async (h) => {
+    const r = await h({ m: 'POST', p: CHAT_PATH, b: { ...CHAT(), tools: [WEATHER_TOOL] } });
+    if (!ok(r)) return false;
+    const calls = choice0(r).message.tool_calls as Body[];
+    if (!Array.isArray(calls) || calls.length !== 1) return false;
+    const args = JSON.parse(calls[0]!.function.arguments);
+    return calls[0]!.type === 'function' && calls[0]!.function.name === 'get_weather'
+      && typeof calls[0]!.id === 'string' && calls[0]!.id.length > 0
+      // Arguments must contain every declared property with a type-appropriate placeholder.
+      && args.city === '' && args.days === 0
+      && choice0(r).message.content === null && choice0(r).finish_reason === 'tool_calls';
+  })),
+
+  done('deepseek.tools.tool_choice', 'tools', "tool_choice none suppresses calls, a named function forces that one, and an unknown value is refused", 'api', 'common', () => withRoot(async (h) => {
+    const none = await h({ m: 'POST', p: CHAT_PATH, b: { ...CHAT(), tools: [WEATHER_TOOL], tool_choice: 'none' } });
+    if (!ok(none) || none.body === undefined) return false;
+    if (choice0(none).message.tool_calls !== undefined || choice0(none).finish_reason !== 'stop') return false;
+    const named = await h({ m: 'POST', p: CHAT_PATH, b: { ...CHAT(), tools: [WEATHER_TOOL, TIME_TOOL], tool_choice: { type: 'function', function: { name: 'get_time' } } } });
+    if (!ok(named)) return false;
+    const calls = choice0(named).message.tool_calls as Body[];
+    // Exactly the NAMED tool, not the first one — a handler ignoring tool_choice returns get_weather.
+    if (calls.length !== 1 || calls[0]!.function.name !== 'get_time') return false;
+    const bad = await h({ m: 'POST', p: CHAT_PATH, b: { ...CHAT(), tools: [WEATHER_TOOL], tool_choice: 'any' } });
+    const badNamed = await h({ m: 'POST', p: CHAT_PATH, b: { ...CHAT(), tools: [WEATHER_TOOL], tool_choice: { type: 'function' } } });
+    return bad.status === 422 && badNamed.status === 422;
+  })),
+
+  done('deepseek.tools.tool_result_turn', 'tools', 'A role:tool result turn is accepted and folded into the prompt', 'api', 'common', () => withRoot(async (h) => {
+    const r = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [
+      { role: 'user', content: 'weather in Lisbon?' },
+      { role: 'assistant', content: null, reasoning_content: '', tool_calls: [{ id: 'call_1', type: 'function', function: { name: 'get_weather', arguments: '{"city":"Lisbon"}' } }] },
+      { role: 'tool', tool_call_id: 'call_1', content: '{"temp":21}' },
+    ] } });
+    if (!ok(r)) return false;
+    // The tool turn is real payload: it must be counted, so a handler dropping it reports fewer tokens.
+    const withoutTool = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [{ role: 'user', content: 'weather in Lisbon?' }] } });
+    return body(r).usage.prompt_tokens > body(withoutTool).usage.prompt_tokens && choice0(r).finish_reason === 'stop';
+  })),
+
+  done('deepseek.tools.max_128', 'tools', 'More than 128 function tools is refused', 'api', 'niche', () => withRoot(async (h) => {
+    const tool = (n: number) => ({ type: 'function', function: { name: `f${n}`, parameters: { type: 'object', properties: {} } } });
+    const at = await h({ m: 'POST', p: CHAT_PATH, b: { ...CHAT(), tools: Array.from({ length: 128 }, (_, i) => tool(i)) } });
+    const over = await h({ m: 'POST', p: CHAT_PATH, b: { ...CHAT(), tools: Array.from({ length: 129 }, (_, i) => tool(i)) } });
+    const malformed = await h({ m: 'POST', p: CHAT_PATH, b: { ...CHAT(), tools: [{ type: 'retrieval' }] } });
+    return ok(at) && over.status === 422 && malformed.status === 422;
+  })),
+
+  done('deepseek.tools.strict_is_beta_only_and_all_or_nothing', 'tools', 'strict:true requires the /beta base URL, and inside it every function tool must be strict', 'api', 'common', () => withRoot(async (h) => {
+    const strict = { type: 'function', function: { name: 'a', strict: true, parameters: { type: 'object', properties: {} } } };
+    const loose = { type: 'function', function: { name: 'b', parameters: { type: 'object', properties: {} } } };
+    const offBeta = await h({ m: 'POST', p: CHAT_PATH, b: { ...CHAT(), tools: [strict] } });
+    const mixed = await h({ m: 'POST', p: BETA_CHAT, b: { ...CHAT(), tools: [strict, loose] } });
+    const allStrict = await h({ m: 'POST', p: BETA_CHAT, b: { ...CHAT(), tools: [strict] } });
+    // The non-strict path must still work on the standard base URL, or the check has proved nothing
+    // about `strict` in particular.
+    const plain = await h({ m: 'POST', p: CHAT_PATH, b: { ...CHAT(), tools: [loose] } });
+    return offBeta.status === 422 && msg(offBeta).includes('beta base URL')
+      && mixed.status === 422 && ok(allStrict) && ok(plain);
+  })),
+
+  todo('deepseek.tools.strict_schema_enforcement', 'tools', 'Under beta strict mode, generated arguments are guaranteed to validate against the declared JSON schema', 'api', 'niche'),
+  todo('deepseek.beta.prefix_with_tools', 'beta', 'Prefix completion combined with tools in one beta request', 'api', 'niche'),
+  // CORE for the same reason: an agent integration meets parallel tool calls immediately.
+  todo('deepseek.tools.parallel_multi_tool', 'tools', 'A turn returning several tool_calls at once, as the vendor does for independent tools', 'api', 'core'),
+
+  // ══ structured outputs ═══════════════════════════════════════════════════════════════════
+  done('deepseek.structured_outputs.json_object', 'structured_outputs', "On /chat/completions, response_format accepts text and json_object only — json_schema is REFUSED", 'api', 'core', () => withRoot(async (h) => {
+    const r = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ response_format: { type: 'json_object' } }) });
+    if (!ok(r)) return false;
+    const parsed = JSON.parse(text0(r));
+    if (parsed._twin_stub !== true || parsed.model !== MODEL) return false;
+    // THE DIVERGENCE, and it is ENDPOINT-SCOPED — stating it as "DeepSeek has no json_schema" would
+    // be wrong: its Responses API's `text.format` does take one. What has no json_schema is
+    // /chat/completions, and `@ai-sdk/deepseek` confirms it from the other side by INJECTING the
+    // schema into a system message rather than sending `response_format.json_schema`
+    // (src/chat/convert-to-deepseek-chat-messages.ts). A twin that accepted it here would be
+    // serving OpenAI's surface on an endpoint that does not have it.
+    const schema = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ response_format: { type: 'json_schema', json_schema: { name: 'x', schema: { type: 'object' } } } }) });
+    const bogus = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ response_format: { type: 'xml' } }) });
+    const text = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ response_format: { type: 'text' } }) });
+    return schema.status === 422 && bogus.status === 422 && ok(text) && !text0(text).startsWith('{');
+  })),
+
+  // ── Responses API (real surface, wholly unmodeled) ───────────────────────────────────────
+  // `POST /responses` is a first-class entry in DeepSeek's own API-reference nav alongside Chat
+  // Completions, FIM, Lists Models, Get User Balance and Files. It is a DIFFERENT protocol — an
+  // `input` item array rather than `messages`, an `output` item array rather than `choices`,
+  // semantic SSE events rather than delta chunks — so it is enumerated as its own area rather than
+  // folded into chat. The twin answers it like any other unmodeled operation, never a fake success.
+  todo('deepseek.responses.create', 'responses', 'POST /responses — the Responses-protocol envelope (input items in, output items out, its own usage block)', 'api', 'common'),
+  todo('deepseek.responses.instructions', 'responses', "The Responses API's top-level `instructions` system-level input", 'api', 'niche'),
+  todo('deepseek.responses.reasoning_items', 'responses', 'Chain of thought returned as `reasoning` OUTPUT ITEMS rather than a reasoning_content field', 'api', 'common'),
+  todo('deepseek.responses.reasoning_effort_set', 'responses', "The Responses API's WIDER effort set (none|minimal|low|medium|high|xhigh|max) — /chat/completions takes only low|high|max", 'api', 'niche'),
+  todo('deepseek.responses.text_format_json_schema', 'responses', '`text.format` accepting json_schema — the structured-output shape /chat/completions does NOT have', 'api', 'common'),
+  todo('deepseek.responses.streaming', 'responses', 'Semantic SSE with `event` + `sequence_number`, terminating in response.completed / .incomplete / .failed', 'api', 'common'),
+  todo('deepseek.responses.function_tools', 'responses', 'Function tools and tool_choice on the Responses protocol, returning function_call output items', 'api', 'common'),
+  todo('deepseek.responses.web_search_tool', 'responses', 'The built-in server-side `web_search` tool and its web_search_call output items', 'api', 'niche'),
+  todo('deepseek.responses.stateless', 'responses', 'The documented statelessness: responses are not stored, so a client resubmits history rather than passing a previous-response id', 'api', 'niche'),
+
+  todo('deepseek.structured_outputs.system_prompt_contract', 'structured_outputs', 'JSON mode\'s documented requirement that the prompt itself instruct the model to emit JSON, and its empty-content failure mode', 'api', 'common'),
+
+  // ══ beta: chat prefix completion ═════════════════════════════════════════════════════════
+  done('deepseek.beta.prefix_completion', 'beta', 'Under /beta, an assistant message with prefix:true is CONTINUED rather than answered', 'api', 'common', () => withRoot(async (h) => {
+    const r = await h({ m: 'POST', p: BETA_CHAT, b: { model: MODEL, messages: [
+      { role: 'user', content: 'describe the sky' },
+      { role: 'assistant', content: 'The sky is', prefix: true },
+    ] } });
+    if (!ok(r)) return false;
+    // Continuation, not a fresh turn: the caller's own text must lead the content.
+    return text0(r).startsWith('The sky is') && text0(r).length > 'The sky is'.length && text0(r).includes('[twin-stub:');
+  })),
+
+  done('deepseek.beta.prefix_placement_rules', 'beta', 'prefix:true is refused off /beta, on a non-assistant role, and when it is not the final message', 'api', 'common', () => withRoot(async (h) => {
+    const offBeta = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [{ role: 'user', content: 'x' }, { role: 'assistant', content: 'y', prefix: true }] } });
+    const notFinal = await h({ m: 'POST', p: BETA_CHAT, b: { model: MODEL, messages: [{ role: 'assistant', content: 'y', prefix: true }, { role: 'user', content: 'x' }] } });
+    const wrongRole = await h({ m: 'POST', p: BETA_CHAT, b: { model: MODEL, messages: [{ role: 'user', content: 'x', prefix: true }] } });
+    return offBeta.status === 422 && msg(offBeta).includes('beta base URL')
+      && notFinal.status === 422 && msg(notFinal).includes('final message')
+      && wrongRole.status === 422 && msg(wrongRole).includes('assistant message');
+  })),
+
+  done('deepseek.beta.standard_surface_unchanged', 'beta', 'The /beta base URL serves the SAME chat surface — it only unlocks prefix and strict tools', 'api', 'common', () => withRoot(async (h) => {
+    const std = await h({ m: 'POST', p: CHAT_PATH, b: CHAT() });
+    const beta = await h({ m: 'POST', p: BETA_CHAT, b: CHAT() });
+    if (!ok(std) || !ok(beta)) return false;
+    // Same request, same answer: /beta is a feature-flag prefix, not a second API. (Usage differs
+    // because the first call seeds the cache ledger, so only the content is compared.)
+    return text0(std) === text0(beta) && body(beta).object === 'chat.completion'
+      // …and /beta still refuses what the standard surface refuses.
+      && (await h({ m: 'POST', p: BETA_CHAT, b: CHAT({ n: 2 }) })).status === 422;
+  })),
+
+  // ══ files (images only) ══════════════════════════════════════════════════════════════════
+  done('deepseek.files.upload', 'files', 'POST /files stores an image and returns the vendor file object', 'api', 'common', () => withRoot(async (h) => {
+    const r = await h({ m: 'POST', p: FILES, b: UPLOAD() });
+    if (!ok(r)) return false;
+    const b = body(r);
+    return b.object === 'file' && b.id === FILE_1 && b.filename === 'shot.png' && b.purpose === 'user_data'
+      && b.bytes === 3 && typeof b.created_at === 'number' && b.expires_at === undefined;
+  })),
+
+  done('deepseek.files.image_only', 'files', "The Files API accepts JPEG/PNG/GIF/WebP only, and purpose must be 'user_data'", 'api', 'common', () => withRoot(async (h) => {
+    // DeepSeek's Files API is for vision inputs. The OpenAI habit — uploading a .jsonl for a Batch
+    // API — has no counterpart here, and accepting it would fabricate a whole product.
+    const jsonl = await h({ m: 'POST', p: FILES, b: { purpose: 'user_data', filename: 'in.jsonl', media_type: 'application/jsonl', content: 'x', bytes: 1 } });
+    const batch = await h({ m: 'POST', p: FILES, b: UPLOAD({ purpose: 'batch' }) });
+    const pdf = await h({ m: 'POST', p: FILES, b: UPLOAD({ filename: 'doc.pdf', media_type: 'application/pdf' }) });
+    if (jsonl.status !== 422 || batch.status !== 422 || pdf.status !== 422) return false;
+    // Every accepted format must actually be accepted, or the allowlist is wrong in the other
+    // direction.
+    for (const [filename, media] of [['a.jpg', 'image/jpeg'], ['a.jpeg', 'image/jpeg'], ['a.png', 'image/png'], ['a.gif', 'image/gif'], ['a.webp', 'image/webp']]) {
+      if (!ok(await h({ m: 'POST', p: FILES, b: UPLOAD({ filename, media_type: media }) }))) return false;
+    }
+    return true;
+  })),
+
+  done('deepseek.files.expires_after', 'files', 'expires_after sets expires_at; the anchor is closed and the range is 3600..2592000', 'api', 'niche', () => withRoot(async (h) => {
+    const r = await h({ m: 'POST', p: FILES, b: UPLOAD({ 'expires_after[anchor]': 'created_at', 'expires_after[seconds]': 3600 }) });
+    if (!ok(r)) return false;
+    if (body(r).expires_at !== body(r).created_at + 3600) return false;
+    const tooShort = await h({ m: 'POST', p: FILES, b: UPLOAD({ 'expires_after[anchor]': 'created_at', 'expires_after[seconds]': 3599 }) });
+    const tooLong = await h({ m: 'POST', p: FILES, b: UPLOAD({ 'expires_after[anchor]': 'created_at', 'expires_after[seconds]': 2_592_001 }) });
+    const badAnchor = await h({ m: 'POST', p: FILES, b: UPLOAD({ 'expires_after[anchor]': 'now', 'expires_after[seconds]': 7200 }) });
+    const atMax = await h({ m: 'POST', p: FILES, b: UPLOAD({ 'expires_after[anchor]': 'created_at', 'expires_after[seconds]': 2_592_000 }) });
+    return tooShort.status === 422 && tooLong.status === 422 && badAnchor.status === 422 && ok(atMax);
+  })),
+
+  done('deepseek.files.limits', 'files', 'A 64 MiB size cap and a 512-character filename cap are enforced', 'api', 'niche', () => withRoot(async (h) => {
+    const tooBig = await h({ m: 'POST', p: FILES, b: UPLOAD({ bytes: 64 * 1024 * 1024 + 1 }) });
+    const atCap = await h({ m: 'POST', p: FILES, b: UPLOAD({ bytes: 64 * 1024 * 1024 }) });
+    const longName = await h({ m: 'POST', p: FILES, b: UPLOAD({ filename: `${'a'.repeat(510)}.png` }) });
+    return tooBig.status === 422 && ok(atCap) && longName.status === 422;
+  })),
+
+  done('deepseek.files.list_and_retrieve', 'files', 'GET /files lists with after/limit/order, and GET /files/{id} retrieves one', 'api', 'common', () => withRoot(async (h) => {
+    await h({ m: 'POST', p: FILES, b: UPLOAD({ filename: 'one.png' }) });
+    await h({ m: 'POST', p: FILES, b: UPLOAD({ filename: 'two.png' }) });
+    const all = await h({ m: 'GET', p: FILES });
+    if (!ok(all) || (body(all).data as Body[]).length !== 2 || body(all).has_more !== false) return false;
+    const one = await h({ m: 'GET', p: `${FILES}/${FILE_1}` });
+    if (!ok(one) || body(one).filename !== 'one.png') return false;
+    // The documented list envelope carries the cursor bookends, not just `has_more`.
+    if (body(all).first_id !== FILE_1 || body(all).last_id !== FILE_2) return false;
+    const desc = await h({ m: 'GET', p: `${FILES}?order=desc` });
+    if ((body(desc).data as Body[])[0].id !== FILE_2) return false;
+    if (body(desc).first_id !== FILE_2 || body(desc).last_id !== FILE_1) return false;
+    const after = await h({ m: 'GET', p: `${FILES}?after=${FILE_1}` });
+    if ((body(after).data as Body[]).length !== 1 || (body(after).data as Body[])[0].id !== FILE_2) return false;
+    const capped = await h({ m: 'GET', p: `${FILES}?limit=1` });
+    if ((body(capped).data as Body[]).length !== 1 || body(capped).has_more !== true) return false;
+    const missing = await h({ m: 'GET', p: `${FILES}/file-api-nope` });
+    const badLimit = await h({ m: 'GET', p: `${FILES}?limit=1001` });
+    const badOrder = await h({ m: 'GET', p: `${FILES}?order=sideways` });
+    const badPurpose = await h({ m: 'GET', p: `${FILES}?purpose=batch` });
+    return missing.status === 404 && badLimit.status === 422 && badOrder.status === 422 && badPurpose.status === 422;
+  })),
+
+  done('deepseek.files.delete_then_recreate_ratchets_ids', 'files', 'DIRTY STATE: after delete→recreate, the new file gets a FRESH id — a deleted id is never handed out twice', 'api', 'common', () => withRoot(async (h) => {
+    // A fresh-root-only manifest structurally cannot catch this class. Three sibling packs' §9
+    // reviews each found an id-reuse or tombstone bug here, so it is verified deliberately over
+    // prior state rather than from nothing.
+    const first = await h({ m: 'POST', p: FILES, b: UPLOAD({ filename: 'first.png' }) });
+    if (!ok(first) || body(first).id !== FILE_1) return false;
+    const del = await h({ m: 'DELETE', p: `${FILES}/${FILE_1}` });
+    if (!ok(del) || body(del).deleted !== true) return false;
+    const gone = await h({ m: 'GET', p: `${FILES}/${FILE_1}` });
+    const doubleDelete = await h({ m: 'DELETE', p: `${FILES}/${FILE_1}` });
+    if (gone.status !== 404 || doubleDelete.status !== 404) return false;
+    const second = await h({ m: 'POST', p: FILES, b: UPLOAD({ filename: 'second.png' }) });
+    // The counter must RATCHET across the tombstone: reusing FILE_1 would resurrect the deleted
+    // file's identity and silently clobber it.
+    if (!ok(second) || body(second).id !== FILE_2) return false;
+    const list = await h({ m: 'GET', p: FILES });
+    const ids = (body(list).data as Body[]).map((f) => f.id);
+    return ids.length === 1 && ids[0] === FILE_2;
+  })),
+
+  todo('deepseek.files.expiry_removes_the_file', 'files', 'A file past its `expires_at` stops being listed and retrievable — the twin stores the timestamp faithfully but nothing ever expires (§9 round one, SHOULD-FIX 5)', 'api', 'niche'),
+  todo('deepseek.files.storage_quota', 'files', 'The account-level 25 GiB / 10,000-file storage limits', 'api', 'niche'),
+  todo('deepseek.files.reference_in_chat', 'files', 'Passing an uploaded file_id as a chat content part to deepseek-v4-flash-vision-exp', 'api', 'common'),
+  todo('deepseek.files.binary_content', 'files', 'Files: persist the uploaded bytes and serve them back (upload metadata and byte count are recorded today)', 'api', 'niche'),
+
+  // ══ vision ═══════════════════════════════════════════════════════════════════════════════
+  todo('deepseek.vision.image_url_part', 'vision', 'image_url content parts (with the low/high/original/auto detail option) on the vision model', 'api', 'common'),
+  todo('deepseek.vision.file_data_part', 'vision', "The `file` content part carrying inline `file_data`, which @ai-sdk/deepseek's fileData option produces", 'api', 'niche'),
+  todo('deepseek.vision.media_type_closed_set', 'vision', 'Rejecting an image media type outside JPEG/PNG/GIF/WebP, and a URL beyond 8192 characters', 'api', 'niche'),
+  todo('deepseek.vision.non_vision_model_refuses_images', 'vision', 'A non-vision model refuses an image part the way the vendor does', 'api', 'common'),
+
+  // ══ Anthropic-compatible surface ═════════════════════════════════════════════════════════
+  todo('deepseek.anthropic.messages', 'anthropic', 'POST /anthropic/v1/messages — the Anthropic-shaped surface DeepSeek serves alongside the OpenAI-shaped one', 'api', 'common'),
+  todo('deepseek.anthropic.model_mapping', 'anthropic', 'Claude model names mapped to DeepSeek models (Opus→v4-pro, Haiku/Sonnet→v4-flash, unmapped→v4-flash)', 'api', 'niche'),
+  todo('deepseek.anthropic.x_api_key_auth', 'anthropic', 'The Anthropic surface authenticates with x-api-key, not a bearer Authorization header', 'api', 'niche'),
+  todo('deepseek.anthropic.streaming', 'anthropic', "Server-sent events on the Anthropic-compatible surface (Anthropic's own event grammar, not the OpenAI chunk shape)", 'api', 'niche'),
+  todo('deepseek.anthropic.thinking_budget_ignored', 'anthropic', "The Anthropic surface accepts `thinking` but IGNORES budget_tokens — a documented accept-and-ignore, so it must not be an error", 'api', 'niche'),
+  todo('deepseek.anthropic.unsupported_content_types', 'anthropic', 'Refusing the Anthropic content types DeepSeek does not support (document, search result, MCP tools, container uploads)', 'api', 'niche'),
+
+  // ══ errors ═══════════════════════════════════════════════════════════════════════════════
+  done('deepseek.errors.status_split_400_vs_422', 'errors', "DeepSeek's 400 is BODY FORMAT and its 422 is INVALID PARAMETERS — the split OpenAI does not have", 'api', 'core', () => withRoot(async (h) => {
+    // The single most consequential divergence in this pack. An OpenAI-copied twin answers 400 for
+    // both, which passes a status>=400 check and is wrong on every parameter refusal.
+    // 400 is ONLY for a body this API cannot parse as a JSON object: absent, malformed, or the
+    // wrong JSON kind.
+    const absent = await h({ m: 'POST', p: CHAT_PATH, b: undefined });
+    const raw = await handleDeepSeekTwinRequest({ method: 'POST', path: CHAT_PATH, body: '{not json' });
+    const notObject = await handleDeepSeekTwinRequest({ method: 'POST', path: CHAT_PATH, body: '[1,2]' });
+    if (raw.status !== 400 || !String((raw.body as Body).error.message).includes('Invalid request body format')) return false;
+    if (notObject.status !== 400 || absent.status !== 400) return false;
+    // …and EVERY complaint about parsed content is 422, including the ones an OpenAI-shaped twin
+    // would 400: a missing required parameter is the same class as a bad one and must not be
+    // reported two different ways.
+    for (const b of [CHAT({ model: 'nope' }), { messages: [{ role: 'user', content: 'x' }] }, { model: MODEL }, { model: MODEL, messages: [null] }]) {
+      const r = await h({ m: 'POST', p: CHAT_PATH, b });
+      if (r.status !== 422 || !msg(r).includes('invalid parameters')) return false;
+    }
+    return true;
+  })),
+
+  done('deepseek.errors.envelope', 'errors', "Refusals carry DeepSeek's { error: { message, ... } } envelope and no key its decoder does not declare", 'api', 'core', () => withRoot(async (h) => {
+    const r = await h({ m: 'POST', p: CHAT_PATH, b: CHAT({ model: 'nope' }) });
+    const e = body(r).error as Body;
+    // The key set is a LITERAL here, from @ai-sdk/deepseek's `deepSeekErrorSchema` — asserting
+    // against the handler's own constant would be a tautology that could not catch it drifting.
+    const declared = new Set(['message', 'type', 'param', 'code']);
+    if (r.status !== 422 || !e || typeof e.message !== 'string' || !e.message.length) return false;
+    if (!Object.keys(e).every((k) => declared.has(k))) return false;
+    // …and the envelope really is DECODABLE by the vendor's own schema shape on every status the
+    // twin emits, not just this one. §9 round two: a subset check alone cannot fail for anything the
+    // twin currently produces, so it is paired with a sweep that asserts `message` is a non-empty
+    // string and no undeclared key appears anywhere.
+    const others = [
+      await handleDeepSeekTwinRequest({ method: 'GET', path: MODELS, headers: {} }),
+      await h({ m: 'GET', p: '/nope' }),
+      await handleDeepSeekTwinRequest({ method: 'POST', path: CHAT_PATH, body: '{not json' }),
+      await handleDeepSeekTwinRequest({ method: 'POST', path: CHAT_PATH, body: JSON.stringify(CHAT()), readOnly: true }),
+    ];
+    for (const o of others) {
+      const oe = (o.body as Body)?.error as Body;
+      if (o.status < 400 || !oe || typeof oe.message !== 'string' || !oe.message.length) return false;
+      if (!Object.keys(oe).every((k) => declared.has(k))) return false;
+    }
+    return true;
+  })),
+
+  done('deepseek.errors.envelope_omits_an_unsourced_type', 'errors', "A 422 and a 402 carry NO `type` — nothing first-party names one for those statuses, and the string a 422 used to emit resolves to 400 in the SDK's own discriminator table", 'api', 'core', () => withRoot(async (h, root) => {
+    // §9 ROUND ONE, SHOULD-FIX 3, and the pin the fix itself lacked. `@ai-sdk/deepseek`'s
+    // `getDeepSeekStreamErrorMetadata` has NO 422 case at all, and maps `invalid_request_error` to
+    // `statusCode: 400` — so emitting that string on a 422 made a real client resolve the twin's
+    // own refusal to the wrong status. The rule the twin states is: use a type only where something
+    // first-party names one for that status, otherwise omit the field.
+    // SWEEP every 422 the twin can produce, not one sample. §9 ROUND TWO, BLOCKER 2: the fix was
+    // applied to the `invalidParameters` helper only, so the FIM streaming refusal — a 422 built
+    // inline 700 lines away — kept emitting `invalid_request_error`, and this cell passed because it
+    // happened to probe a different one. A universal claim needs a universal check.
+    const fourTwentyTwos: Array<{ m: string; p: string; b?: unknown }> = [
+      { m: 'POST', p: CHAT_PATH, b: CHAT({ model: 'nope' }) },
+      { m: 'POST', p: CHAT_PATH, b: CHAT({ n: 2 }) },
+      { m: 'POST', p: CHAT_PATH, b: CHAT({ response_format: { type: 'json_schema' } }) },
+      { m: 'POST', p: FIM_PATH, b: { model: PRO, prompt: 'x', stream: true } },
+      { m: 'POST', p: FIM_PATH, b: { model: MODEL, prompt: 'x' } },
+      { m: 'POST', p: FILES, b: UPLOAD({ purpose: 'batch' }) },
+      { m: 'GET', p: `${FILES}?limit=5000` },
+    ];
+    for (const req of fourTwentyTwos) {
+      const r = await h(req);
+      if (r.status !== 422 || 'type' in (body(r).error as Body)) return false;
+    }
+    // The 405 is the OTHER status nothing first-party names a type for, and it is built in a third
+    // place again — the revert matrix showed `errors.envelope` cannot catch it (a `type` is a
+    // DECLARED key, so a subset check passes), so the universal has to sweep it here.
+    const ro = await handleDeepSeekTwinRequest({ method: 'POST', path: CHAT_PATH, body: JSON.stringify(CHAT()), readOnly: true });
+    if (ro.status !== 405 || 'type' in (body(ro).error as Body)) return false;
+    // 402 likewise carries none — and this DRIVES that path rather than asserting it in a comment.
+    await applyTwinWrite('deepseek', {
+      operation: 'balance.update', subjectType: 'balance', subjectId: 'account',
+      fields: { is_available: false, balance_infos: [] }, occurredAt: OCCURRED_AT, actor: { kind: 'agent' },
+    }, root);
+    const drained = await h({ m: 'POST', p: CHAT_PATH, b: CHAT() });
+    if (drained.status !== 402 || 'type' in (body(drained).error as Body)) return false;
+    // …but the statuses the SDK's table DOES name keep their discriminator, or the rule would just
+    // be "never emit a type", which is a different (and equally unsourced) claim.
+    const unauth = await handleDeepSeekTwinRequest({ method: 'GET', path: MODELS, headers: {} });
+    const notFound = await h({ m: 'GET', p: '/nope' });
+    return unauth.status === 401 && (body(unauth).error as Body).type === 'authentication_error'
+      && refused(notFound) && (body(notFound).error as Body).type === 'not_found_error';
+  })),
+
+  done('deepseek.errors.unmodeled_ops_fail', 'errors', 'Unmodeled operations and OpenAI-only endpoints fail rather than fake a success', 'api', 'core', () => withRoot(async (h) => {
+    for (const [m, p] of [
+      ['POST', '/embeddings'], ['POST', '/images/generations'], ['POST', '/audio/transcriptions'],
+      ['POST', '/moderations'], ['POST', '/batches'], ['GET', '/models/deepseek-v4-flash'],
+      ['POST', '/fine_tuning/jobs'],
+    ]) {
+      const r = await h({ m: m!, p: p!, b: {} });
+      // Refused as a CLIENT error with the vendor envelope; the exact code is the twin's unverified
+      // choice (see deepseek.errors.unknown_route_envelope), so it is not asserted (NIT 11).
+      if (!refused(r)) return false;
+    }
+    // REAL vendor surface this twin does not model yet must fail too — and must not be confused
+    // with the OpenAI-only endpoints above. The Anthropic surface says so by name; `/responses` is
+    // a first-class entry in DeepSeek's own reference nav and falls through to the router's
+    // not-found rather than being answered as if it were /chat/completions.
+    const anthropic = await h({ m: 'POST', p: '/anthropic/v1/messages', b: {} });
+    if (!refused(anthropic) || !msg(anthropic).includes('Anthropic-compatible')) return false;
+    const responses = await h({ m: 'POST', p: '/responses', b: { model: MODEL, input: 'hi' } });
+    const betaResponses = await h({ m: 'POST', p: '/beta/responses', b: { model: MODEL, input: 'hi' } });
+    return refused(responses) && refused(betaResponses);
+  })),
+
+  done('deepseek.errors.read_only_405', 'errors', 'A read-only twin refuses every write with 405 while reads keep working', 'api', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'deepseek-cap-'));
+    try {
+      return await verifyBoundary('deepseek.errors.read_only_405', async () => {
+        const chat = await handleDeepSeekTwinRequest({ method: 'POST', path: CHAT_PATH, body: JSON.stringify(CHAT()), root, readOnly: true });
+        const upload = await handleDeepSeekTwinRequest({ method: 'POST', path: FILES, body: JSON.stringify(UPLOAD()), root, readOnly: true });
+        const models = await handleDeepSeekTwinRequest({ method: 'GET', path: MODELS, root, readOnly: true });
+        // And nothing was written: the projection must still be empty.
+        const wrote = projectResources('deepseek', root).length > 0;
+        return chat.status === 405 && upload.status === 405 && ok(models) && !wrote;
+      });
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+
+  todo('deepseek.errors.rate_limit_429', 'errors', "Answering DeepSeek's documented 429 under a real rate condition. The twin serves the faithful envelope, but only behind a twin-only `x-twin-force-rate-limit` header — scaffolding, which §6 keeps OUT of the coverage claim, so this is a todo rather than a done proven by its own trigger (§9 round one)", 'api', 'common'),
+
+  // (Scripted 500/503 failures used to be claimed here as a `done`. They are SCENARIO scaffolding,
+  // which ADDING_A_TWIN.md §6 says to keep out of the capability manifest because counting it pads
+  // the denominator — the behaviour is gated by deepseek-scenario.test.ts instead. §9 round one.)
+  todo('deepseek.errors.server_5xx', 'errors', "Answering DeepSeek's documented 500 'Our server encounters an issue' and 503 'The server is overloaded' under real conditions rather than only when a scenario handler scripts them", 'api', 'niche'),
+
+  todo('deepseek.errors.unknown_route_envelope', 'errors', "The exact status/body a real DeepSeek gateway returns for an unrouted path — its published error table (400/401/402/422/429/500/503) has no 404 entry, so the twin's 404 shape is unverified against a first-party source", 'api', 'niche'),
+  todo('deepseek.errors.retryable_metadata', 'errors', 'Error `code`/`type` discriminators the SDK maps to retryability (insufficient_quota, overloaded_error, timeout, …)', 'api', 'niche'),
+
+  // ══ auth ═════════════════════════════════════════════════════════════════════════════════
+  done('deepseek.auth.bearer_required', 'auth', 'A request carrying an auth surface needs a bearer credential; a missing or sentinel-invalid one is 401', 'api', 'core', () => withRootH(async (h) => {
+    const missing = await h({ m: 'GET', p: MODELS, headers: {} });
+    const invalid = await h({ m: 'GET', p: MODELS, headers: { authorization: 'Bearer sk_invalid' } });
+    const notBearer = await h({ m: 'GET', p: MODELS, headers: { authorization: 'Basic abc' } });
+    const good = await h({ m: 'GET', p: MODELS, headers: { authorization: 'Bearer sk-anything' } });
+    return missing.status === 401 && invalid.status === 401 && notBearer.status === 401 && ok(good)
+      && msg(missing).includes('Authentication fails');
+  })),
+
+  todo('deepseek.auth.gates_before_routing', 'auth', 'Whether DeepSeek authenticates BEFORE routing (401 rather than 404 on an unknown path with no credential). The twin does, but nothing first-party documents the ordering, so it is a twin design choice and not a proven vendor fact (§9 round one, NIT 12)', 'api', 'common'),
+
+  todo('deepseek.auth.x_api_key', 'auth', 'x-api-key authentication on the Anthropic-compatible surface', 'api', 'niche'),
+
+  // ══ rate limits / budget ═════════════════════════════════════════════════════════════════
+  done('deepseek.rate_limits.budget_refuses_past_ceiling', 'rate_limits', 'The client-side budget THROWS instead of calling past its ceiling, with the vendor call count unchanged', 'connector', 'core', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'deepseek-cap-'));
+    try {
+      return await verifyBoundary('deepseek.rate_limits.budget_refuses_past_ceiling', async () => {
+        const { DeepSeekBudget } = await import('./deepseek-budget.ts');
+        let calls = 0;
+        const fetchImpl = (async () => { calls++; return new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } }); }) as unknown as typeof fetch;
+        const ledger = new DeepSeekBudget({ path: join(root, 'ledger.json') });
+        const execute = liveDeepSeekExecute('sk-twin', 'http://127.0.0.1:1', { fetchImpl, budget: ledger });
+        // /models costs the default weight 2 against a ceiling of 60 → exactly 30 fit.
+        for (let i = 0; i < 30; i++) await execute('GET', '/models');
+        if (calls !== 30) return false;
+        let threw = false;
+        try { await execute('GET', '/models'); } catch { threw = true; }
+        // "It threw" is not the proof — the unchanged COUNT is what shows nothing reached DeepSeek.
+        return threw && calls === 30;
+      });
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+
+  done('deepseek.rate_limits.inference_costs_more', 'rate_limits', 'Token-billed inference endpoints are priced above the default weight, including under the /beta prefix', 'connector', 'common', async () => {
+    const { deepseekCallWeight } = await import('./deepseek-budget.ts');
+    // The weights are asserted as LITERALS: importing the weight table and comparing it with itself
+    // would drift together and could never catch an inference call being priced as a read.
+    return deepseekCallWeight('POST', '/chat/completions') === 6
+      && deepseekCallWeight('POST', '/beta/chat/completions') === 6
+      && deepseekCallWeight('POST', '/beta/completions') === 6
+      && deepseekCallWeight('GET', '/models') === 2
+      && deepseekCallWeight('GET', '/user/balance') === 2
+      // …and the anchored rules survive the two evasions that would otherwise price a write as a read.
+      && deepseekCallWeight('post', '/chat/completions') === 6
+      && deepseekCallWeight('POST', '//chat/completions') === 6
+      && deepseekCallWeight('POST', '/chat/completions/') === 6;
+  }),
+
+  done('deepseek.rate_limits.ledger_survives_restart', 'rate_limits', 'The spend ledger is persistent: a fresh executor over the same ledger gets no fresh allowance', 'connector', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'deepseek-cap-'));
+    try {
+      return await verifyBoundary('deepseek.rate_limits.ledger_survives_restart', async () => {
+        const path = join(root, 'ledger.json');
+        let calls = 0;
+        const fetchImpl = (async () => { calls++; return new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } }); }) as unknown as typeof fetch;
+        const first = liveDeepSeekExecute('sk-twin', 'http://127.0.0.1:1', { budgetOptions: { path }, fetchImpl });
+        for (let i = 0; i < 30; i++) await first('GET', '/models');
+        // A brand-new budget object over the SAME ledger file — the "restarted process" case.
+        const second = liveDeepSeekExecute('sk-twin', 'http://127.0.0.1:1', { budgetOptions: { path }, fetchImpl });
+        let threw = false;
+        try { await second('GET', '/models'); } catch { threw = true; }
+        return threw && calls === 30;
+      });
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+
+  done('deepseek.rate_limits.executor_path_allowlist', 'rate_limits', 'The live executor refuses an unmodeled path BEFORE spending budget or touching the network', 'connector', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'deepseek-cap-'));
+    try {
+      return await verifyBoundary('deepseek.rate_limits.executor_path_allowlist', async () => {
+        const { DeepSeekBudget } = await import('./deepseek-budget.ts');
+        const counter = { n: 0 };
+        const fetchImpl = (async () => { counter.n++; return new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } }); }) as unknown as typeof fetch;
+        const ledger = new DeepSeekBudget({ path: join(root, 'ledger.json') });
+        const execute = liveDeepSeekExecute('sk-twin', 'http://127.0.0.1:1', { fetchImpl, budget: ledger });
+        // The OpenAI-shaped path is the one a careless caller reaches for, and it would evade both
+        // the budget's anchored rules and DeepSeek's own routing.
+        for (const p of ['/v1/models', '/chat/completions', '/anthropic/v1/messages', '/../etc']) {
+          let threw = false;
+          try { await execute('GET', p); } catch { threw = true; }
+          if (!threw) return false;
+        }
+        if (counter.n !== 0) return false;
+        // The budget must be UNSPENT: the refusal happens BEFORE `checkBudget`, so a modeled call
+        // still has the full allowance afterwards.
+        if (ledger.snapshot().spend !== 0) return false;
+        await execute('GET', '/models');
+        return counter.n > 0;
+      });
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  }),
+
+
+  // ══ usage accounting ═════════════════════════════════════════════════════════════════════
+  done('deepseek.usage.token_counts', 'usage', 'usage reports deterministic prompt/completion/total counts that respond to the actual payload', 'api', 'core', () => withRoot(async (h) => {
+    const short = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [{ role: 'user', content: 'hi' }] } });
+    const long = await h({ m: 'POST', p: CHAT_PATH, b: { model: MODEL, messages: [{ role: 'user', content: 'hi '.repeat(200) }] } });
+    if (!ok(short) || !ok(long)) return false;
+    const su = body(short).usage as Body;
+    const lu = body(long).usage as Body;
+    return su.prompt_tokens > 0 && lu.prompt_tokens > su.prompt_tokens
+      && su.total_tokens === su.prompt_tokens + su.completion_tokens
+      && lu.total_tokens === lu.prompt_tokens + lu.completion_tokens;
+  })),
+
+  done('deepseek.usage.serve_path_determinism', 'usage', 'The same request against two independent roots yields a byte-identical response', 'api', 'core', async () => {
+    const a = mkdtempSync(join(tmpdir(), 'deepseek-det-a-'));
+    const b = mkdtempSync(join(tmpdir(), 'deepseek-det-b-'));
+    try {
+      return await verifyBoundary('deepseek.usage.serve_path_determinism', async () => {
+        // Both roots are driven through the IDENTICAL history from here on, which is what makes the
+        // later comparison a (request, state) equality rather than a coincidence (§9 round two, NIT 1
+        // — the comment used to claim this while root `a` had received extra calls root `b` had not).
+        const run = (root: string) => handleDeepSeekTwinRequest({ method: 'POST', path: CHAT_PATH, body: JSON.stringify(CHAT({ logprobs: true, top_logprobs: 2 })), root, occurredAt: OCCURRED_AT });
+        const [ra, rb] = await Promise.all([run(a), run(b)]);
+        // MUTATION-GATE FINDING: byte-equality alone is satisfied by a dead twin answering {} on
+        // both roots. Determinism is only a claim about a REAL response, so every derived value the
+        // cell is about — the id, the fingerprint, the cache split, the logprob numbers — is
+        // asserted to EXIST and be well-formed before the two are compared.
+        const bodyA = ra.body as Body;
+        if (!ok(ra) || bodyA.object !== 'chat.completion') return false;
+        if (typeof bodyA.id !== 'string' || !bodyA.id.startsWith('chatcmpl-twin-')) return false;
+        if (typeof bodyA.system_fingerprint !== 'string' || !bodyA.system_fingerprint.endsWith('_twin_stub_kvcache')) return false;
+        if (typeof (bodyA.usage as Body).prompt_cache_miss_tokens !== 'number') return false;
+        if (!Array.isArray((choice0(ra).logprobs as Body)?.content) || (choice0(ra).logprobs as Body).content.length === 0) return false;
+        if (typeof (choice0(ra).logprobs as Body).content[0].logprob !== 'number') return false;
+        // Every derived value must be a pure function of (request, stored state). A wall clock or an
+        // entropy source anywhere on the serve path breaks this.
+        if (JSON.stringify(ra.body) !== JSON.stringify(rb.body)) return false;
+        // …and a REPLAY into the same root is identical too, once the cache ledger already holds
+        // this request's own prefix (proving the ledger read is deterministic, not accumulating).
+        // A replay into each root, kept in lockstep so the two histories stay identical.
+        const againA = await run(a);
+        const againB = await run(b);
+        if ((againA.body as Body).object !== 'chat.completion') return false;
+        if (JSON.stringify(againA.body) !== JSON.stringify(againB.body)) return false;
+        // The single-turn request above never HITS the cache, so it cannot prove the ledger read is
+        // deterministic on the path that matters. This does: a continuation that genuinely hits,
+        // replayed against a root whose ledger has since grown, must answer byte-identically — a
+        // ledger read that accumulated (or a hit measured off stored state rather than the request)
+        // would drift on the second call.
+        // The cache-bearing path, which the single-turn half above never reaches (a one-message
+        // request reads the ledger but cannot match anything until it has been served once).
+        //
+        // The comparison is across two roots driven through the SAME history, NOT two calls into
+        // one root: serving a request CHANGES the ledger, so a second call into the same root is a
+        // different (request, state) pair and is legitimately allowed to answer differently. The
+        // determinism claim is "same request + same stored state → same bytes", and this is what
+        // that actually looks like.
+        const opening = { model: MODEL, messages: [{ role: 'user', content: 'a determinism opening turn' }] };
+        const post = (root: string, payload: unknown) => handleDeepSeekTwinRequest({ method: 'POST', path: CHAT_PATH, body: JSON.stringify(payload), root, occurredAt: OCCURRED_AT });
+        const seededA = await post(a, opening);
+        const seededB = await post(b, opening);
+        if (!ok(seededA) || !ok(seededB)) return false;
+        const convo = {
+          model: MODEL,
+          messages: [
+            { role: 'user', content: 'a determinism opening turn' },
+            { role: 'assistant', content: text0(seededA), reasoning_content: '' },
+            { role: 'user', content: 'and a follow-up' },
+          ],
+        };
+        const hitA = await post(a, convo);
+        const hitB = await post(b, convo);
+        // It really HIT — otherwise this cell would be proving determinism on the same cache-free
+        // path the single-turn half already covered.
+        if (!ok(hitA) || (body(hitA).usage as Body).prompt_cache_hit_tokens === 0) return false;
+        return JSON.stringify(hitA.body) === JSON.stringify(hitB.body);
+      });
+    } finally { rmSync(a, { recursive: true, force: true }); rmSync(b, { recursive: true, force: true }); }
+  }),
+
+  todo('deepseek.usage.real_tokenizer', 'usage', "Token counts from DeepSeek's real tokenizer: a BPE tokenizer is a data file, runs offline and is deterministic, so nothing about the serve-path invariant forbids it (§9 round one, SHOULD-FIX 5). The twin's counts are a ~4-chars-per-token estimate — the right order of magnitude and stable for a fixed input, but not DeepSeek's vocabulary, and no capability asserts an exact vendor count", 'api', 'common'),
+
+  // ══ connector ════════════════════════════════════════════════════════════════════════════
+  done('deepseek.connector.pull_models', 'connector', 'Pull maps real model rows into the twin projection', 'connector', 'core', () => withConnectorRoot('deepseek.connector.pull_models', async (root) => {
+    const calls: Array<{ method: string; path: string }> = [];
+    const execute = fakeExecute({ models: [{ id: 'deepseek-v4-pro', object: 'model', owned_by: 'deepseek' }] }, calls);
+    const res = await syncDeepSeekFromReal(execute, { root, occurredAt: OCCURRED_AT });
+    const row = projectResources('deepseek', root).find((r) => r.type === 'model' && r.id === 'deepseek-v4-pro');
+    return res.observed > 0 && !!row && row.owned_by === 'deepseek'
+      // …and the paths it actually addressed are DeepSeek's, not OpenAI-shaped ones.
+      && calls.some((c) => c.method === 'GET' && c.path === '/models');
+  })),
+
+  done('deepseek.connector.pull_files_and_balance', 'connector', 'Pull maps real files and the singleton user balance into the projection', 'connector', 'core', () => withConnectorRoot('deepseek.connector.pull_files_and_balance', async (root) => {
+    const execute = fakeExecute({
+      files: [{ id: 'file-api-a1b2c3d4e5f6g7h8', object: 'file', bytes: 1024, created_at: 1_700_000_000, filename: 'real.png', purpose: 'user_data', expires_at: 1_700_003_600 }],
+      balance: { is_available: false, balance_infos: [{ currency: 'USD', total_balance: '0.00', granted_balance: '0.00', topped_up_balance: '0.00' }] },
+    });
+    await syncDeepSeekFromReal(execute, { root, occurredAt: OCCURRED_AT });
+    const file = projectResources('deepseek', root).find((r) => r.type === 'file' && r.id === 'file-api-a1b2c3d4e5f6g7h8');
+    const bal = projectResources('deepseek', root).find((r) => r.type === 'balance' && r.id === 'account');
+    if (!file || file.filename !== 'real.png' || file.bytes !== 1024 || file.expires_at !== 1_700_003_600) return false;
+    if (!bal || bal.is_available !== false) return false;
+    // The pull is LOAD-BEARING, not decorative: a pulled drained balance makes the twin refuse
+    // completions exactly as the real account would.
+    const chat = await handleDeepSeekTwinRequest({ method: 'POST', path: CHAT_PATH, body: JSON.stringify(CHAT()), root });
+    const served = await handleDeepSeekTwinRequest({ method: 'GET', path: `${FILES}/file-api-a1b2c3d4e5f6g7h8`, root });
+    return chat.status === 402 && ok(served) && body(served).filename === 'real.png';
+  })),
+
+  done('deepseek.connector.pull_is_idempotent', 'connector', 'Re-pulling identical state appends no deltas', 'connector', 'core', () => withConnectorRoot('deepseek.connector.pull_is_idempotent', async (root) => {
+    const execute = fakeExecute({ files: [{ id: 'file-api-aaaa', object: 'file', bytes: 1, created_at: 1, filename: 'a.png', purpose: 'user_data' }] });
+    const first = await syncDeepSeekFromReal(execute, { root, occurredAt: '2026-08-31T12:00:00.000Z' });
+    // A MOVING timestamp on the second poll, deliberately: the kernel hashes an observed event over
+    // (occurredAt + post-state), so a pinned poll time would make this pass for the wrong reason.
+    const second = await syncDeepSeekFromReal(execute, { root, occurredAt: '2026-08-31T12:05:00.000Z' });
+    const rows = projectResources('deepseek', root).filter((r) => r.type === 'file');
+    return first.deltasAppended > 0 && second.deltasAppended === 0 && rows.length === 1;
+  })),
+
+  done('deepseek.connector.pull_refuses_an_error_envelope', 'connector', 'A refused pull THROWS rather than folding an empty account over real observed state', 'connector', 'core', () => withConnectorRoot('deepseek.connector.pull_refuses_an_error_envelope', async (root) => {
+    const good = fakeExecute({ files: [{ id: 'file-api-keepme', object: 'file', bytes: 1, created_at: 1, filename: 'keep.png', purpose: 'user_data' }] });
+    await syncDeepSeekFromReal(good, { root, occurredAt: OCCURRED_AT });
+    const failing = fakeExecute({ files: [], fail: '/files' });
+    let threw = false;
+    // `pullDeepSeekState` is a PURE mapper over the injected executor — it takes no root and writes
+    // nothing, which is precisely why the refusal must happen here rather than in `syncPull`. The
+    // root-scoped half is the survival check below (§9 round two, NIT 7).
+    try { await pullDeepSeekState(failing); } catch { threw = true; }
+    if (!threw) return false;
+    // …and the same refusal through the ROOT-SCOPED entry point, so nothing was folded either.
+    let syncThrew = false;
+    try { await syncDeepSeekFromReal(failing, { root, occurredAt: '2026-08-31T12:20:00.000Z' }); } catch { syncThrew = true; }
+    if (!syncThrew) return false;
+    // The previously observed file must SURVIVE — the whole point of throwing.
+    const still = await handleDeepSeekTwinRequest({ method: 'GET', path: `${FILES}/file-api-keepme`, root });
+    return ok(still) && body(still).filename === 'keep.png';
+  })),
+
+  done('deepseek.connector.push_file_delete', 'connector', 'A local delete of a PULLED file is pushed to the real account and confirmed', 'connector', 'core', () => withConnectorRoot('deepseek.connector.push_file_delete', async (root) => {
+    const calls: Array<{ method: string; path: string }> = [];
+    const execute = fakeExecute({ files: [{ id: 'file-api-realone', object: 'file', bytes: 1, created_at: 1, filename: 'real.png', purpose: 'user_data' }] }, calls);
+    await syncDeepSeekFromReal(execute, { root, occurredAt: OCCURRED_AT });
+    const del = await handleDeepSeekTwinRequest({ method: 'DELETE', path: `${FILES}/file-api-realone`, root, occurredAt: OCCURRED_AT });
+    if (!ok(del)) return false;
+    if (pendingActions('deepseek', root).filter((a) => a.subject.type === 'file').length !== 1) return false;
+    const res = await pushPendingDeepSeekActions(execute, { root, occurredAt: '2026-08-31T12:10:00.000Z' });
+    return res.pushed === 1
+      && calls.some((c) => c.method === 'DELETE' && c.path === '/files/file-api-realone')
+      && pendingActions('deepseek', root).filter((a) => a.subject.type === 'file').length === 0;
+  })),
+
+  done('deepseek.connector.refuses_the_twins_own_id', 'connector', "A locally-minted file's delete is REFUSED, never issued against the real account under the twin's own id", 'connector', 'core', () => withConnectorRoot('deepseek.connector.refuses_the_twins_own_id', async (root) => {
+    const calls: Array<{ method: string; path: string }> = [];
+    const execute = fakeExecute({}, calls);
+    await handleDeepSeekTwinRequest({ method: 'POST', path: FILES, body: JSON.stringify(UPLOAD()), root, occurredAt: OCCURRED_AT });
+    await handleDeepSeekTwinRequest({ method: 'DELETE', path: `${FILES}/${FILE_1}`, root, occurredAt: OCCURRED_AT });
+    const res = await pushPendingDeepSeekActions(execute, { root, occurredAt: '2026-08-31T12:10:00.000Z' });
+    // Both actions must be refused — the create because the vendor endpoint is multipart, the
+    // delete because no vendor id was ever recorded — and NOTHING may have gone out.
+    if (res.pushed !== 0 || res.refused.length !== 2) return false;
+    if (calls.length !== 0) return false;
+    if (!res.refused.some((r) => r.operation === 'file.create' && r.reason.includes('multipart'))) return false;
+    if (!res.refused.some((r) => r.operation === 'file.delete' && r.reason.includes('no vendor id recorded'))) return false;
+    // And the path builder refuses the twin's mint outright, not merely by convention.
+    if (externalIdFor('file', FILE_1, root) !== null) return false;
+    let threw = false;
+    try { deepseekRequestForAction({ operation: 'file.delete', subject: { type: 'file', id: FILE_1 } } as never); } catch { threw = true; }
+    return threw;
+  })),
+
+  done('deepseek.connector.skips_the_internal_cache_ledger', 'connector', 'The twin-only context-cache ledger is skipped BY NAME rather than pushed or silently dropped', 'connector', 'common', () => withConnectorRoot('deepseek.connector.skips_the_internal_cache_ledger', async (root) => {
+    const calls: Array<{ method: string; path: string }> = [];
+    const execute = fakeExecute({}, calls);
+    await handleDeepSeekTwinRequest({ method: 'POST', path: CHAT_PATH, body: JSON.stringify(CHAT()), root, occurredAt: OCCURRED_AT });
+    const pendingCache = pendingActions('deepseek', root).filter((a) => a.subject.type === 'cache_prefix');
+    if (pendingCache.length === 0) return false; // the completion really did mint ledger actions
+    const res = await pushPendingDeepSeekActions(execute, { root, occurredAt: '2026-08-31T12:10:00.000Z' });
+    // Reported, not refused (they are not a gap) and not pushed (DeepSeek has no cache endpoint).
+    return res.skippedInternal.length === pendingCache.length && res.refused.length === 0 && calls.length === 0
+      && unpushableReason('cache_prefix.observe') !== null;
+  })),
+
+  done('deepseek.connector.pull_after_local_create', 'connector', 'ID COLLISION, both directions: a pulled vendor id and a locally-minted one never collide', 'connector', 'common', () => withConnectorRoot('deepseek.connector.pull_after_local_create', async (root) => {
+    // Direction 1 — local create, THEN pull: the pulled row must not overwrite the local one.
+    await handleDeepSeekTwinRequest({ method: 'POST', path: FILES, body: JSON.stringify(UPLOAD({ filename: 'local.png' })), root, occurredAt: OCCURRED_AT });
+    const execute = fakeExecute({ files: [{ id: 'file-api-vendor01', object: 'file', bytes: 9, created_at: 2, filename: 'vendor.png', purpose: 'user_data' }] });
+    await syncDeepSeekFromReal(execute, { root, occurredAt: OCCURRED_AT });
+    const local = await handleDeepSeekTwinRequest({ method: 'GET', path: `${FILES}/${FILE_1}`, root });
+    const vendor = await handleDeepSeekTwinRequest({ method: 'GET', path: '/files/file-api-vendor01', root });
+    if (!ok(local) || body(local).filename !== 'local.png' || !ok(vendor)) return false;
+    // Direction 2 — create AFTER the pull: the new mint must not land on the pulled id, and the
+    // local namespace must ratchet from the local set only.
+    const next = await handleDeepSeekTwinRequest({ method: 'POST', path: FILES, body: JSON.stringify(UPLOAD({ filename: 'after.png' })), root, occurredAt: OCCURRED_AT });
+    return ok(next) && body(next).id === FILE_2 && body(next).id !== 'file-api-vendor01';
+  })),
+
+  done('deepseek.connector.full_sync', 'connector', 'fullSync pushes pending writes then pulls every modeled collection and the balance singleton', 'connector', 'common', () => withConnectorRoot('deepseek.connector.full_sync', async (root) => {
+    const calls: Array<{ method: string; path: string }> = [];
+    const execute = fakeExecute({
+      models: [{ id: 'deepseek-v4-flash', object: 'model', owned_by: 'deepseek' }],
+      files: [{ id: 'file-api-sync01', object: 'file', bytes: 3, created_at: 5, filename: 's.png', purpose: 'user_data' }],
+      balance: { is_available: true, balance_infos: [{ currency: 'USD', total_balance: '5.00', granted_balance: '0.00', topped_up_balance: '5.00' }] },
+    }, calls);
+    const res = await fullSyncDeepSeek(execute, { root, occurredAt: OCCURRED_AT });
+    const paths = calls.map((c) => `${c.method} ${c.path}`);
+    return res.collections === 3 && res.observed === 3 && res.deltasAppended > 0
+      && paths.includes('GET /models') && paths.includes('GET /files') && paths.includes('GET /user/balance');
+  })),
+
+  todo('deepseek.connector.push_file_create', 'connector', "Pushing a local file create — real DeepSeek's POST /files is multipart/form-data with the image bytes, which the JSON executor cannot express and the twin has no real bytes for", 'connector', 'common'),
+  todo('deepseek.connector.pull_pagination', 'connector', 'Following the Files API `after` cursor across more than one page during a pull', 'connector', 'niche'),
+  todo('deepseek.connector.unpushable_actions_drain', 'connector', 'Acknowledging a permanently-unpushable action so `pendingActions` can reach empty again', 'connector', 'niche'),
+
+  // ══ conformance ══════════════════════════════════════════════════════════════════════════
+  done('deepseek.conformance.probes', 'conformance', 'Offline conformance harness passes: probes, the router census, the must-not-serve list and the rejection table', 'api', 'core', async () => {
+    const { checkDeepSeekConformance } = await import('./deepseek-conformance.ts');
+    const report = await checkDeepSeekConformance();
+    return report.ok && report.probes >= 11 && report.checksRun >= 60;
+  }),
+];
+
+// TWIN-87 committed area census — DeepSeek's top-level API product areas, authored top-down from
+// the api-docs.deepseek.com nav (Quick Start, API Reference, and each Guide) independently of what a
+// manifest entry happens to already exist for. deepseek-capabilities.test.ts's area-census meta-test
+// (assertAreaCensus) fails the gate if a declared area has zero manifest entries, OR if a manifest
+// entry's `area` drifts outside this list — so a whole missing area can never hide invisibly.
+export const DEEPSEEK_AREAS = [
+  'anthropic', 'auth', 'balance', 'beta', 'cache', 'chat', 'completions', 'conformance',
+  'connector', 'errors', 'files', 'models', 'rate_limits', 'reasoning', 'responses',
+  'streaming', 'structured_outputs', 'tools', 'usage', 'vision',
+] as const;
+
+export function deepseekCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('deepseek', DEEPSEEK_CAPABILITIES);
+}