opencode-cache-engine 0.4.0 → 0.4.2

package/README.md

@@ -18,15 +18,30 @@ plugin under `~/.config/opencode/plugins/`. For released installs where
 reproducibility matters, pin an exact package version rather than relying on
 `@latest` resolution or a moving cache entry; see [Installation](#installation).
 
+Quick Installation (TUI): 
+``` text
+opencode plugin opencode-cache-engine
+```
+
 `CacheEngine` is an OpenCode plugin designed for long-running agent sessions where prompt-cache efficiency affects both latency and cost. It keeps the harness conservative for providers whose cache behavior is already automatic, while applying provider-specific optimizations where the provider exposes useful cache controls or where prompt structure can be safely improved.
 
 The plugin currently has four cache-policy families:
 
 * **DeepSeek** — passive cache observability; request structure is preserved.
-* **GPT-5.6** — documented cache-key/options metadata, with prompt text unchanged.
+* **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.
 * **MiMo-V2.6** — narrow, content-preserving `<env>` relocation and diagnostics.
 
+Family classification is not hard-coded in the runtime. A pure policy registry
+and resolver in `src/cache-policy-core.mjs` returns a structured result
+(`creator`, `family`, `baseline`, `overlays`, `transport`, `matchType`,
+`matchReason`), and the hooks gate their behavior on that result. The registry is
+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
 `x-session-id` request header only when OpenCode identifies the actual provider
 as `openrouter`. It does not add that OpenRouter-specific header for
@@ -44,12 +59,12 @@ The plugin operates at the OpenCode harness level rather than implementing a pro
 
 It:
 
-1. Detects the model/provider family in use.
-2. Applies only the policy appropriate for that family.
+1. Resolves the model/provider policy through the registry resolver.
+2. Applies only the mutations registered for that policy.
 3. Observes system-prompt and tool-definition stability.
 4. Records provider-reported cache token usage.
 5. Adds a deterministic compaction continuation block.
-6. Applies GPT-5.6 cache-control metadata.
+6. Applies GPT-5.6-and-later cache-control metadata.
 7. Applies the GLM-5.3 and MiMo-V2.6 volatile-environment relocation.
 8. Records diagnostics that help determine whether prompt-shape changes correlate with cache behavior.
 9. Records MiMo/GLM affinity outcomes and provider-identity changes.
@@ -115,7 +130,7 @@ DeepSeek:
 
 ### Policy: active cache control
 
-GPT-5.6 is the only current policy that actively injects cache-control request metadata.
+GPT-5.6 and later is the only policy family that actively injects cache-control request metadata.
 
 The plugin adds:
 
@@ -405,7 +420,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` |
-| GPT-5.6 | `gpt-5.6*` on OpenAI-ish endpoints | No | Yes: `prompt_cache_key` + options | None | provider cache tokens |
+| 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` |
 
@@ -923,7 +938,7 @@ The model detector recognizes:
 * GLM-5.3 variants
 * MiMo-V2.6 Flash and Pro (`xiaomi/mimo-v2.6-flash`, `mimo-v2.6-pro`, ...)
 
-GPT-5.6 has an additional OpenAI/Azure-context check so a string containing `gpt-5.6` does not automatically cause GPT-specific fields to be sent to an unrelated endpoint.
+The GPT-5.6-and-later family has an additional OpenAI/Azure-context check, so a string containing a qualifying GPT version (for example `gpt-5.6` or `gpt-6`) does not automatically cause GPT-specific fields to be sent to an unrelated endpoint.
 
 MiMo detection targets exactly Flash and Pro: it excludes `mimo-v2.5`,
 `mimo-v2.5-pro`, and `mimo-v2.6-pro-ultraspeed`.
@@ -953,7 +968,8 @@ For that reason, a stable provider route is preferable when your goal is to meas
 
 # Architecture
 
-The implementation is split into two layers.
+The implementation is split across a hook entry point, a pure logic core, and a
+pure policy registry.
 
 ## `cache-engine.ts`
 
@@ -989,7 +1005,7 @@ This contains dependency-light pure logic.
 
 It owns:
 
-* provider classification
+* the legacy `detectPolicy()` compatibility wrapper (delegating to the registry)
 * configuration parsing
 * hashing
 * canonicalization
@@ -1006,6 +1022,42 @@ Keeping these functions in plain JavaScript allows the logic to be tested indepe
 
 ---
 
+## `cache-policy-core.mjs`
+
+This is the pure policy registry and resolver. It separates cache policy from
+request mutation:
+
+* creator / family classification
+* baseline cache-policy descriptors (documented facts)
+* model-specific overlays (for example GLM/MiMo `<env>` relocation)
+* transport capabilities (for example OpenRouter `x-session-id` affinity)
+* explicit, inventory-traceable inheritance (`inheritsFrom`)
+* safe neutral fallback for unknown or future models
+
+`resolvePolicy(model)` returns `creator`, `family`, `baseline`, `overlays`,
+`transport`, `matchType`, and `matchReason`. `resolveRuntimePolicy(model)`
+returns the runtime-facing descriptor the hooks consume: the legacy policy
+string plus explicit capability flags.
+
+Only registry entries marked `legacy` enable runtime behavior; documented but
+non-legacy entries (for example `mimo-v2.6-pro-ultraspeed`) and all unknown
+models resolve to a neutral runtime. A newer or unknown model therefore never
+inherits a current model's mutation unless the registry explicitly registers it.
+The GPT family is a documented exception in the sense that its boundary is
+version-based (`GPT-5.6 and later`), so GPT-6 and future 5.6+/6+/7+ versions are
+covered by the registered boundary rather than by an exact-model list.
+
+Transport is kept separate from cache policy: OpenRouter affinity is a transport
+capability, not part of a creator's cache semantics. Overlays are also explicit,
+so being classified into a family does not by itself enable a prompt
+transformation.
+
+The module is pure: no network calls and no runtime documentation lookups. The
+legacy `detectPolicy()` in `cache-engine-core.mjs` remains a thin compatibility
+wrapper over the resolver's legacy path.
+
+---
+
 ## Tests
 
 The repository's test suite validates the provider-independent and provider-specific logic.
@@ -1013,6 +1065,7 @@ The repository's test suite validates the provider-independent and provider-spec
 Coverage includes:
 
 * model detection
+* policy registry resolution and runtime-policy equivalence
 * GPT cache-key stability
 * GPT cache-option defaults
 * protection against overwriting existing cache options
@@ -1176,11 +1229,14 @@ opencode-cache-engine/
 ├── src/
 │   ├── cache-engine.ts
 │   ├── cache-engine-core.mjs
+│   ├── cache-policy-core.mjs
 │   └── tui.mjs
 ├── test/
 │   └── cache-engine.test.mjs
 ├── examples/
 │   └── cache-engine.json
+├── docs/
+│   └── cache-policy-inventory.md
 ├── package.json
 ├── README.md
 └── LICENSE
@@ -1219,7 +1275,7 @@ release, use:
 ```json
 {
   "plugin": [
-    "opencode-cache-engine@0.3.6"
+    "opencode-cache-engine@0.4.1"
   ]
 }
 ```
@@ -1286,7 +1342,7 @@ A prefix change is a diagnostic signal, not automatic proof of a cache miss.
 
 ## GPT-5.6 cache options are missing
 
-Verify that the model is actually classified as GPT-5.6 and that the endpoint is recognized as OpenAI/Azure-compatible.
+Verify that the model is within the documented GPT-5.6-and-later boundary (for example `gpt-5.6-*` or `gpt-6-*`) and that the endpoint is recognized as OpenAI/Azure-compatible.
 
 The detector intentionally rejects ambiguous OpenAI-compatible providers rather than guessing.
 

package/docs/cache-policy-inventory.md

@@ -32,22 +32,47 @@ Caching behavior is never inferred from pricing alone, from one SDK's type
 declarations, or from a third-party blog when first-party documentation exists.
 "unknown — first-party docs insufficient" is used instead of a guess.
 
+## Runtime integration
+
+This inventory is the research input for the policy registry in
+`src/cache-policy-core.mjs`. As of **v0.4.1** the runtime hooks consume
+`resolveRuntimePolicy(model)` and gate behavior on the registry's explicit
+capabilities, so the "CacheEngine current treatment" column below describes
+resolver-driven behavior.
+
+Two guarantees follow from that migration:
+
+- `resolveRuntimePolicy(model).policy` equals the legacy `detectPolicy(model)`
+  string, so telemetry and gating are unchanged for every model supported in
+  v0.3.6.
+- Registry entries marked non-`legacy` (for example
+  `mimo-v2.6-pro-ultraspeed`) and all unknown models resolve to a neutral
+  runtime, so no documented-but-unwired model gains a current model's mutation.
+
+The runtime reads the registry at classification time only; there are no network
+calls and no runtime documentation lookups.
+
 ## CacheEngine current treatment (baseline for the matrix)
 
-Source: `src/cache-engine-core.mjs` (detection, transforms) and
-`src/cache-engine.ts` (hooks), revision `19b87f2`.
+Source: the pure registry/resolver (`src/cache-policy-core.mjs`) and the hook
+entry (`src/cache-engine.ts`), as wired in v0.4.1. The behavior described here is
+the same as at the pre-resolver revision `19b87f2`; only the classification
+source changed.
 
 | Family | Detection (verbatim) | Current treatment | Affinity header |
 | --- | --- | --- | --- |
 | DeepSeek | `/deepseek/i` on `${apiID} ${modelID}` or `providerID` | Passive; no mutation | none |
-| GPT-5.6 | `/gpt-5\.6(?![\d.])/i` on slug **and** `isOpenAIish` (provider `openai`/`azure`, slug `openai/`/`azure/`, or npm `@ai-sdk/openai`/`@ai-sdk/azure`) | Inject missing `promptCacheKey` + `promptCacheOptions` (`implicit`, `30m`) | none |
+| GPT-5.6 | version boundary `gpt-<major>[.<minor>] ≥ 5.6` on slug **and** `isOpenAIish` (provider `openai`/`azure`, slug `openai/`/`azure/`, or npm `@ai-sdk/openai`/`@ai-sdk/azure`); since v0.4.2 covers GPT-6 and later | Inject missing `promptCacheKey` + `promptCacheOptions` (`implicit`, `30m`) | none |
 | GLM-5.3 | `/glm-5\.3(?![\d.])/i` on slug | Relocate identifiable `<env>` block to system tail | `x-session-id` only when `providerID === "openrouter"` |
 | MiMo-V2.6 | `/mimo-v2\.6-(flash\|pro)(?![\w-])/i` on slug | Relocate identifiable `<env>` block to system tail; provider-change telemetry | `x-session-id` only when `providerID === "openrouter"` |
 | Neutral | everything else | Byte-untouched | none |
 
 Detection consequences worth stating explicitly:
 
-- `gpt-6*` / `gpt-6-*` is **not** matched → neutral. **[O]**
+- `gpt-6` / `gpt-6-*` (and any future 5.6+/6+/7+ version) is matched by the
+  documented GPT-5.6-and-later boundary → GPT policy. **[O]** (v0.4.2)
+- `gpt-5.5`, `gpt-5.2`, `gpt-4o`, and the malformed `gpt-5.60` are **not**
+  matched → neutral. **[O]**
 - `deepseek-v5` (or any future `*deepseek*` id) matches the passive DeepSeek
   branch because the regex is a bare substring test. **[O]**
 - `mimo-v2.6-pro-ultraspeed` is **not** matched: the `(?![\w-])` lookahead fails
@@ -95,8 +120,10 @@ catch-all "earlier models". [D]
 baseline: it injects only `promptCacheKey` + `promptCacheOptions{mode:implicit,
 ttl:"30m"}`, preserves runtime-supplied values, and never sets context/output
 limits. It does not use explicit breakpoints or `prewarm`, which is a subset of
-the documented capability. GPT-6 is **not** classified and therefore gets no GPT
-cache metadata — a documented-scope gap, not a documented incompatibility.
+the documented capability. Since v0.4.2 the policy resolves by the documented
+"GPT-5.6 and later" boundary, so GPT-6 (astra/sol/luna) receives the same
+baseline; no GPT-6 cache-control exception is documented (OpenAI *Prompt
+caching* guide, re-verified 2026-09-27), and none is coded.
 
 ---
 
@@ -254,7 +281,7 @@ made here); **hold** = do not inherit without first-party evidence.
 | Creator | Model / example pattern | Cache policy (documented) | CacheEngine current treatment | Recommended family inheritance | Recommended exact-model exception | Confidence | Source | Verified |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- |
 | OpenAI | `gpt-5.6`, `gpt-5.6-*` (sol/terra/luna/cyber) | "GPT-5.6 and later": implicit default, optional explicit breakpoints, min 1,024, TTL 30m, write 1.25×/read 0.1× | GPT policy: inject `promptCacheKey` + `promptCacheOptions{implicit,30m}` | keep | none documented; CacheEngine's subset is valid | High (docs) / Medium (treatment) | OpenAI *Prompt caching*; *GPT-5.6 Sol* | 2026-09-26 |
-| OpenAI | GPT-6 / current later GPT family: `gpt-6`, `gpt-6-*` (astra/sol/luna) | Inherits the GPT-5.6-and-later policy | **Not matched** → neutral (no GPT metadata) | **extend**: docs classify GPT-6 as "later", so it inherits the same policy | none documented | High (docs) / High (gap) | OpenAI *Using GPT-6*; *GPT-6 Astra*; *Prompt caching* | 2026-09-26 |
+| OpenAI | GPT-6 / current later GPT family: `gpt-6`, `gpt-6-*` (astra/sol/luna) | Inherits the GPT-5.6-and-later policy | **GPT policy** via the GPT-5.6-and-later boundary (v0.4.2) | **keep** — covered by the boundary predicate; no exact-model entry needed | none documented | High (docs) / High (treatment) | OpenAI *Using GPT-6*; *GPT-6 Astra*; *Prompt caching* | 2026-09-27 |
 | 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 |
@@ -311,3 +338,27 @@ a newer model inherits an older policy. They must not be resolved by guessing.
 - The existing test suite was run only to confirm the repository remains green
   (116/116).
 - This release contains research and documentation only.
+
+### Follow-up: v0.4.1 runtime integration
+
+- v0.4.0 added the registry (`src/cache-policy-core.mjs`) without wiring it.
+- v0.4.1 wired the runtime to `resolveRuntimePolicy()` and preserved behavior:
+  every model supported in v0.3.6 keeps its prior treatment, and non-legacy or
+  unknown models remain neutral.
+- The v0.4.0 research statements above are unchanged; only the runtime now reads
+  this registry as its single source of policy classification.
+
+### Follow-up: v0.4.2 GPT-5.6-and-later boundary
+
+- OpenAI's documented "GPT-5.6 and later" boundary was re-verified against the
+  first-party *Prompt caching* guide and *Using GPT-6* guide on **2026-09-27**.
+  GPT-6 (astra/sol/luna) is documented in the same cache regime with no
+  cache-control exception.
+- v0.4.2 replaces the exact `gpt-5.6` string match with a version-boundary
+  predicate (`gpt-<major>[.<minor>] ≥ 5.6`), still gated on the OpenAI-ish
+  provider check. GPT-6 and future 5.6+/6+/7+ models therefore need no
+  exact-model registry entry, while `gpt-5.5` and earlier and malformed ids such
+  as `gpt-5.60` stay neutral.
+- 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-cache-engine",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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)
@@ -54,6 +56,31 @@ export function isOpenAIish(s) {
   return false
 }
 
+// The documented OpenAI cache-policy boundary is the generation phrase
+// "GPT-5.6 and later" (docs/cache-policy-inventory.md §1; OpenAI *Prompt
+// caching* guide, re-verified 2026-09-27). This matcher expresses that boundary
+// by version rather than by an exact-model string, so future 5.6+/6+/7+ models
+// need no registry entry:
+//   - major > 5                      -> in family
+//   - major === 5 && minor >= 6      -> in family
+//   - everything else                -> out
+// The token must be followed by a non-digit/non-dot boundary, so malformed ids
+// such as "gpt-5.60" and "gpt-5.6.1" do not match (same guard as pre-v0.4.2).
+// OpenAI minor versions are single-digit, so a multi-digit minor is treated as
+// malformed rather than as a higher version.
+export function isGpt56OrLater(slug) {
+  const text = String(slug ?? "").toLowerCase()
+  const re = /gpt-(\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 >= 6) 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" ->
@@ -206,6 +233,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
 //
@@ -219,31 +276,32 @@ function resolveTransport(s) {
 
 export const POLICY_REGISTRY = [
   {
-    id: "openai.gpt-5.6",
+    // v0.4.2: one documented GPT-5.6-and-later family, matched by the version
+    // boundary rather than an exact model string. GPT-6 (astra/sol/luna) is
+    // documented in the same regime with no cache-control exception, so it
+    // inherits this baseline and overlay. Future 5.6+/6+/7+ models resolve here
+    // without a new registry entry.
+    id: "openai.gpt-5.6-plus",
     creator: "openai",
     family: "gpt-5.6",
     kind: "family",
-    pattern: /gpt-5\.6(?![\d.])/i,
+    predicate: isGpt56OrLater,
     requiresOpenAIish: true,
-    exactIds: ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.6-cyber"],
+    exactIds: [
+      "gpt-5.6-sol",
+      "gpt-5.6-terra",
+      "gpt-5.6-luna",
+      "gpt-5.6-cyber",
+      "gpt-6-astra",
+      "gpt-6-sol",
+      "gpt-6-luna",
+    ],
     baseline: "openai.gpt56.cache",
     overlays: ["gpt56.prompt-cache-options"],
     legacy: true,
-    inventoryRef: "§1 OpenAI",
-  },
-  {
-    id: "openai.gpt-6",
-    creator: "openai",
-    family: "gpt-6",
-    kind: "family",
-    pattern: /gpt-6(?![\d.])/i,
-    requiresOpenAIish: true,
-    exactIds: ["gpt-6-astra", "gpt-6-sol", "gpt-6-luna"],
-    baseline: "openai.gpt56.cache",
-    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("gpt56", { gptCacheMetadata: true }),
+    boundary: "GPT-5.6 and later",
+    note: "Documented boundary 'GPT-5.6 and later' (OpenAI Prompt caching guide, re-verified 2026-09-27) includes GPT-6 with no documented cache-control exception. No explicit breakpoint or prewarm behavior is registered.",
     inventoryRef: "§1 OpenAI",
   },
   {
@@ -256,6 +314,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 +333,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 +351,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 +366,7 @@ export const POLICY_REGISTRY = [
     baseline: "deepseek.kv-cache",
     overlays: [],
     legacy: true,
+    runtime: rt("deepseek"),
     inventoryRef: "§2 DeepSeek",
   },
 ]
@@ -301,13 +375,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 +397,7 @@ function neutralResult(reason, transport) {
     family: "neutral",
     baseline: BASELINES["neutral.none"],
     overlays: [],
+    runtime: NEUTRAL_RUNTIME,
     transport,
     matchType: "neutral",
     matchReason: reason,
@@ -333,12 +411,25 @@ function overlaysFor(ids) {
   return (ids ?? []).map((id) => OVERLAYS[id]).filter(Boolean)
 }
 
+// A family entry matches by regex `pattern` or by a pure `predicate(slug)`.
+function familyMatches(entry, slug) {
+  if (typeof entry.predicate === "function") return entry.predicate(slug)
+  return entry.pattern ? entry.pattern.test(slug) : false
+}
+
+// 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 +439,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,20 +481,23 @@ 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).
+  // 2. Exact model ids (documented models). The entry's context gate still
+  // applies, so an exact OpenAI id on a non-OpenAI endpoint is never guessed.
   for (const entry of POLICY_REGISTRY) {
     if (!entry.exactIds || entry.exactIds.length === 0) continue
     const hit = ids.find((id) => entry.exactIds.includes(id))
-    if (hit) return resultFromEntry(entry, "exact", `exact-id:${hit}`, hit, transport)
+    if (!hit) continue
+    if (entry.requiresOpenAIish && !isOpenAIish(s)) continue
+    return resultFromEntry(entry, "exact", `exact-id:${hit}`, hit, transport)
   }
 
-  // 3. Model family / range patterns.
+  // 3. Model family / range matchers (regex pattern or version predicate).
   for (const entry of POLICY_REGISTRY) {
-    if (entry.kind !== "family" || !entry.pattern) continue
-    if (!entry.pattern.test(s.slug)) continue
+    if (entry.kind !== "family") continue
+    if (!familyMatches(entry, s.slug)) continue
     if (entry.requiresOpenAIish && !isOpenAIish(s)) continue
     return resultFromEntry(entry, "family", `family-pattern:${entry.id}`, null, transport)
   }
@@ -415,6 +513,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
@@ -426,7 +531,7 @@ export function resolveLegacyFamily(model) {
   for (const entry of POLICY_REGISTRY) {
     if (!entry.legacy) continue
     if (entry.kind === "family") {
-      if (!entry.pattern.test(s.slug)) continue
+      if (!familyMatches(entry, s.slug)) continue
       if (entry.requiresOpenAIish && !isOpenAIish(s)) continue
       return entry.family
     }

package/test/cache-engine.test.mjs

@@ -53,8 +53,10 @@ import {
   MODEL_ALIASES,
   OVERLAYS,
   POLICY_REGISTRY,
+  isGpt56OrLater,
   resolveLegacyFamily,
   resolvePolicy,
+  resolveRuntimePolicy,
 } from "../src/cache-policy-core.mjs"
 
 const asst = (id, read, write) => ({
@@ -1358,26 +1360,27 @@ test("resolvePolicy: GPT-5.6 exact + inventory aliases resolve to the gpt-5.6 fa
   assert.equal(orVariant.matchType, "exact")
 })
 
-test("resolvePolicy: GPT-6 resolves via explicit documented inheritance, with no overlay", () => {
+test("v0.4.2: GPT-6 resolves through the documented GPT-5.6-and-later boundary", () => {
   const r = resolvePolicy(M("openrouter", "openai/gpt-6-luna"))
   assert.equal(r.creator, "openai")
-  assert.equal(r.family, "gpt-6")
+  assert.equal(r.family, "gpt-5.6")
   assert.equal(baseId(r), "openai.gpt56.cache")
-  assert.deepEqual(overlayIds(r), [])
-  assert.equal(resolvePolicy(M("openai", "gpt-6-astra")).family, "gpt-6")
+  // GPT-6 is documented in the same cache regime, so it gets the same overlay.
+  assert.deepEqual(overlayIds(r), ["gpt56.prompt-cache-options"])
+  assert.equal(resolvePolicy(M("openai", "gpt-6-astra")).family, "gpt-5.6")
 
-  // Inheritance is explicit, not "newer means same": the registry records it.
-  const gpt6 = POLICY_REGISTRY.find((e) => e.family === "gpt-6")
-  assert.equal(gpt6.inheritsFrom, "gpt-5.6")
-  assert.ok(gpt6.inventoryRef)
-  // And no overlay is implied by that inheritance.
-  assert.deepEqual(gpt6.overlays, [])
+  // The boundary is version-based, not an exact-model list.
+  const entry = POLICY_REGISTRY.find((e) => e.id === "openai.gpt-5.6-plus")
+  assert.equal(entry.boundary, "GPT-5.6 and later")
+  assert.equal(typeof entry.predicate, "function")
+  assert.ok(entry.inventoryRef)
 })
 
-test("resolvePolicy: GPT-6 is not classified by the legacy detectPolicy wrapper", () => {
-  // Intentional: the new layer knows gpt-6, the compatibility wrapper does not.
-  assert.equal(detectPolicy(M("openai", "gpt-6-astra")), POLICY_NEUTRAL)
-  assert.equal(resolvePolicy(M("openai", "gpt-6-astra")).family, "gpt-6")
+test("v0.4.2: the legacy detectPolicy wrapper follows the same boundary", () => {
+  assert.equal(detectPolicy(M("openai", "gpt-6-astra")), POLICY_GPT56)
+  assert.equal(detectPolicy(M("openai", "gpt-5.6")), POLICY_GPT56)
+  assert.equal(detectPolicy(M("openai", "gpt-5.5")), POLICY_NEUTRAL)
+  assert.equal(detectPolicy(M("openai", "gpt-5.60")), POLICY_NEUTRAL)
 })
 
 test("resolvePolicy: pre-5.6 GPT negative controls are neutral with no overlays", () => {
@@ -1551,3 +1554,268 @@ 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: "gpt56", env: false, gpt: true, header: false } },
+      { name: "gpt-6-openrouter", model: { providerID: "openrouter", id: "openai/gpt-6-luna", api: { id: "openai/gpt-6-luna" } }, expect: { policy: "gpt56", env: false, gpt: true, header: false } },
+      { name: "gpt-6-openai-compatible", model: { providerID: "openai-compatible", id: "gpt-6-astra", api: { id: "gpt-6-astra" } }, expect: { policy: "neutral", env: false, gpt: false, header: false } },
+      { name: "gpt-5.60-malformed", model: { providerID: "openai", id: "gpt-5.60", api: { id: "gpt-5.60", 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-daybreak-alias",
+    "gpt-5.5",
+    "gpt-6-openai-compatible",
+    "gpt-5.60-malformed",
+    "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`)
+  }
+})
+
+// ===========================================================================
+// v0.4.2 GPT-5.6-and-later boundary
+//
+// Source: OpenAI *Prompt caching* guide, "GPT-5.6 and later" generation
+// boundary, re-verified 2026-09-27 (docs/cache-policy-inventory.md §1). GPT-6
+// is documented in the same regime with no cache-control exception.
+// ===========================================================================
+
+test("v0.4.2: isGpt56OrLater matches the documented boundary by version", () => {
+  const inFamily = [
+    "gpt-5.6",
+    "gpt-5.6-luna",
+    "openai/gpt-5.6-sol",
+    "gpt-6",
+    "gpt-6-astra",
+    "gpt-6-sol",
+    "gpt-6-luna",
+    "gpt-5.7",
+    "gpt-7",
+    "gpt-6.1",
+  ]
+  for (const id of inFamily) assert.equal(isGpt56OrLater(id), true, `${id} is in family`)
+  const outOfFamily = [
+    "gpt-5.5",
+    "gpt-5.4",
+    "gpt-5.2",
+    "gpt-5.1",
+    "gpt-5",
+    "gpt-4.1",
+    "gpt-4o",
+    "gpt-5.60",
+    "gpt-5.6.1",
+    "gpt-4",
+    "claude-sonnet-4-5",
+  ]
+  for (const id of outOfFamily) assert.equal(isGpt56OrLater(id), false, `${id} is out of family`)
+})
+
+test("v0.4.2: GPT boundary respects OpenAI/provider gating", () => {
+  assert.equal(resolveRuntimePolicy(M("openai", "gpt-5.6")).gptCacheMetadata, true)
+  assert.equal(resolveRuntimePolicy(M("openai", "gpt-6-astra")).gptCacheMetadata, true)
+  assert.equal(resolveRuntimePolicy(M("azure", "gpt-6-sol")).gptCacheMetadata, true)
+  assert.equal(resolveRuntimePolicy(M("openrouter", "openai/gpt-6-luna")).gptCacheMetadata, true)
+  assert.equal(resolveRuntimePolicy(M("openai-compatible", "gpt-6-astra")).gptCacheMetadata, false)
+  assert.equal(resolveRuntimePolicy(M("llama.cpp", "gpt-5.6")).gptCacheMetadata, false)
+  assert.equal(resolveRuntimePolicy(M("openai", "gpt-5.5")).gptCacheMetadata, false)
+  assert.equal(resolveRuntimePolicy(M("openai", "gpt-5.60")).gptCacheMetadata, false)
+})
+
+test("v0.4.2: covered later GPT requests receive the same documented baseline at runtime", async () => {
+  const { results } = await policyMigrationResults()
+  const gpt6 = results.find((r) => r.name === "gpt-6-astra")
+  assert.equal(gpt6.runtimePolicy, "gpt56")
+  assert.equal(gpt6.gptOptionInjected, true)
+  assert.deepEqual(gpt6.gptOptions, { mode: "implicit", ttl: "30m" })
+  // Same baseline as GPT-5.6, no new mechanism.
+  const gpt56 = results.find((r) => r.name === "gpt-5.6")
+  assert.deepEqual(gpt6.gptOptions, gpt56.gptOptions)
+  // No prompt transformation or affinity was introduced for gpt-6.
+  assert.equal(gpt6.systemRelocated, false)
+  assert.equal(gpt6.affinityHeaderAttached, false)
+})
+
+test("v0.4.2: pre-5.6 and out-of-family GPT ids get no GPT options", async () => {
+  const { results } = await policyMigrationResults()
+  for (const name of ["gpt-5.5", "gpt-5.60-malformed", "gpt-6-openai-compatible"]) {
+    const r = results.find((x) => x.name === name)
+    assert.equal(r.gptOptionInjected, false, `${name}: no GPT options`)
+    assert.equal(r.runtimePolicy, "neutral", `${name}: neutral runtime`)
+  }
+})