opencode-cache-engine 0.4.0 → 0.4.1

package/package.json

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

package/src/cache-engine.ts

@@ -4,12 +4,7 @@ import {
   DEFAULT_CONFIG_PATH,
   DIGEST_TEMPLATE,
   affinityTelemetryFields,
-  POLICY_GLM53,
-  POLICY_GPT56,
-  POLICY_MIMO26,
-  POLICY_NEUTRAL,
   createRecorder,
-  detectPolicy,
   detectReasoningIssues,
   digestDecision,
   ensureMetricsDir,
@@ -37,6 +32,7 @@ import {
   toolFingerprint,
   toolWireFingerprint,
 } from "./cache-engine-core.mjs"
+import { resolveRuntimePolicy } from "./cache-policy-core.mjs"
 
 // ---------------------------------------------------------------------------
 // cache-engine
@@ -101,7 +97,21 @@ type Shape = {
   toolCount: number | null
 }
 
-type ModelInfo = { family: string; providerID: string; modelID: string }
+// Resolved runtime policy (the registry's runtime descriptor). `policy` is the
+// legacy telemetry/state string emitted by the pre-v0.4.0 classifier.
+type PolicyRuntime = {
+  policy: string
+  isNeutral: boolean
+  gptCacheMetadata: boolean
+  envRelocation: "glm" | "mimo" | null
+  thinkingIntegrity: boolean
+  cacheRatio: "glm" | "mimo" | null
+  providerChange: "glm" | "mimo" | null
+  prefixDiagnostics: boolean
+  openRouterAffinity: boolean
+}
+
+type ModelInfo = { family: string; providerID: string; modelID: string; caps: PolicyRuntime }
 
 type ToolCache = { semanticToolsHash: string | null; wireToolsHash: string | null }
 
@@ -258,19 +268,21 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
   // gpt56/glm53/deepseek classification once established.
   const rememberModel = (sid: string, model: ChatParamsModel | undefined): ModelInfo | null => {
     if (!model) return null
-    const family = detectPolicy(model)
+    // Single runtime source of policy classification: the registry resolver.
+    const caps = resolveRuntimePolicy(model) as PolicyRuntime
     const s = get(sid)
     const info: ModelInfo = {
-      family,
+      family: caps.policy,
       providerID: String(model.providerID ?? ""),
       modelID: String(model.api?.id ?? model.id ?? ""),
+      caps,
     }
-    if (s.modelInfo == null || (s.modelInfo.family === POLICY_NEUTRAL && family !== POLICY_NEUTRAL)) {
+    if (s.modelInfo == null || (s.modelInfo.caps.isNeutral && !caps.isNeutral)) {
       s.modelInfo = info
       // A title/summary request (neutral small model) may have established the
       // system baseline first. Its "powered by the model named ..." env line
       // differs from the real model's, so re-baseline on upgrade.
-      if (s.baselineSystem !== null && s.modelInfo.family !== POLICY_NEUTRAL) {
+      if (s.baselineSystem !== null && !caps.isNeutral) {
         s.baselineSystem = null
         s.shape = null
       }
@@ -350,11 +362,11 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
 
       s.lastProcessedMessageID = nextProcessedCursor(firstPage, startCursor)
 
-      const family = s.modelInfo?.family
+      const caps = s.modelInfo?.caps
       const glmIntegrity =
-        family === POLICY_GLM53 &&
-        policyEnabled(cfg, POLICY_GLM53) &&
-        cfg.policies?.[POLICY_GLM53]?.preserveThinkingIntegrity === true
+        caps?.thinkingIntegrity === true &&
+        policyEnabled(cfg, caps.policy) &&
+        cfg.policies?.[caps.policy]?.preserveThinkingIntegrity === true
 
       if (glmIntegrity && reasoningNewestFirst.length > 0) {
         // messages arrive newest-first; process oldest->newest so `seen` grows
@@ -417,11 +429,11 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
           recFields.model = s.modelInfo.modelID
           recFields.policy = s.modelInfo.family
         }
-        if (family === POLICY_GLM53) {
+        if (caps?.cacheRatio === "glm") {
           recFields.promptTokens = read + write + input
           recFields.glmHitRate = glmHitRatio(read, write, input)
         }
-        if (family === POLICY_MIMO26) {
+        if (caps?.cacheRatio === "mimo") {
           // Provider-reported cached tokens / total prompt tokens. The runtime's
           // `input` is the non-cached prompt input and `cache.read` is the
           // cached prompt input, so total prompt tokens are derived as read +
@@ -431,7 +443,7 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
           recFields.promptTokens = promptTokens
           recFields.cachedTokens = read
           recFields.cacheHitRate = mimoHitRate(read, promptTokens)
-          if (cfg.policies?.[POLICY_MIMO26]?.stickySession === true) {
+          if (cfg.policies?.[caps.policy]?.stickySession === true) {
             recFields.stickySessionId = mimoSessionIdFor(sid)
           }
           // Prefer the latest live provider identity over the latched one.
@@ -440,10 +452,10 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
             recFields.model = s.mimoProvider.modelID
           }
         }
-        if (family === POLICY_GPT56 && s.gptInjected) {
+        if (caps?.gptCacheMetadata === true && s.gptInjected) {
           recFields.keyStrategy = "session"
-          recFields.mode = cfg.policies?.[POLICY_GPT56]?.mode
-          recFields.ttl = cfg.policies?.[POLICY_GPT56]?.ttl
+          recFields.mode = cfg.policies?.[caps.policy]?.mode
+          recFields.ttl = cfg.policies?.[caps.policy]?.ttl
         }
         rec.record(recFields)
       } else {
@@ -495,8 +507,9 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
       try {
         const model = input.model as unknown as ChatParamsModel
         const providerID = String(model?.providerID ?? "")
-        const family = detectPolicy(model)
-        if (family !== POLICY_MIMO26 && family !== POLICY_GLM53) return
+        const caps = resolveRuntimePolicy(model) as PolicyRuntime
+        if (!caps.openRouterAffinity) return
+        const family = caps.policy
 
         const hasSessionIDHeader = (headers?: Record<string, string>) =>
           Object.keys(headers ?? {}).some((name) => name.toLowerCase() === "x-session-id")
@@ -536,6 +549,7 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
       try {
         const info = rememberModel(input.sessionID, input.model as unknown as ChatParamsModel)
         const family = info?.family
+        const caps = info?.caps
 
         // ---- MiMo-V2.6: provider-switch diagnostics (telemetry only) ---------
         // MiMo cache lives at the provider side, so a provider change within one
@@ -545,7 +559,7 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
         // NOTE: OpenRouter's *upstream* provider selection (e.g. xiaomi/fp8) is
         // not exposed to plugins; only the OpenCode providerID/modelID are
         // observable here.
-        if (family === POLICY_MIMO26 && policyEnabled(cfg, POLICY_MIMO26) && info) {
+        if (caps?.providerChange === "mimo" && policyEnabled(cfg, caps.policy) && info) {
           // Use the LIVE model identity (not the latched one) so a provider
           // switch within the session is actually observable.
           const live = input.model as unknown as ChatParamsModel
@@ -558,7 +572,7 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
             const ev = providerChangeEvent(s.mimoProvider, cur)
             if (ev.changed) {
               const sticky =
-                cfg.policies?.[POLICY_MIMO26]?.stickySession === true
+                cfg.policies?.[caps.policy]?.stickySession === true
                   ? { stickySessionId: mimoSessionIdFor(input.sessionID) }
                   : {}
               rec.record({
@@ -566,7 +580,7 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
                 sid: input.sessionID,
                 ts: Date.now(),
                 reason: "mimo_provider_changed",
-                policy: POLICY_MIMO26,
+                policy: caps.policy,
                 from: ev.from,
                 to: ev.to,
                 ...sticky,
@@ -579,7 +593,7 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
         }
 
         // ---- GLM-5.3 provider identity observation (telemetry only) ----------
-        if (family === POLICY_GLM53 && policyEnabled(cfg, POLICY_GLM53) && info) {
+        if (caps?.providerChange === "glm" && policyEnabled(cfg, caps.policy) && info) {
           const live = input.model as unknown as ChatParamsModel
           const cur = {
             providerID: String(live?.providerID ?? ""),
@@ -594,7 +608,7 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
                 sid: input.sessionID,
                 ts: Date.now(),
                 reason: "glm_provider_changed",
-                policy: POLICY_GLM53,
+                policy: caps.policy,
                 from: ev.from,
                 to: ev.to,
                 note: "OpenCode providerID changed; provider-specific upstream routing is not plugin-visible",
@@ -605,12 +619,12 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
           return
         }
 
-        if (!(family === POLICY_GPT56 && policyEnabled(cfg, POLICY_GPT56))) {
+        if (!(caps?.gptCacheMetadata === true && policyEnabled(cfg, caps.policy))) {
           // DeepSeek / GLM / neutral: nothing to inject. GLM has no cache-key API;
           // DeepSeek caching is fully passive; we never mutate requests for them.
           return
         }
-        const gpol = cfg.policies?.[POLICY_GPT56]
+        const gpol = cfg.policies?.[caps.policy]
         const applyRoot = gpol?.cacheRootKey !== false
         const compaction = input.agent === "compaction"
         const isolated = compaction && gpol?.compactionCacheIsolation === true
@@ -678,7 +692,7 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
             kind: "cache-options",
             sid: input.sessionID,
             ts: Date.now(),
-            policy: POLICY_GPT56,
+            policy: caps.policy,
             provider: info.providerID,
             model: info.modelID,
             keyStrategy: applyRoot ? "cache-root" : "session",
@@ -784,43 +798,40 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
         const model = input.model as unknown as ChatParamsModel
         rememberModel(sid, model)
         const s = get(sid)
-        const family = s.modelInfo?.family
+        const caps = s.modelInfo?.caps
 
         // ---- GLM-5.3 / MiMo-V2.6 input-shape stabilization ------------------
         // Relocate the identifiable volatile env block (per-day date) to the
         // tail of the single system string, content-preserving, ONLY when the
-        // family opts into system stabilization and the block markers are
-        // present exactly. Never touches other content/order; never applied to
-        // other families. The runtime passes a single-element system array
-        // (verified against the installed runtime), so no generic reordering is
-        // involved.
+        // resolved runtime policy opts into system stabilization and the block
+        // markers are present exactly. Never touches other content/order; never
+        // applied to other families. The runtime passes a single-element system
+        // array (verified against the installed runtime), so no generic
+        // reordering is involved.
         //
         // In-place mutation note: request.ts keeps using its own local `system`
         // array after the hook (the trigger's returned output is ignored), so
         // reassigning `output.system = [...]` would be lost. We rewrite the
         // single element in place instead.
         let systemText = output.system.join("\n")
-        const glmStabilize =
-          family === POLICY_GLM53 &&
-          policyEnabled(cfg, POLICY_GLM53) &&
-          cfg.policies?.[POLICY_GLM53]?.stabilizeSystem === true
-        const mimoStabilize =
-          family === POLICY_MIMO26 &&
-          policyEnabled(cfg, POLICY_MIMO26) &&
-          cfg.policies?.[POLICY_MIMO26]?.stabilizeSystem === true
-        if ((glmStabilize || mimoStabilize) && output.system.length === 1) {
+        const envVariant = caps?.envRelocation ?? null
+        const stabilize =
+          envVariant !== null &&
+          policyEnabled(cfg, caps!.policy) &&
+          cfg.policies?.[caps!.policy]?.stabilizeSystem === true
+        if (stabilize && output.system.length === 1) {
           const rel = relocateVolatileEnvBlock(output.system[0])
           if (rel.changed) {
             output.system[0] = rel.text
             systemText = rel.text
-            if (family === POLICY_MIMO26) {
+            if (envVariant === "mimo") {
               log("debug", "mimo system env block relocated to suffix", { sid })
               rec.record({
                 kind: "boundary",
                 sid,
                 ts: Date.now(),
                 reason: "mimo_system_env_relocated",
-                policy: POLICY_MIMO26,
+                policy: caps!.policy,
                 provider: s.modelInfo?.providerID,
                 model: s.modelInfo?.modelID,
               })
@@ -906,13 +917,13 @@ export const CacheEngine: Plugin = async ({ client, directory }) => {
           // MiMo-specific explicit diagnostic: the STABLE prefix changed (not
           // just the relocated volatile env suffix). Reported only; the new
           // content is never overwritten with a stale snapshot.
-          if (family === POLICY_MIMO26 && reasons.includes("system_stable_prefix_changed")) {
+          if (caps?.prefixDiagnostics === true && reasons.includes("system_stable_prefix_changed")) {
             rec.record({
               kind: "boundary",
               sid,
               ts: Date.now(),
               reason: "mimo_system_prefix_changed",
-              policy: POLICY_MIMO26,
+              policy: caps!.policy,
               provider: s.modelInfo?.providerID,
               model: s.modelInfo?.modelID,
               changedFields: granular,

package/src/cache-policy-core.mjs

@@ -17,8 +17,10 @@
 // `inventoryRef`. Inheritance is always explicit (`inheritsFrom`); "newer means
 // same behavior" is never an unconditional rule.
 //
-// This release does not wire the resolver into runtime hooks. detectPolicy()
-// remains the compatibility classifier until wiring is approved.
+// As of v0.4.1 the runtime hook layer (cache-engine.ts) consumes
+// resolveRuntimePolicy() as its single source of policy classification.
+// detectPolicy() is retained as the compatibility classifier for the legacy
+// POLICY_* strings.
 
 // ---------------------------------------------------------------------------
 // Model normalization (shared with the legacy classifier)
@@ -206,6 +208,36 @@ function resolveTransport(s) {
   return { id: p, kind: "direct", sessionAffinityHeader: null, stickyRouting: false, inventoryRef: "§5 OpenRouter transport" }
 }
 
+// ---------------------------------------------------------------------------
+// Runtime capability descriptors
+//
+// The runtime consumes `resolvePolicy(...).runtime` for gating. `policy` is the
+// legacy telemetry/state string, so telemetry stays byte-identical. Every
+// capability is explicit per registry entry: classification into a creator or
+// family never implies a mutation. `legacy: false` entries always resolve to
+// NEUTRAL_RUNTIME, so a future-looking model gains nothing until the registry
+// explicitly says so.
+// ---------------------------------------------------------------------------
+
+const NEUTRAL_RUNTIME = Object.freeze({
+  policy: "neutral",
+  isNeutral: true,
+  gptCacheMetadata: false,
+  envRelocation: null,
+  thinkingIntegrity: false,
+  cacheRatio: null,
+  providerChange: null,
+  prefixDiagnostics: false,
+  openRouterAffinity: false,
+})
+
+const rt = (policy, overrides = {}) => ({
+  ...NEUTRAL_RUNTIME,
+  ...overrides,
+  policy,
+  isNeutral: policy === "neutral",
+})
+
 // ---------------------------------------------------------------------------
 // Registry
 //
@@ -229,6 +261,7 @@ export const POLICY_REGISTRY = [
     baseline: "openai.gpt56.cache",
     overlays: ["gpt56.prompt-cache-options"],
     legacy: true,
+    runtime: rt("gpt56", { gptCacheMetadata: true }),
     inventoryRef: "§1 OpenAI",
   },
   {
@@ -243,7 +276,8 @@ export const POLICY_REGISTRY = [
     inheritsFrom: "gpt-5.6",
     overlays: [],
     legacy: false,
-    note: "Documented inheritance of the GPT-5.6-and-later baseline. No CacheEngine overlay is registered for gpt-6 yet.",
+    runtime: rt("neutral"),
+    note: "Documented inheritance of the GPT-5.6-and-later baseline. No CacheEngine overlay is registered for gpt-6 yet, so the runtime stays neutral.",
     inventoryRef: "§1 OpenAI",
   },
   {
@@ -256,6 +290,13 @@ export const POLICY_REGISTRY = [
     baseline: "zai.implicit-cache",
     overlays: ["glm53.env-relocation"],
     legacy: true,
+    runtime: rt("glm53", {
+      envRelocation: "glm",
+      thinkingIntegrity: true,
+      cacheRatio: "glm",
+      providerChange: "glm",
+      openRouterAffinity: true,
+    }),
     inventoryRef: "§3 Z.AI GLM",
   },
   {
@@ -268,6 +309,13 @@ export const POLICY_REGISTRY = [
     baseline: "xiaomi.implicit-cache",
     overlays: ["mimo26.env-relocation"],
     legacy: true,
+    runtime: rt("mimo26", {
+      envRelocation: "mimo",
+      cacheRatio: "mimo",
+      providerChange: "mimo",
+      prefixDiagnostics: true,
+      openRouterAffinity: true,
+    }),
     inventoryRef: "§4 Xiaomi MiMo",
   },
   {
@@ -279,6 +327,7 @@ export const POLICY_REGISTRY = [
     baseline: "xiaomi.implicit-cache",
     overlays: [],
     legacy: false,
+    runtime: rt("neutral"),
     policyStatus: "documented-series-member-without-registered-overlay",
     note: "Documented as a Pro mode in the same V2.6 series, but the inventory does not establish identical cache controls and CacheEngine registers no overlay for it.",
     inventoryRef: "§4 Xiaomi MiMo",
@@ -293,6 +342,7 @@ export const POLICY_REGISTRY = [
     baseline: "deepseek.kv-cache",
     overlays: [],
     legacy: true,
+    runtime: rt("deepseek"),
     inventoryRef: "§2 DeepSeek",
   },
 ]
@@ -301,13 +351,16 @@ export const POLICY_REGISTRY = [
 // Explicit aliases identified by the inventory
 // ---------------------------------------------------------------------------
 
+// `legacy` records whether the pre-v0.4.0 classifier already matched this alias.
+// Only legacy aliases carry runtime capabilities; newer documented aliases are
+// resolved for information but stay runtime-neutral (no new optimization).
 export const MODEL_ALIASES = {
-  "gpt-5.6": { canonicalId: "gpt-5.6-sol", family: "gpt-5.6", creator: "openai", inventoryRef: "§1 OpenAI" },
-  "gpt-daybreak-blue-latest": { canonicalId: "gpt-5.6-sol", family: "gpt-5.6", creator: "openai", inventoryRef: "§1 OpenAI" },
-  "gpt-daybreak-red-latest": { canonicalId: "gpt-5.6-cyber", family: "gpt-5.6", creator: "openai", inventoryRef: "§1 OpenAI" },
-  "deepseek-v4-flash": { canonicalId: "deepseek-flash", family: "deepseek", creator: "deepseek", status: "retired-legacy-id", inventoryRef: "§2 DeepSeek" },
-  "deepseek-chat": { canonicalId: null, family: "deepseek", creator: "deepseek", status: "retired", inventoryRef: "§2 DeepSeek" },
-  "deepseek-reasoner": { canonicalId: null, family: "deepseek", creator: "deepseek", status: "retired", inventoryRef: "§2 DeepSeek" },
+  "gpt-5.6": { canonicalId: "gpt-5.6-sol", family: "gpt-5.6", creator: "openai", legacy: true, inventoryRef: "§1 OpenAI" },
+  "gpt-daybreak-blue-latest": { canonicalId: "gpt-5.6-sol", family: "gpt-5.6", creator: "openai", legacy: false, inventoryRef: "§1 OpenAI" },
+  "gpt-daybreak-red-latest": { canonicalId: "gpt-5.6-cyber", family: "gpt-5.6", creator: "openai", legacy: false, inventoryRef: "§1 OpenAI" },
+  "deepseek-v4-flash": { canonicalId: "deepseek-flash", family: "deepseek", creator: "deepseek", legacy: true, status: "retired-legacy-id", inventoryRef: "§2 DeepSeek" },
+  "deepseek-chat": { canonicalId: null, family: "deepseek", creator: "deepseek", legacy: true, status: "retired", inventoryRef: "§2 DeepSeek" },
+  "deepseek-reasoner": { canonicalId: null, family: "deepseek", creator: "deepseek", legacy: true, status: "retired", inventoryRef: "§2 DeepSeek" },
 }
 
 // ---------------------------------------------------------------------------
@@ -320,6 +373,7 @@ function neutralResult(reason, transport) {
     family: "neutral",
     baseline: BASELINES["neutral.none"],
     overlays: [],
+    runtime: NEUTRAL_RUNTIME,
     transport,
     matchType: "neutral",
     matchReason: reason,
@@ -333,12 +387,19 @@ function overlaysFor(ids) {
   return (ids ?? []).map((id) => OVERLAYS[id]).filter(Boolean)
 }
 
+// Only legacy entries carry runtime capabilities. A non-legacy entry (gpt-6,
+// Pro UltraSpeed) resolves for information but stays neutral at runtime.
+function runtimeForEntry(entry) {
+  return entry.legacy === false ? NEUTRAL_RUNTIME : entry.runtime ?? NEUTRAL_RUNTIME
+}
+
 function resultFromEntry(entry, matchType, matchReason, matchedId, transport) {
   return {
     creator: entry.creator,
     family: entry.family,
     baseline: BASELINES[entry.baseline] ?? null,
     overlays: overlaysFor(entry.overlays),
+    runtime: runtimeForEntry(entry),
     transport,
     matchType,
     matchReason,
@@ -348,13 +409,17 @@ function resultFromEntry(entry, matchType, matchReason, matchedId, transport) {
   }
 }
 
-function resultFromFamily(family, creator, matchType, matchReason, matchedId, inventoryRef, note, transport) {
+function resultFromFamily(family, creator, matchType, matchReason, matchedId, inventoryRef, note, transport, aliasLegacy) {
   const entry = POLICY_REGISTRY.find((e) => e.family === family && e.kind !== "exact")
+  // An alias is runtime-active only when both the alias and its target family
+  // were recognized before v0.4.0.
+  const active = aliasLegacy !== false && (!entry || entry.legacy !== false)
   return {
     creator,
     family,
     baseline: entry ? BASELINES[entry.baseline] ?? null : null,
     overlays: entry ? overlaysFor(entry.overlays) : [],
+    runtime: active && entry ? entry.runtime ?? NEUTRAL_RUNTIME : NEUTRAL_RUNTIME,
     transport,
     matchType,
     matchReason,
@@ -386,7 +451,7 @@ export function resolvePolicy(model) {
     const familyEntry = POLICY_REGISTRY.find((e) => e.family === alias.family && e.kind !== "exact")
     if (familyEntry?.requiresOpenAIish && !isOpenAIish(s)) continue
     const reason = `alias:${id}->${alias.canonicalId ?? alias.family}`
-    return resultFromFamily(alias.family, alias.creator, "exact", reason, id, alias.inventoryRef, alias.status ?? null, transport)
+    return resultFromFamily(alias.family, alias.creator, "exact", reason, id, alias.inventoryRef, alias.status ?? null, transport, alias.legacy)
   }
 
   // 2. Exact model ids (documented models).
@@ -415,6 +480,13 @@ export function resolvePolicy(model) {
   return neutralResult("neutral:no-match", transport)
 }
 
+// Convenience accessor for the runtime: the legacy policy string + explicit
+// capability flags. This is the single source the runtime gates on; it is
+// guaranteed equal to the pre-v0.4.0 detectPolicy() classification.
+export function resolveRuntimePolicy(model) {
+  return resolvePolicy(model).runtime
+}
+
 // Compatibility classification used by detectPolicy(). Reproduces the
 // pre-v0.4.0 behavior exactly: it considers only `legacy` registry entries,
 // excludes newer-generation/alias/exact-overlay additions, and returns a family

package/test/cache-engine.test.mjs

@@ -55,6 +55,7 @@ import {
   POLICY_REGISTRY,
   resolveLegacyFamily,
   resolvePolicy,
+  resolveRuntimePolicy,
 } from "../src/cache-policy-core.mjs"
 
 const asst = (id, read, write) => ({
@@ -1551,3 +1552,192 @@ test("registry is traceable and internally consistent", () => {
     assert.ok(alias.family)
   }
 })
+
+// ===========================================================================
+// v0.4.1 runtime policy migration (behavior preservation)
+//
+// The runtime now classifies via resolveRuntimePolicy(). These tests prove the
+// resolved policy equals the legacy detectPolicy() string for every supported
+// model, and that the hook-observable behavior (GPT cache options, <env>
+// relocation, OpenRouter affinity) is unchanged. Newer/unknown models must
+// gain no mutation.
+// ===========================================================================
+
+const policyCoreURL = new URL("../src/cache-policy-core.mjs", import.meta.url).href
+
+test("v0.4.1: resolveRuntimePolicy.policy matches detectPolicy across a broad matrix", () => {
+  const samples = [
+    M("openai", "gpt-5.6"),
+    M("openai", "gpt-5.6-sol"),
+    M("openrouter", "openai/gpt-5.6-luna"),
+    M("openai-compatible", "gpt-5.6"),
+    M("openai", "gpt-6-astra"),
+    M("openai", "gpt-5.5"),
+    M("openai", "gpt-daybreak-blue-latest"),
+    M("openai", "gpt-daybreak-red-latest"),
+    M("zai", "glm-5.3"),
+    M("zai", "glm-5.3-flash"),
+    M("zai", "glm-5.2"),
+    M("xiaomi", "mimo-v2.6-flash"),
+    M("xiaomi", "mimo-v2.6-pro"),
+    M("xiaomi", "mimo-v2.6-pro-ultraspeed"),
+    M("xiaomi", "mimo-v2.5"),
+    M("deepseek", "deepseek-v4-pro"),
+    M("deepseek", "deepseek-flash"),
+    M("deepseek", "deepseek-v4-flash"),
+    M("deepseek", "deepseek-chat"),
+    M("openrouter", "x-ai/grok-4"),
+    {},
+    null,
+    undefined,
+    42,
+  ]
+  for (const m of samples) {
+    assert.equal(resolveRuntimePolicy(m).policy, detectPolicy(m))
+  }
+})
+
+test("v0.4.1: GPT-5.6 alias keeps the overlay but a newer alias stays runtime-neutral", () => {
+  // Legacy alias: gpt-5.6 -> gpt-5.6-sol (was matched by the old regex).
+  const legacy = resolveRuntimePolicy(M("openai", "gpt-5.6"))
+  assert.equal(legacy.policy, "gpt56")
+  assert.equal(legacy.gptCacheMetadata, true)
+  // Newer documented alias that the old classifier did NOT match: no mutation.
+  const newer = resolveRuntimePolicy(M("openai", "gpt-daybreak-blue-latest"))
+  assert.equal(newer.policy, "neutral")
+  assert.equal(newer.gptCacheMetadata, false)
+  assert.equal(resolvePolicy(M("openai", "gpt-daybreak-blue-latest")).family, "gpt-5.6")
+})
+
+async function runPolicyMigrationProbe() {
+  const home = mkdtempSync(join(tmpdir(), "ce-policy-migration-"))
+  const pluginURL = new URL("../src/cache-engine.ts", import.meta.url).href
+  const coreURL = new URL("../src/cache-engine-core.mjs", import.meta.url).href
+  const script = `
+    import assert from "node:assert/strict"
+    process.env.CACHE_ENGINE_METRICS_FILE = process.env.HOME + "/policy-migration.jsonl"
+    const { CacheEngine } = await import(${JSON.stringify(pluginURL)})
+    const { detectPolicy } = await import(${JSON.stringify(coreURL)})
+    const { resolvePolicy, resolveRuntimePolicy } = await import(${JSON.stringify(policyCoreURL)})
+    const client = {
+      app: { log: async () => ({}) },
+      session: { get: async () => ({ data: { parentID: null } }) },
+      tool: { list: async () => ({ data: [] }) },
+    }
+    const hooks = await CacheEngine({ client, directory: process.env.HOME })
+    assert.equal(typeof hooks["chat.params"], "function")
+    assert.equal(typeof hooks["chat.headers"], "function")
+    assert.equal(typeof hooks["experimental.chat.system.transform"], "function")
+    const SYS = ["A: keep1", "B: You are powered by the model named x. The exact model ID is acme/x", "C: <env>", "D: Today's date: 2026-08-17", "E: </env>", "F: keep2"].join("\\n")
+    const CASES = [
+      { name: "gpt-5.6", model: { providerID: "openai", id: "gpt-5.6", api: { id: "gpt-5.6", npm: "@ai-sdk/openai" } }, expect: { policy: "gpt56", env: false, gpt: true, header: false } },
+      { name: "gpt-5.6-openrouter", model: { providerID: "openrouter", id: "openai/gpt-5.6-sol", api: { id: "openai/gpt-5.6-sol" } }, expect: { policy: "gpt56", env: false, gpt: true, header: false } },
+      { name: "gpt-6-astra", model: { providerID: "openai", id: "gpt-6-astra", api: { id: "gpt-6-astra", npm: "@ai-sdk/openai" } }, expect: { policy: "neutral", env: false, gpt: false, header: false } },
+      { name: "gpt-5.5", model: { providerID: "openai", id: "gpt-5.5", api: { id: "gpt-5.5", npm: "@ai-sdk/openai" } }, expect: { policy: "neutral", env: false, gpt: false, header: false } },
+      { 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: "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 } },
+      { 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 } },
+      { name: "mimo-v2.6-pro-ultraspeed", model: { providerID: "xiaomi", id: "mimo-v2.6-pro-ultraspeed", api: { id: "mimo-v2.6-pro-ultraspeed" } }, expect: { policy: "neutral", env: false, gpt: false, header: false } },
+      { name: "mimo-v2.5", model: { providerID: "xiaomi", id: "mimo-v2.5", api: { id: "mimo-v2.5" } }, expect: { policy: "neutral", env: false, gpt: false, header: false } },
+      { name: "unknown-provider", model: { providerID: "mystery-provider", id: "xiaomi/mimo-v2.6-flash", api: { id: "xiaomi/mimo-v2.6-flash" } }, expect: { policy: "mimo26", env: true, gpt: false, header: false } },
+      { name: "unknown-openrouter", model: { providerID: "openrouter", id: "acme/mystery-9", api: { id: "acme/mystery-9" } }, expect: { policy: "neutral", env: false, gpt: false, header: false } },
+    ]
+    const results = []
+    for (const c of CASES) {
+      const model = c.model
+      const sid = "ses_" + c.name
+      const provider = { source: "config", info: { id: String(model.providerID ?? "") }, options: {} }
+      const existing = { "User-Agent": "preserve", "x-custom": "preserve" }
+      const paramsOut = { options: {} }
+      const headersOut = { headers: { ...existing } }
+      const sysOut = { system: [SYS] }
+      await hooks["chat.params"]({ sessionID: sid, agent: "build", model, provider, message: { id: "msg-" + c.name, sessionID: sid, role: "user", content: "probe" } }, paramsOut)
+      await hooks["experimental.chat.system.transform"]({ sessionID: sid, model, provider }, sysOut)
+      await hooks["chat.headers"]({ sessionID: sid, agent: "build", model, provider, message: { id: "msg-" + c.name, sessionID: sid, role: "user", content: "probe" } }, headersOut)
+      const rt = resolveRuntimePolicy(model)
+      const existingHeadersPreserved = Object.entries(existing).every(([k, v]) => headersOut.headers[k] === v)
+      results.push({
+        name: c.name,
+        runtimePolicy: rt.policy,
+        detectPolicy: detectPolicy(model),
+        richFamily: resolvePolicy(model).family,
+        overlays: resolvePolicy(model).overlays.map((o) => o.id),
+        systemRelocated: sysOut.system[0] !== SYS,
+        gptOptionInjected: paramsOut.options.promptCacheKey !== undefined,
+        gptOptions: paramsOut.options.promptCacheOptions ?? null,
+        affinityHeaderAttached: headersOut.headers["x-session-id"] !== undefined,
+        existingHeadersPreserved,
+        expect: c.expect,
+      })
+    }
+    process.stdout.write(JSON.stringify({ results }))
+  `
+  const stdout = execFileSync(process.execPath, ["--experimental-strip-types", "--input-type=module", "-e", script], {
+    cwd: process.cwd(),
+    env: { ...process.env, HOME: home },
+    encoding: "utf8",
+  })
+  return JSON.parse(stdout.trim())
+}
+
+let policyMigrationProbe
+const policyMigrationResults = async () => (policyMigrationProbe ??= runPolicyMigrationProbe())
+
+test("v0.4.1: runtime policy is the resolver's and stays equal to detectPolicy (hook path)", async () => {
+  const { results } = await policyMigrationResults()
+  assert.ok(results.length >= 15)
+  for (const r of results) {
+    assert.equal(r.runtimePolicy, r.detectPolicy, `${r.name}: resolver policy must equal legacy detectPolicy`)
+    assert.equal(r.runtimePolicy, r.expect.policy, `${r.name}: unexpected policy`)
+  }
+})
+
+test("v0.4.1: every supported model keeps its pre-migration hook behavior", async () => {
+  const { results } = await policyMigrationResults()
+  for (const r of results) {
+    assert.equal(r.systemRelocated, r.expect.env, `${r.name}: <env> relocation`)
+    assert.equal(r.gptOptionInjected, r.expect.gpt, `${r.name}: GPT cache-options injection`)
+    assert.equal(r.affinityHeaderAttached, r.expect.header, `${r.name}: OpenRouter affinity header`)
+    // No provider in the matrix mutates or drops pre-existing headers.
+    assert.equal(r.existingHeadersPreserved, true, `${r.name}: existing headers preserved`)
+  }
+})
+
+test("v0.4.1: GPT-5.6 keeps promptCacheOptions implicit/30m through the resolver", async () => {
+  const { results } = await policyMigrationResults()
+  const gpt = results.find((r) => r.name === "gpt-5.6")
+  assert.deepEqual(gpt.gptOptions, { mode: "implicit", ttl: "30m" })
+})
+
+test("v0.4.1: future-looking and unknown models gain no mutation", async () => {
+  const { results } = await policyMigrationResults()
+  const noMutation = [
+    "gpt-6-astra",
+    "gpt-daybreak-alias",
+    "gpt-5.5",
+    "glm-5.2",
+    "mimo-v2.6-pro-ultraspeed",
+    "mimo-v2.5",
+    "unknown-openrouter",
+  ]
+  for (const name of noMutation) {
+    const r = results.find((x) => x.name === name)
+    assert.ok(r, `${name} present`)
+    assert.equal(r.gptOptionInjected, false, `${name}: no GPT options`)
+    assert.equal(r.systemRelocated, false, `${name}: no <env> relocation`)
+    assert.equal(r.affinityHeaderAttached, false, `${name}: no affinity header`)
+  }
+})
+
+test("v0.4.1: non-OpenRouter models never receive the OpenRouter header", async () => {
+  const { results } = await policyMigrationResults()
+  for (const name of ["glm-5.3-direct", "mimo-v2.6-flash-direct", "unknown-provider", "gpt-5.6", "deepseek-v4-pro"]) {
+    const r = results.find((x) => x.name === name)
+    assert.equal(r.affinityHeaderAttached, false, `${name}: no affinity header off OpenRouter`)
+  }
+})