opencode-cache-engine 0.4.2 → 0.4.3

package/README.md

@@ -74,7 +74,7 @@ The plugin deliberately avoids pretending that a local hash is proof of a provid
 
 # Provider behavior
 
-## DeepSeek V4.1 Flash
+## DeepSeek V4 and later
 
 ### Policy: passive
 
@@ -93,6 +93,13 @@ The DeepSeek branch exists primarily to preserve a stable harness while providin
 
 This is intentional. The implementation describes DeepSeek as a passive policy whose purpose is to preserve the existing high-cache-rate behavior rather than introduce new request mutations.
 
+Since v0.4.3 this is formalized as the documented **"DeepSeek V4 and later"**
+family. Canonical ids (`deepseek-flash`, `deepseek-v4-pro`) and the accepted
+`deepseek-v4-flash` aliases resolve to this passive baseline, and pre-V4 or
+unknown future `*deepseek*` ids fall back to the same passive baseline. No cache
+key, cache-control field, prompt rewrite, or OpenRouter affinity is ever added
+for DeepSeek.
+
 The plugin still observes:
 
 * system-prompt shape
@@ -419,7 +426,7 @@ and are reported diagnostically; the message content is left untouched.
 
 | Policy family | Detection | Prompt text changed? | Cache metadata changed? | OpenRouter affinity header | Primary cache signal |
 | ------------- | --------- | ------------------- | ----------------------- | -------------------------- | -------------------- |
-| DeepSeek | `deepseek` | No | No | None | provider `cache.read` / `cache.write` |
+| DeepSeek | `deepseek` (V4-and-later family + passive fallback) | No | No | None | provider `cache.read` / `cache.write` |
 | GPT-5.6 and later | version boundary `gpt-<major>[.<minor>] ≥ 5.6` on OpenAI-ish endpoints (includes GPT-6) | No | Yes: `prompt_cache_key` + options | None | provider cache tokens |
 | GLM-5.3 | `glm-5.3*` | Yes, narrowly (`<env>` tail) | No provider cache key | `x-session-id` on OpenRouter only | provider cache tokens (GLM ratio) |
 | MiMo-V2.6 | Flash / Pro only | Yes, narrowly (`<env>` tail) | No: implicit caching only | `x-session-id` on OpenRouter only | `cached_tokens / prompt_tokens` |

package/docs/cache-policy-inventory.md

@@ -285,7 +285,7 @@ made here); **hold** = do not inherit without first-party evidence.
 | OpenAI | pre-5.6 negative controls: `gpt-5.5`, `gpt-5.4`, `gpt-5.2`, `gpt-5.1`, `gpt-5`, `gpt-4.1`, `gpt-4o` | Implicit only; different min-length class; `in_memory`/`24h` retention; `prompt_cache_key` for routing | neutral | **hold** — do not inherit 5.6 policy | n/a | High | OpenAI *Prompt caching*; *Pricing* | 2026-09-26 |
 | DeepSeek | V4: `deepseek-v4-pro`, legacy `deepseek-v4-flash` | Provider-wide automatic disk cache; implicit; prefix-unit matching; hit/miss token fields | Passive (no mutation) | keep | none | High | DeepSeek *Context Caching*; *Models & Pricing* | 2026-09-26 |
 | DeepSeek | V4.1 / current V4-family: `deepseek-flash` (MODEL VERSION "DeepSeek-V4.1-Flash") | Same provider-wide automatic policy; cache-hit pricing listed for both current models | Passive | keep (creator/family baseline) | none documented | High | DeepSeek *Models & Pricing*; *news260910* | 2026-09-26 |
-| DeepSeek | future-looking V4+ identifiers: `deepseek-v4.1`, `deepseek-v4`, `deepseek-v5` | Not documented as request ids (`deepseek-v4.1`/`deepseek-v4` invalid or version-string only) | Passive via `/deepseek/i` substring (e.g. `deepseek-v5` already passive) | keep passive; treat as unknown-friendly | none | Medium (detection) / Low (future ids) | DeepSeek *Models & Pricing*; *Chat Completions API* | 2026-09-26 |
+| DeepSeek | future-looking V4+ identifiers: `deepseek-v4.1`, `deepseek-v4`, `deepseek-v5` | Not documented as request ids (`deepseek-v4.1`/`deepseek-v4` invalid or version-string only) | Passive via the V4-and-later family predicate or the safe creator fallback (v0.4.3); no mutation | keep passive; treat as unknown-friendly | none | Medium (detection) / Low (future ids) | DeepSeek *Models & Pricing*; *Chat Completions API* | 2026-09-27 |
 | DeepSeek | pre-V4 negative controls: `deepseek-chat`, `deepseek-reasoner` | Retired names (retired 2026-07-24); no separate V4+ cache policy claimed | Passive | hold | n/a | High | DeepSeek *Change Log*; *news260424* | 2026-09-26 |
 | Z.AI | GLM 5.3: `glm-5.3`, `glm-5.3-flash`, `glm-5.3-flashx` | Implicit automatic caching; `cached_tokens`; stable-prompt-first guidance; no documented min/TTL/key | GLM policy: `<env>` relocation; OpenRouter `x-session-id` | keep (env relocation is an exact overlay, not a Z.AI control) | env relocation is the overlay; keep scoped to GLM-5.3 | Medium | Z.AI *Context Caching*; *Chat Completion*; *Pricing* | 2026-09-26 |
 | Z.AI | current later GLM generations (documented): none newer than 5.3; newest below is `glm-5.2`/`glm-5.1`/`glm-5`/`glm-4.7` | Same implicit mechanism documented service-wide; cached-input price per model | neutral (only `glm-5.3` matched) | **hold** — no doc says 5.3 overlay extends upward; none newer documented | n/a | High (no later gens documented) | Z.AI *New Released*; *Pricing* | 2026-09-26 |
@@ -362,3 +362,25 @@ a newer model inherits an older policy. They must not be resolved by guessing.
 - The only OpenAI cache controls injected remain `promptCacheKey` +
   `promptCacheOptions{implicit,30m}`; no breakpoint or prewarm behavior was
   added. DeepSeek, GLM, MiMo, and OpenRouter affinity behavior are unchanged.
+
+### Follow-up: v0.4.3 DeepSeek V4-and-later passive coverage
+
+- DeepSeek first-party docs were re-verified on **2026-09-27**. Confirmed:
+  context caching is provider-wide and passive — no `prompt_cache_key`, flag, or
+  breakpoint exists, and Anthropic-style `cache_control` is documented as
+  **ignored**. Only `user_id` is cache-relevant (KVCache isolation). Usage fields
+  are `prompt_cache_hit_tokens`, `prompt_cache_miss_tokens`, and
+  `prompt_tokens_details.cached_tokens`.
+- Canonical request ids are `deepseek-flash` (= DeepSeek-V4.1-Flash) and
+  `deepseek-v4-pro`; `deepseek-v4-flash`/`deepseek-v4-flash-vision-exp` are
+  accepted retired aliases, and `deepseek-chat`/`deepseek-reasoner` are
+  discontinued. First-party docs publish **no** generational naming rule, and the
+  V4.1 codename id `deepseek-flash` carries no version token.
+- v0.4.3 adds a passive `deepseek.v4-plus` family entry: canonical ids match by
+  exact id, `deepseek-v<major≥4>` version tokens match by predicate, and
+  pre-V4 / retired / unknown future `*deepseek*` ids fall through to the passive
+  creator baseline. No cache-control field, cache key, prompt rewrite, or
+  OpenRouter affinity is introduced for DeepSeek.
+- Evidence caveat: first-party pages conflict on whether `deepseek-v4-pro` still
+  routes as a distinct model in late 2026; this does not affect the passive
+  policy, which carries no mutation either way.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-cache-engine",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "private": false,
   "description": "Provider-aware prompt-cache optimization and telemetry for OpenCode",
   "keywords": [

package/src/cache-policy-core.mjs

@@ -81,6 +81,27 @@ export function isGpt56OrLater(slug) {
   return false
 }
 
+// DeepSeek V4-and-later coverage (docs/cache-policy-inventory.md §2; 2026-09-27
+// first-party re-check). DeepSeek caching is provider-wide and passive: there is
+// no cache key, flag, or breakpoint, and Anthropic-style `cache_control` is
+// documented as ignored. This predicate therefore only classifies a version
+// token (`deepseek-v<major>[.<minor>]` with major >= 4) into the passive family;
+// it grants no mutation. Because the baseline is passive, matching an unknown
+// future `deepseek-v5+` id is safe by construction.
+//
+// First-party docs do NOT publish a generational naming rule, and the current
+// V4.1 codename id `deepseek-flash` carries no version token, so it is covered
+// by explicit exact ids rather than by this predicate.
+export function isDeepseekV4OrLater(slug) {
+  const text = String(slug ?? "").toLowerCase()
+  const re = /deepseek-v(\d+)(?:\.(\d+))?(?![\d.])/g
+  let m
+  while ((m = re.exec(text)) !== null) {
+    if (Number(m[1]) >= 4) return true
+  }
+  return false
+}
+
 // Candidate ids for exact/alias lookup. Includes the raw apiID/modelID, the
 // lower-cased forms, and a single stripped transport/vendor prefix
 // (e.g. "openai/gpt-5.6-luna" -> "gpt-5.6-luna", "xiaomi/mimo-v2.6-flash" ->
@@ -357,6 +378,28 @@ export const POLICY_REGISTRY = [
     inventoryRef: "§4 Xiaomi MiMo",
   },
   {
+    // v0.4.3: formalize the documented "DeepSeek V4 and later" family. Coverage
+    // is passive (no mutation, no overlays). Version ids inherit via the
+    // predicate; the V4.1 codename id `deepseek-flash` has no version token and
+    // is matched by exact id. Pre-V4 and unknown future ids fall through to the
+    // passive creator baseline below, so nothing speculative is ever applied.
+    id: "deepseek.v4-plus",
+    creator: "deepseek",
+    family: "deepseek",
+    kind: "family",
+    predicate: isDeepseekV4OrLater,
+    exactIds: ["deepseek-flash", "deepseek-v4-pro"],
+    baseline: "deepseek.kv-cache",
+    overlays: [],
+    legacy: true,
+    runtime: rt("deepseek"),
+    boundary: "DeepSeek V4 and later",
+    note: "DeepSeek caching is provider-wide and passive (no cache key, flag, breakpoint, or cache-control; Anthropic `cache_control` is ignored). Verified 2026-09-27. Canonical current ids: `deepseek-flash` (V4.1-Flash) and `deepseek-v4-pro`; `deepseek-v4-flash`/`deepseek-v4-flash-vision-exp` are accepted retired aliases.",
+    inventoryRef: "§2 DeepSeek",
+  },
+  {
+    // Safe passive fallback for any other `*deepseek*` id (pre-V4, retired, or
+    // unknown future models) so DeepSeek always fails safe to observation only.
     id: "deepseek.baseline",
     creator: "deepseek",
     family: "deepseek",

package/test/cache-engine.test.mjs

@@ -53,6 +53,7 @@ import {
   MODEL_ALIASES,
   OVERLAYS,
   POLICY_REGISTRY,
+  isDeepseekV4OrLater,
   isGpt56OrLater,
   resolveLegacyFamily,
   resolvePolicy,
@@ -1392,11 +1393,12 @@ test("resolvePolicy: pre-5.6 GPT negative controls are neutral with no overlays"
   }
 })
 
-test("resolvePolicy: DeepSeek V4 / V4.1 resolve to the creator baseline (passive, no overlay)", () => {
+test("resolvePolicy: DeepSeek V4 / V4.1 resolve to the passive baseline (no overlay)", () => {
   const v4 = resolvePolicy(M("deepseek", "deepseek-v4-pro"))
   assert.equal(v4.creator, "deepseek")
   assert.equal(v4.family, "deepseek")
-  assert.equal(v4.matchType, "creator")
+  // v0.4.3: deepseek-v4-pro is a documented canonical id, so it matches exactly.
+  assert.equal(v4.matchType, "exact")
   assert.equal(baseId(v4), "deepseek.kv-cache")
   assert.deepEqual(overlayIds(v4), [])
 
@@ -1642,6 +1644,10 @@ async function runPolicyMigrationProbe() {
       { name: "gpt-daybreak-alias", model: { providerID: "openai", id: "gpt-daybreak-blue-latest", api: { id: "gpt-daybreak-blue-latest", npm: "@ai-sdk/openai" } }, expect: { policy: "neutral", env: false, gpt: false, header: false } },
       { name: "deepseek-v4-pro", model: { providerID: "deepseek", id: "deepseek-v4-pro", api: { id: "deepseek-v4-pro" } }, expect: { policy: "deepseek", env: false, gpt: false, header: false } },
       { name: "deepseek-flash", model: { providerID: "deepseek", id: "deepseek-flash", api: { id: "deepseek-flash" } }, expect: { policy: "deepseek", env: false, gpt: false, header: false } },
+      { name: "deepseek-v5-future", model: { providerID: "deepseek", id: "deepseek-v5", api: { id: "deepseek-v5" } }, expect: { policy: "deepseek", env: false, gpt: false, header: false } },
+      { name: "deepseek-v3-pre", model: { providerID: "deepseek", id: "deepseek-v3", api: { id: "deepseek-v3" } }, expect: { policy: "deepseek", env: false, gpt: false, header: false } },
+      { name: "deepseek-openrouter", model: { providerID: "openrouter", id: "deepseek/deepseek-v4-pro", api: { id: "deepseek/deepseek-v4-pro" } }, expect: { policy: "deepseek", env: false, gpt: false, header: false } },
+      { name: "deepseek-gateway", model: { providerID: "acme-gateway", id: "my-deepseek-mirror", api: { id: "my-deepseek-mirror" } }, expect: { policy: "deepseek", env: false, gpt: false, header: false } },
       { name: "glm-5.3-direct", model: { providerID: "zai", id: "glm-5.3", api: { id: "glm-5.3" } }, expect: { policy: "glm53", env: true, gpt: false, header: false } },
       { name: "glm-5.3-openrouter", model: { providerID: "openrouter", id: "z-ai/glm-5.3-flash", api: { id: "z-ai/glm-5.3-flash" } }, expect: { policy: "glm53", env: true, gpt: false, header: true } },
       { name: "glm-5.2", model: { providerID: "zai", id: "glm-5.2", api: { id: "glm-5.2" } }, expect: { policy: "neutral", env: false, gpt: false, header: false } },
@@ -1819,3 +1825,93 @@ test("v0.4.2: pre-5.6 and out-of-family GPT ids get no GPT options", async () =>
     assert.equal(r.runtimePolicy, "neutral", `${name}: neutral runtime`)
   }
 })
+
+// ===========================================================================
+// v0.4.3 DeepSeek V4-and-later passive coverage
+//
+// Source: DeepSeek first-party docs re-verified 2026-09-27
+// (docs/cache-policy-inventory.md §2). Caching is provider-wide and passive:
+// no cache key/flag/breakpoint; Anthropic `cache_control` is ignored.
+// ===========================================================================
+
+test("v0.4.3: isDeepseekV4OrLater matches V4+ version tokens only", () => {
+  const inFamily = ["deepseek-v4-pro", "deepseek-v4-flash", "deepseek-v4.1", "deepseek-v4.5-pro", "deepseek-v5", "deepseek-v10", "deepseek/deepseek-v4-pro"]
+  for (const id of inFamily) assert.equal(isDeepseekV4OrLater(id), true, `${id} is V4+`)
+  const outOfFamily = ["deepseek-v3", "deepseek-v2", "deepseek-chat", "deepseek-reasoner", "deepseek-coder", "deepseek-flash", "my-deepseek-mirror", ""]
+  for (const id of outOfFamily) assert.equal(isDeepseekV4OrLater(id), false, `${id} is not a V4+ version token`)
+})
+
+test("v0.4.3: canonical V4 ids and aliases resolve to the passive DeepSeek family", () => {
+  for (const id of ["deepseek-flash", "deepseek-v4-pro"]) {
+    const r = resolvePolicy(M("deepseek", id))
+    assert.equal(r.creator, "deepseek")
+    assert.equal(r.family, "deepseek")
+    assert.equal(baseId(r), "deepseek.kv-cache")
+    assert.deepEqual(overlayIds(r), [])
+    const rt = resolveRuntimePolicy(M("deepseek", id))
+    assert.equal(rt.policy, "deepseek")
+    assert.equal(rt.gptCacheMetadata, false)
+    assert.equal(rt.envRelocation, null)
+    assert.equal(rt.cacheRatio, null)
+    assert.equal(rt.openRouterAffinity, false)
+  }
+  // v0.4.0 alias handling is preserved.
+  const alias = resolvePolicy(M("deepseek", "deepseek-v4-flash"))
+  assert.equal(alias.family, "deepseek")
+  assert.ok(alias.matchReason.startsWith("alias:deepseek-v4-flash"))
+  assert.equal(resolveRuntimePolicy(M("deepseek", "deepseek-v4-flash")).policy, "deepseek")
+  assert.equal(resolvePolicy(M("deepseek", "deepseek-chat")).family, "deepseek")
+})
+
+test("v0.4.3: later and unknown DeepSeek ids stay passive (no speculative mutation)", () => {
+  for (const id of ["deepseek-v5", "deepseek-v6.2", "deepseek-v4.1-pro", "deepseek-nova"]) {
+    const r = resolvePolicy(M("deepseek", id))
+    assert.equal(r.creator, "deepseek")
+    assert.equal(r.family, "deepseek")
+    assert.deepEqual(overlayIds(r), [], `${id}: no overlay`)
+    const rt = resolveRuntimePolicy(M("deepseek", id))
+    assert.equal(rt.policy, "deepseek", `${id}: passive policy`)
+    assert.equal(rt.gptCacheMetadata, false)
+    assert.equal(rt.envRelocation, null)
+    assert.equal(rt.cacheRatio, null)
+    assert.equal(rt.openRouterAffinity, false)
+  }
+})
+
+test("v0.4.3: pre-V4 DeepSeek ids remain passive and outside the V4+ family entry", () => {
+  for (const id of ["deepseek-v3", "deepseek-v2", "deepseek-coder"]) {
+    const r = resolvePolicy(M("deepseek", id))
+    assert.equal(r.family, "deepseek")
+    // handled by the safe creator fallback, not the V4+ family predicate
+    assert.equal(r.matchType, "creator", `${id}: creator fallback`)
+    assert.equal(resolveRuntimePolicy(M("deepseek", id)).policy, "deepseek")
+  }
+})
+
+test("v0.4.3: DeepSeek keeps the generic read/write ratio and no family-specific fields", () => {
+  const rt = resolveRuntimePolicy(M("deepseek", "deepseek-v4-pro"))
+  assert.equal(rt.cacheRatio, null) // generic read/(read+write) accounting is used
+  assert.equal(hitRatePct(30, 70), 30)
+})
+
+test("v0.4.3: DeepSeek never receives OpenRouter affinity or GPT/GLM/MiMo fields", async () => {
+  const { results } = await policyMigrationResults()
+  const deepseekCases = [
+    "deepseek-v4-pro",
+    "deepseek-flash",
+    "deepseek-v5-future",
+    "deepseek-v3-pre",
+    "deepseek-openrouter",
+    "deepseek-gateway",
+  ]
+  for (const name of deepseekCases) {
+    const r = results.find((x) => x.name === name)
+    assert.ok(r, `${name} present`)
+    assert.equal(r.runtimePolicy, "deepseek", `${name}: passive policy`)
+    assert.equal(r.detectPolicy, "deepseek", `${name}: detectPolicy agrees`)
+    assert.equal(r.gptOptionInjected, false, `${name}: no GPT options leak`)
+    assert.equal(r.systemRelocated, false, `${name}: no GLM/MiMo env relocation`)
+    assert.equal(r.affinityHeaderAttached, false, `${name}: no OpenRouter affinity`)
+    assert.equal(r.existingHeadersPreserved, true, `${name}: headers preserved`)
+  }
+})