@volter/twin-deepseek 0.1.0

package/src/deepseek-cache.ts

@@ -0,0 +1,159 @@
+// 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.ts';
+import type { DeepSeekMessageParam } from './deepseek-types.ts';
+
+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: DeepSeekMessageParam): string {
+  // 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: DeepSeekMessageParam[], count: number): string {
+  // 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: string): string {
+  return `cachepfx_twin_${fnv1a(key).toString(36)}_${key.length}`;
+}
+
+type PrefixRow = { id: unknown; messages?: unknown; key?: unknown; _deleted?: unknown };
+
+function prefixRows(root?: string): PrefixRow[] {
+  return projectResources(SERVICE, root).filter((r) => r.type === 'cache_prefix') as unknown as PrefixRow[];
+}
+
+/**
+ * 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: DeepSeekMessageParam[], root?: string): number {
+  if (messages.length < 1) return 0;
+  const byId = new Map<string, PrefixRow>();
+  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: DeepSeekMessageParam[],
+  assistant: DeepSeekMessageParam | null,
+  occurredAt?: string,
+  root?: string,
+): Promise<void> {
+  const units: DeepSeekMessageParam[][] = [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);
+  }
+}