opencode-cache-engine 0.4.3 → 0.4.4

package/README.md

@@ -31,7 +31,7 @@ The plugin currently has four cache-policy families:
 * **GPT-5.6 and later** — documented cache-key/options metadata, with prompt text
   unchanged. GPT-6 and future 5.6+/6+/7+ versions resolve through the same
   documented boundary.
-* **GLM-5.3** — narrow, content-preserving `<env>` relocation and diagnostics.
+* **GLM-5.3 and later** — GLM implicit-cache baseline and diagnostics; GLM-5.3 additionally uses a narrow, content-preserving `<env>` relocation overlay.
 * **MiMo-V2.6** — narrow, content-preserving `<env>` relocation and diagnostics.
 
 Family classification is not hard-coded in the runtime. A pure policy registry
@@ -42,7 +42,7 @@ the single runtime source of policy classification. The first-party research
 behind each registry entry is recorded in
 [docs/cache-policy-inventory.md](docs/cache-policy-inventory.md).
 
-For both MiMo-V2.6 and GLM-5.3, CacheEngine adds its deterministic
+For MiMo-V2.6 and the GLM-5.3-and-later family, CacheEngine adds its deterministic
 `x-session-id` request header only when OpenCode identifies the actual provider
 as `openrouter`. It does not add that OpenRouter-specific header for
 non-OpenRouter providers; direct provider endpoints retain their provider-native
@@ -205,6 +205,12 @@ GLM-5.3 and MiMo-V2.6 use the only prompt-text transformation in the current
 plugin: a narrow, content-preserving relocation of the identifiable `<env>`
 block for the eligible model family.
 
+Since v0.4.4 the GLM **family baseline** and the GLM-5.3 **overlay** are
+separate. A resolved GLM-5.3-and-later model inherits the implicit-cache baseline
+and the non-mutating GLM diagnostics/transport, but the `<env>` relocation below
+is a GLM-5.3-specific overlay and is **not** inherited by a newer GLM merely
+because its version number is higher.
+
 The plugin identifies OpenCode's volatile `<env>` section and moves it to the **tail of the system prompt**.
 
 Conceptually:
@@ -428,7 +434,7 @@ and are reported diagnostically; the message content is left untouched.
 | ------------- | --------- | ------------------- | ----------------------- | -------------------------- | -------------------- |
 | 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) |
+| GLM-5.3 and later | `glm-5.3+` | Yes, narrowly (`<env>` tail) on GLM-5.3 only | 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` |
 
 `x-session-id` is an HTTP affinity header, not a provider cache key or
@@ -1392,7 +1398,7 @@ not matched.
 
 ## OpenRouter affinity header is not added
 
-CacheEngine adds its `x-session-id` only for a detected MiMo-V2.6 or GLM-5.3
+CacheEngine adds its `x-session-id` only for a detected MiMo-V2.6 or GLM-5.3-and-later
 request when the actual OpenCode `providerID` is exactly `openrouter`. A direct
 provider route or missing provider identity is bypassed. If a case-insensitive
 `x-session-id` is already present in model or plugin headers, it is preserved

package/docs/cache-policy-inventory.md

@@ -288,7 +288,7 @@ made here); **hold** = do not inherit without first-party evidence.
 | 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 |
+| 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 | GLM-5.3 family baseline via the 5.3-and-later boundary; **no** `<env>` overlay (v0.4.4) | **baseline only** — overlay stays 5.3-explicit | none documented | High (no later gens documented) | Z.AI *New Released*; *Pricing* | 2026-09-27 |
 | Z.AI | 5.2 and earlier negative controls: `glm-5.2`, `glm-5.1`, `glm-5`, `glm-4.7`, `glm-4.6`, `glm-4.5`, `glm-4-32b-*` | Cacheable (except `glm-4-32b-0414-128k`), different cached-input pricing; no cache-semantics difference documented | neutral | hold | n/a | High | Z.AI *Pricing*; *Chat Completion* (enum) | 2026-09-26 |
 | Xiaomi | MiMo V2.6 Flash: `mimo-v2.6-flash` (OR `xiaomi/mimo-v2.6-flash`) | Provider-managed implicit caching; `cached_tokens`; no documented min/TTL/key/prefix rules | MiMo policy: `<env>` relocation; provider-change telemetry; OpenRouter `x-session-id` | keep scoped as exact-model overlay | env relocation unsupported by docs → treat as overlay | Medium | MiMo *Models*; *Pricing*; *openai-api* | 2026-09-26 |
 | Xiaomi | MiMo V2.6 Pro: `mimo-v2.6-pro` (OR `xiaomi/mimo-v2.6-pro`) | Same documented per-model implicit caching; per-model pricing | MiMo policy (same as Flash) | keep | none documented | Medium | MiMo *Models*; *Pricing* | 2026-09-26 |
@@ -384,3 +384,24 @@ a newer model inherits an older policy. They must not be resolved by guessing.
 - 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.
+
+### Follow-up: v0.4.4 GLM-5.3-and-later baseline vs GLM-5.3 overlay
+
+- Z.AI docs were re-verified on **2026-09-27**. GLM-5.3 is the newest documented
+  text generation (no `glm-5.4`/`glm-6`); GLM-5.3 is explicitly "the same base
+  model as GLM-5.2" with post-training differences. Caching is implicit with no
+  `cache_control`/`prompt_cache_key`/breakpoint/TTL field; `cached_tokens` is the
+  reported field. Z.AI publishes **no** generational-inheritance rule.
+- The `<env>` relocation has **no first-party basis** — it is a CacheEngine
+  implementation overlay. v0.4.4 therefore separates the concepts:
+  - **Family baseline** (`zai.glm-5.3-plus`, predicate `glm >= 5.3`): implicit
+    caching plus the non-mutating GLM diagnostics/transport (thinking-integrity
+    telemetry, GLM cache ratio, provider-change telemetry, OpenRouter
+    `x-session-id`). No prompt rewrite.
+  - **GLM-5.3 overlay**: the `<env>` relocation stays registered only on the
+    GLM-5.3 family entry, so a later GLM does **not** inherit it.
+- GLM-5.2 and earlier remain neutral. No new GLM cache-control field is added,
+  and GLM-5.3 behavior is unchanged.
+- Evidence caveat: because no later GLM generation is documented, the
+  "GLM-5.3 and later" boundary is a CacheEngine inference about a passive
+  baseline, not a Z.AI contract; it is safe because it introduces no mutation.

package/package.json

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

package/src/cache-policy-core.mjs

@@ -102,6 +102,25 @@ export function isDeepseekV4OrLater(slug) {
   return false
 }
 
+// GLM-5.3-and-later family baseline (docs/cache-policy-inventory.md §3; Z.AI
+// docs re-verified 2026-09-27). Z.AI publishes no generational-inheritance rule
+// and no explicit cache control, so this is a CacheEngine inference about a
+// passive/implicit baseline; it is safe because it grants no mutation. The
+// GLM-5.3 `<env>` relocation is a separate, explicit overlay and is NOT granted
+// by this predicate. GLM-5.2 and earlier stay outside this family.
+export function isGlm53OrLater(slug) {
+  const text = String(slug ?? "").toLowerCase()
+  const re = /glm-(\d{1,3})(?:\.(\d))?(?![\d.])/g
+  let m
+  while ((m = re.exec(text)) !== null) {
+    const major = Number(m[1])
+    const minor = m[2] === undefined ? 0 : Number(m[2])
+    if (major > 5) return true
+    if (major === 5 && minor >= 3) 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" ->
@@ -344,6 +363,29 @@ export const POLICY_REGISTRY = [
     }),
     inventoryRef: "§3 Z.AI GLM",
   },
+  {
+    // v0.4.4: "GLM-5.3 and later" family baseline. A future 5.3+ model inherits
+    // the implicit-cache baseline and its non-mutating diagnostics/transport,
+    // but NOT the GLM-5.3-specific `<env>` relocation overlay (`overlays: []`
+    // and no `envRelocation` capability). GLM-5.2 and earlier stay neutral.
+    id: "zai.glm-5.3-plus",
+    creator: "z.ai",
+    family: "glm-5.3",
+    kind: "family",
+    predicate: isGlm53OrLater,
+    baseline: "zai.implicit-cache",
+    overlays: [],
+    legacy: true,
+    runtime: rt("glm53", {
+      thinkingIntegrity: true,
+      cacheRatio: "glm",
+      providerChange: "glm",
+      openRouterAffinity: true,
+    }),
+    boundary: "GLM-5.3 and later",
+    note: "Z.AI publishes no generational-inheritance rule and no explicit cache control. The baseline is implicit caching; the `<env>` relocation is a GLM-5.3-only CacheEngine overlay and is intentionally not inherited. No cache-control field is invented.",
+    inventoryRef: "§3 Z.AI GLM",
+  },
   {
     id: "xiaomi.mimo-v2.6",
     creator: "xiaomi",

package/test/cache-engine.test.mjs

@@ -54,6 +54,7 @@ import {
   OVERLAYS,
   POLICY_REGISTRY,
   isDeepseekV4OrLater,
+  isGlm53OrLater,
   isGpt56OrLater,
   resolveLegacyFamily,
   resolvePolicy,
@@ -1650,6 +1651,8 @@ async function runPolicyMigrationProbe() {
       { 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.4-direct", model: { providerID: "zai", id: "glm-5.4", api: { id: "glm-5.4" } }, expect: { policy: "glm53", env: false, gpt: false, header: false } },
+      { name: "glm-5.4-openrouter", model: { providerID: "openrouter", id: "z-ai/glm-5.4", api: { id: "z-ai/glm-5.4" } }, expect: { policy: "glm53", env: false, 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 } },
       { name: "mimo-v2.6-flash-direct", model: { providerID: "xiaomi", id: "mimo-v2.6-flash", api: { id: "mimo-v2.6-flash" } }, expect: { policy: "mimo26", env: true, gpt: false, header: false } },
       { name: "mimo-v2.6-pro-openrouter", model: { providerID: "openrouter", id: "xiaomi/mimo-v2.6-pro", api: { id: "xiaomi/mimo-v2.6-pro" } }, expect: { policy: "mimo26", env: true, gpt: false, header: true } },
@@ -1915,3 +1918,95 @@ test("v0.4.3: DeepSeek never receives OpenRouter affinity or GPT/GLM/MiMo fields
     assert.equal(r.existingHeadersPreserved, true, `${name}: headers preserved`)
   }
 })
+
+// ===========================================================================
+// v0.4.4 GLM-5.3-and-later family baseline vs the GLM-5.3-specific overlay
+//
+// Source: Z.AI docs re-verified 2026-09-27 (docs/cache-policy-inventory.md §3).
+// Z.AI documents implicit caching (no cache control) and publishes no
+// generational-inheritance rule; the `<env>` relocation is a CacheEngine overlay
+// with no first-party basis. GLM-5.2 and earlier stay neutral.
+// ===========================================================================
+
+test("v0.4.4: isGlm53OrLater matches GLM-5.3+ version tokens only", () => {
+  const inFamily = ["glm-5.3", "glm-5.3-flash", "glm-5.3-flashx", "glm-5.4", "glm-5.9", "glm-6", "z-ai/glm-5.3-flash"]
+  for (const id of inFamily) assert.equal(isGlm53OrLater(id), true, `${id} is 5.3+`)
+  const outOfFamily = ["glm-5.2", "glm-5.1", "glm-5", "glm-4.7", "glm-4.6", "glm-4.5", "glm-4.5-air", "glm-4-32b-0414-128k", ""]
+  for (const id of outOfFamily) assert.equal(isGlm53OrLater(id), false, `${id} is pre-5.3`)
+})
+
+test("v0.4.4: GLM-5.3 keeps its overlay; a later GLM gets the baseline only", () => {
+  const g53 = resolvePolicy(M("zai", "glm-5.3"))
+  assert.equal(g53.family, "glm-5.3")
+  assert.equal(baseId(g53), "zai.implicit-cache")
+  assert.deepEqual(overlayIds(g53), ["glm53.env-relocation"])
+
+  const g54 = resolvePolicy(M("zai", "glm-5.4"))
+  assert.equal(g54.creator, "z.ai")
+  assert.equal(g54.family, "glm-5.3")
+  assert.equal(baseId(g54), "zai.implicit-cache") // same family baseline
+  assert.deepEqual(overlayIds(g54), []) // overlay is NOT inherited
+
+  // Runtime capability separation: baseline diagnostics/transport yes, prompt rewrite no.
+  const c53 = resolveRuntimePolicy(M("zai", "glm-5.3"))
+  const c54 = resolveRuntimePolicy(M("zai", "glm-5.4"))
+  assert.equal(c54.policy, "glm53")
+  assert.equal(c54.envRelocation, null)
+  assert.equal(c54.thinkingIntegrity, true)
+  assert.equal(c54.cacheRatio, "glm")
+  assert.equal(c54.providerChange, "glm")
+  assert.equal(c54.openRouterAffinity, true)
+  assert.equal(c53.envRelocation, "glm")
+
+  // Boundary metadata is traceable and the overlay is registered separately.
+  const plus = POLICY_REGISTRY.find((e) => e.id === "zai.glm-5.3-plus")
+  assert.equal(plus.boundary, "GLM-5.3 and later")
+  assert.deepEqual(plus.overlays, [])
+  assert.ok(plus.inventoryRef)
+})
+
+test("v0.4.4: GLM-5.2 and earlier stay neutral", () => {
+  for (const id of ["glm-5.2", "glm-5.1", "glm-5", "glm-4.7", "glm-4.6", "glm-4.5"]) {
+    const r = resolvePolicy(M("zai", id))
+    assert.equal(r.family, "neutral", `${id} neutral`)
+    assert.deepEqual(overlayIds(r), [])
+    assert.equal(resolveRuntimePolicy(M("zai", id)).policy, "neutral")
+  }
+})
+
+test("v0.4.4: legacy detectPolicy follows the GLM-5.3-and-later boundary", () => {
+  assert.equal(detectPolicy(M("zai", "glm-5.3-flash")), POLICY_GLM53)
+  assert.equal(detectPolicy(M("zai", "glm-5.4")), POLICY_GLM53)
+  assert.equal(detectPolicy(M("zai", "glm-5.2")), POLICY_NEUTRAL)
+})
+
+test("v0.4.4: <env> absent leaves system content unchanged", () => {
+  const plain = "Stable instructions only.\nNo environment block here."
+  const r = relocateVolatileEnvBlock(plain)
+  assert.equal(r.changed, false)
+  assert.equal(r.text, plain)
+})
+
+test("v0.4.4: later GLM inherits the baseline but never the <env> rewrite (runtime)", async () => {
+  const { results } = await policyMigrationResults()
+  const g53 = results.find((r) => r.name === "glm-5.3-direct")
+  const g54 = results.find((r) => r.name === "glm-5.4-direct")
+  assert.ok(g53 && g54)
+  // Identical system text with a valid <env> block present in both cases.
+  assert.equal(g53.systemRelocated, true) // 5.3 overlay fires
+  assert.equal(g54.systemRelocated, false) // later GLM does NOT inherit it
+  assert.equal(g54.runtimePolicy, "glm53") // but the family baseline applies
+  assert.equal(g54.gptOptionInjected, false)
+  assert.equal(g54.affinityHeaderAttached, false)
+})
+
+test("v0.4.4: GLM OpenRouter affinity is transport-gated for later GLM too", async () => {
+  const { results } = await policyMigrationResults()
+  const or = results.find((r) => r.name === "glm-5.4-openrouter")
+  const direct = results.find((r) => r.name === "glm-5.4-direct")
+  assert.equal(or.affinityHeaderAttached, true)
+  assert.equal(or.systemRelocated, false)
+  assert.equal(direct.affinityHeaderAttached, false)
+  assert.equal(or.existingHeadersPreserved, true)
+  assert.equal(direct.existingHeadersPreserved, true)
+})