@volter/twin-deepseek 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,198 @@
+# @volter/twin-deepseek
+
+> **Legacy connector helpers:** this package still has callable helpers using the retired v1
+> `syncPull` API. Those paths require migration before use on the current kernel;
+> older helper descriptions below do not establish current compatibility. Check the
+> [generated index](../../../generated/INDEX.md) for protocol standing and use the
+> [shared model](../../../docs/concepts/the-model.md) for current state semantics.
+
+A local, faithful **DeepSeek Platform API** twin your real `@ai-sdk/deepseek` talks to
+unmodified — point the provider at the twin's `baseURL` and `doGenerate`, `doStream`, `files()`,
+`GET /models` and `GET /user/balance` all work. Built on the shared `@volter/world-core` kernel (durable
+event/action log + projection); no parallel side store.
+
+```ts
+import { createDeepSeek } from '@ai-sdk/deepseek';
+import { createDeepSeekTwinServer } from '@volter/twin-deepseek';
+
+const { port } = createDeepSeekTwinServer({});
+// NOTE: no `/v1`. DeepSeek's base_url has no version segment, and the SDK appends
+// `/chat/completions` to whatever you give it.
+const deepseek = createDeepSeek({ apiKey: 'sk-twin', baseURL: `http://127.0.0.1:${port}` });
+
+const result = await deepseek('deepseek-v4-flash').doGenerate({
+  prompt: [{ role: 'user', content: [{ type: 'text', text: 'hello' }] }],
+});
+// The text part starts with "[twin-stub:…]" — a deterministic stub, clearly labeled.
+// A `reasoning` part precedes it (V4 models think by default), and
+// result.providerMetadata.deepseek carries promptCacheHitTokens / promptCacheMissTokens.
+```
+
+The beta surface is a base-URL suffix, exactly as on the real vendor — it unlocks assistant-prefix
+completion and strict tool calls, and it is where FIM completion lives:
+
+```ts
+const beta = createDeepSeek({ apiKey: 'sk-twin', baseURL: `http://127.0.0.1:${port}/beta` });
+```
+
+## DeepSeek is not OpenAI — and the REFUSALS are what this twin is for
+
+DeepSeek exposes an *OpenAI-compatible* surface, and treating "compatible" as "identical" is how a
+DeepSeek twin gets built wrong: the response shapes are the easy half, and what actually
+distinguishes the vendor is **what it refuses**. Every divergence below is modeled and pinned by a
+capability with a failable negative verify, grounded in
+[`@ai-sdk/deepseek@3.0.37`](https://www.npmjs.com/package/@ai-sdk/deepseek) read as source and
+[api-docs.deepseek.com](https://api-docs.deepseek.com/), both read 2026-08-31.
+
+| | DeepSeek | OpenAI |
+|---|---|---|
+| base path | **`https://api.deepseek.com/chat/completions`** — no version segment | `https://api.openai.com/v1/chat/completions` |
+| bad parameter | **422** "Your request contains invalid parameters" | 400 |
+| malformed body | 400 "Invalid request body format" | 400 |
+| out of credit | **402** "You have run out of balance" | (no 402) |
+| documented statuses | 400 / 401 / **402** / **422** / 429 / 500 / 503 — **no 404** | 400 / 401 / 403 / 404 / 429 / 5xx |
+| usage cache fields | **`prompt_cache_hit_tokens` / `prompt_cache_miss_tokens`** | `prompt_tokens_details.cached_tokens` |
+| reasoning | **`reasoning_content`** on the message and the delta | `reasoning` on o-series responses only |
+| finish reasons | `stop`, `length`, `content_filter`, `tool_calls`, **`insufficient_system_resource`** | no `insufficient_system_resource` |
+| end-user id | **`user_id`** (`^[a-zA-Z0-9_-]+$`, ≤512) | `user` |
+| structured output (chat) | `text`, `json_object` — **no `json_schema` on `/chat/completions`** (its Responses API's `text.format` does take one) | `text`, `json_object`, `json_schema` |
+| not parameters at all | **`n`, `seed`, `logit_bias`, `top_k`, `user`, `max_completion_tokens`, `service_tier`, `parallel_tool_calls`, `functions`** — each a 422 by name | all accepted |
+| deprecated-but-accepted | `frequency_penalty`, `presence_penalty` — **no effect, never an error** | still honoured |
+| ignored-but-accepted | `temperature`, `top_p` while thinking is on — **no effect, never an error** | honoured |
+| beta-only | assistant `prefix: true`, `strict: true` tools, FIM `/beta/completions` | n/a |
+| tools + history | **400** unless every prior assistant turn carries back `reasoning_content` | n/a |
+| model row | `{id, object, owned_by}` — **no `created`** | includes `created` |
+| Files API | **images only** (JPEG/PNG/GIF/WebP, ≤64 MiB), `purpose: user_data` | any purpose incl. `batch`, `assistants` |
+| second surface | an **Anthropic-compatible** API at `/anthropic` | n/a |
+| third surface | a **Responses API** at `/responses` with its own protocol (input/output items, semantic SSE) | `/v1/responses` |
+
+The inverse mistake is modeled too: a twin that *rejected* what DeepSeek deprecates-but-accepts
+would be just as unfaithful, so `deepseek.chat.deprecated_params_accepted` and
+`deepseek.chat.temperature_ignored_while_thinking` assert those requests still return **200** with
+byte-identical content.
+
+## The context cache is real state, not a fabricated number
+
+Every DeepSeek completion reports how many input tokens hit its KV cache. A twin has two options:
+invent a split (a lie the caller cannot detect), or keep the ledger. This twin keeps the ledger, in
+the same append-only kernel log as everything else (`deepseek-cache.ts`):
+
+- after serving a request the twin records two **cache prefix units** — the caller's messages
+  (user-input end) and those plus the assistant turn (model-output end), which is exactly where the
+  vendor documents its own units being cut;
+- a later request hits on the longest recorded unit that is a full prefix of its own message list,
+  and those tokens are `prompt_cache_hit_tokens`.
+
+So a genuine conversation continuation genuinely reports a hit, an unrelated prompt genuinely
+reports a full miss, and `hit + miss === prompt_tokens` is structural rather than clamped. What is
+**not** modeled is filed rather than faked: the vendor also cuts units at "fixed token intervals"
+inside long inputs but publishes no interval (`deepseek.cache.interval_units`, todo), and its cache
+auto-clears "within hours to days", which the twin does not do yet (`deepseek.cache.expiry`, a
+**todo** — the kernel's world clock is deterministic by construction and is explicitly the seam TTL
+logic reads at serve time, so this is unbuilt rather than unbuildable).
+
+## The generative-stub design (be honest)
+
+A twin cannot run the model, and that is an **invariant, not a gap**: a realism upgrade that costs
+determinism is not an upgrade. So the generated strings are deterministic, clearly labeled stubs —
+`[twin-stub:<model>]` in the content, in `reasoning_content`, and in the FIM continuation — and
+everything around them is vendor-faithful: the response envelope, the SSE chunk sequence (reasoning
+deltas before text deltas, an opt-in empty-choices usage tail), `tool_calls`, `finish_reason`, the
+KV-cache usage split, and the `fp_…_kvcache`-shaped `system_fingerprint`.
+
+The whole serve path is a pure function of (request, stored state): the ids, the fingerprint, the
+cache split and the logprob values are all derived, never clocked or randomised, so a replay is
+byte-identical (`deepseek.usage.serve_path_determinism`).
+
+## Scenario scripting (twin-only)
+
+When a flow under test needs specific model output, script it: a JSON handler file in the world dir
+(`handlers/deepseek.json`), run by the ONE kernel scenario engine with this pack's adapter.
+
+```jsonc
+{ "handlers": [
+  { "on": { "userTextIncludes": "summarize", "hasTool": "search_docs" },
+    "respond": { "text": "Scripted summary.", "reasoning": "Scripted chain of thought." } },
+  { "on": { "thinkingEquals": "disabled" }, "respond": { "text": "Fast path." } },
+  { "on": { "userTextIncludes": "broke" }, "respond": { "error": { "type": "insufficient_balance" } } }
+] }
+```
+
+Matchers: `modelEquals`, `userTextIncludes`, `anyTextIncludes`, `hasTool`, `toolResultFor`,
+`lastMessageIsToolResult`, `thinkingEquals`, `nthCall`. Scriptable failures map onto DeepSeek's own
+statuses: `rate_limit_exceeded` (429), `insufficient_balance` (402), `internal_server_error` (500),
+`server_overloaded` (503). Load is **strict and loud** — a mis-typed rule throws at startup rather
+than silently falling back to the stub. Scenario support is twin-only scaffolding, so it is
+deliberately **absent from the capability manifest** and gated by `deepseek-scenario.test.ts`
+instead.
+
+Read doors (read-only): `GET /twin` (the manifest, explaining the handler grammar) and
+`GET /twin/scenario` (handlers, matches, recent misses).
+
+## CLI
+
+```bash
+world-deepseek serve [--port N] [--root DIR] [--read-only] [--scenario FILE]
+world-deepseek conformance [--root DIR]
+```
+
+## Connector (pull / push)
+
+`pull` mirrors the real account over an **injected** executor — models, files and the singleton user
+balance — and is idempotent (a re-pull of identical state appends nothing). A refused pull **throws**
+rather than folding an empty account over real observed state. The pulled balance is load-bearing: a
+drained account makes the twin answer 402 exactly as the real one does.
+
+`push` sends local deletes of **pulled** files and confirms them. Two things it deliberately will
+not do: it refuses `file.create` by name (real DeepSeek's `POST /files` is multipart carrying image
+bytes the twin does not store), and it refuses to address the real account by the twin's own minted
+id. The context-cache ledger is twin-internal and is skipped by name, reported separately from real
+gaps rather than mixed into them.
+
+Every live call goes through **one guarded client** with a persistent, fail-closed spend ledger
+(`deepseek-budget.ts`). DeepSeek publishes **no scalar rate limit** — only per-model concurrency
+ceilings, which bound calls in flight rather than per minute — so the declaration is pinned at the
+kernel fallback (30 calls/minute) and buys resolution downward only; that is stated in its `reason`
+rather than dressed up as a vendor fact.
+
+## Coverage
+
+**Partial and honest.** The capability manifest is the *real DeepSeek surface* as the denominator,
+enumerated top-down from the docs nav and cross-checked against the SDK's own schemas — not a list
+of what was built. The measurement lives in the repo-root coverage table (README.md /
+../../../docs/contributing/conformance.md, regenerated by `bun scripts/twin-capabilities.ts --write-docs`); run
+`bun scripts/manifest-baseline-one.ts deepseek` for this pack alone.
+
+A note on the ratio: this pack reads higher than a brand-new twin usually does, and that is a fact
+about the vendor rather than a thin denominator. DeepSeek's entire published API is five endpoints
+(`/chat/completions`, `/beta/completions`, `/models`, `/user/balance`, `/files`) plus an
+Anthropic-compatible mirror — there is no Stripe-sized resource tree to be 12% of. The remaining
+`todo`s are real surface: the whole **Responses API** (`POST /responses` — a first-class entry in
+DeepSeek's own reference nav, and a different protocol from chat completions: input items in, output
+items out, semantic SSE, a built-in server-side `web_search` tool, and a `text.format` that DOES
+take a json_schema), the whole Anthropic-compatible API, image/vision inputs, FIM streaming,
+strict-mode schema enforcement, storage quotas, and the connector gaps filed in `pull-audit.json`.
+
+### No UI mirror
+
+DeepSeek is an API-first vendor: an integrator POSTs `/chat/completions` from
+code, and platform.deepseek.com is a keys/billing/usage console — incidental tooling, not where the
+work happens. So this pack ships no `client/` mirror and declares no UI capabilities.
+
+### What this twin does not run, and what is planned
+
+A local twin runs no model weights, so the completion is a deterministic labeled stub under a
+faithful envelope; the chain of thought is the same, served in the faithful `reasoning_content`
+field at the faithful stream position, and the beta fill-in-the-middle endpoint likewise. Log
+probabilities are an output of the forward pass: on `/chat/completions` the twin serves the faithful
+two-channel block with deterministic derived values, and on `/beta/completions` it leaves the
+block's four arrays empty rather than synthesising per-token numbers for text it did not generate —
+nothing asserts the numbers mean anything. Concurrency ceilings are a property of the vendor's
+serving fleet; a single-process local twin has nothing to contend for, and DeepSeek publishes no
+per-minute rate a client-side budget could reproduce.
+
+Planned: `deepseek.files.binary_content` — the twin records upload metadata and byte counts
+faithfully but stores no bytes, and the connector refuses to push a file create rather than
+fabricate a multipart body. Also `deepseek.usage.real_tokenizer` (a BPE tokenizer is a data file
+that runs offline and is deterministic) and `deepseek.cache.expiry` (the kernel's world clock is
+deterministic by construction and is explicitly the seam TTL logic reads at serve time).

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,28 @@
+#!/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.js";
+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.js");
+    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/dist/src/deepseek-budget.d.ts

@@ -0,0 +1,51 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export declare const DEEPSEEK_BUDGET_WINDOW_MS = 60000;
+/**
+ * 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 declare const DEEPSEEK_BUDGET_CEILING = 60;
+/** Seconds. A `retry-after` above this means the key is throttled hard — fail loudly, don't sleep. */
+export declare 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 declare 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. */
+    readonly inference: 6;
+    /** Everything else: files list/upload/retrieve/delete, models, user balance. */
+    readonly other: 2;
+};
+/** THE PACK'S DECLARATION — pure data, the only DeepSeek-specific thing in the whole budget. */
+export declare const DEEPSEEK_RATE_BUDGET: RateBudgetDeclaration;
+/**
+ * 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 declare function deepseekCallWeight(method: string, path: string): number;
+/** 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 declare function deepseekBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** 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 declare class DeepSeekBudget extends RateBudget {
+    constructor(opts?: DeepSeekBudgetOptions);
+}
+/** 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;

package/dist/src/deepseek-budget.js

@@ -0,0 +1,152 @@
+// 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, } 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,
+};
+/** THE PACK'S DECLARATION — pure data, the only DeepSeek-specific thing in the whole budget. */
+export const DEEPSEEK_RATE_BUDGET = {
+    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, path) {
+    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) {
+    const at = path.indexOf('?');
+    const query = {};
+    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 = {}) {
+    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 });
+}
+/**
+ * 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 = {}) {
+        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';