@volter/twin-deepseek 0.1.0

package/src/deepseek-scenario.ts

@@ -0,0 +1,188 @@
+// The deepseek pack's scenario system on the kernel's ONE engine (@volter/world-core scenario.ts):
+// DeepSeek chat-completions vocabulary + the scripted-turn respond shape. THE KERNEL ENGINE IS NOT
+// RE-IMPLEMENTED HERE — this file is only the pack's adapter (features, matchers, load
+// validation) plus the realizer that turns a validated `respond` into DeepSeek's own envelope.
+//
+// The handler FILE (handlers/deepseek.json in a world dir) is the only write surface; the doors
+// (`GET /twin`, `GET /twin/scenario`) are read-only. Scenario support is twin-only scaffolding
+// for eval worlds, NOT vendor surface, so it is deliberately absent from the capability
+// manifest (ADDING_A_TWIN.md §6, "Scenario scripting") and gated by deepseek-scenario.test.ts.
+import { getActiveWorldStore, parseScenarioDocument, type PackScenarioAdapter, ScenarioError, type ScenarioDocument, ScenarioEngine, type ScenarioFeatures } from '@volter/world-core';
+import { contentToText, lastUserText } from './deepseek-stub.ts';
+import type { DeepSeekMessageParam, DeepSeekToolCall } from './deepseek-types.ts';
+
+export type DeepSeekScenarioRequest = {
+  model: string;
+  messages: DeepSeekMessageParam[];
+  tools?: unknown;
+  /** DeepSeek-specific: 'enabled' | 'disabled'. Scriptable because thinking mode is what decides
+   *  whether a turn carries `reasoning_content` at all. */
+  thinking?: string;
+};
+export type DeepSeekScenarioEngine = ScenarioEngine<DeepSeekScenarioRequest>;
+
+export type ScenarioToolCall = { name: string; arguments: Record<string, unknown>; id?: string };
+
+/**
+ * What a deepseek handler may script. `reasoning` becomes the assistant turn's
+ * `reasoning_content` (DeepSeek-specific — OpenAI has no such field); `error` scripts one of
+ * DeepSeek's own documented failure statuses rather than a success.
+ */
+export type DeepSeekScenarioRespond = {
+  text?: string;
+  reasoning?: string;
+  toolCalls?: ScenarioToolCall | ScenarioToolCall[];
+  finishReason?: 'stop' | 'length' | 'content_filter' | 'tool_calls' | 'insufficient_system_resource';
+  /** A scripted vendor failure. Every type here maps onto a status DeepSeek's own error table
+   *  publishes (api-docs.deepseek.com/quick_start/error_codes): 429, 402, 500 and 503 respectively.
+   *  `insufficient_balance` and `server_overloaded` have no OpenAI counterpart. */
+  error?: { type: 'rate_limit_exceeded' | 'insufficient_balance' | 'internal_server_error' | 'server_overloaded'; message?: string };
+};
+
+export type ScriptedResult = {
+  text: string | null;
+  reasoning: string | null;
+  toolCalls: DeepSeekToolCall[];
+  finishReason: 'stop' | 'length' | 'content_filter' | 'tool_calls' | 'insufficient_system_resource';
+};
+
+const RESPOND_KEYS = new Set(['text', 'reasoning', 'toolCalls', 'finishReason', 'error']);
+// DeepSeek's own finish_reason set — note `insufficient_system_resource`, which has no OpenAI
+// counterpart, and the absence of OpenAI's `function_call`.
+const FINISH_REASONS = new Set(['stop', 'length', 'content_filter', 'tool_calls', 'insufficient_system_resource']);
+const ERROR_TYPES = new Set(['rate_limit_exceeded', 'insufficient_balance', 'internal_server_error', 'server_overloaded']);
+const THINKING_STATES = new Set(['enabled', 'disabled']);
+const nonEmptyString = (cond: unknown): cond is string => typeof cond === 'string' && cond.length > 0;
+
+function lastToolResultNames(messages: DeepSeekMessageParam[]): Set<string> {
+  const names = new Set<string>();
+  const last = messages[messages.length - 1] as { role?: string; tool_call_id?: unknown } | undefined;
+  if (!last || last.role !== 'tool' || typeof last.tool_call_id !== 'string') return names;
+  for (const m of messages) {
+    const am = m as { role?: string; tool_calls?: Array<{ id?: unknown; function?: { name?: unknown } }> };
+    if (am.role !== 'assistant' || !Array.isArray(am.tool_calls)) continue;
+    for (const tc of am.tool_calls) {
+      if (tc?.id === last.tool_call_id && typeof tc?.function?.name === 'string') names.add(tc.function.name);
+    }
+  }
+  return names;
+}
+
+function toolNames(tools: unknown): string[] {
+  if (!Array.isArray(tools)) return [];
+  return (tools as Array<{ function?: { name?: unknown }; name?: unknown }>).map((t) =>
+    typeof t?.function?.name === 'string' ? t.function.name : typeof t?.name === 'string' ? t.name : null,
+  ).filter((n): n is string => n !== null);
+}
+
+export const deepseekScenarioAdapter: PackScenarioAdapter<DeepSeekScenarioRequest> = {
+  vendor: 'deepseek',
+  features: (req): ScenarioFeatures => ({
+    model: req.model,
+    lastUserText: lastUserText(req.messages).slice(0, 300),
+    tools: toolNames(req.tools),
+    lastMessageIsToolResult: (req.messages[req.messages.length - 1] as { role?: string } | undefined)?.role === 'tool',
+    toolResultFor: [...lastToolResultNames(req.messages)],
+    thinking: req.thinking ?? 'enabled',
+  }),
+  matchers: {
+    modelEquals: (req, cond) => nonEmptyString(cond) && req.model === cond,
+    userTextIncludes: (req, cond) => nonEmptyString(cond) && lastUserText(req.messages).toLowerCase().includes(cond.toLowerCase()),
+    anyTextIncludes: (req, cond) => nonEmptyString(cond) && req.messages.map((m) => contentToText(m.content)).join('\n').toLowerCase().includes(cond.toLowerCase()),
+    lastMessageIsToolResult: (req, cond) => typeof cond === 'boolean' && ((req.messages[req.messages.length - 1] as { role?: string } | undefined)?.role === 'tool') === cond,
+    toolResultFor: (req, cond) => nonEmptyString(cond) && lastToolResultNames(req.messages).has(cond),
+    hasTool: (req, cond) => nonEmptyString(cond) && toolNames(req.tools).includes(cond),
+    // DeepSeek-specific: script behaviour by thinking mode (V4 models think by default).
+    thinkingEquals: (req, cond) => nonEmptyString(cond) && (req.thinking ?? 'enabled') === cond,
+  },
+  text: (req) => req.messages.map((m) => contentToText(m.content)).join('\n'),
+  validateOn: (on) => {
+    for (const k of ['modelEquals', 'userTextIncludes', 'anyTextIncludes', 'toolResultFor', 'hasTool'] as const) {
+      if (on[k] !== undefined && (typeof on[k] !== 'string' || !on[k])) return `on.${k} is a non-empty string`;
+    }
+    if (on.lastMessageIsToolResult !== undefined && typeof on.lastMessageIsToolResult !== 'boolean') return 'on.lastMessageIsToolResult is a boolean';
+    if (on.thinkingEquals !== undefined) {
+      if (typeof on.thinkingEquals !== 'string' || !THINKING_STATES.has(on.thinkingEquals)) {
+        return `on.thinkingEquals is one of ${[...THINKING_STATES].join(', ')}`;
+      }
+    }
+    return null;
+  },
+  validateRespond: (respond) => {
+    if (typeof respond !== 'object' || respond === null || Array.isArray(respond)) return 'respond is an object { text?, reasoning?, toolCalls?, finishReason?, error? }';
+    const r = respond as Record<string, unknown>;
+    for (const k of Object.keys(r)) if (!RESPOND_KEYS.has(k)) return `respond: unknown key "${k}" (valid: ${[...RESPOND_KEYS].join(', ')})`;
+    if (r.error !== undefined) {
+      const e = r.error as Record<string, unknown>;
+      if (!e || typeof e !== 'object' || Array.isArray(e)) return 'respond.error is an object { type, message? }';
+      if (typeof e.type !== 'string' || !ERROR_TYPES.has(e.type)) return `respond.error.type is one of ${[...ERROR_TYPES].join(', ')}`;
+      if (e.message !== undefined && typeof e.message !== 'string') return 'respond.error.message is a string';
+      // An error handler scripts a FAILURE — mixing it with success content is a mis-typed rule.
+      for (const k of ['text', 'reasoning', 'toolCalls', 'finishReason']) if (r[k] !== undefined) return `respond.error cannot be combined with respond.${k}`;
+      return null;
+    }
+    if (r.text !== undefined && typeof r.text !== 'string') return 'respond.text is a string';
+    if (r.reasoning !== undefined && typeof r.reasoning !== 'string') return 'respond.reasoning is a string';
+    if (r.finishReason !== undefined && (typeof r.finishReason !== 'string' || !FINISH_REASONS.has(r.finishReason))) return `respond.finishReason is one of ${[...FINISH_REASONS].join(', ')}`;
+    if (r.toolCalls !== undefined) {
+      for (const tc of Array.isArray(r.toolCalls) ? r.toolCalls : [r.toolCalls]) {
+        const t = tc as Record<string, unknown>;
+        if (!t || typeof t !== 'object' || Array.isArray(t)) return 'respond.toolCalls entries are objects';
+        if (typeof t.name !== 'string' || !t.name) return 'respond.toolCalls[].name is a non-empty string';
+        if (!t.arguments || typeof t.arguments !== 'object' || Array.isArray(t.arguments)) return 'respond.toolCalls[].arguments is an object';
+        if (t.id !== undefined && typeof t.id !== 'string') return 'respond.toolCalls[].id is a string';
+      }
+    }
+    if (r.text === undefined && r.toolCalls === undefined) return 'respond needs text or toolCalls (or an error)';
+    return null;
+  },
+};
+
+/** Load + STRICTLY validate a scenario document. A malformed file throws at load with what is
+ *  wrong — never a silent ignore-and-stub (a mis-typed rule falling back is a fake success). */
+export function loadDeepSeekScenarioDocument(path: string): ScenarioDocument {
+  let parsed: unknown;
+  try {
+    // Read through the ACTIVE WorldStore, never the filesystem directly (runtime contract
+    // R12b): the handlers document is WORLD STATE, so a MemoryWorldStore / DO-backed world
+    // serves ITS OWN scenario instead of whatever happens to sit on the host disk — and the
+    // serve path stays workerd-clean. A missing document keeps the historical ENOENT wording,
+    // so the loud load-time failure reads byte-identically to the read it replaces.
+    const raw = getActiveWorldStore().read(path);
+    if (raw === null) throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new ScenarioError(`deepseek scenario: cannot read/parse ${path}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  return parseScenarioDocument(parsed, deepseekScenarioAdapter);
+}
+
+export function createDeepSeekScenarioEngine(document?: ScenarioDocument): DeepSeekScenarioEngine {
+  return new ScenarioEngine(deepseekScenarioAdapter, document);
+}
+
+/**
+ * Turn a validated `respond` into the pack's own faithful assistant turn.
+ *
+ * §9 ROUND TWO: this used a MODULE-LEVEL counter, so two identical scripted requests in one
+ * process got different `tool_calls[].id`s and the same request answered differently after a
+ * restart — a serve-path determinism violation (CLAUDE.md: a served response is a pure function of
+ * (request, stored state)). The id is now derived from the scripted call's own content and its
+ * position in the handler, exactly as the non-scenario path derives its ids.
+ */
+export function realizeDeepSeekRespond(respond: DeepSeekScenarioRespond): ScriptedResult {
+  const toolCalls: DeepSeekToolCall[] = [];
+  const scripted = respond.toolCalls ? (Array.isArray(respond.toolCalls) ? respond.toolCalls : [respond.toolCalls]) : [];
+  scripted.forEach((tc, index) => {
+    const seed = `${index}:${tc.name}:${JSON.stringify(tc.arguments)}`;
+    let h = 0x811c9dc5;
+    for (let i = 0; i < seed.length; i++) { h ^= seed.charCodeAt(i); h = Math.imul(h, 0x01000193); }
+    toolCalls.push({ id: tc.id ?? `call_scripted_${(h >>> 0).toString(36)}`, type: 'function', function: { name: tc.name, arguments: JSON.stringify(tc.arguments) } });
+  });
+  return {
+    text: respond.text ?? (toolCalls.length ? null : ''),
+    reasoning: respond.reasoning ?? null,
+    toolCalls,
+    finishReason: respond.finishReason ?? (toolCalls.length ? 'tool_calls' : 'stop'),
+  };
+}

package/src/deepseek-server.ts

@@ -0,0 +1,201 @@
+// DeepSeek twin HTTP server — serve the full DeepSeek twin handler over HTTP so the real
+// `@ai-sdk/deepseek` works UNMODIFIED: `createDeepSeek({ baseURL: 'http://127.0.0.1:<port>' })` for
+// the standard surface and `.../beta` for prefix completion + strict tool calls, exactly as a real
+// integrator configures it. There is NO `/v1` segment — DeepSeek's own base_url has none. JSON
+// bodies pass straight through. Writable by default; pass readOnly to reject mutations (D3).
+//
+// Streaming: when the request body has `"stream": true`, the server constructs a REAL SSE
+// response by feeding the handler an sseSink that writes each chunk in DeepSeek's `data: <json>\n\n`
+// wire format, ending with `data: [DONE]\n\n`. (The handler itself stays socket-free — the sink
+// is the only place a socket is touched, on the live HTTP path.)
+//
+// Multipart: POST /files takes `multipart/form-data`. The server
+// parses the form into the handler's JSON contract so the handler stays a pure JSON function.
+//
+// FETCH-FIRST (runtime contract R12b): the surface is the plain `createDeepSeekTwinFetch` and the
+// SERVER is one line of `Bun.serve` around it. This is a CUSTOM fetch, not the kernel adapter
+// (`createTwinFetchFromHandler`): SSE streaming plus the multipart adaptation genuinely exceed the
+// common shape — openai-server.ts is the reference for that lane.
+import { serveHttp } from '@volter/world-core';
+import { twinManifest, worldNow } from '@volter/world-core';
+import { createDeepSeekScenarioEngine, type DeepSeekScenarioEngine, loadDeepSeekScenarioDocument } from './deepseek-scenario.ts';
+import { DEEPSEEK_BETA_PREFIX, handleDeepSeekTwinRequest } from './deepseek-twin.ts';
+import type { SseEvent } from './deepseek-types.ts';
+
+function wantsStream(body: string): boolean {
+  if (!body) return false;
+  try {
+    return (JSON.parse(body) as { stream?: unknown })?.stream === true;
+  } catch {
+    return false;
+  }
+}
+
+function encodeSse(event: SseEvent): string {
+  if (event.done) return 'data: [DONE]\n\n';
+  return `data: ${JSON.stringify(event.data)}\n\n`;
+}
+
+// Both the standard and the beta chat endpoints stream. (`/beta/completions` — FIM — declares a
+// `stream` parameter too; the twin does not model its SSE shape yet and files it as
+// `deepseek.completions.streaming`, so it is deliberately absent here rather than served wrongly.)
+const STREAMABLE = new Set(['/chat/completions', `${DEEPSEEK_BETA_PREFIX}/chat/completions`]);
+
+async function multipartToJson(request: Request): Promise<string> {
+  try {
+    const form = await request.formData();
+    const out: Record<string, unknown> = {};
+    // Forward every scalar field generically. On DeepSeek that is `purpose` and the two
+    // `expires_after[...]` fields the vendor documents and @ai-sdk/deepseek appends verbatim
+    // (src/files/deepseek-files.ts). (§9 round one, SHOULD-FIX 6: this comment used to list
+    // `response_format`, `language` and `url` — Groq/OpenAI AUDIO-transcription fields that
+    // survived the clone. DeepSeek publishes no audio endpoint at all.)
+    for (const [key, value] of form.entries()) {
+      if (typeof value === 'string') {
+        // A repeated scalar field would arrive one entry at a time; kept generic rather than
+        // named after a field DeepSeek does not have.
+        if (key.endsWith('[]')) {
+          const k = key.slice(0, -2);
+          const prior = out[k];
+          out[k] = Array.isArray(prior) ? [...prior, value] : [value];
+        } else {
+          out[key] = value;
+        }
+      }
+    }
+    const file = form.get('file');
+    if (file instanceof File) {
+      const bytes = new Uint8Array(await file.arrayBuffer());
+      out.file = file.name || 'upload';
+      out.filename = file.name || 'upload';
+      // Base64 so binary image bytes survive the JSON handler contract intact.
+      out.content = Buffer.from(bytes).toString('base64');
+      // The declared media type is what DeepSeek's image-only Files API checks first.
+      out.media_type = file.type || '';
+      out.bytes = bytes.length;
+    }
+    return JSON.stringify(out);
+  } catch {
+    return '{}';
+  }
+}
+
+/** Options every DeepSeek-twin HTTP surface needs, independent of who owns the socket. */
+export interface DeepSeekTwinFetchOptions {
+  root?: string;
+  readOnly?: boolean;
+  scenarioPath?: string;
+}
+
+export function createDeepSeekTwinFetch(options: DeepSeekTwinFetchOptions): (request: Request) => Promise<Response> {
+  const readOnly = options.readOnly ?? false;
+  // Scenario scripting (deepseek-scenario.ts): a JSON scenario file — via the scenarioPath option or
+  // the TWIN_DEEPSEEK_SCENARIO env var — scripts chat completions. Loaded ONCE at startup (a
+  // malformed file fails loudly here, never silently).
+  const scenarioPath = options.scenarioPath ?? process.env.TWIN_DEEPSEEK_SCENARIO;
+  const scenarioEngine: DeepSeekScenarioEngine | undefined = scenarioPath ? createDeepSeekScenarioEngine(loadDeepSeekScenarioDocument(scenarioPath)) : undefined;
+  return async function deepSeekTwinFetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+    // THE READ DOORS (TWIN-PROGRAMMING-MODEL): discovery + inspection, read-only.
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin') {
+      return Response.json(twinManifest({
+        vendor: 'deepseek',
+        twinOf: 'DeepSeek Platform API (OpenAI-compatible; base_url has NO /v1 segment, and /beta unlocks prefix completion + strict tools)',
+        stateSentence: 'Seed image files through the ordinary API (POST /files, multipart, purpose=user_data) with any key; the context-cache ledger fills itself as you chat.',
+        behaviorSentence: "Chat completions are scripted by MSW-shaped handlers in the world dir (handlers/deepseek.json): {on:{userTextIncludes|anyTextIncludes|modelEquals|hasTool|toolResultFor|lastMessageIsToolResult|thinkingEquals|nthCall}, respond:{text|reasoning|toolCalls, finishReason?} | {error:{type:rate_limit_exceeded|insufficient_balance|internal_server_error|server_overloaded}}, once?, phase?}. Unmatched requests answer a labeled stub naming this door.",
+        exampleHandler: { on: { userTextIncludes: 'summarize', hasTool: 'search_docs' }, respond: { text: 'Scripted summary.' }, once: true },
+        engine: scenarioEngine as never,
+      }));
+    }
+    if (request.method === 'GET' && url.pathname.replace(/\/+$/, '') === '/twin/scenario') {
+      return Response.json(scenarioEngine ? scenarioEngine.status() : { vendor: 'deepseek', handlers: [], misses: 0, recentMisses: [] });
+    }
+
+    const path = url.pathname + (url.search || '');
+    // Collapse REPEATED slashes as well as the trailing one, exactly as `routeDeepSeek` does when
+    // it builds `seg` (and as the budget's `splitQuery` does for its anchored rules). §9 ROUND
+    // TWO, SHOULD-FIX 1: the two normalizations disagreed, so `POST /beta//chat/completions` with
+    // `stream: true` reached the streaming ROUTE but missed this STREAMABLE set and was answered
+    // with a unary JSON body to a client reading text/event-stream.
+    const cleanPath = url.pathname.replace(/\/{2,}/g, '/').replace(/\/+$/, '');
+    const contentType = request.headers.get('content-type') ?? '';
+
+    const passHeaders: Record<string, string> = {};
+    for (const k of ['authorization', 'x-twin-force-rate-limit']) {
+      const v = request.headers.get(k);
+      if (v !== null) passHeaders[k] = v;
+    }
+
+    let body = '';
+    if (request.method !== 'GET') {
+      body = contentType.includes('multipart/form-data') ? await multipartToJson(request) : await request.text();
+    }
+
+    // Streaming POST → a real text/event-stream response built from the sink.
+    //
+    // Events are COLLECTED first, then framed. The handler is synchronous-fast, so buffering
+    // costs nothing — and it is what lets a PRE-STREAM failure (a 422 for an unknown model,
+    // a 400 for a body with no `messages`, auth 401, rate-limit 429) answer with its REAL
+    // status and the vendor's JSON error envelope. Emitting the refusal as a lone `data:`
+    // frame inside a 200 text/event-stream was a FAKE SUCCESS the in-process path could not
+    // see: `handleDeepSeekTwinRequest` returns 422 for `model: "nope"` while the wire
+    // returned 200, so every verify asserting that 422 asserted a status the socket never
+    // carried. DeepSeek rejects a bad request BEFORE opening the event stream.
+    if (!readOnly && request.method.toUpperCase() === 'POST' && STREAMABLE.has(cleanPath) && wantsStream(body)) {
+      const events: SseEvent[] = [];
+      const { status, body: out, headers: errHeaders } = await handleDeepSeekTwinRequest({
+        ...(scenarioEngine ? { scenarioEngine } : {}),
+        method: request.method, path, body, readOnly, occurredAt: worldNow(), headers: passHeaders,
+        ...(options.root !== undefined ? { root: options.root } : {}), sseSink: (e: SseEvent) => events.push(e),
+      });
+      // No `x-request-id`: DeepSeek documents no such response header, and §6's figma precedent
+      // is that a twin declines to fabricate headers the vendor does not publish (§9 NIT 10).
+      if (status >= 400) {
+        return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', ...(errHeaders ?? {}) } });
+      }
+      const stream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          const enc = new TextEncoder();
+          for (const e of events) controller.enqueue(enc.encode(encodeSse(e)));
+          controller.close();
+        },
+      });
+      return new Response(stream, { headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache' } });
+    }
+
+    // Defensive: a handler throw must become a vendor-shaped 500, never an escaped exception
+    // (ADDING_A_TWIN.md §8, "In-process server harnesses … contain handler errors").
+    let status: number;
+    let out: unknown;
+    let outHeaders: Record<string, string> | undefined;
+    try {
+      const res = await handleDeepSeekTwinRequest({
+        ...(scenarioEngine ? { scenarioEngine } : {}),
+        method: request.method, path, body, readOnly,
+        occurredAt: worldNow(), headers: passHeaders,
+        ...(options.root !== undefined ? { root: options.root } : {}),
+      });
+      status = res.status; out = res.body; outHeaders = res.headers;
+    } catch (err) {
+      return new Response(JSON.stringify({ error: { message: `twin handler error: ${err instanceof Error ? err.message : String(err)}`, type: 'internal_server_error' } }), {
+        status: 500, headers: { 'content-type': 'application/json' },
+      });
+    }
+
+    // NOTE there is deliberately no raw/string-body branch. The clone this pack came from had one
+    // for file-content downloads, `response_format:'text'` transcripts and a TTS stub body —
+    // three surfaces DeepSeek does not have (its Files API is image upload only, and it publishes
+    // no audio endpoints). `handleDeepSeekTwinRequest` never returns a string body, so the branch
+    // was dead code whose comment asserted vendor surface that does not exist (§9, SHOULD-FIX 6).
+    return new Response(JSON.stringify(out), { status, headers: { 'content-type': 'application/json', ...(outHeaders ?? {}) } });
+  };
+}
+
+export async function createDeepSeekTwinServer(options: { root?: string; port?: number; readOnly?: boolean; scenarioPath?: string }): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    fetch: createDeepSeekTwinFetch(options),
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/src/deepseek-stub.ts

@@ -0,0 +1,200 @@
+// THE GENERATIVE-STUB CORE — the deterministic labeled answer this twin gives where the vendor
+// runs a model.
+//
+// The twin CANNOT run the model — there are no weights here. So `POST /chat/completions` returns a
+// DETERMINISTIC STUB completion that is CLEARLY a twin stub, NEVER pretending to be real model
+// output, and the same is true of `reasoning_content` and the beta FIM endpoint. What IS faithful
+// is the ENTIRE PROTOCOL ENVELOPE: the response shape, the SSE chunk sequence, the `tool_calls`
+// shape, `finish_reason`, and DeepSeek's KV-cache-bearing `usage`.
+//
+// SERVE-PATH DETERMINISM (CLAUDE.md): every number below is a pure function of (request, stored
+// state). Note what is NOT here: DeepSeek's cache-hit accounting is NOT a random split and NOT a
+// clock reading — it is computed from the twin's own observed cache-prefix ledger
+// (deepseek-cache.ts), so a replay is byte-identical and a genuine prefix reuse is genuinely
+// reported as a hit.
+//
+// The stub IS the twin's answer: the manifest's chat, reasoning and FIM capabilities are claimed
+// on the envelope and the determinism. See the README ## Coverage.
+
+import type { DeepSeekMessageParam, DeepSeekUsage } from './deepseek-types.ts';
+
+/** Deterministic token estimate for a string: ~1 token per 4 chars (faithful order of magnitude;
+ *  deterministic so usage counts are assertable, like the vendor's tokenizer on a fixed input).
+ *  Never zero for non-empty text. */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  return Math.max(1, Math.ceil(text.length / 4));
+}
+
+/** Flatten a chat message's content (string OR content-part array) to its text for token counting
+ *  / echo. Non-text parts contribute their JSON length so the count is deterministic and reflects
+ *  payload size. */
+export function contentToText(content: DeepSeekMessageParam['content']): string {
+  if (typeof content === 'string') return content;
+  if (content === null || content === undefined) return '';
+  if (!Array.isArray(content)) return '';
+  return content
+    .map((part) => {
+      if (part && typeof part === 'object' && (part as { type?: string }).type === 'text') {
+        return String((part as { text?: unknown }).text ?? '');
+      }
+      return JSON.stringify(part);
+    })
+    .join('\n');
+}
+
+/** Deterministic prompt-token count for one message (the unit the cache ledger also counts in, so
+ *  a prefix's hit tokens and the request's prompt tokens are measured the same way). */
+export function messageTokens(m: DeepSeekMessageParam): number {
+  let total = estimateTokens(contentToText(m.content));
+  if (m.name) total += estimateTokens(m.name);
+  if (typeof m.reasoning_content === 'string') total += estimateTokens(m.reasoning_content);
+  for (const tc of m.tool_calls ?? []) total += estimateTokens(JSON.stringify(tc));
+  return total;
+}
+
+/** Deterministic prompt-token count for the full set of messages. */
+export function countPromptTokens(messages: DeepSeekMessageParam[]): number {
+  let total = 0;
+  for (const m of messages) total += messageTokens(m);
+  return total;
+}
+
+/** The last user turn's text — the thing the stub echoes (deterministic, clearly labeled). */
+export function lastUserText(messages: DeepSeekMessageParam[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]!.role === 'user') return contentToText(messages[i]!.content);
+  }
+  return messages.length ? contentToText(messages[messages.length - 1]!.content) : '';
+}
+
+/**
+ * Build the deterministic stub ASSISTANT text. It is unmistakably a twin stub: it carries the
+ * `[twin-stub:<model>]` marker and echoes the prompt, so no caller can mistake it for real model
+ * output. Deterministic for a given prompt → assertable in tests.
+ */
+export function stubAssistantText(messages: DeepSeekMessageParam[], model: string): string {
+  const prompt = lastUserText(messages).trim();
+  const echo = prompt.length > 200 ? `${prompt.slice(0, 200)}…` : prompt;
+  return `[twin-stub:${model}] This is a deterministic stub from the DeepSeek twin (no model weights are run). Echoing your last message: ${echo || '(empty)'}`;
+}
+
+/**
+ * The `reasoning_content` DeepSeek returns while thinking mode is enabled (the default for every
+ * V4 model). A labeled stub, like the content — never a real chain of thought.
+ */
+export function stubReasoningText(messages: DeepSeekMessageParam[], model: string, effort: string): string {
+  return `[twin-stub:${model}] deterministic stub reasoning_content (no model weights are run, reasoning_effort=${effort}) for: ${lastUserText(messages).trim().slice(0, 120) || '(empty)'}`;
+}
+
+/** The deterministic FIM continuation for `POST /beta/completions`. Labeled, and it names the
+ *  suffix it was asked to bridge to so the caller can see the twin honoured the parameter. */
+export function stubFimText(model: string, prompt: string, suffix: string | undefined): string {
+  const bridge = suffix ? ` bridging to suffix "${suffix.slice(0, 60)}"` : '';
+  return `[twin-stub:${model}] deterministic fill-in-the-middle stub (no model weights are run)${bridge} after: ${prompt.trim().slice(0, 120) || '(empty)'}`;
+}
+
+/**
+ * Assemble DeepSeek's `usage`. The cache split is supplied by the caller (from the cache-prefix
+ * ledger) and the invariant DeepSeek's own docs state is enforced here rather than assumed:
+ * `prompt_cache_hit_tokens + prompt_cache_miss_tokens === prompt_tokens`
+ * (api-docs.deepseek.com/guides/kv_cache). `prompt_tokens_details.cached_tokens` mirrors the hit
+ * count — `@ai-sdk/deepseek`'s usage schema declares it and reads `prompt_cache_hit_tokens` for
+ * `cacheRead`, so the two must agree.
+ */
+export function buildUsage(
+  promptTokens: number,
+  completionTokens: number,
+  cacheHitTokens: number,
+  reasoningTokens = 0,
+): DeepSeekUsage {
+  const hit = Math.max(0, Math.min(cacheHitTokens, promptTokens));
+  return {
+    prompt_tokens: promptTokens,
+    completion_tokens: completionTokens,
+    total_tokens: promptTokens + completionTokens,
+    prompt_cache_hit_tokens: hit,
+    prompt_cache_miss_tokens: promptTokens - hit,
+    prompt_tokens_details: { cached_tokens: hit },
+    ...(reasoningTokens > 0 ? { completion_tokens_details: { reasoning_tokens: reasoningTokens } } : {}),
+  };
+}
+
+/** Extract a tool's function name from a DeepSeek/OpenAI-shaped tool
+ *  (`{ type:'function', function:{ name } }`). */
+function toolName(t: unknown): string {
+  const o = t as { function?: { name?: unknown } } | undefined;
+  if (o?.function && typeof o.function.name === 'string') return o.function.name;
+  return 'unknown_function';
+}
+
+function placeholderForSchema(def: unknown): unknown {
+  const d = def as { type?: unknown; enum?: unknown[] } | undefined;
+  if (Array.isArray(d?.enum) && d!.enum!.length) return d!.enum![0];
+  switch (d?.type) {
+    case 'number':
+    case 'integer': return 0;
+    case 'boolean': return false;
+    case 'array': return [];
+    case 'object': return {};
+    default: return '';
+  }
+}
+
+/**
+ * Build a deterministic stub argument string for a tool. When the tool declares a JSON-schema
+ * `parameters` object, real models emit arguments that validate against the schema; the twin
+ * synthesizes a deterministic object containing every declared property with a type-appropriate
+ * placeholder so strict callers parse it cleanly.
+ */
+export function stubToolArguments(tool: unknown): string {
+  const o = tool as { function?: { parameters?: unknown } } | undefined;
+  const schema = o?.function?.parameters as { properties?: Record<string, unknown> } | undefined;
+  const props = schema && typeof schema === 'object' ? schema.properties : undefined;
+  if (!props || typeof props !== 'object') return '{}';
+  const out: Record<string, unknown> = {};
+  for (const [key, def] of Object.entries(props)) out[key] = placeholderForSchema(def);
+  return JSON.stringify(out);
+}
+
+/**
+ * When tools are provided, real models may respond with `tool_calls` and
+ * `finish_reason:'tool_calls'`. The stub deterministically "calls" the tool selected by
+ * `forcedName` (a named tool_choice) or the FIRST provided tool. Returns null when no tools.
+ */
+export function stubToolCall(tools: unknown, seq: number, forcedName?: string): { id: string; type: 'function'; function: { name: string; arguments: string } } | null {
+  if (!Array.isArray(tools) || tools.length === 0) return null;
+  const chosen = forcedName ? (tools.find((t) => toolName(t) === forcedName) ?? tools[0]) : tools[0];
+  return { id: `call_twin_${seq}`, type: 'function', function: { name: toolName(chosen), arguments: stubToolArguments(chosen) } };
+}
+
+/**
+ * A deterministic JSON-object stub for `response_format: { type: 'json_object' }`. DeepSeek's JSON
+ * output mode guarantees only that the content parses as JSON — there is no schema on this vendor
+ * (`json_schema` is rejected, see deepseek-twin.ts), so the twin returns a clearly-labeled
+ * deterministic object rather than fabricating schema conformance it was never given.
+ */
+export function stubJsonObject(messages: DeepSeekMessageParam[], model: string): string {
+  return JSON.stringify({ _twin_stub: true, model, echo: lastUserText(messages).slice(0, 200) });
+}
+
+// ── Deterministic hashing ───────────────────────────────────────────────────────────────
+/** A small deterministic 32-bit hash (FNV-1a) of a string. */
+export function fnv1a(text: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/**
+ * DeepSeek's `system_fingerprint` is a backend-configuration string like
+ * `fp_eaab8d114b_prod0820_fp8_kvcache` (`@ai-sdk/deepseek` docs/30-deepseek.mdx, "Provider
+ * Metadata"). The twin serves a value in that SHAPE that is unmistakably a twin fingerprint and is
+ * derived from the request, so a replay is byte-identical.
+ */
+export function stubFingerprint(seed: string): string {
+  return `fp_${fnv1a(seed).toString(16).padStart(8, '0')}_twin_stub_kvcache`;
+}