opencode-cache-engine 0.4.1 → 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.1",
+  "version": "0.4.2",
   "private": false,
   "description": "Provider-aware prompt-cache optimization and telemetry for OpenCode",
   "keywords": [

package/src/cache-policy-core.mjs

@@ -56,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" ->
@@ -251,33 +276,32 @@ const rt = (policy, overrides = {}) => ({
 
 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,
     runtime: rt("gpt56", { gptCacheMetadata: 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,
-    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.",
+    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",
   },
   {
@@ -387,6 +411,12 @@ 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) {
@@ -454,17 +484,20 @@ export function resolvePolicy(model) {
     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)
   }
@@ -498,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,6 +53,7 @@ import {
   MODEL_ALIASES,
   OVERLAYS,
   POLICY_REGISTRY,
+  isGpt56OrLater,
   resolveLegacyFamily,
   resolvePolicy,
   resolveRuntimePolicy,
@@ -1359,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", () => {
@@ -1632,7 +1634,10 @@ async function runPolicyMigrationProbe() {
     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-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 } },
@@ -1717,9 +1722,10 @@ test("v0.4.1: GPT-5.6 keeps promptCacheOptions implicit/30m through the resolver
 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",
+    "gpt-6-openai-compatible",
+    "gpt-5.60-malformed",
     "glm-5.2",
     "mimo-v2.6-pro-ultraspeed",
     "mimo-v2.5",
@@ -1741,3 +1747,75 @@ test("v0.4.1: non-OpenRouter models never receive the OpenRouter header", async
     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`)
+  }
+})