@volter/twin-deepseek 0.1.0

package/dist/src/deepseek-twin.js

@@ -0,0 +1,1103 @@
+// DeepSeek twin REQUEST HANDLER — the canonical DeepSeek Platform API surface for the twin.
+// Contract: handleDeepSeekTwinRequest({method, path, body}) -> {status, body}. It is the faithful
+// DeepSeek API the real `@ai-sdk/deepseek` (pointed at this baseURL) talks to UNMODIFIED.
+//
+// THE HONEST DESIGN: the twin cannot run the model, so `POST /chat/completions` and
+// `POST /beta/completions` return DETERMINISTIC STUB output (deepseek-stub.ts) clearly labeled a
+// twin stub — never pretending to be real inference. But the ENTIRE PROTOCOL ENVELOPE is
+// vendor-faithful: response shapes, SSE chunk sequence, tool_calls, `reasoning_content`,
+// finish_reason, and DeepSeek's KV-cache-bearing `usage`. The genuinely stateful surface is real:
+//   • GET /models                       — the published catalog (+ anything a pull observed)
+//   • GET /user/balance                 — kernel state; drives the real 402 path
+//   • POST/GET/DELETE /files            — stateful (kernel action log)
+//   • the context-cache prefix ledger   — stateful (deepseek-cache.ts), which is what makes
+//     `prompt_cache_hit_tokens` a measured fact rather than a fabricated number
+//
+// ═══ DEEPSEEK IS OPENAI-COMPATIBLE, WHICH IS EXACTLY WHY THE REJECTIONS ARE THE SURFACE ═══
+// ADDING_A_TWIN.md §0 names this hazard by name: copying an OpenAI-shaped exemplar's PERMISSIVE
+// validation is the bug, because what distinguishes the real vendor is what it REFUSES. Every
+// refusal below is grounded in a first-party source, cited inline. The headline divergences:
+//
+//   • THERE IS NO `/v1` PREFIX. `base_url` is `https://api.deepseek.com` and the path is
+//     `/chat/completions` (api-docs.deepseek.com, "Your First API Call", read 2026-08-31). A twin
+//     that answered on `/v1/chat/completions` would be serving a route the vendor does not.
+//   • DEEPSEEK'S DOCUMENTED ERROR TABLE IS {400, 401, 402, 422, 429, 500, 503} — no 404, and it
+//     includes two OpenAI does not use: 402 Insufficient Balance and 422 Invalid Parameters
+//     (api-docs.deepseek.com/quick_start/error_codes). OpenAI 400s a bad parameter; DeepSeek 422s
+//     it. 400 is reserved for "Invalid request body format".
+//   • `n`, `seed`, `logit_bias`, `top_k`, `user`, `max_completion_tokens`, `service_tier`,
+//     `parallel_tool_calls`, `functions` are NOT DeepSeek parameters. The accepted set is a closed
+//     documented table (api-docs.deepseek.com/api/create-chat-completion), which §6 licenses as a
+//     literal-allowlist oracle — so anything outside CHAT_PARAMS is 422 by name.
+//   • `response_format` accepts `text` and `json_object` ONLY. `json_schema` is an OpenAI feature;
+//     `@ai-sdk/deepseek` confirms it by INJECTING the schema into a system message instead of
+//     sending `response_format.json_schema` (src/chat/convert-to-deepseek-chat-messages.ts).
+//   • `user_id`, not `user` — with a regex and a 512-character cap the SDK enforces client-side and
+//     the vendor documents server-side.
+//   • Assistant-prefix completion and strict tool calls exist ONLY under the `/beta` base URL.
+//   • `frequency_penalty` / `presence_penalty` are DEPRECATED but MUST NOT ERROR, and
+//     `temperature` / `top_p` are IGNORED (not rejected) while thinking is enabled: "setting these
+//     parameters will not trigger an error but will also have no effect"
+//     (api-docs.deepseek.com/guides/thinking_mode). Rejecting them would be the mirror-image
+//     infidelity of the permissiveness this file exists to avoid.
+//   • With `tools` in the request, previous assistant turns MUST carry `reasoning_content` back or
+//     "the API will return a 400 error" (same page).
+//
+// State lives in the kernel action log (D1): all writes are local actions, reads are the
+// projection. No real DeepSeek is ever called from this path (D4). Streaming uses an INJECTED sink
+// — no real sockets / setTimeout (D5 verify is offline + deterministic).
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { cacheHitTokens, recordCachePrefixes } from "./deepseek-cache.js";
+import { DEEPSEEK_MODELS, FIM_MODELS, RETIRED_MODEL_IDS, findModel, isThinkingModel } from "./deepseek-models.js";
+import { buildUsage, countPromptTokens, estimateTokens, fnv1a, stubAssistantText, stubFimText, stubFingerprint, stubJsonObject, stubReasoningText, stubToolCall, } from "./deepseek-stub.js";
+import { realizeDeepSeekRespond } from "./deepseek-scenario.js";
+const SERVICE = 'deepseek';
+/** DeepSeek's beta base URL suffix. `@ai-sdk/deepseek` turns prefix-completion and strict tool
+ *  calls on iff `baseURL.endsWith('/beta')` (src/deepseek-provider.ts), so the twin gates the same
+ *  two features on the same path segment. */
+export const DEEPSEEK_BETA_PREFIX = '/beta';
+/** DeepSeek's Anthropic-compatible surface lives here (api-docs.deepseek.com/guides/anthropic_api).
+ *  It is real vendor surface this twin does not model yet — filed as `deepseek.anthropic.messages`
+ *  and answered like any other unmodeled operation, never faked. */
+export const DEEPSEEK_ANTHROPIC_PREFIX = '/anthropic';
+// ── vendor-shaped errors ──────────────────────────────────────────────────────────────
+/**
+ * DeepSeek's error envelope. `message` is the only key the vendor's own decoder requires; `type`,
+ * `param` and `code` are nullish (`deepSeekErrorSchema`, `@ai-sdk/deepseek@3.0.37`
+ * src/chat/deepseek-chat-api-types.ts — an SDK-generated schema, which §6's precedence order ranks
+ * above a rendered docs example).
+ *
+ * THE `type` STRINGS ARE NOT INVENTED AND NOT GUESSED. DeepSeek publishes STATUS codes and their
+ * causes, not envelope `type` values. Where `@ai-sdk/deepseek`'s own discriminator table
+ * (`getDeepSeekStreamErrorMetadata`) names a type that maps to the same status DeepSeek documents,
+ * the twin uses that string — the SDK wrote that table for THIS provider, so it is first-party
+ * evidence about what DeepSeek emits. Where it names none that agrees (402 has no entry at all),
+ * the twin OMITS `type` rather than making one up, and the capability asserts status + message
+ * only. The `message` strings are DeepSeek's own documented causes
+ * (api-docs.deepseek.com/quick_start/error_codes) plus a specific detail.
+ */
+function errBody(message, type) {
+    return { error: { message, ...(type !== undefined ? { type } : {}) } };
+}
+/** 400 — "Invalid request body format". Reserved for a body the vendor cannot parse or a
+ *  structurally impossible message list, NOT for a bad parameter value (that is 422). */
+function invalidFormat(detail) {
+    return { status: 400, body: errBody(`Invalid request body format: ${detail}`, 'invalid_request_error') };
+}
+/** 422 — "Your request contains invalid parameters". DeepSeek's status for a well-formed body with
+ *  a parameter the API refuses; this is the single most common OpenAI divergence in this file. */
+function invalidParameters(detail) {
+    // NO `type`, deliberately — and this is the file's own stated rule applied to itself (see
+    // errBody). `@ai-sdk/deepseek`'s discriminator table has NO 422 entry at all, and the
+    // `invalid_request_error` this used to emit is mapped there to `statusCode: 400` — so a real
+    // client resolving a streamed 422 would have been told 400 by the twin's own discriminator.
+    // Where nothing first-party names a type for a status, the twin omits the field rather than
+    // inventing one, exactly as it does for 402. (§9 round one, SHOULD-FIX 3.)
+    return { status: 422, body: errBody(`Your request contains invalid parameters: ${detail}`) };
+}
+/** 401 — "Authentication fails due to the wrong API key". */
+function authError() {
+    return { status: 401, body: errBody('Authentication fails due to the wrong API key', 'authentication_error') };
+}
+/** 402 — "You have run out of balance". DeepSeek's own status; OpenAI has no 402. No `type` is
+ *  emitted: nothing first-party names one for this status (see errBody). */
+function insufficientBalance() {
+    return { status: 402, body: errBody('You have run out of balance') };
+}
+/** 429 — "You are sending requests too quickly". */
+function rateLimitError() {
+    return { status: 429, body: errBody('You are sending requests too quickly', 'rate_limit_exceeded') };
+}
+/**
+ * The reply to a route DeepSeek does not serve, or one this twin does not model yet.
+ *
+ * HONESTY NOTE: DeepSeek's published error table (400/401/402/422/429/500/503) covers REQUEST
+ * errors and contains no 404, and the vendor publishes nothing about its unknown-route envelope.
+ * The twin answers 404 with the vendor's envelope SHAPE because an unmodeled operation must fail
+ * rather than fake a success (docs/contributing/architecture.md); the exact status/body a real gateway returns for an
+ * unrouted path is filed as `deepseek.errors.unknown_route_envelope` (todo), and no capability
+ * asserts a published fact it does not have.
+ */
+function notFound(message) {
+    return { status: 404, body: errBody(message, 'not_found_error') };
+}
+// ── modeled authentication (401) ────────────────────────────────────────────────────────
+// Real DeepSeek requires a bearer credential on every request and returns 401 when it is missing or
+// wrong. The twin can't validate against real keys, so it models the CHECKABLE failures: a missing
+// credential, and a reserved sentinel for the invalid-key path. Any other non-empty key is
+// accepted. Trusted in-process calls carry NEITHER `headers` nor `apiKey` and are NOT auth-gated.
+function checkAuth(req) {
+    const auth = req.headers?.['authorization'];
+    const bearer = typeof auth === 'string' && auth.toLowerCase().startsWith('bearer ') ? auth.slice(7).trim() : '';
+    const key = (req.apiKey ?? '').trim() || bearer;
+    if (!key)
+        return authError();
+    if (key === 'sk_invalid' || key === 'invalid')
+        return authError();
+    return null;
+}
+function triggered(req, header) {
+    const v = req.headers?.[header];
+    return v === '1' || v === 'true';
+}
+function nowEpoch(occurredAt) {
+    return Math.floor((occurredAt ? Date.parse(occurredAt) : 0) / 1000);
+}
+// ── kernel helpers ──────────────────────────────────────────────────────────────────────
+function rows(type, root) {
+    return projectResources(SERVICE, root).filter((r) => r.type === type);
+}
+/**
+ * Mint the next local file id. Derived from the ID SET ALREADY IN STATE (a scan of the projection),
+ * never a row count — a count-mint silently clobbers a pulled vendor id sitting in a gap above the
+ * count (ADDING_A_TWIN.md §5). Two further properties matter:
+ *   • the `twin` infix namespaces LOCAL mints, so a pulled DeepSeek id (`file-api-a1b2c3d4e5f6g7h8`)
+ *     is not matched by this regex and therefore is not re-minted. "Never" would be over-stated: a
+ *     vendor id of literally `twin000000000123` has the same 16-character width and would match.
+ *     That is astronomically unlikely rather than impossible, and saying so is the honest form
+ *     (§9 round one, NIT 19);
+ *   • the scan includes TOMBSTONED rows (a soft-deleted file keeps its projection row), so the
+ *     counter RATCHETS across delete→recreate and a deleted id is never handed out twice.
+ * The shape matches DeepSeek's own `file-api-xxxxxxxxxxxxxxxx` (16 characters after the prefix).
+ */
+const LOCAL_FILE_ID = /^file-api-twin(\d{12})$/;
+function nextFileId(root) {
+    let max = 0;
+    for (const r of rows('file', root)) {
+        const m = LOCAL_FILE_ID.exec(String(r.id));
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return `file-api-twin${String(max + 1).padStart(12, '0')}`;
+}
+/** Models observed by a connector pull, reshaped into the served three-key model object. */
+function pulledModels(root) {
+    return rows('model', root)
+        .filter((r) => !r._deleted)
+        .map((r) => ({ id: r.id, object: 'model', owned_by: r.owned_by ?? 'deepseek' }));
+}
+/** The catalog a request sees: the published table, with any PULLED row of the same id overriding
+ *  it — otherwise a pulled account's model list is folded into the log and then never served. */
+function servedModels(root) {
+    const byId = new Map();
+    for (const m of DEEPSEEK_MODELS)
+        byId.set(m.id, m);
+    for (const m of pulledModels(root))
+        byId.set(String(m.id), m);
+    return [...byId.values()];
+}
+function getRow(type, id, root) {
+    return rows(type, root).find((r) => r.id === id);
+}
+/** The account balance the twin serves and enforces. DeepSeek's own example response is the
+ *  default until a connector pull or a twin-only seed replaces it. */
+const DEFAULT_BALANCE = {
+    is_available: true,
+    balance_infos: [{ currency: 'CNY', total_balance: '110.00', granted_balance: '10.00', topped_up_balance: '100.00' }],
+};
+function servedBalance(root) {
+    const row = getRow('balance', 'account', root);
+    if (!row)
+        return DEFAULT_BALANCE;
+    return {
+        is_available: row.is_available !== false,
+        balance_infos: Array.isArray(row.balance_infos) ? row.balance_infos : DEFAULT_BALANCE.balance_infos,
+    };
+}
+// ── request parsing ─────────────────────────────────────────────────────────────────────
+/** Parse the body, distinguishing "no body" from "unparseable body" — the latter is DeepSeek's
+ *  400 "Invalid request body format", which is the ONLY thing 400 is for. */
+function parseJson(body) {
+    // THE LINE BETWEEN 400 AND 422, drawn once and applied everywhere: 400 is for a body this API
+    // cannot parse as a JSON object at all — absent, malformed, or an array/scalar. EVERYTHING about
+    // the parsed CONTENT (a missing required parameter, a bad type, a value outside a closed set) is
+    // 422 "Your request contains invalid parameters". The first cut had these mixed — a missing
+    // `messages` answered 400 while a missing `model` answered 422, which is the same class of error
+    // reported two different ways.
+    if (!body || !body.trim())
+        return { error: invalidFormat('a JSON request body is required') };
+    try {
+        const v = JSON.parse(body);
+        if (!v || typeof v !== 'object' || Array.isArray(v))
+            return { error: invalidFormat('the request body must be a JSON object') };
+        return { params: v };
+    }
+    catch {
+        return { error: invalidFormat('the request body is not valid JSON') };
+    }
+}
+/**
+ * THE CLOSED PARAMETER TABLE for `POST /chat/completions`
+ * (api-docs.deepseek.com/api/create-chat-completion, read 2026-08-31) plus the two streaming keys
+ * and the top-level `reasoning_effort` `@ai-sdk/deepseek` actually sends.
+ *
+ * §6 licenses a literal allowlist as an ORACLE precisely when the vendor documents a closed set,
+ * and this is one — which is what gives `n`, `seed`, `logit_bias`, `top_k`, `user`,
+ * `max_completion_tokens`, `service_tier` and `parallel_tool_calls` a *checkable* refusal instead
+ * of the silent acceptance an OpenAI-copied twin gives them.
+ *
+ * DOC CONFLICT, recorded rather than resolved by guess: the reference table puts reasoning effort
+ * at `thinking.reasoning_effort`, while `@ai-sdk/deepseek` sends a TOP-LEVEL `reasoning_effort`
+ * (src/chat/deepseek-chat-language-model.ts). Both are first-party. The twin accepts BOTH placements
+ * rather than rejecting a shape a first-party client demonstrably sends; it never invents a third.
+ */
+const CHAT_PARAMS = new Set([
+    'messages', 'model', 'thinking', 'max_tokens', 'response_format', 'stop', 'stream',
+    'stream_options', 'temperature', 'top_p', 'tools', 'tool_choice', 'logprobs', 'top_logprobs',
+    'user_id', 'frequency_penalty', 'presence_penalty', 'reasoning_effort',
+]);
+/** The closed table for `POST /beta/completions` (api-docs.deepseek.com/api/create-completion). */
+const FIM_PARAMS = new Set([
+    'model', 'prompt', 'suffix', 'echo', 'max_tokens', 'temperature', 'top_p', 'logprobs', 'stop',
+    'stream', 'stream_options', 'frequency_penalty', 'presence_penalty',
+]);
+const MESSAGE_ROLES = new Set(['system', 'user', 'assistant', 'tool']);
+/** `thinking.type` — a closed set of two (`enabled`, `disabled`). */
+const THINKING_TYPES = new Set(['enabled', 'disabled']);
+/** The canonical reasoning-effort values. */
+const REASONING_EFFORTS = new Set(['low', 'high', 'max']);
+/**
+ * Legacy values DeepSeek maps rather than refuses: "`medium` and `xhigh` both map to actual `high`
+ * effort" (api-docs.deepseek.com/guides/thinking_mode). Recorded as a MAP, not silently swallowed,
+ * so the twin normalizes exactly the two values the vendor says it normalizes and 422s the rest.
+ */
+// A SECOND recorded conflict, alongside the placement one above: the vendor's mapping table says
+// BOTH `medium` and `xhigh` become `high`, while `@ai-sdk/deepseek` maps `xhigh` to `max`
+// client-side (`mapDeepSeekProviderReasoningEffort`; docs/30-deepseek.mdx: "reasoningEffort 'xhigh'
+// becomes 'max'"). The twin follows the VENDOR page because this is server-side behaviour and the
+// SDK's mapping happens before the request is sent — so the server never sees `xhigh` from that
+// client anyway. (§9 round one, NIT 14.)
+const LEGACY_EFFORTS = { medium: 'high', xhigh: 'high' };
+/** "Up to 16 sequences where the API will stop" (api-docs.deepseek.com/api/create-chat-completion). */
+const MAX_STOP_SEQUENCES = 16;
+/** "Nullable; max 128 functions" (same page). */
+const MAX_TOOLS = 128;
+/** `user_id`: "a-zA-Z0-9, hyphens, underscores", "max 512 chars" (same page; enforced client-side by
+ *  `@ai-sdk/deepseek`'s `deepseekLanguageModelChatOptions` with the identical regex and cap). */
+const USER_ID_RE = /^[a-zA-Z0-9_-]+$/;
+const USER_ID_MAX = 512;
+function asStringArray(v) {
+    if (typeof v === 'string')
+        return [v];
+    if (Array.isArray(v) && v.every((s) => typeof s === 'string'))
+        return v;
+    return null;
+}
+function validateChat(params, beta) {
+    // (1) The closed parameter table. A key outside it is 422 BY NAME — the flagship
+    //     OpenAI-divergence check (see CHAT_PARAMS).
+    for (const key of Object.keys(params)) {
+        if (!CHAT_PARAMS.has(key))
+            return { error: invalidParameters(`'${key}' is not a parameter of the DeepSeek chat completions API`) };
+    }
+    // (2) Structure. A missing or ill-typed `messages` is a complaint about parsed CONTENT and is
+    //     therefore 422, not 400 — see `parseJson`, which owns the whole of the 400 side. (§9 round
+    //     two, SHOULD-FIX 7: this comment still stated the pre-fix rule the code had stopped
+    //     following, which is exactly the class round one caught elsewhere.)
+    if (!Array.isArray(params.messages))
+        return { error: invalidParameters("'messages' is a required array") };
+    if (params.messages.length === 0)
+        return { error: invalidParameters("'messages' must contain at least 1 item") };
+    const messages = params.messages;
+    for (const m of messages) {
+        if (!m || typeof m !== 'object' || typeof m.role !== 'string')
+            return { error: invalidParameters("each entry of 'messages' must be an object with a 'role'") };
+        if (!MESSAGE_ROLES.has(m.role))
+            return { error: invalidParameters(`'messages[].role' must be one of ${[...MESSAGE_ROLES].map((r) => `'${r}'`).join(', ')}`) };
+        // MESSAGE FIELD TYPES, brought under the same 422 rule as everything else about parsed content.
+        // §9 round two, SHOULD-FIX 2 + 3: these were unchecked, and both failure modes were worse than a
+        // wrong status. A non-string `name` reached `estimateTokens` and produced NaN, which serialises
+        // as `null` — so the twin answered 200 with `prompt_tokens: null`, breaking the cache invariant
+        // its own capability asserts and handing its own fidelity client a body the SDK's usage schema
+        // cannot decode. A non-array `tool_calls` threw a TypeError that surfaced as a 500 with
+        // `internal_server_error`, which the SDK marks RETRYABLE — so a client would retry a permanently
+        // invalid request forever.
+        for (const field of ['name', 'reasoning_content', 'tool_call_id']) {
+            const v = m[field];
+            if (v !== undefined && v !== null && typeof v !== 'string') {
+                return { error: invalidParameters(`'messages[].${field}' must be a string`) };
+            }
+        }
+        if (m.tool_calls !== undefined && m.tool_calls !== null && !Array.isArray(m.tool_calls)) {
+            return { error: invalidParameters("'messages[].tool_calls' must be an array") };
+        }
+        for (const tc of m.tool_calls ?? []) {
+            if (!tc || typeof tc !== 'object' || typeof tc.function?.name !== 'string' || typeof tc.function?.arguments !== 'string') {
+                return { error: invalidParameters("each entry of 'messages[].tool_calls' must be { id, type: 'function', function: { name, arguments } }") };
+            }
+        }
+    }
+    // (3) Model. The catalog is closed and `deepseek-chat` / `deepseek-reasoner` were RETIRED on
+    //     2026-07-24 (`@ai-sdk/deepseek` docs/30-deepseek.mdx). A retired alias gets a message that
+    //     says so instead of a generic refusal.
+    if (typeof params.model !== 'string' || !params.model)
+        return { error: invalidParameters("'model' is a required string") };
+    const model = params.model;
+    if (!findModel(model)) {
+        if (RETIRED_MODEL_IDS.has(model)) {
+            return { error: invalidParameters(`'model' "${model}" was retired on 2026-07-24; use 'deepseek-v4-flash' or 'deepseek-v4-pro'`) };
+        }
+        return { error: invalidParameters(`'model' "${model}" does not exist`) };
+    }
+    // (4) Thinking. `thinking.type` is a closed set; effort is closed with two legacy values the
+    //     vendor documents as MAPPED (never a third behaviour invented here).
+    let thinkingEnabled = isThinkingModel(model); // "thinking mode is enabled" by default on V4
+    let effortRaw = params.reasoning_effort;
+    const thinking = params.thinking;
+    if (thinking !== undefined && thinking !== null) {
+        if (typeof thinking !== 'object' || Array.isArray(thinking))
+            return { error: invalidParameters("'thinking' must be an object") };
+        const t = thinking;
+        if (t.type !== undefined && t.type !== null) {
+            if (typeof t.type !== 'string' || !THINKING_TYPES.has(t.type)) {
+                return { error: invalidParameters(`'thinking.type' must be one of ${[...THINKING_TYPES].map((v) => `'${v}'`).join(', ')}`) };
+            }
+            thinkingEnabled = t.type === 'enabled';
+        }
+        if (t.reasoning_effort !== undefined && t.reasoning_effort !== null)
+            effortRaw = t.reasoning_effort;
+    }
+    // "Default: … effort level set to `high`" (api-docs.deepseek.com/guides/thinking_mode).
+    let reasoningEffort = 'high';
+    if (effortRaw !== undefined && effortRaw !== null) {
+        const raw = typeof effortRaw === 'string' ? effortRaw : '';
+        if (REASONING_EFFORTS.has(raw))
+            reasoningEffort = raw;
+        else if (raw in LEGACY_EFFORTS)
+            reasoningEffort = LEGACY_EFFORTS[raw];
+        else
+            return { error: invalidParameters(`'reasoning_effort' must be one of ${[...REASONING_EFFORTS].map((v) => `'${v}'`).join(', ')}`) };
+    }
+    // (5) Sampling. `temperature` 0–2, `top_p` 0–1 (documented ranges). NOTE what is NOT here:
+    //     `frequency_penalty` / `presence_penalty` are accepted and ignored (deprecated, "no
+    //     effect"), and temperature/top_p are IGNORED — not rejected — while thinking is enabled.
+    if (params.temperature !== undefined && params.temperature !== null) {
+        const t = params.temperature;
+        if (typeof t !== 'number' || Number.isNaN(t) || t < 0 || t > 2)
+            return { error: invalidParameters("'temperature' must be a number between 0 and 2") };
+    }
+    if (params.top_p !== undefined && params.top_p !== null) {
+        const p = params.top_p;
+        if (typeof p !== 'number' || Number.isNaN(p) || p <= 0 || p > 1)
+            return { error: invalidParameters("'top_p' must be a number in (0, 1]") };
+    }
+    // (6) max_tokens.
+    let maxTokens;
+    if (params.max_tokens !== undefined && params.max_tokens !== null) {
+        const v = params.max_tokens;
+        if (typeof v !== 'number' || !Number.isInteger(v) || v < 1)
+            return { error: invalidParameters("'max_tokens' must be an integer >= 1") };
+        maxTokens = v;
+    }
+    // (7) stop — "Up to 16 sequences".
+    let stop;
+    if (params.stop !== undefined && params.stop !== null) {
+        const s = asStringArray(params.stop);
+        if (s === null)
+            return { error: invalidParameters("'stop' must be a string or an array of strings") };
+        if (s.length > MAX_STOP_SEQUENCES)
+            return { error: invalidParameters(`'stop' supports up to ${MAX_STOP_SEQUENCES} sequences`) };
+        stop = s;
+    }
+    // (8) response_format — TEXT or JSON_OBJECT ONLY. `json_schema` is the OpenAI feature DeepSeek
+    //     does not have on this endpoint, and it is the single most likely thing an OpenAI-copied
+    //     twin would happily serve.
+    let responseFormat = 'text';
+    const rf = params.response_format;
+    if (rf !== undefined && rf !== null) {
+        if (typeof rf !== 'object' || Array.isArray(rf))
+            return { error: invalidParameters("'response_format' must be an object") };
+        const type = rf.type;
+        if (type !== undefined && type !== null) {
+            if (type === 'json_object')
+                responseFormat = 'json_object';
+            else if (type === 'text')
+                responseFormat = 'text';
+            else
+                return { error: invalidParameters("'response_format.type' must be one of 'text', 'json_object'") };
+        }
+    }
+    // (9) logprobs — a BOOLEAN here (the beta FIM endpoint's `logprobs` is an integer instead, a
+    //     divergence modelled in validateFim). `top_logprobs` is 0–20 and "requires logprobs: true".
+    if (params.logprobs !== undefined && params.logprobs !== null && typeof params.logprobs !== 'boolean') {
+        return { error: invalidParameters("'logprobs' must be a boolean") };
+    }
+    const logprobs = params.logprobs === true;
+    let topLogprobs;
+    if (params.top_logprobs !== undefined && params.top_logprobs !== null) {
+        const v = params.top_logprobs;
+        if (typeof v !== 'number' || !Number.isInteger(v) || v < 0 || v > 20)
+            return { error: invalidParameters("'top_logprobs' must be an integer between 0 and 20") };
+        if (!logprobs)
+            return { error: invalidParameters("'top_logprobs' requires 'logprobs' to be true") };
+        topLogprobs = v;
+    }
+    // (10) user_id — DeepSeek's end-user identifier. NOT OpenAI's `user` (which CHAT_PARAMS refuses).
+    let userId;
+    if (params.user_id !== undefined && params.user_id !== null) {
+        const v = params.user_id;
+        if (typeof v !== 'string' || !USER_ID_RE.test(v))
+            return { error: invalidParameters("'user_id' must match /^[a-zA-Z0-9_-]+$/") };
+        if (v.length > USER_ID_MAX)
+            return { error: invalidParameters(`'user_id' must be at most ${USER_ID_MAX} characters long`) };
+        userId = v;
+    }
+    // (11) Tools — "max 128 functions"; strict mode is BETA-ONLY and all-or-nothing.
+    let tools;
+    if (params.tools !== undefined && params.tools !== null) {
+        if (!Array.isArray(params.tools))
+            return { error: invalidParameters("'tools' must be an array") };
+        if (params.tools.length > MAX_TOOLS)
+            return { error: invalidParameters(`'tools' supports at most ${MAX_TOOLS} functions`) };
+        for (const t of params.tools) {
+            const tool = t;
+            if (!tool || typeof tool !== 'object' || tool.type !== 'function' || typeof tool.function?.name !== 'string') {
+                return { error: invalidParameters("each entry of 'tools' must be { type: 'function', function: { name } }") };
+            }
+        }
+        const strictFlags = params.tools.map((t) => t.function?.strict === true);
+        if (strictFlags.some(Boolean)) {
+            // "DeepSeek strict tool calls require a beta base URL ending in `/beta`" and "DeepSeek strict
+            // mode requires every function tool in the request to set `strict: true`"
+            // (@ai-sdk/deepseek src/chat/deepseek-prepare-tools.ts — the SDK refuses both locally, which
+            // is first-party evidence of the vendor rule the twin reproduces server-side).
+            if (!beta)
+                return { error: invalidParameters("strict tool calls require the beta base URL (append '/beta' to your base_url)") };
+            if (!strictFlags.every(Boolean))
+                return { error: invalidParameters("strict mode requires every function tool to set 'strict': true") };
+        }
+        tools = params.tools;
+    }
+    let toolChoice;
+    const tcRaw = params.tool_choice;
+    if (tcRaw !== undefined && tcRaw !== null) {
+        if (typeof tcRaw === 'string') {
+            if (!['auto', 'none', 'required'].includes(tcRaw))
+                return { error: invalidParameters("'tool_choice' must be one of 'none', 'auto', 'required' or a named function") };
+            toolChoice = tcRaw;
+        }
+        else if (typeof tcRaw === 'object' && !Array.isArray(tcRaw)) {
+            const name = tcRaw.function?.name;
+            if (typeof name !== 'string' || !name)
+                return { error: invalidParameters("'tool_choice.function.name' is required for a named tool choice") };
+            toolChoice = { name };
+        }
+        else {
+            return { error: invalidParameters("'tool_choice' must be a string or an object") };
+        }
+    }
+    // (12) THE reasoning_content HAND-BACK RULE. "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). Scoped to thinking models, exactly as
+    //      `@ai-sdk/deepseek` scopes its own back-fill (`isDeepSeekV4`), so client and twin can never
+    //      disagree about which turn owes the field. An EMPTY STRING counts as passed back — that is
+    //      literally what the SDK sends for a turn with no reasoning.
+    if (tools !== undefined && isThinkingModel(model)) {
+        for (const m of messages) {
+            if (m.role !== 'assistant')
+                continue;
+            if (typeof m.reasoning_content !== 'string') {
+                // The ONE content-level 400 on this vendor, and it is 400 because DeepSeek documents it
+                // as one by name: "the API will return a 400 error" when a tools request omits a previous
+                // turn's reasoning_content (api-docs.deepseek.com/guides/thinking_mode). Everything else
+                // about parsed content is 422 — this is the deliberate exception, not a leak of the rule.
+                return { error: { status: 400, body: errBody("Invalid request body format: when 'tools' is set, every previous assistant message must carry back its 'reasoning_content'", 'invalid_request_error') } };
+            }
+        }
+    }
+    // (13) Assistant prefix completion — BETA ONLY, and only on the FINAL message.
+    const prefixIndexes = messages.map((m, i) => (m.prefix === true ? i : -1)).filter((i) => i >= 0);
+    if (prefixIndexes.length > 0) {
+        for (const i of prefixIndexes) {
+            if (messages[i].role !== 'assistant')
+                return { error: invalidParameters("'prefix' is only valid on an assistant message") };
+        }
+        if (!beta)
+            return { error: invalidParameters("chat prefix completion requires the beta base URL (append '/beta' to your base_url)") };
+        if (prefixIndexes.length > 1 || prefixIndexes[0] !== messages.length - 1) {
+            return { error: invalidParameters("the message carrying 'prefix' must be the final message") };
+        }
+    }
+    // (14) Streaming.
+    if (params.stream !== undefined && params.stream !== null && typeof params.stream !== 'boolean') {
+        return { error: invalidParameters("'stream' must be a boolean") };
+    }
+    const stream = params.stream === true;
+    let includeUsage = false;
+    if (params.stream_options !== undefined && params.stream_options !== null) {
+        if (typeof params.stream_options !== 'object' || Array.isArray(params.stream_options))
+            return { error: invalidParameters("'stream_options' must be an object") };
+        // ACCEPTED WITHOUT `stream`, deliberately. The reference table says only "set when stream: true"
+        // — guidance, not a documented refusal — and refusing it would be the over-strictness that is
+        // the mirror image of inherited permissiveness. It simply has no effect on a unary request.
+        // The vendor's actual behaviour here is unobserved and filed as
+        // `deepseek.streaming.stream_options_without_stream`. (§9 round one, NIT 13.)
+        includeUsage = stream && params.stream_options.include_usage === true;
+    }
+    return {
+        args: {
+            model,
+            messages,
+            ...(tools !== undefined ? { tools } : {}),
+            ...(maxTokens !== undefined ? { maxTokens } : {}),
+            ...(stop !== undefined ? { stop } : {}),
+            stream,
+            includeUsage,
+            ...(toolChoice !== undefined ? { toolChoice } : {}),
+            responseFormat,
+            thinkingEnabled,
+            reasoningEffort,
+            logprobs,
+            ...(topLogprobs !== undefined ? { topLogprobs } : {}),
+            ...(userId !== undefined ? { userId } : {}),
+            beta,
+        },
+    };
+}
+/** Build ONE deterministic stub choice. */
+function buildChoice(args) {
+    const hasTools = Array.isArray(args.tools) && args.tools.length > 0;
+    const forbidTools = args.toolChoice === 'none';
+    const forcedName = typeof args.toolChoice === 'object' ? args.toolChoice.name : undefined;
+    // Thinking is on by default for every V4 model, so the stub emits `reasoning_content` unless the
+    // caller turned it off — matching what a real V4 turn looks like on the wire.
+    const reasoning = args.thinkingEnabled ? stubReasoningText(args.messages, args.model, args.reasoningEffort) : undefined;
+    const reasoningTokens = reasoning ? estimateTokens(reasoning) : 0;
+    if (hasTools && !forbidTools) {
+        const list = args.tools;
+        const calls = [];
+        if (forcedName) {
+            const tc = stubToolCall(list, 1, forcedName);
+            if (tc)
+                calls.push(tc);
+        }
+        else {
+            for (let t = 0; t < list.length; t++) {
+                const tc = stubToolCall([list[t]], t + 1);
+                if (tc)
+                    calls.push(tc);
+            }
+        }
+        if (calls.length) {
+            const message = { role: 'assistant', content: null, tool_calls: calls };
+            if (reasoning)
+                message.reasoning_content = reasoning;
+            return {
+                choice: { index: 0, message, logprobs: null, finish_reason: 'tool_calls' },
+                completionTokens: estimateTokens(JSON.stringify(calls)) + reasoningTokens,
+                reasoningTokens,
+            };
+        }
+    }
+    // Beta prefix completion: DeepSeek CONTINUES the final assistant message's content rather than
+    // starting a new turn, so the stub is appended to what the caller already wrote.
+    const prefixMessage = args.beta && args.messages[args.messages.length - 1]?.prefix === true ? args.messages[args.messages.length - 1] : null;
+    const prefixText = prefixMessage ? String(prefixMessage.content ?? '') : '';
+    let text = args.responseFormat === 'json_object'
+        ? stubJsonObject(args.messages, args.model)
+        : `${prefixText}${stubAssistantText(args.messages, args.model)}`;
+    let finish = 'stop';
+    // Truncate at the EARLIEST-occurring stop sequence across the whole `stop` list.
+    let stopAt = -1;
+    for (const s of args.stop ?? []) {
+        if (!s)
+            continue;
+        const i = text.indexOf(s);
+        if (i >= 0 && (stopAt < 0 || i < stopAt))
+            stopAt = i;
+    }
+    if (stopAt >= 0)
+        text = text.slice(0, stopAt);
+    if (args.maxTokens !== undefined && estimateTokens(text) > args.maxTokens) {
+        text = text.slice(0, args.maxTokens * 4);
+        finish = 'length';
+    }
+    const message = { role: 'assistant', content: text };
+    if (reasoning)
+        message.reasoning_content = reasoning;
+    return {
+        choice: { index: 0, message, logprobs: args.logprobs ? stubLogprobs(text, reasoning, args.topLogprobs) : null, finish_reason: finish },
+        completionTokens: estimateTokens(text) + reasoningTokens,
+        reasoningTokens,
+    };
+}
+/**
+ * DeepSeek's `logprobs` block, which — unlike OpenAI's — has TWO channels: `content` and
+ * `reasoning_content` (`deepseekChatLogprobsSchema`, `@ai-sdk/deepseek`
+ * src/chat/deepseek-chat-api-types.ts). The VALUES are a labeled deterministic derivation, not real
+ * model probabilities — the twin runs no model.
+ */
+function stubLogprobs(text, reasoning, topLogprobs) {
+    const entry = (token) => {
+        const h = fnv1a(token);
+        const logprob = -Math.round(((h % 5000) / 1000) * 1e6) / 1e6;
+        const top = [];
+        for (let i = 0; i < (topLogprobs ?? 0); i++) {
+            top.push({ token: `${token}#${i}`, logprob: Math.round((logprob - i * 0.5) * 1e6) / 1e6, bytes: null });
+        }
+        return { token, logprob, bytes: [...new TextEncoder().encode(token)], top_logprobs: top };
+    };
+    const split = (s) => s.split(/(?<=\s)/).slice(0, 8).filter(Boolean);
+    const content = split(text).map(entry);
+    return {
+        ...(content.length ? { content } : { content: null }),
+        ...(reasoning ? { reasoning_content: split(reasoning).map(entry) } : {}),
+    };
+}
+/** A deterministic id suffix from the request (so ids are stable + assertable). */
+function stableSuffix(args) {
+    return fnv1a(JSON.stringify(args.messages) + args.model + args.reasoningEffort).toString(36);
+}
+export function buildChatCompletion(args, occurredAt, scenarioEngine, root) {
+    const promptTokens = countPromptTokens(args.messages);
+    const hitTokens = cacheHitTokens(args.messages, root);
+    let scripted = null;
+    let missTeach = '';
+    if (scenarioEngine) {
+        const decision = scenarioEngine.next({ model: args.model, messages: args.messages, tools: args.tools, thinking: args.thinkingEnabled ? 'enabled' : 'disabled' });
+        if (decision.kind === 'handler') {
+            const respond = decision.respond;
+            if (respond.error)
+                return scriptedError(respond.error);
+            scripted = realizeDeepSeekRespond(respond);
+        }
+        else {
+            missTeach = `\n[twin-scenario miss — no handler matched. Author one in the world dir's handlers/deepseek.json (GET /twin explains; GET /twin/scenario lists handlers + misses). Features seen: ${JSON.stringify(decision.miss.features)}]`;
+        }
+    }
+    let choice;
+    let completionTokens;
+    let reasoningTokens = 0;
+    if (scripted) {
+        const message = scripted.toolCalls.length
+            ? { role: 'assistant', content: scripted.text, tool_calls: scripted.toolCalls }
+            : { role: 'assistant', content: scripted.text ?? '' };
+        if (scripted.reasoning !== null) {
+            message.reasoning_content = scripted.reasoning;
+            reasoningTokens = estimateTokens(scripted.reasoning);
+        }
+        choice = { index: 0, message, logprobs: null, finish_reason: scripted.finishReason };
+        completionTokens = estimateTokens(JSON.stringify(scripted.toolCalls.length ? scripted.toolCalls : scripted.text ?? '')) + reasoningTokens;
+    }
+    else {
+        const built = buildChoice(args);
+        choice = built.choice;
+        completionTokens = built.completionTokens;
+        reasoningTokens = built.reasoningTokens;
+        if (missTeach && typeof choice.message.content === 'string')
+            choice.message.content += missTeach;
+    }
+    const usage = buildUsage(promptTokens, completionTokens, hitTokens, reasoningTokens);
+    return {
+        id: `chatcmpl-twin-${stableSuffix(args)}`,
+        object: 'chat.completion',
+        created: nowEpoch(occurredAt),
+        model: args.model,
+        choices: [choice],
+        usage,
+        system_fingerprint: stubFingerprint(`${args.model}|${args.reasoningEffort}`),
+    };
+}
+/** Map a scripted scenario failure onto DeepSeek's real status + envelope. */
+function scriptedError(err) {
+    if (err.type === 'rate_limit_exceeded') {
+        const base = rateLimitError();
+        return err.message ? { ...base, body: errBody(err.message, 'rate_limit_exceeded') } : base;
+    }
+    if (err.type === 'insufficient_balance') {
+        const base = insufficientBalance();
+        return err.message ? { ...base, body: errBody(err.message) } : base;
+    }
+    if (err.type === 'server_overloaded') {
+        return { status: 503, body: errBody(err.message ?? 'The server is overloaded due to high traffic', 'service_unavailable') };
+    }
+    return { status: 500, body: errBody(err.message ?? 'Our server encounters an issue', 'server_error') };
+}
+const isEnvelope = (v) => typeof v.status === 'number' && 'body' in v;
+/** Split text into deterministic streaming chunks (≤ ~20 chars each), preserving order. */
+function chunkText(text) {
+    if (!text)
+        return [];
+    const out = [];
+    for (let i = 0; i < text.length; i += 20)
+        out.push(text.slice(i, i + 20));
+    return out;
+}
+/**
+ * Emit the vendor-faithful DeepSeek streaming sequence into the injected sink (NO sockets, NO
+ * setTimeout). The order: a first chunk with `delta:{role:'assistant', content:''}`, then
+ * `reasoning_content` deltas, then `content` deltas (or `tool_calls` deltas), then a chunk carrying
+ * `finish_reason`, and — when `stream_options.include_usage` was set — a FINAL chunk with an EMPTY
+ * `choices` array whose `usage` holds the completion's usage. `@ai-sdk/deepseek`'s `doStream`
+ * always sends `stream_options: { include_usage: true }`, so that tail chunk is what makes its
+ * `finish` part carry real token counts.
+ *
+ * REASONING BEFORE TEXT is not cosmetic: the SDK's transform closes its `reasoning-0` part the
+ * moment the first `content` delta arrives, so emitting them interleaved would produce a different
+ * part sequence than the vendor's.
+ */
+export function streamChat(args, sink, occurredAt, scenarioEngine, root) {
+    const built = buildChatCompletion(args, occurredAt, scenarioEngine, root);
+    if (isEnvelope(built))
+        return built;
+    const full = built;
+    const base = { id: full.id, object: 'chat.completion.chunk', created: full.created, model: full.model, system_fingerprint: full.system_fingerprint };
+    const choice = full.choices[0];
+    sink({ data: { ...base, choices: [{ index: 0, delta: { role: 'assistant', content: '' }, logprobs: null, finish_reason: null }] } });
+    for (const piece of chunkText(choice.message.reasoning_content ?? '')) {
+        sink({ data: { ...base, choices: [{ index: 0, delta: { reasoning_content: piece }, logprobs: null, finish_reason: null }] } });
+    }
+    if (choice.message.tool_calls && choice.message.tool_calls.length) {
+        choice.message.tool_calls.forEach((tc, tIdx) => {
+            sink({ data: { ...base, choices: [{ index: 0, delta: { tool_calls: [{ index: tIdx, id: tc.id, type: 'function', function: { name: tc.function.name, arguments: '' } }] }, logprobs: null, finish_reason: null }] } });
+            sink({ data: { ...base, choices: [{ index: 0, delta: { tool_calls: [{ index: tIdx, function: { arguments: tc.function.arguments } }] }, logprobs: null, finish_reason: null }] } });
+        });
+    }
+    else {
+        for (const piece of chunkText(choice.message.content ?? '')) {
+            sink({ data: { ...base, choices: [{ index: 0, delta: { content: piece }, logprobs: null, finish_reason: null }] } });
+        }
+    }
+    sink({ data: { ...base, choices: [{ index: 0, delta: {}, logprobs: choice.logprobs, finish_reason: choice.finish_reason }] } });
+    // The usage tail is OPT-IN, exactly as the vendor's `stream_options.include_usage` documents.
+    if (args.includeUsage)
+        sink({ data: { ...base, choices: [], usage: full.usage } });
+    sink({ done: true });
+    return full;
+}
+function validateFim(params) {
+    for (const key of Object.keys(params)) {
+        if (!FIM_PARAMS.has(key))
+            return { error: invalidParameters(`'${key}' is not a parameter of the DeepSeek FIM completions API`) };
+    }
+    if (typeof params.model !== 'string' || !params.model)
+        return { error: invalidParameters("'model' is a required string") };
+    // "Only value: `deepseek-v4-pro`" — a closed set of one.
+    if (!FIM_MODELS.has(params.model)) {
+        return { error: invalidParameters(`'model' must be one of ${[...FIM_MODELS].map((m) => `'${m}'`).join(', ')} for FIM completion`) };
+    }
+    if (typeof params.prompt !== 'string' || !params.prompt)
+        return { error: invalidParameters("'prompt' is a required string") };
+    if (params.suffix !== undefined && params.suffix !== null && typeof params.suffix !== 'string')
+        return { error: invalidParameters("'suffix' must be a string") };
+    // THE DIVERGENCE FROM CHAT: here `logprobs` is an INTEGER ("Return log probabilities for top N
+    // tokens (max: 20)"), where the chat endpoint's `logprobs` is a boolean. Same key name, different
+    // type, on the same vendor — modelled rather than smoothed over.
+    let logprobs;
+    if (params.logprobs !== undefined && params.logprobs !== null) {
+        const v = params.logprobs;
+        if (typeof v !== 'number' || !Number.isInteger(v) || v < 0 || v > 20)
+            return { error: invalidParameters("'logprobs' must be an integer between 0 and 20") };
+        logprobs = v;
+    }
+    let maxTokens;
+    if (params.max_tokens !== undefined && params.max_tokens !== null) {
+        const v = params.max_tokens;
+        if (typeof v !== 'number' || !Number.isInteger(v) || v < 1)
+            return { error: invalidParameters("'max_tokens' must be an integer >= 1") };
+        maxTokens = v;
+    }
+    let stop;
+    if (params.stop !== undefined && params.stop !== null) {
+        const s = asStringArray(params.stop);
+        if (s === null)
+            return { error: invalidParameters("'stop' must be a string or an array of strings") };
+        if (s.length > MAX_STOP_SEQUENCES)
+            return { error: invalidParameters(`'stop' supports up to ${MAX_STOP_SEQUENCES} sequences`) };
+        stop = s;
+    }
+    if (params.echo !== undefined && params.echo !== null && typeof params.echo !== 'boolean')
+        return { error: invalidParameters("'echo' must be a boolean") };
+    // UNMODELED, NOT FAKED. DeepSeek's FIM endpoint really does declare `stream` / `stream_options`,
+    // and the twin does not model its SSE shape yet (`deepseek.completions.streaming`, todo). Serving
+    // a unary text_completion to a caller who asked for a stream is the fake success the bar forbids
+    // — a client reading `text/event-stream` would hang or mis-parse — so the twin refuses BY NAME
+    // and says it is the twin's gap, not the vendor's.
+    if (params.stream === true) {
+        // NO `type` — this is a 422 and the rule at `invalidParameters` is universal, not a property of
+        // one helper. §9 round two, BLOCKER 2: this envelope was written before that fix landed and kept
+        // emitting `invalid_request_error`, which the SDK's discriminator table resolves to 400.
+        return { error: { status: 422, body: errBody('the DeepSeek twin does not model streaming on /beta/completions yet (deepseek.completions.streaming); omit `stream` or use /chat/completions') } };
+    }
+    if (params.stream !== undefined && params.stream !== null && typeof params.stream !== 'boolean')
+        return { error: invalidParameters("'stream' must be a boolean") };
+    return {
+        args: {
+            model: params.model,
+            prompt: params.prompt,
+            ...(typeof params.suffix === 'string' ? { suffix: params.suffix } : {}),
+            echo: params.echo === true,
+            ...(maxTokens !== undefined ? { maxTokens } : {}),
+            ...(stop !== undefined ? { stop } : {}),
+            ...(logprobs !== undefined ? { logprobs } : {}),
+        },
+    };
+}
+function buildFimCompletion(args, hitTokens, occurredAt) {
+    let text = stubFimText(args.model, args.prompt, args.suffix);
+    let finish = 'stop';
+    let stopAt = -1;
+    for (const s of args.stop ?? []) {
+        if (!s)
+            continue;
+        const i = text.indexOf(s);
+        if (i >= 0 && (stopAt < 0 || i < stopAt))
+            stopAt = i;
+    }
+    if (stopAt >= 0)
+        text = text.slice(0, stopAt);
+    if (args.maxTokens !== undefined && estimateTokens(text) > args.maxTokens) {
+        text = text.slice(0, args.maxTokens * 4);
+        finish = 'length';
+    }
+    // "`echo`: Return prompt with completion" — so the prompt is PREPENDED to the returned text.
+    const out = args.echo ? `${args.prompt}${text}` : text;
+    const promptTokens = estimateTokens(args.prompt) + estimateTokens(args.suffix ?? '');
+    const completionTokens = estimateTokens(text);
+    return {
+        id: `cmpl-twin-${fnv1a(args.prompt + (args.suffix ?? '')).toString(36)}`,
+        object: 'text_completion',
+        created: nowEpoch(occurredAt),
+        model: args.model,
+        choices: [{
+                index: 0,
+                text: out,
+                finish_reason: finish,
+                logprobs: args.logprobs === undefined ? null : { tokens: [], token_logprobs: [], text_offset: [], top_logprobs: [] },
+            }],
+        usage: buildUsage(promptTokens, completionTokens, hitTokens),
+        system_fingerprint: stubFingerprint(`${args.model}|fim`),
+    };
+}
+// ── Files (stateful) ────────────────────────────────────────────────────────────────────
+/** "`purpose`: Must be `user_data`" — a closed set of one (api-docs.deepseek.com/guides/files_api). */
+const FILE_PURPOSES = new Set(['user_data']);
+/** "Supported formats: JPEG, PNG, GIF, and WebP" (same page; `@ai-sdk/deepseek`'s
+ *  `supportedMediaTypes` / `supportedFilenameExtensions` enforce the identical sets client-side). */
+const FILE_MEDIA_TYPES = new Set(['image/gif', 'image/jpeg', 'image/jpg', 'image/png', 'image/webp']);
+const FILE_EXTENSIONS = new Set(['gif', 'jpeg', 'jpg', 'png', 'webp']);
+/** "Max upload size: 64 MiB"; "Max filename: 512 characters". */
+const MAX_FILE_BYTES = 64 * 1024 * 1024;
+const MAX_FILENAME_LENGTH = 512;
+/** "Lifetime range of 3600-2592000 seconds (1 hour to 30 days)". */
+const MIN_EXPIRES_SECONDS = 3600;
+const MAX_EXPIRES_SECONDS = 2_592_000;
+/** "`limit`: 1-1000 files per request". */
+const MAX_FILE_LIST_LIMIT = 1000;
+function fileExtension(filename) {
+    const i = filename.lastIndexOf('.');
+    return i === -1 ? '' : filename.slice(i + 1).toLowerCase();
+}
+async function createFile(params, req) {
+    const purpose = typeof params.purpose === 'string' ? params.purpose : '';
+    if (!purpose)
+        return invalidParameters("'purpose' is a required property");
+    if (!FILE_PURPOSES.has(purpose))
+        return invalidParameters(`'purpose' must be 'user_data' (got '${purpose}')`);
+    const filename = typeof params.filename === 'string' && params.filename ? params.filename : '';
+    if (!filename)
+        return invalidParameters("'file' is a required property");
+    if ([...filename].length > MAX_FILENAME_LENGTH)
+        return invalidParameters(`'filename' must be at most ${MAX_FILENAME_LENGTH} characters`);
+    const mediaType = typeof params.media_type === 'string' ? params.media_type.split(';', 1)[0].trim().toLowerCase() : '';
+    // DeepSeek's Files API is IMAGE-ONLY. A caller uploading a .jsonl batch file (the OpenAI habit)
+    // must be refused, not stored: this vendor has no batch surface here at all.
+    if (!FILE_MEDIA_TYPES.has(mediaType) && !FILE_EXTENSIONS.has(fileExtension(filename))) {
+        return invalidParameters('DeepSeek file uploads support JPEG, PNG, GIF, and WebP images');
+    }
+    const content = typeof params.content === 'string' ? params.content : '';
+    const bytes = typeof params.bytes === 'number' ? params.bytes : content.length;
+    if (bytes > MAX_FILE_BYTES)
+        return invalidParameters(`DeepSeek file uploads must not exceed ${MAX_FILE_BYTES} bytes`);
+    // `expires_after[anchor]` / `expires_after[seconds]` arrive as the flat form-field names the
+    // vendor documents and `@ai-sdk/deepseek` appends verbatim (src/files/deepseek-files.ts).
+    const anchor = params['expires_after[anchor]'];
+    const secondsRaw = params['expires_after[seconds]'];
+    let expiresAt;
+    if (anchor !== undefined || secondsRaw !== undefined) {
+        if (anchor !== undefined && anchor !== 'created_at')
+            return invalidParameters("'expires_after[anchor]' must be 'created_at'");
+        const seconds = Number(secondsRaw);
+        if (!Number.isInteger(seconds) || seconds < MIN_EXPIRES_SECONDS || seconds > MAX_EXPIRES_SECONDS) {
+            return invalidParameters(`'expires_after[seconds]' must be an integer between ${MIN_EXPIRES_SECONDS} and ${MAX_EXPIRES_SECONDS}`);
+        }
+        expiresAt = nowEpoch(req.occurredAt) + seconds;
+    }
+    const id = nextFileId(req.root);
+    await applyTwinWrite(SERVICE, {
+        operation: 'file.create',
+        subjectType: 'file',
+        subjectId: id,
+        fields: {
+            object: 'file', bytes, created_at: nowEpoch(req.occurredAt), filename, purpose,
+            ...(expiresAt !== undefined ? { expires_at: expiresAt } : {}),
+            _content: content,
+        },
+        ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+        actor: { kind: 'agent' },
+    }, req.root);
+    return { status: 200, body: fileView(getRow('file', id, req.root) ?? {}) };
+}
+function fileView(r) {
+    return {
+        id: r.id, object: 'file', bytes: r.bytes, created_at: r.created_at, filename: r.filename, purpose: r.purpose,
+        ...(r.expires_at !== undefined ? { expires_at: r.expires_at } : {}),
+    };
+}
+function listFiles(query, root) {
+    const purpose = query.get('purpose');
+    if (purpose !== null && !FILE_PURPOSES.has(purpose))
+        return invalidParameters("'purpose' must be 'user_data'");
+    const order = query.get('order');
+    if (order !== null && order !== 'asc' && order !== 'desc')
+        return invalidParameters("'order' must be 'asc' or 'desc'");
+    const limitRaw = query.get('limit');
+    let limit = MAX_FILE_LIST_LIMIT;
+    if (limitRaw !== null) {
+        const v = Number(limitRaw);
+        if (!Number.isInteger(v) || v < 1 || v > MAX_FILE_LIST_LIMIT)
+            return invalidParameters(`'limit' must be an integer between 1 and ${MAX_FILE_LIST_LIMIT}`);
+        limit = v;
+    }
+    let data = rows('file', root).filter((r) => !r._deleted).map(fileView);
+    data.sort((a, b) => Number(a.created_at) - Number(b.created_at) || String(a.id).localeCompare(String(b.id)));
+    if (order === 'desc')
+        data.reverse();
+    const after = query.get('after');
+    if (after !== null) {
+        const idx = data.findIndex((f) => f.id === after);
+        if (idx === -1)
+            return invalidParameters(`'after' cursor "${after}" is not a known file id`);
+        data = data.slice(idx + 1);
+    }
+    const has_more = data.length > limit;
+    const page = data.slice(0, limit);
+    // DeepSeek's own list example carries `first_id` / `last_id` alongside `has_more`
+    // (api-docs.deepseek.com/guides/files_api) — the cursor bookends a caller pages with. They are
+    // omitted on an empty page rather than emitted as null, because the vendor's example shows file
+    // ids there and a null would be a shape this twin cannot source.
+    return {
+        status: 200,
+        body: {
+            object: 'list',
+            data: page,
+            ...(page.length > 0 ? { first_id: page[0].id, last_id: page[page.length - 1].id } : {}),
+            has_more,
+        },
+    };
+}
+// ── public entry: cross-cutting protocol (auth / rate-limit) then route ──────────────────
+export async function handleDeepSeekTwinRequest(req) {
+    const method = req.method.toUpperCase();
+    if (req.headers !== undefined || req.apiKey !== undefined) {
+        const authErr = checkAuth(req);
+        if (authErr)
+            return authErr;
+    }
+    // 429 is non-deterministic in production, so the twin exposes a DETERMINISTIC opt-in trigger.
+    if (triggered(req, 'x-twin-force-rate-limit'))
+        return rateLimitError();
+    return routeDeepSeek(req, method);
+}
+// ── router ──────────────────────────────────────────────────────────────────────────────
+async function routeDeepSeek(req, method) {
+    const [rawPath, rawQuery] = req.path.split('?');
+    const path = (rawPath ?? '/').replace(/\/+$/, '') || '/';
+    const query = new URLSearchParams(rawQuery ?? '');
+    const dec = (s) => decodeURIComponent(s);
+    // D3: a read-only twin rejects any mutation with a vendor-shaped error.
+    if (req.readOnly && method !== 'GET') {
+        // Same rule again (§9 round two, NIT 6): nothing first-party names a `type` for a 405 on this
+        // vendor, and `invalid_request_error` would resolve to 400 in the SDK's own table.
+        return { status: 405, body: errBody('twin is read-only; omit readOnly to accept writes') };
+    }
+    // DeepSeek's Anthropic-compatible surface is REAL vendor surface this twin does not model yet.
+    // It fails like an unmodeled operation rather than silently answering as if it were the
+    // OpenAI-shaped endpoint (`deepseek.anthropic.messages`, todo).
+    if (path === DEEPSEEK_ANTHROPIC_PREFIX || path.startsWith(`${DEEPSEEK_ANTHROPIC_PREFIX}/`)) {
+        return notFound(`The DeepSeek twin does not model the Anthropic-compatible surface (${method} ${path}) yet.`);
+    }
+    // THE BETA BASE URL. `https://api.deepseek.com/beta` unlocks assistant-prefix completion and
+    // strict tool calls, and is where FIM completion lives — nothing else changes.
+    const beta = path === DEEPSEEK_BETA_PREFIX || path.startsWith(`${DEEPSEEK_BETA_PREFIX}/`);
+    const rest = beta ? (path.slice(DEEPSEEK_BETA_PREFIX.length) || '/') : path;
+    const seg = rest.replace(/^\/+/, '').split('/').filter(Boolean);
+    // A GET carries no body by definition, so it never goes through the body-format gate. A DELETE
+    // likewise: `DELETE /files/{id}` addresses its subject by path.
+    const parsed = method === 'GET' || method === 'DELETE' ? { params: {} } : parseJson(req.body);
+    if ('error' in parsed)
+        return parsed.error;
+    const params = parsed.params;
+    // ---- models (published catalog + anything a pull observed) ----
+    if (seg[0] === 'models' && seg.length === 1 && method === 'GET') {
+        return { status: 200, body: { object: 'list', data: servedModels(req.root) } };
+    }
+    // ---- user balance ----
+    if (seg[0] === 'user' && seg[1] === 'balance' && seg.length === 2 && method === 'GET') {
+        return { status: 200, body: servedBalance(req.root) };
+    }
+    // ---- chat completions (the generative stub; envelope is faithful) ----
+    if (seg[0] === 'chat' && seg[1] === 'completions' && seg.length === 2 && method === 'POST') {
+        const validated = validateChat(params, beta);
+        if ('error' in validated)
+            return validated.error;
+        const args = validated.args;
+        // 402 is a real DeepSeek status with no OpenAI counterpart, and it is STATE-DRIVEN here: an
+        // account whose balance says `is_available:false` cannot complete. That makes the 402 path a
+        // fact about the twin's projection rather than a header trick.
+        if (!servedBalance(req.root).is_available)
+            return insufficientBalance();
+        // §9 ROUND TWO, SHOULD-FIX 1: this used to fall through to the UNARY builder whenever a sink was
+        // absent, so a `stream: true` request could be answered with a JSON blob a client reading
+        // `text/event-stream` cannot parse — the same fake success `deepseek.completions.refuses_unmodeled_streaming`
+        // exists to forbid on the FIM endpoint, live on the primary one. A streaming request with no
+        // sink is now a loud refusal rather than a silent downgrade.
+        if (args.stream && !req.sseSink) {
+            return { status: 422, body: errBody("'stream' was requested but this caller supplied no SSE sink; the twin refuses to answer a streaming request with a unary body") };
+        }
+        const result = args.stream && req.sseSink
+            ? streamChat(args, req.sseSink, req.occurredAt, req.scenarioEngine, req.root)
+            : buildChatCompletion(args, req.occurredAt, req.scenarioEngine, req.root);
+        if (isEnvelope(result))
+            return result;
+        // Record the context-cache prefix units this completion creates (deepseek-cache.ts) so a
+        // follow-up turn genuinely reports `prompt_cache_hit_tokens`.
+        await recordCachePrefixes(args.messages, { role: 'assistant', content: result.choices[0].message.content ?? '', ...(result.choices[0].message.tool_calls ? { tool_calls: result.choices[0].message.tool_calls } : {}) }, req.occurredAt, req.root);
+        return { status: 200, body: result };
+    }
+    // ---- FIM completions (BETA ONLY) ----
+    if (seg[0] === 'completions' && seg.length === 1 && method === 'POST') {
+        // FIM lives at `https://api.deepseek.com/beta/completions`. On the non-beta base URL there is
+        // no such endpoint, so it must fail rather than quietly work.
+        if (!beta)
+            return notFound("FIM completion requires the beta base URL (append '/beta' to your base_url).");
+        const validated = validateFim(params);
+        if ('error' in validated)
+            return validated.error;
+        if (!servedBalance(req.root).is_available)
+            return insufficientBalance();
+        return { status: 200, body: buildFimCompletion(validated.args, 0, req.occurredAt) };
+    }
+    // ---- files (stateful) ----
+    if (seg[0] === 'files' && seg.length === 1 && method === 'POST')
+        return createFile(params, req);
+    if (seg[0] === 'files' && seg.length === 1 && method === 'GET')
+        return listFiles(query, req.root);
+    if (seg[0] === 'files' && seg.length === 2 && method === 'GET') {
+        const f = getRow('file', dec(seg[1]), req.root);
+        return f && !f._deleted ? { status: 200, body: fileView(f) } : notFound(`No such File object: ${dec(seg[1])}`);
+    }
+    if (seg[0] === 'files' && seg.length === 2 && method === 'DELETE') {
+        const fid = dec(seg[1]);
+        const f = getRow('file', fid, req.root);
+        if (!f || f._deleted)
+            return notFound(`No such File object: ${fid}`);
+        await applyTwinWrite(SERVICE, {
+            operation: 'file.delete', subjectType: 'file', subjectId: fid, fields: { _deleted: true, object: 'file' },
+            ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'agent' },
+        }, req.root);
+        return { status: 200, body: { id: fid, object: 'file', deleted: true } };
+    }
+    // Unmodeled operation → fail like the vendor (never a fake success).
+    return notFound(`Unknown request URL: ${method} ${path}.`);
+}