@volter/twin-deepseek 0.1.0

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

@@ -0,0 +1,56 @@
+import type { DeepSeekMessageParam } from './deepseek-types.js';
+/**
+ * The canonical text of one message — see the file header for why this, not the JSON.
+ *
+ * §9 ROUND ONE, NIT 15: the key must cover EVERY field `messageTokens` charges for. It previously
+ * dropped `name` and `reasoning_content` while the token count included them, so a caller could
+ * attach an arbitrarily large `reasoning_content` to a replayed assistant turn, still match the
+ * recorded unit, and have those tokens billed as a HIT. Both are now normalized into the key
+ * (`?? ''`), which keeps an absent field and an empty string identical — the shape
+ * `@ai-sdk/deepseek` produces, since it back-fills `reasoning_content: ''` on every V4 assistant
+ * turn — while making a DIFFERENT reasoning payload a different key, i.e. a miss. Under-reporting
+ * is the safe direction here; over-reporting bills the caller for cache they did not earn.
+ */
+export declare function canonicalMessage(m: DeepSeekMessageParam): string;
+/** The prefix key for the first `count` messages. */
+export declare function prefixKey(messages: DeepSeekMessageParam[], count: number): string;
+/** The deterministic subject id a prefix unit is stored under. */
+export declare function prefixId(key: string): string;
+/**
+ * How many of THIS request's prompt tokens hit the cache: the token count of the longest recorded
+ * prefix unit that fully matches the head of `messages` — INCLUDING the whole message list.
+ *
+ * §9 ROUND ONE, SHOULD-FIX 4: this used to stop one short (`count < messages.length`), on the
+ * stated grounds that counting the whole request "is not what the vendor's prefix unit rule says".
+ * The vendor's rule says the opposite. Verbatim: a request hits when it "fully matches a cache
+ * prefix unit", and units form at "the end position of the user input" — so a byte-identical repeat
+ * of a request fully matches the user-input-end unit the first call recorded. That is the canonical
+ * KV-cache demonstration, and the SDK's own docs example shows it (promptCacheHitTokens 1856 /
+ * MissTokens 5). The twin was answering 0/0 for exactly that case, and the comment justifying it
+ * misquoted the page it cited.
+ *
+ * TWO properties are load-bearing and were both defects in the first cut:
+ *
+ *   • The count is taken over the CURRENT request's own messages, with the SAME function that
+ *     computes its `prompt_tokens` (`countPromptTokens`). The ledger stores only HOW MANY messages
+ *     the unit covers, never a token total of its own. Measuring the stored prefix text separately
+ *     produced a hit figure larger than the request's whole prompt — which `buildUsage`'s clamp then
+ *     silently hid, reporting a 100%-cache follow-up whose new turn had vanished from the
+ *     accounting. Deriving both halves from one function makes `hit + miss === prompt_tokens` a
+ *     structural fact rather than something a clamp rescues.
+ * (A second bullet used to stand here saying the full message list was deliberately excluded. That
+ * WAS the bug — see the paragraph above — and leaving the justification in place while the loop did
+ * the opposite is the same stale-comment class round one caught elsewhere. §9 round two,
+ * SHOULD-FIX 6.)
+ */
+export declare function cacheHitTokens(messages: DeepSeekMessageParam[], root?: string): number;
+/**
+ * Record the cache prefix units a served completion creates: the caller's messages (user-input
+ * end) and those plus the assistant turn (model-output end).
+ *
+ * `occurredAt` is threaded so the write is deterministic. Re-recording an identical prefix is
+ * idempotent by construction — the subject id is derived from the prefix content, and the kernel
+ * folds a repeat into the same subject — so a replayed request neither grows the log nor changes
+ * what a later request reads.
+ */
+export declare function recordCachePrefixes(messages: DeepSeekMessageParam[], assistant: DeepSeekMessageParam | null, occurredAt?: string, root?: string): Promise<void>;

package/dist/src/deepseek-cache.js

@@ -0,0 +1,151 @@
+// DeepSeek's CONTEXT CACHE, modeled as real state rather than a made-up number.
+//
+// Every DeepSeek chat completion reports `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens`
+// (api-docs.deepseek.com/guides/kv_cache, read 2026-08-31). A twin has two ways to fill those in:
+// fabricate a split (a lie the caller cannot detect), or actually keep the ledger. This file keeps
+// the ledger, in the kernel's append-only action log like every other piece of twin state, so the
+// number a caller reads is a fact about what this twin has actually served.
+//
+// THE VENDOR'S RULE, quoted: "A subsequent request can only hit the cache if it **fully matches** a
+// **cache prefix unit**", and prefix units are created at request boundaries — "user input end and
+// model output end". So:
+//   • after serving a request, the twin records TWO prefix units: the messages the caller sent
+//     (user-input end) and those messages plus the assistant turn it answered with (model-output
+//     end);
+//   • a later request hits on the LONGEST recorded unit that is a full prefix of its own message
+//     list; those tokens are `prompt_cache_hit_tokens`, the rest are misses.
+//
+// WHAT IS DELIBERATELY NOT MODELED (filed as todos, not faked):
+//   • the vendor also cuts units "at fixed token intervals" for long inputs — it publishes no
+//     interval, so this twin does not invent one (`deepseek.cache.interval_units`);
+//   • the vendor's cache is best-effort and "auto-clears within hours to days" — the twin does not
+//     expire entries yet (`deepseek.cache.expiry`, a TODO). It is deliberately NOT called
+//     impossible: the kernel's world clock is deterministic by construction and is explicitly the
+//     seam TTL/expiry logic reads at serve time, so this is unbuilt rather than unbuildable
+//     (§9 round one, SHOULD-FIX 5; the "must not have" wording that stood here was the claim that
+//     fix retracted).
+//
+// THE PREFIX KEY IS THE CONVERSATION TEXT, NOT THE RAW JSON. A caller replaying a turn rebuilds
+// the assistant message from its own client state, so the JSON it sends back is never byte-equal to
+// what the twin emitted (`@ai-sdk/deepseek`, for example, back-fills `reasoning_content: ''` on
+// every V4 assistant turn). Keying on `role:text` per message is what makes a genuine continuation
+// register as one; keying on the raw JSON would report a miss for every real conversation and the
+// whole ledger would be decoration.
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { contentToText, countPromptTokens, fnv1a } from "./deepseek-stub.js";
+const SERVICE = 'deepseek';
+/**
+ * The canonical text of one message — see the file header for why this, not the JSON.
+ *
+ * §9 ROUND ONE, NIT 15: the key must cover EVERY field `messageTokens` charges for. It previously
+ * dropped `name` and `reasoning_content` while the token count included them, so a caller could
+ * attach an arbitrarily large `reasoning_content` to a replayed assistant turn, still match the
+ * recorded unit, and have those tokens billed as a HIT. Both are now normalized into the key
+ * (`?? ''`), which keeps an absent field and an empty string identical — the shape
+ * `@ai-sdk/deepseek` produces, since it back-fills `reasoning_content: ''` on every V4 assistant
+ * turn — while making a DIFFERENT reasoning payload a different key, i.e. a miss. Under-reporting
+ * is the safe direction here; over-reporting bills the caller for cache they did not earn.
+ */
+export function canonicalMessage(m) {
+    // THE WHOLE tool call, not just name+arguments. §9 ROUND TWO, BLOCKER 1: `messageTokens` charges
+    // `estimateTokens(JSON.stringify(tc))` — id and type included — while this rendered only
+    // name(arguments). A caller could pad `tool_calls[0].id` with 4000 characters, still match the
+    // recorded unit, and have 999 tokens of its own padding billed as a cache HIT. That is the
+    // over-reporting direction this function's own header calls the unsafe one, and it was only
+    // runtime-reachable because the round-one fix to `cacheHitTokens` let a full replay match at all.
+    const calls = (m.tool_calls ?? []).map((tc) => JSON.stringify(tc)).join(',');
+    const name = m.name ?? '';
+    const reasoning = m.reasoning_content ?? '';
+    const toolCallId = m.tool_call_id ?? '';
+    return `${m.role}|${name}|${toolCallId}:${contentToText(m.content)}|r:${reasoning}${calls ? `|tools:${calls}` : ''}`;
+}
+/** The prefix key for the first `count` messages. */
+export function prefixKey(messages, count) {
+    // The separator is a NUL between newlines, written as an ESCAPE so this source file stays pure
+    // ASCII text. A raw NUL byte here would make `file` classify the module as binary, and `grep`
+    // silently matches NOTHING in a file it thinks is binary — so every later verification grep
+    // over this tree would read as "no survivors" while checking nothing (ADDING_A_TWIN.md §0.5).
+    // NUL is the right SEPARATOR because no message text can contain it, so two different
+    // conversations can never join into the same key.
+    return messages.slice(0, count).map(canonicalMessage).join('\n\u0000\n');
+}
+/** The deterministic subject id a prefix unit is stored under. */
+export function prefixId(key) {
+    return `cachepfx_twin_${fnv1a(key).toString(36)}_${key.length}`;
+}
+function prefixRows(root) {
+    return projectResources(SERVICE, root).filter((r) => r.type === 'cache_prefix');
+}
+/**
+ * How many of THIS request's prompt tokens hit the cache: the token count of the longest recorded
+ * prefix unit that fully matches the head of `messages` — INCLUDING the whole message list.
+ *
+ * §9 ROUND ONE, SHOULD-FIX 4: this used to stop one short (`count < messages.length`), on the
+ * stated grounds that counting the whole request "is not what the vendor's prefix unit rule says".
+ * The vendor's rule says the opposite. Verbatim: a request hits when it "fully matches a cache
+ * prefix unit", and units form at "the end position of the user input" — so a byte-identical repeat
+ * of a request fully matches the user-input-end unit the first call recorded. That is the canonical
+ * KV-cache demonstration, and the SDK's own docs example shows it (promptCacheHitTokens 1856 /
+ * MissTokens 5). The twin was answering 0/0 for exactly that case, and the comment justifying it
+ * misquoted the page it cited.
+ *
+ * TWO properties are load-bearing and were both defects in the first cut:
+ *
+ *   • The count is taken over the CURRENT request's own messages, with the SAME function that
+ *     computes its `prompt_tokens` (`countPromptTokens`). The ledger stores only HOW MANY messages
+ *     the unit covers, never a token total of its own. Measuring the stored prefix text separately
+ *     produced a hit figure larger than the request's whole prompt — which `buildUsage`'s clamp then
+ *     silently hid, reporting a 100%-cache follow-up whose new turn had vanished from the
+ *     accounting. Deriving both halves from one function makes `hit + miss === prompt_tokens` a
+ *     structural fact rather than something a clamp rescues.
+ * (A second bullet used to stand here saying the full message list was deliberately excluded. That
+ * WAS the bug — see the paragraph above — and leaving the justification in place while the loop did
+ * the opposite is the same stale-comment class round one caught elsewhere. §9 round two,
+ * SHOULD-FIX 6.)
+ */
+export function cacheHitTokens(messages, root) {
+    if (messages.length < 1)
+        return 0;
+    const byId = new Map();
+    for (const r of prefixRows(root))
+        if (!r._deleted)
+            byId.set(String(r.id), r);
+    if (byId.size === 0)
+        return 0;
+    for (let count = messages.length; count >= 1; count--) {
+        if (byId.has(prefixId(prefixKey(messages, count))))
+            return countPromptTokens(messages.slice(0, count));
+    }
+    return 0;
+}
+/**
+ * Record the cache prefix units a served completion creates: the caller's messages (user-input
+ * end) and those plus the assistant turn (model-output end).
+ *
+ * `occurredAt` is threaded so the write is deterministic. Re-recording an identical prefix is
+ * idempotent by construction — the subject id is derived from the prefix content, and the kernel
+ * folds a repeat into the same subject — so a replayed request neither grows the log nor changes
+ * what a later request reads.
+ */
+export async function recordCachePrefixes(messages, assistant, occurredAt, root) {
+    const units = [messages];
+    if (assistant)
+        units.push([...messages, assistant]);
+    for (const unit of units) {
+        if (unit.length === 0)
+            continue;
+        const key = prefixKey(unit, unit.length);
+        const id = prefixId(key);
+        await applyTwinWrite(SERVICE, {
+            operation: 'cache_prefix.observe',
+            subjectType: 'cache_prefix',
+            subjectId: id,
+            // `key` is stored so an operator inspecting the log can see WHAT was cached; `messages` is
+            // how many turns the unit covers. Deliberately NO token total: the hit count is measured off
+            // the requesting message list (see `cacheHitTokens`), never off the recorded one.
+            fields: { key: key.slice(0, 512), messages: unit.length },
+            ...(occurredAt ? { occurredAt } : {}),
+            actor: { kind: 'agent' },
+        }, root);
+    }
+}

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

@@ -0,0 +1,4 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const DEEPSEEK_CAPABILITIES: CapabilitySpec[];
+export declare const DEEPSEEK_AREAS: readonly ["anthropic", "auth", "balance", "beta", "cache", "chat", "completions", "conformance", "connector", "errors", "files", "models", "rate_limits", "reasoning", "responses", "streaming", "structured_outputs", "tools", "usage", "vision"];
+export declare function deepseekCapabilities(): Promise<CapabilityReport>;