@volter/twin-deepseek 0.1.0

package/dist/src/deepseek-types.d.ts

@@ -0,0 +1,172 @@
+/** A chat message param as the caller sends it (content is a string OR a content-part array). */
+export type DeepSeekMessageParam = {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content?: string | Array<Record<string, unknown>> | null;
+    /** Optional participant name — supported on system, user and assistant messages only.
+     *  `@ai-sdk/deepseek` warns `unsupported: message name on tool messages`. */
+    name?: string;
+    /** Beta-only: continue this assistant message's content instead of starting a new turn.
+     *  Requires the `/beta` base URL and must be the FINAL message. */
+    prefix?: boolean;
+    /** The chain-of-thought DeepSeek returned on a previous assistant turn. When the request carries
+     *  `tools`, DeepSeek requires previous turns to carry it back or answers 400
+     *  (api-docs.deepseek.com/guides/thinking_mode). */
+    reasoning_content?: string | null;
+    tool_calls?: DeepSeekToolCall[];
+    tool_call_id?: string;
+};
+/** A function tool_call inside an assistant message (faithful shape). */
+export type DeepSeekToolCall = {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+/**
+ * The chat.completion `usage` object. `prompt_cache_hit_tokens` + `prompt_cache_miss_tokens` are
+ * DeepSeek's KV-cache accounting and always sum to `prompt_tokens`
+ * (api-docs.deepseek.com/guides/kv_cache: "the number of tokens in the input of this request that
+ * resulted in a cache hit" / "…that did not result in a cache hit"). `@ai-sdk/deepseek` reads both
+ * into `providerMetadata.deepseek.promptCacheHitTokens` / `…MissTokens` and derives
+ * `usage.inputTokens.cacheRead` from the hit count (src/chat/convert-to-deepseek-usage.ts).
+ */
+export type DeepSeekUsage = {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    prompt_cache_hit_tokens: number;
+    prompt_cache_miss_tokens: number;
+    prompt_tokens_details?: {
+        cached_tokens: number;
+    };
+    completion_tokens_details?: {
+        reasoning_tokens: number;
+    };
+};
+/**
+ * The assistant message DeepSeek returns. NOTE `reasoning_content` (no OpenAI counterpart) and the
+ * absence of OpenAI's `refusal` / `annotations`.
+ */
+export type DeepSeekAssistantMessage = {
+    role: 'assistant';
+    content: string | null;
+    reasoning_content?: string | null;
+    tool_calls?: DeepSeekToolCall[];
+};
+/** One entry of a `logprobs.content` / `logprobs.reasoning_content` array. */
+export type DeepSeekLogprob = {
+    token: string;
+    logprob: number;
+    bytes: number[] | null;
+    top_logprobs: Array<{
+        token: string;
+        logprob: number;
+        bytes: number[] | null;
+    }>;
+};
+/** DeepSeek splits logprobs by channel: generated content AND reasoning content. */
+export type DeepSeekLogprobs = {
+    content?: DeepSeekLogprob[] | null;
+    reasoning_content?: DeepSeekLogprob[] | null;
+};
+/** `insufficient_system_resource` is DeepSeek's own value — `@ai-sdk/deepseek` maps it to the
+ *  unified `error` finish reason (src/chat/map-deepseek-finish-reason.ts). */
+export type DeepSeekFinishReason = 'stop' | 'length' | 'content_filter' | 'tool_calls' | 'insufficient_system_resource';
+export type DeepSeekChoice = {
+    index: number;
+    message: DeepSeekAssistantMessage;
+    logprobs: DeepSeekLogprobs | null;
+    finish_reason: DeepSeekFinishReason;
+};
+/** The unary chat.completion response envelope (faithful shape). */
+export type DeepSeekChatCompletion = {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: DeepSeekChoice[];
+    usage: DeepSeekUsage;
+    system_fingerprint: string;
+};
+/** `POST https://api.deepseek.com/beta/completions` — fill-in-the-middle. `object` is
+ *  `text_completion` and the choice carries `text`, not a message. */
+export type DeepSeekCompletionChoice = {
+    index: number;
+    text: string;
+    finish_reason: 'stop' | 'length' | 'content_filter' | 'insufficient_system_resource';
+    logprobs: {
+        tokens: string[];
+        token_logprobs: number[];
+        text_offset: number[];
+        top_logprobs: Array<Record<string, number>>;
+    } | null;
+};
+export type DeepSeekCompletion = {
+    id: string;
+    object: 'text_completion';
+    created: number;
+    model: string;
+    choices: DeepSeekCompletionChoice[];
+    usage: DeepSeekUsage;
+    system_fingerprint: string;
+};
+/**
+ * A DeepSeek model row. THREE keys, and that is the whole object: DeepSeek's own
+ * `GET /models` example response is `{"id": "...", "object": "model", "owned_by": "deepseek"}`
+ * (api-docs.deepseek.com/api/list-models, read 2026-08-31). OpenAI's row additionally carries
+ * `created`; DeepSeek's does not, and inventing one would be surface the vendor does not have.
+ */
+export type DeepSeekModel = {
+    id: string;
+    object: 'model';
+    owned_by: string;
+};
+/** `GET /user/balance` (api-docs.deepseek.com/api/get-user-balance). Balances are STRINGS. */
+export type DeepSeekBalanceInfo = {
+    currency: 'CNY' | 'USD';
+    total_balance: string;
+    granted_balance: string;
+    topped_up_balance: string;
+};
+export type DeepSeekBalance = {
+    is_available: boolean;
+    balance_infos: DeepSeekBalanceInfo[];
+};
+/** The file object (api-docs.deepseek.com/guides/files_api; validated key-for-key by
+ *  `@ai-sdk/deepseek`'s `deepSeekFilesResponseSchema`). `expires_at` appears only when an
+ *  expiration was requested. */
+export type DeepSeekFile = {
+    id: string;
+    object: 'file';
+    bytes: number;
+    created_at: number;
+    filename: string;
+    purpose: 'user_data';
+    expires_at?: number;
+};
+/**
+ * DeepSeek's error envelope. `message` is the only REQUIRED key; `type`, `param` and `code` are
+ * nullish. This is not folklore from a rendered docs example — it is the zod schema
+ * `@ai-sdk/deepseek@3.0.37` actually decodes every failed response with
+ * (`deepSeekErrorSchema`, src/chat/deepseek-chat-api-types.ts), which is the stronger first-party
+ * oracle (ADDING_A_TWIN.md §6, "When first-party sources conflict").
+ */
+export type DeepSeekError = {
+    error: {
+        message: string;
+        type?: string | null;
+        param?: unknown;
+        code?: string | number | null;
+    };
+};
+/** A single Server-Sent Event the streaming path emits (collected, never socketed in tests).
+ *  `data` is the JSON payload; `[DONE]` is signalled with `done: true` (no data object). */
+export type SseEvent = {
+    data?: Record<string, unknown>;
+    done?: boolean;
+};
+/** A sink the streaming path writes events into (an injected collector in tests / a real
+ *  HTTP SSE writer in the server). NO real sockets or setTimeout in the handler. */
+export type SseSink = (event: SseEvent) => void;

package/dist/src/deepseek-types.js

@@ -0,0 +1,26 @@
+// Shared wire-shape types for the DeepSeek Platform API. These mirror the REAL vendor JSON shapes
+// as published by DeepSeek's own API reference (api-docs.deepseek.com, read 2026-08-31) and by the
+// zod schemas `@ai-sdk/deepseek@3.0.37` decodes responses with (src/chat/deepseek-chat-api-types.ts,
+// src/files/deepseek-files-api.ts). The twin never imports the SDK at runtime; the SDK is exercised
+// only in *.test.ts.
+//
+// DEEPSEEK IS OPENAI-COMPATIBLE, NOT OPENAI, and the differences below are load-bearing — they are
+// exactly what a "copy the openai pack" twin gets wrong (ADDING_A_TWIN.md §0, the compatible-vendor
+// warning). The REJECTIONS are the fidelity surface:
+//   • there is NO `/v1` path prefix — `base_url` is `https://api.deepseek.com` and the endpoint is
+//     `/chat/completions` (api-docs.deepseek.com "Your First API Call", read 2026-08-31);
+//   • the documented error table has NO 404 and DOES have 402 (Insufficient Balance) and
+//     422 (Invalid Parameters) — OpenAI 400s where DeepSeek 422s
+//     (api-docs.deepseek.com/quick_start/error_codes);
+//   • `usage` carries the KV-cache split `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens`
+//     (OpenAI reports `prompt_tokens_details.cached_tokens` instead);
+//   • the assistant message/delta carries `reasoning_content` (OpenAI has no such field);
+//   • `finish_reason` includes DeepSeek's own `insufficient_system_resource`;
+//   • the end-user identifier is `user_id` (regex + 512-char cap), NOT OpenAI's `user`;
+//   • `response_format` accepts ONLY `text` and `json_object` — `json_schema` is OpenAI-only;
+//   • `n`, `seed`, `logit_bias` and `top_k` are not DeepSeek parameters at all;
+//   • `frequency_penalty` / `presence_penalty` are DEPRECATED but accepted with NO effect (they
+//     must NOT be errors), as are `temperature` / `top_p` while thinking is enabled;
+//   • assistant-prefix completion and strict tool calls live only under the `/beta` base URL;
+//   • a `GET /models` row is `{id, object, owned_by}` — no `created`, no `context_window`.
+export {};

package/dist/src/index.d.ts

@@ -0,0 +1,15 @@
+export { handleDeepSeekTwinRequest, streamChat, buildChatCompletion, DEEPSEEK_BETA_PREFIX, DEEPSEEK_ANTHROPIC_PREFIX } from './deepseek-twin.js';
+export type { DeepSeekRequest, DeepSeekResponseEnvelope } from './deepseek-twin.js';
+export { createDeepSeekTwinFetch, createDeepSeekTwinServer, type DeepSeekTwinFetchOptions } from './deepseek-server.js';
+export { DEEPSEEK_MODELS, FIM_MODELS, RETIRED_MODEL_IDS, VISION_MODELS, findModel, isThinkingModel } from './deepseek-models.js';
+export { cacheHitTokens, canonicalMessage, prefixId, prefixKey, recordCachePrefixes } from './deepseek-cache.js';
+export { buildUsage, contentToText, countPromptTokens, estimateTokens, fnv1a, lastUserText, messageTokens, stubAssistantText, stubFimText, stubFingerprint, stubJsonObject, stubReasoningText, stubToolArguments, stubToolCall, } from './deepseek-stub.js';
+export type { DeepSeekAssistantMessage, DeepSeekBalance, DeepSeekBalanceInfo, DeepSeekChatCompletion, DeepSeekChoice, DeepSeekCompletion, DeepSeekCompletionChoice, DeepSeekError, DeepSeekFile, DeepSeekFinishReason, DeepSeekLogprob, DeepSeekLogprobs, DeepSeekMessageParam, DeepSeekModel, DeepSeekToolCall, DeepSeekUsage, SseEvent, SseSink, } from './deepseek-types.js';
+export { createDeepSeekScenarioEngine, deepseekScenarioAdapter, loadDeepSeekScenarioDocument, realizeDeepSeekRespond } from './deepseek-scenario.js';
+export type { DeepSeekScenarioEngine, DeepSeekScenarioRequest, DeepSeekScenarioRespond, ScenarioToolCall, ScriptedResult } from './deepseek-scenario.js';
+export { fullSyncDeepSeek, externalIdFor, deepseekRequestForAction, liveDeepSeekExecute, mapBalance, mapFile, mapModel, pullDeepSeekState, pushDeepSeekAction, pushPendingDeepSeekActions, syncDeepSeekFromReal, unpushableReason, } from './deepseek-connector.js';
+export type { DeepSeekExecute, LiveDeepSeekOptions } from './deepseek-connector.js';
+export { DEEPSEEK_BUDGET_CEILING, DEEPSEEK_BUDGET_MAX_RETRY_AFTER_S, DEEPSEEK_BUDGET_WINDOW_MS, DEEPSEEK_CALL_WEIGHTS, DEEPSEEK_RATE_BUDGET, DeepSeekBudget, DeepSeekBudgetError, deepseekBudgetPath, deepseekCallWeight, } from './deepseek-budget.js';
+export type { DeepSeekBudgetErrorKind, DeepSeekBudgetOptions, DeepSeekBudgetReservation, DeepSeekBudgetSnapshot } from './deepseek-budget.js';
+import type { TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,93 @@
+// @volter/twin-deepseek — the DeepSeek twin (one vendor, one package), built on the shared
+// @volter/world-core kernel. The DeepSeek Platform API: a vendor-faithful protocol envelope (chat
+// completions/streaming/tool_calls, `reasoning_content`, DeepSeek's KV-cache-bearing `usage`), the
+// published model catalog, the account balance, beta FIM completion, and a STATEFUL image Files API
+// — over an event/action log. (DeepSeek is an API-first vendor: platform.deepseek.com is a
+// keys/billing/usage console, not where the work happens — docs/contributing/architecture.md C1b — so this pack ships
+// no mirror.)
+//
+// THE DETERMINISTIC STUB IS THE ANSWER: the twin runs no model, so POST /chat/completions returns a
+// DETERMINISTIC STUB completion (clearly labeled), its `reasoning_content` is a labeled stub, and
+// POST /beta/completions returns a labeled FIM stub — never pretending to be real inference.
+// Everything around them — the wire protocol, and above all WHAT DEEPSEEK REFUSES — is faithful.
+// (Conformance + capability tooling live in @volter/world-tooling, a dev dependency — NOT
+// re-exported here, per E2.)
+export { handleDeepSeekTwinRequest, streamChat, buildChatCompletion, DEEPSEEK_BETA_PREFIX, DEEPSEEK_ANTHROPIC_PREFIX } from "./deepseek-twin.js";
+export { createDeepSeekTwinFetch, createDeepSeekTwinServer } from "./deepseek-server.js";
+export { DEEPSEEK_MODELS, FIM_MODELS, RETIRED_MODEL_IDS, VISION_MODELS, findModel, isThinkingModel } from "./deepseek-models.js";
+export { cacheHitTokens, canonicalMessage, prefixId, prefixKey, recordCachePrefixes } from "./deepseek-cache.js";
+export { buildUsage, contentToText, countPromptTokens, estimateTokens, fnv1a, lastUserText, messageTokens, stubAssistantText, stubFimText, stubFingerprint, stubJsonObject, stubReasoningText, stubToolArguments, stubToolCall, } from "./deepseek-stub.js";
+export { createDeepSeekScenarioEngine, deepseekScenarioAdapter, loadDeepSeekScenarioDocument, realizeDeepSeekRespond } from "./deepseek-scenario.js";
+export { fullSyncDeepSeek, externalIdFor, deepseekRequestForAction, liveDeepSeekExecute, mapBalance, mapFile, mapModel, pullDeepSeekState, pushDeepSeekAction, pushPendingDeepSeekActions, syncDeepSeekFromReal, unpushableReason, } from "./deepseek-connector.js";
+// The client-side rate budget — the fail-closed backstop `liveDeepSeekExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is DeepSeek's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `DeepSeekBudgetError` by type; there is deliberately no export that disables the guard.
+export { DEEPSEEK_BUDGET_CEILING, DEEPSEEK_BUDGET_MAX_RETRY_AFTER_S, DEEPSEEK_BUDGET_WINDOW_MS, DEEPSEEK_CALL_WEIGHTS, DEEPSEEK_RATE_BUDGET, DeepSeekBudget, DeepSeekBudgetError, deepseekBudgetPath, deepseekCallWeight, } from "./deepseek-budget.js";
+import { DEEPSEEK_RATE_BUDGET as RATE_BUDGET } from "./deepseek-budget.js";
+export const pack = {
+    vendor: 'deepseek',
+    // The SAME object deepseek-budget.ts declares at module load — one source of truth, so registering
+    // the pack and importing the connector can never arm two different ceilings.
+    rateBudget: RATE_BUDGET,
+    transport: 'rest',
+    archetype: 'generative',
+    bin: 'world-deepseek',
+    // R2 adopted-as-debt, legibly: declared types no replay can create, each with its reason.
+    resourcesUnreachable: {
+        'model': 'the vendor catalog',
+        'balance': 'the account ledger the vendor keeps; read-only',
+    },
+    resources: ['model', 'file', 'balance', 'cache_prefix'],
+    specSource: "DeepSeek Platform API — enumerated top-down from api-docs.deepseek.com (quick_start/{error_codes,rate_limit,pricing}, api/{create-chat-completion,create-completion,list-models,get-user-balance}, guides/{kv_cache,thinking_mode,files_api,anthropic_api,chat_prefix_completion}; read 2026-08-31) and cross-checked key-for-key against the zod schemas @ai-sdk/deepseek@3.0.37 encodes/decodes with (src/chat/deepseek-chat-api-types.ts, src/chat/deepseek-chat-language-model{,-options}.ts, src/chat/deepseek-prepare-tools.ts, src/files/deepseek-files{,-api,-options}.ts) plus the provider doc page shipped in that tarball (docs/30-deepseek.mdx). DeepSeek publishes no OpenAPI document. Envelope-faithful; model output, reasoning_content, FIM text and logprob values are labeled deterministic stubs.",
+    description: "DeepSeek Platform API twin — faithful protocol envelope (chat completions/streaming/tool_calls, reasoning_content, KV-cache-split usage), the published catalog, user balance, beta FIM + prefix completion + strict tools, and a stateful image Files API; generative output is a labeled stub and the OpenAI-divergent REFUSALS (402/422, no json_schema, no n/seed/logit_bias/user) are modeled.",
+    // DeepSeek's base_url is https://api.deepseek.com with NO version segment — the endpoint is
+    // `/chat/completions` (api-docs.deepseek.com "Your First API Call", read 2026-08-31). This is the
+    // single most likely thing to be copied wrong from an OpenAI-shaped exemplar.
+    browserRouting: { apiPathPrefix: '/', loaderHost: 'https://api.deepseek.com' },
+    // ADOPTION (adding-a-twin.md §3): how an app repo betrays that it talks to DeepSeek. Declared
+    // HERE, not in world-runtime's central SDK_TWINS/ENV_STEM_VENDORS maps — declaring in both throws.
+    //
+    // `@ai-sdk/deepseek` is the Vercel AI SDK provider and the ONLY first-party npm client of this
+    // surface — DeepSeek publishes no SDK of its own; its docs tell integrators to point the OpenAI
+    // or Anthropic SDK at api.deepseek.com instead ("The DeepSeek API uses an API format compatible
+    // with OpenAI/Anthropic"). That is exactly why `openai` is NOT claimed here: a repo depending on
+    // `openai` is an OpenAI repo unless its base URL says otherwise, and claiming the package would
+    // mis-attribute every OpenAI integration in the census to this pack. The 2026-08-31-b census
+    // bears this out — 5 of the 6 demanding repos signal `@ai-sdk/deepseek`; the sixth (nextchat)
+    // signals the bare `deepseek` stem via DEEPSEEK_API_KEY / DEEPSEEK_URL.
+    //
+    // `envStems: ['DEEPSEEK']` normalizes (covers.ts `normalizeId`: lowercase + strip
+    // non-alphanumerics) to `deepseek`, which is what DEEPSEEK_API_KEY — the one env
+    // `@ai-sdk/deepseek` reads (`loadApiKey({ environmentVariableName: 'DEEPSEEK_API_KEY' })`,
+    // src/deepseek-provider.ts) — and NextChat's DEEPSEEK_URL both reduce to.
+    //
+    // No `scopes`: `@ai-sdk/` is Vercel's scope shared by every provider package, not DeepSeek's.
+    adoption: {
+        // No official Python SDK: DeepSeek's own docs tell Python callers to use the `openai` client
+        // against api.deepseek.com, and that distribution belongs to the openai pack (the pypi list is
+        // the distribution; DEEPSEEK_BASE_URL is what routes it). The `deepseek` name on PyPI is an
+        // unaffiliated third-party wrapper with no adoption, deliberately not claimed.
+        pypi: [],
+        sdks: ['@ai-sdk/deepseek'], envStems: ['DEEPSEEK'],
+    },
+    // INTERCEPTION: the one host every client addresses. `@ai-sdk/deepseek` defaults its baseURL to
+    // `https://api.deepseek.com` and builds every URL as `${baseURL}${path}` for chat and
+    // `${baseURL}/files` for uploads (src/deepseek-provider.ts, src/files/deepseek-files.ts), so the
+    // standard surface, the `/beta` surface and the `/anthropic` surface all live on this one host.
+    // No second host exists anywhere in the SDK.
+    hosts: [{ host: 'api.deepseek.com' }],
+    // The injector intercepts api.deepseek.com (see `hosts`), so a world wires this pack through
+    // DEEPSEEK_TWIN_URL rather than an app-read base-URL var.
+    //
+    // THE GROUNDING FOR THE "NONE" HALF: `@ai-sdk/deepseek` reads exactly ONE environment variable —
+    // `DEEPSEEK_API_KEY`, via `loadApiKey` — and takes `baseURL` as a constructor option only
+    // (`DeepSeekProviderSettings.baseURL`, src/deepseek-provider.ts). There is no DEEPSEEK_BASE_URL
+    // in the SDK, in DeepSeek's docs, or anywhere in the tarball. NextChat's `DEEPSEEK_URL` is that
+    // one application's own convention, not a vendor-documented var, and injecting it would make
+    // `covers` report every DeepSeek world covered while the five repos on `@ai-sdk/deepseek` — which
+    // read no such var — still talked to the real vendor. That is precisely the class of lie
+    // ADDING_A_TWIN.md §7 point 12 forbids ("never invent a <VENDOR>_BASE_URL the app does not read").
+    endpointEnvNone: "no app-read endpoint env: @ai-sdk/deepseek — the only first-party npm client of this surface — reads exactly one environment variable (DEEPSEEK_API_KEY, via loadApiKey in src/deepseek-provider.ts) and takes baseURL as a constructor option, so there is no vendor-documented base-URL var to inject. The injector covers api.deepseek.com instead (see `hosts`). NextChat's DEEPSEEK_URL is one application's own convention, not vendor surface, and claiming it would report a world covered while the SDK-based majority still reached the real vendor.",
+};

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@volter/twin-deepseek",
+  "version": "0.1.0",
+  "description": "Local DeepSeek twin — a faithful, stateful local DeepSeek Platform API your real `@ai-sdk/deepseek` talks to unmodified. The model is stubbed (deterministic), but the protocol envelope is vendor-faithful and so are DeepSeek's OpenAI-DIVERGENT REFUSALS: 422 for a bad parameter and 402 for a drained balance (not OpenAI's 400), no /v1 path segment, no json_schema/n/seed/logit_bias/user, beta-only prefix completion and strict tools, reasoning_content, and a real KV-cache-split usage ledger. Built on @volter/world-core.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "fixtures",
+    "testing",
+    "sdk",
+    "api",
+    "localstack",
+    "deepseek",
+    "llm",
+    "openai-compatible",
+    "reasoning"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/deepseek"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/deepseek#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-deepseek": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "@ai-sdk/deepseek": "^3.0.37",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-deepseek CLI: serve the DeepSeek API twin or run conformance. DeepSeek is an API-first vendor —
+// its console is a keys/usage/playground dev console, not where the work happens
+// (docs/contributing/architecture.md C1b) — so this pack ships no mirror.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createDeepSeekTwinServer } from './deepseek-server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+const scenario = optionValue(rest, '--scenario') || undefined; // scripted completions (JSON file)
+
+if (cmd === 'serve') {
+  const s = await createDeepSeekTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(scenario ? { scenarioPath: scenario } : {}) });
+  process.stdout.write(`deepseek twin (DeepSeek Platform API, no /v1 segment; model output is a deterministic stub)${readOnly ? ' [read-only]' : ''}${scenario ? ` [scenario: ${scenario}]` : ''} at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  // dev-only; lazy so the bin runs without @volter/world-tooling
+  const { checkDeepSeekConformance } = await import('./deepseek-conformance.ts');
+  const report = await checkDeepSeekConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-deepseek serve|conformance [--port N] [--root DIR] [--read-only] [--scenario FILE]\n');
+}

package/src/deepseek-budget.ts

@@ -0,0 +1,178 @@
+// DeepSeek's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveDeepSeekExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
+// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
+// lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that module's
+// header for the full rationale AND for the honest list of what the guard does not guarantee.
+//
+// ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
+// A real ~4.5-DAY vendor lockout (Figma, 2026-07-25) happened because raw API calls were made
+// outside the pack's connector — no cache, no batching, no ceiling. Discipline only binds the code
+// that follows it; a BUDGET binds the code that does not.
+//
+// ── HOW THE CEILING WAS CHOSEN (live-read, 2026-08-31) ──────────────────────────────────────
+// https://api-docs.deepseek.com/quick_start/rate_limit (read 2026-08-31) publishes NO scalar
+// per-minute or per-day request allowance at all. What it publishes is a CONCURRENCY table —
+// deepseek-v4-pro 500, deepseek-v4-flash 2500, deepseek-v4-flash-vision-exp 2500 simultaneous
+// connections per account — plus the note that "if you need higher concurrency, you can submit a
+// capacity expansion request". Concurrency is not a rate: it bounds how many calls are in flight,
+// not how many are made per minute, so nothing on that page can be turned into a window ceiling.
+// (This figure was live-fetched for THIS build. The copied-exemplar hazard ADDING_A_TWIN.md §0.5
+// warns about is real: the pack this one was cloned from asserted GroqCloud's eight-dimension
+// RPM/RPD/TPM/ASH scheme, which DeepSeek does not have at all.)
+//
+// So — exactly as ADDING_A_TWIN.md directs when a vendor publishes no scalar limit ("say exactly
+// that in `reason` and stay at or under the fallback") — this declaration is pinned at the kernel's
+// undeclared fallback in every dimension: window 60s, ceiling 60, defaultWeight 2, i.e. 30
+// calls/minute, EXACTLY `DEFAULT_RATE_BUDGET`, with no endpoint priced cheaper than the fallback
+// would price it. What the declaration buys is RESOLUTION, and it buys it DOWNWARD only.
+//
+// It bounds the 60s AVERAGE; it does not pace (the kernel refuses, it never sleeps). The backstop
+// for a sub-second burst is the cooldown: a `retry-after` read off a real 429 turns into a
+// persisted refusal.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN (and what is a judgement call) ───────────────────────────────
+//   • `/chat/completions`, `/beta/chat/completions` and `/beta/completions` cost 6. DeepSeek prices
+//     and meters these by TOKENS, not requests (api-docs.deepseek.com/quick_start/pricing bills
+//     input cache-hit / cache-miss / output tokens), so one inference request consumes far more of
+//     an account's real allowance than a file-list poll. 60/6 = at most 10 inference calls a window.
+//     That factor is a judgement call, not a vendor figure — it is deliberately the STRICT
+//     direction, which needs no vendor justification; being looser would, and there is none to have.
+//   • Everything else (files, models, balance) costs 2 — the fallback's own default.
+//
+// ── AN HONEST NOTE ON THE INFERENCE RULE ────────────────────────────────────────────────────
+// This pack's connector pulls models, files and the account balance; it NEVER issues live
+// inference, because a twin does not run the model anywhere — local or remote (CLAUDE.md,
+// serve-path determinism). `liveDeepSeekExecute`'s path allowlist refuses `/chat/completions`
+// outright. So the `inference: 6` rule is DEFENCE IN DEPTH, not a live pricing path, and the pack
+// claims exactly that: `deepseek.rate_limits.inference_costs_more` asserts the pure pricing
+// function, `deepseek.rate_limits.executor_path_allowlist` asserts the refusal, and no capability
+// claims a live inference call was ever budgeted.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'deepseek';
+
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const DEEPSEEK_BUDGET_WINDOW_MS = 60_000;
+
+/**
+ * Weighted units allowed inside one window. 60/60s at `defaultWeight` 2 = 30 calls a minute —
+ * EXACTLY the kernel's undeclared fallback, because DeepSeek publishes no scalar that would justify
+ * more. See the header.
+ */
+export const DEEPSEEK_BUDGET_CEILING = 60;
+
+/** Seconds. A `retry-after` above this means the key is throttled hard — fail loudly, don't sleep. */
+export const DEEPSEEK_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs. judged. */
+export const DEEPSEEK_CALL_WEIGHTS = {
+  /** `/chat/completions`, `/beta/chat/completions`, `/beta/completions` — TOKEN-metered and
+   *  token-billed, so one call spends far more of an account's real allowance than a list poll.
+   *  At 60/6 that is at most 10 inference calls a window. */
+  inference: 6,
+  /** Everything else: files list/upload/retrieve/delete, models, user balance. */
+  other: 2,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only DeepSeek-specific thing in the whole budget. */
+export const DEEPSEEK_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: DEEPSEEK_BUDGET_WINDOW_MS,
+  ceiling: DEEPSEEK_BUDGET_CEILING,
+  defaultWeight: DEEPSEEK_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: DEEPSEEK_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    // Anchored on DeepSeek's REAL paths — there is no `/v1` segment on this vendor. The optional
+    // `/beta` prefix is part of the pattern because the beta base URL reaches the SAME priced
+    // inference endpoints; a rule that missed it would price a beta chat call as a 2-unit read.
+    { match: '^POST (/beta)?/chat/completions$', weight: DEEPSEEK_CALL_WEIGHTS.inference },
+    { match: '^POST /beta/completions$', weight: DEEPSEEK_CALL_WEIGHTS.inference },
+  ],
+  reason:
+    'DeepSeek publishes NO scalar request-rate limit at all (api-docs.deepseek.com/quick_start/rate_limit, ' +
+    'read 2026-08-31). The only figures on that page are CONCURRENCY limits — deepseek-v4-pro 500, ' +
+    'deepseek-v4-flash 2500, deepseek-v4-flash-vision-exp 2500 simultaneous connections per account, ' +
+    'with a capacity-expansion request available for more — and concurrency bounds calls in flight, ' +
+    'not calls per minute, so it cannot be turned into a window ceiling. Because no published figure ' +
+    'justifies going higher, the ceiling is pinned at the kernel fallback in every dimension: 60 units ' +
+    '/ 60s at defaultWeight 2 = 30 calls/min, identical to DEFAULT_RATE_BUDGET. The declaration buys ' +
+    'resolution DOWNWARD, never headroom: inference (POST /chat/completions, POST /beta/chat/completions, ' +
+    'POST /beta/completions) costs 6, so at most 10 land in a window, because DeepSeek bills those ' +
+    'endpoints by token (input cache-hit / cache-miss / output) rather than by request. That factor is ' +
+    'a judgement call in the strict direction, not a vendor figure. The window bounds the 60s AVERAGE ' +
+    'and does not pace; a `retry-after` read off a real 429 is the persisted cooldown backstop.',
+};
+
+// Declared at module load, so merely importing this module (which `deepseek-connector.ts` does) is
+// enough to arm the real ceiling.
+declareRateBudget(VENDOR, DEEPSEEK_RATE_BUDGET);
+
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off, so a rule can
+ * price by method (a write is not a read) without the kernel knowing anything about DeepSeek. An
+ * unclassified endpoint still costs `defaultWeight` — nothing is ever free.
+ */
+export function deepseekCallWeight(method: string, path: string): number {
+  const { bare, query } = splitQuery(path);
+  // UPPER-CASE the method: `fetch` normalizes a known lowercase method before sending, so
+  // `execute('post', …)` really does issue a POST and must be priced as one.
+  return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+
+/**
+ * `/chat/completions?a=1` -> `{ bare: '/chat/completions', query: { a: '1' } }`. Rules match the path;
+ * `whenQuery*` the query. NORMALIZED, because the anchored rules are otherwise trivially evaded:
+ * `fetch` upper-cases a known method before sending, so `execute('post', …)` issues a real WRITE
+ * that a `^POST ` rule would price as a read; and a trailing slash makes a path miss a `$` anchor
+ * while most routers treat it as the same endpoint.
+ */
+function splitQuery(path: string): { bare: string; query: Record<string, string> } {
+  const at = path.indexOf('?');
+  const query: Record<string, string> = {};
+  if (at !== -1) for (const [k, v] of new URLSearchParams(path.slice(at + 1))) query[k] = v;
+  // Collapse REPEATED slashes as well as a trailing one: `//chat/completions` reaches the same
+  // endpoint on most routers but misses a `^POST (/beta)?/chat/completions$` rule, which would
+  // price an inference call as a 2-unit read.
+  const raw = (at === -1 ? path : path.slice(0, at)).replace(/\/{2,}/g, '/');
+  const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+  return { bare, query };
+}
+
+/** Where DeepSeek's ledger lives. Token-keyed and cwd-independent by default (DeepSeek's limits are per
+ *  ORGANIZATION, i.e. per key, so a cwd-scoped ledger would hand the same key a fresh allowance in
+ *  every checkout, worktree and CI matrix leg); pass `root` for world-scoped accounting. */
+export function deepseekBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+  // excess-property check only catches object literals) must not redirect this pack's ledger.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options for DeepSeek's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type DeepSeekBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * DeepSeek's budget — the shared kernel guard bound to this vendor's declaration. A real subclass, not
+ * an alias, so `budget instanceof DeepSeekBudget` in `liveDeepSeekExecute` means "a budget that accounts
+ * against DEEPSEEK's ledger under DEEPSEEK's ceiling".
+ */
+export class DeepSeekBudget extends RateBudget {
+  constructor(opts: DeepSeekBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as DeepSeekBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as DeepSeekBudgetErrorKind } from '@volter/world-core';
+export type DeepSeekBudgetReservation = RateBudgetReservation;
+export type DeepSeekBudgetSnapshot = RateBudgetSnapshot;