DS4 Context Engine 0.3.7

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).
• 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.