# Release 0.3.7 — Cache-aware context planning (opt-in)

**Version analyzed:** DS4 Context Engine `0.3.7`
**Commit:** `a03009a4b14d6ab1842fa800076c4b300bd70d8f`
**Coordinated packages:** `ds4-context-core` 0.3.7, `ds4-context-reference-adapter` 0.3.7, `ds4-context-engine` 0.3.7

## Summary

Adds an opt-in cache-aware planning policy driven by model pricing and
observed cache shares, plus a deterministic synthetic prefix-cache simulator.
The default behavior is unchanged: `context.cacheAware.mode` defaults to `off`,
the manifest does not include a `cacheAware` block, and the planner uses the
same tail caps as 0.3.6.

## New configuration

`context.cacheAware` (object, default off):

| Field | Default | Meaning |
|---|---|---|
| `mode` | `off` | `off` preserves 0.3.6 behavior; `auto` may extend the recent tail. |
| `minimumCacheSampleCount` | `3` | Observed samples required before acting. |
| `minimumCacheReadShare` | `0.5` | Observed cache-read share required before acting. |
| `minimumMissHitRatio` | `20` | Minimum cache-miss / cache-hit price ratio. |
| `minimumImprovementRatio` | `0.1` | Relative improvement required to switch plan. |
| `maxTailBudgetShare` | `0.5` | Max fraction of the active input budget for the extended tail. |
| `expectedRequestsPerTurn` | `4` | Provider requests per user turn in the cost model. |
| `expectedTurnsPerEpoch` | `4` | User turns per planning epoch in the cost model. |
| `stickinessEpochs` | `2` | Consecutive epoch losses before dropping an adopted extended tail. |

## Changes

- `ModelDescriptor` gains an optional `cost` profile (`input`, `output`,
  `cacheRead`, `cacheWrite` per million), populated from Pi model metadata in
  `snapshotModel`. No prices are hardcoded in the core.
- `planManagedContext` accepts an optional `cacheAwareTailTokens` override that
  bypasses the automatic context-window ceiling while remaining bounded by the
  active/hard input budgets and atomic groups.
- Runtime: when `mode: "auto"` and the eligibility gates pass, the runtime
  compares the nominal plan with an extended-tail plan using a deterministic
  epoch cost model (stable plans pay one cold transition per epoch; sliding
  plans pay a cold request per turn) and adopts the extended plan only when it
  wins after the minimum improvement margin.
- Manifest: optional `planning.cacheAware` (numbers only, never content) with
  eligibility, tail tokens, miss/hit ratio, observed share, sample count,
  estimated reusable prefix tokens, estimated request cost and winning
  candidate; surfaced in `/context tokens` and `/context explain`.
- Core: `packages/core/src/planner/cache-policy.ts` with pure, deterministic
  functions for common-prefix estimation, request cost and the tail decision.
- Tests: `cache-policy` unit tests, config validation, planner override tests,
  the synthetic prefix-cache simulator (`cache-prefix-simulator`) and runtime
  integration tests for off/auto/no-discount/under-budget paths.

## Compatibility

- Additive configuration; absent fields use the documented defaults.
- `context.cacheAware.mode: "off"` reproduces the 0.3.6 behavior exactly.
- No new required database schema; manifests persist the optional block as-is.
- The existing guarantees (current request, atomicity, privacy, pins, hard
  limits, fail-open, naive compaction path) are unchanged.
- Model metadata without cache pricing or observed samples degrades the
  decision to the nominal plan.

## Validation

- `npm run check` (excluding the known machine-load-dependent
  `long-session` timeout flake): 83 files, 550 tests passed.
- Planner unit tests: 25 passed.
- Cache-policy unit tests: 16 passed.
- Prefix-cache simulator: 7 passed.
- Cache-aware runtime integration: 4 passed.
- Config catalog/loader validation: passed.
- `pack:check` from a clean HEAD snapshot: core 239 files,
  reference-adapter 7 files, engine 91 files; consumer install clean.
- Published and registry-verified: `ds4-context-core` 0.3.7,
  `ds4-context-reference-adapter` 0.3.7, `ds4-context-engine` 0.3.7
  (`registry:check` PASS at exact version; one transient registry replica
  miss on first attempt, confirmed present via `npm view`).
- Release fix `7404a9a`: root `package.json` must depend exactly on
  `ds4-context-core@0.3.7` (caught by the `pack:check` gate on the
  coordinated-version requirement).

## Known limits

- The epoch cost model is an estimate for plan comparison; actual billing is
  whatever the provider reports.
- A real-provider DeepSeek A/B benchmark remains voluntary and out of CI
  (protocol: [CACHE_AWARE_BENCHMARK.md](../CACHE_AWARE_BENCHMARK.md)).
- The workaround override (large `recentTailTokens`, zeroed retrieval and
disabled compaction) remains available and is unaffected; it is more aggressive
than `mode: "auto"`, which deliberately preserves retrieval/project and
compaction for quality.