ds4-context-engine 0.2.0-beta.1 → 0.2.0-beta.2

package/README.md

@@ -16,7 +16,7 @@ bounded active context with provenance
 Pi provider
 ```
 
-> **Project status:** M0–M19 are implemented. Prerelease `0.2.0-beta.1` adds quality measurement, structural/hybrid retrieval, cross-session project memory, learned-ranking shadow evaluation, and the runtime adapter kit. Stable `0.1.2` remains available; both lines target Pi `0.84.3`. M20 local KV reuse is not included in this prerelease.
+> **Project status:** M0–M20 are implemented on `main`. Prerelease `0.2.0-beta.2` includes M14–M20: quality measurement, structural/hybrid retrieval, cross-session project memory, learned-ranking shadow evaluation, the runtime adapter kit, and opt-in local KV reuse. Stable `0.1.2` remains available; all lines target Pi `0.84.3`.
 
 ## Why DS4
 
@@ -39,6 +39,7 @@ It provides:
 - opt-in metadata-only context-quality metrics and deterministic replay comparisons;
 - checksummed metadata-only learned ranking with shadow mode, canonical classified feedback and static fallback;
 - a versioned runtime adapter contract, reusable conformance kit and non-Pi callback/JSONL reference adapter;
+- opt-in exact-prefix local KV reuse for capable local runtime adapters, with volatile handles and full-replay fallback;
 - an inspectable Context Manifest explaining included and excluded material;
 - fail-open recovery to Pi's native context path for operational failures.
 
@@ -359,7 +360,9 @@ Native continuation is also disabled by default. Enabling it requires both expli
 
 Eligible OpenAI Responses requests then set `store: true`. Review the provider's retention policy before enabling this option. DS4 keeps response handles only in volatile memory, verifies exact managed prefixes before reuse and retries once with a full managed replay when recognized continuation state is stale.
 
-See [`docs/PRIVACY.md`](docs/PRIVACY.md) and [`docs/NATIVE_CONTINUATION.md`](docs/NATIVE_CONTINUATION.md).
+Local KV reuse is separately disabled by default through `localKvReuse.enabled`. It also requires a local runtime adapter with a versioned `local-kv-reuse` capability and a volatile runtime port. Pi exposes no such handles and remains unsupported even if configuration is enabled.
+
+See [`docs/PRIVACY.md`](docs/PRIVACY.md), [`docs/NATIVE_CONTINUATION.md`](docs/NATIVE_CONTINUATION.md), and [`docs/LOCAL_KV_REUSE.md`](docs/LOCAL_KV_REUSE.md).
 
 ## Storage and recovery
 
@@ -399,7 +402,7 @@ npm pack --dry-run --workspace ds4-context-core
 npm pack --dry-run --workspace ds4-context-reference-adapter
 ```
 
-The test suite covers configuration, migrations, canonical JSONL projection, planning, atomic tool groups, retrieval, compaction, project knowledge, artifacts, memory, privacy, model awareness, continuation, runtime-adapter conformance, the portable-core dependency boundary and Pi extension lifecycle behavior. The package check builds all three tarballs, installs them in a clean temporary consumer, reruns compiled reference-adapter conformance and starts the packaged Pi extension with isolated RPC state.
+The test suite covers configuration, migrations, canonical JSONL projection, planning, atomic tool groups, retrieval, compaction, project knowledge, artifacts, memory, privacy, model awareness, continuation, local-KV eligibility/replay, runtime-adapter conformance, the portable-core dependency boundary and Pi extension lifecycle behavior. The package check builds all three tarballs, installs them in a clean temporary consumer, reruns compiled reference-adapter conformance and starts the packaged Pi extension with isolated RPC state.
 
 ### Portable core
 
@@ -436,6 +439,7 @@ scripts             package and release-readiness checks
 - [Native continuation](docs/NATIVE_CONTINUATION.md)
 - [Portable core](docs/PORTABLE_CORE.md)
 - [Runtime adapter kit](docs/RUNTIME_ADAPTER_KIT.md)
+- [Local KV reuse](docs/LOCAL_KV_REUSE.md)
 - [Storage](docs/STORAGE.md)
 - [Roadmap 0.2.0](docs/ROADMAP_0.2.0.md)
 - [Release process](docs/RELEASING.md)
@@ -444,9 +448,9 @@ scripts             package and release-readiness checks
 
 ## Roadmap
 
-The original M0–M13 roadmap is complete. `ds4-context-core` contains the compiled runtime-neutral implementation. M14 context-quality metrics, M15 rich symbol indexing, M16 hybrid semantic retrieval, M17 cross-session project memory, M18 learned-ranking shadow evaluation and M19's runtime adapter/conformance kit plus non-Pi reference adapter are implemented on `main`. Learned active ranking remains promotion-gated and static ranking stays authoritative on every failure.
+The original M0–M13 roadmap is complete. `ds4-context-core` contains the compiled runtime-neutral implementation. M14 context-quality metrics, M15 rich symbol indexing, M16 hybrid semantic retrieval, M17 cross-session project memory, M18 learned-ranking shadow evaluation, M19's runtime adapter/conformance kit, and M20 opt-in local KV eligibility/replay are implemented on `main`. Learned active ranking remains promotion-gated, Pi reports local KV as unsupported, and static ranking/native completion stay authoritative on every failure.
 
-The remaining [0.2.0 roadmap](docs/ROADMAP_0.2.0.md) covers optional local KV reuse. Sensitive or transport-specific behavior remains opt-in, and the 0.1 lexical planner stays available as the deterministic fallback.
+The [0.2.0 roadmap](docs/ROADMAP_0.2.0.md) now proceeds to release-candidate hardening. Sensitive or transport-specific behavior remains opt-in, and the 0.1 lexical planner stays available as the deterministic fallback.
 
 ## Contributing
 

package/docs/ARCHITECTURE.md

@@ -66,6 +66,15 @@ optional OpenAI Responses provider wrapper
   -> retry a rejected stale handle once through the complete managed replay before exposing stream events
   -> record metadata-only mode/item counts/retry/invalidation diagnostics; never record the provider handle
 
+optional local runtime KV port (non-Pi adapters)
+  -> require opt-in configuration plus a negotiated versioned local-KV capability
+  -> apply current privacy policy before runtime-specific prefix/options extraction
+  -> hash exact prefix bytes, provider/model/revision, options, privacy policy, runtime revision and capability version
+  -> let the runtime port map only the fingerprint to its volatile native handle
+  -> replay the complete sanitized payload after miss, stale rejection, unavailable state or runtime restart
+  -> report aggregate hits/misses/saved-prefill/replay latency separately from context occupancy
+  -> never place handles, prefixes or payloads in canonical history, manifests, SQLite or diagnostics
+
 assistant message_end
   -> attach uncached input plus cache read/write usage to the pending manifest
   -> append one exact provider/model calibration sample
@@ -162,7 +171,7 @@ ds4-context-engine                        ds4-context-reference-adapter
 
 `ds4-context-core` is compiled ESM and has no dependency on Pi. Its workspace contains:
 
-- `packages/core/src/adapter`: versioned runtime contract, canonical tool-group validation, isolated capability negotiation and framework-neutral conformance runner;
+- `packages/core/src/adapter`: versioned runtime contract, canonical tool-group validation, isolated capability negotiation, exact local-KV eligibility/replay orchestration and framework-neutral conformance runner;
 - `packages/core/src/core`: portable canonical messages, model profiles, robust calibration, adaptive category limits, budgets and token-estimation policy;
 - `packages/core/src/continuation`: hashed-prefix continuation decisions without provider transport or response APIs;
 - `packages/core/src/config`: runtime-neutral configuration model and filesystem loader;
@@ -178,7 +187,7 @@ ds4-context-engine                        ds4-context-reference-adapter
 - `packages/core/src/persistence`: rebuildable session/project/vector/memory/pin/quality SQLite state, repositories, FTS5, event replay and transactional migrations;
 - `packages/core/src/manifest` and `packages/core/src/shared`: runtime-neutral projections, provenance, hashing, stable serialization and logging.
 
-The `packages/reference-adapter` workspace is the non-Pi reference adapter: it reads bounded append-only canonical JSONL, injects completion through a host callback, enforces privacy at that callback boundary, rebuilds disposable snapshots and explicitly disables unsupported native features.
+The `packages/reference-adapter` workspace is the non-Pi reference adapter: it reads bounded append-only canonical JSONL, injects completion through a host callback, enforces privacy at that callback boundary, rebuilds disposable snapshots and explicitly disables unsupported native features. A local host can inject a handle-free `LocalKvRuntimePort`; the port alone retains native handles and transport while core receives only exact prefix bytes transiently for hashing.
 
 The root `ds4-context-engine` package is the Pi adapter:
 

package/docs/CONTEXT_MANIFEST.md

@@ -27,7 +27,7 @@ A Context Manifest explains the context visible at DS4's Pi `context` hook witho
 - finalized uncached input, cache-read, cache-write, total provider input, and cache shares when available;
 - optional native-continuation eligibility, storage-consent state, request mode, full/sent/omitted input-item counts, state age, generic fallback/invalidation reason, and managed-replay retry outcome.
 
-The manifest does **not** contain system instructions, message text, classified spans, pin content, memory claims, project snippets, artifact content/excerpts, learned-ranking feature vectors/labels/candidate IDs/model weights, tool arguments/results, image data, provider payloads, provider response/conversation IDs, API keys, or headers.
+The manifest does **not** contain system instructions, message text, classified spans, pin content, memory claims, project snippets, artifact content/excerpts, learned-ranking feature vectors/labels/candidate IDs/model weights, local-KV prefixes/fingerprints/handles, tool arguments/results, image data, provider payloads, provider response/conversation IDs, API keys, or headers. Local-KV hit/miss/prefill counters are volatile adapter diagnostics and are not copied into Pi manifests.
 
 ## Provenance mapping
 

package/docs/LOCAL_KV_REUSE.md

@@ -0,0 +1,131 @@
+# Local KV Reuse
+
+M20 adds an opt-in, runtime-neutral prefix/KV capability for local inference runtimes. KV state is only an inference optimization: it is not canonical history, memory, retrieval evidence, a Context Manifest source, or a SQLite projection.
+
+Pi does not expose native KV handles and continues to report `local-kv-reuse` as unsupported. The callback/JSONL reference adapter can exercise the capability when its host injects a `LocalKvRuntimePort`; no provider SDK is added to core or the reference package.
+
+## Boundary
+
+```text
+runtime/provider payload
+        ↓
+adapter privacy enforcement
+        ↓
+runtime-specific prefix/options extraction from sanitized payload
+        ↓
+core exact-byte eligibility hashes
+        ↓
+volatile LocalKvRuntimePort lookup + transport
+        ├─ exact hit ───────────────> cached completion
+        └─ miss/rejected/unavailable -> full prompt replay
+```
+
+Core receives the provider-ready prefix only long enough to hash it. It returns metadata-only component hashes and an aggregate fingerprint. A runtime port maps that fingerprint to its own volatile handle. Handles never cross the port, and core has no API for serializing them.
+
+## Configuration and negotiation
+
+Configuration is disabled by default:
+
+```json
+{
+  "localKvReuse": {
+    "enabled": false
+  }
+}
+```
+
+Enabling configuration is not sufficient. The active adapter must independently declare a versioned `local-kv-reuse` capability and provide a `LocalKvRuntimePort`. Unsupported or malformed declarations disable KV reuse without affecting history, privacy, completion fallback, or any other capability.
+
+A reference-adapter host opts in explicitly:
+
+```ts
+const adapter = new JsonlReferenceRuntimeAdapter({
+  // canonical history, model, privacy, and ordinary transport options...
+  localKv: {
+    enabled: true,
+    port: myVolatileKvPort,
+    runtimeRevision: "llama-runtime-build-42",
+    modelRevision: "model-checksum-abc",
+    prepare(sanitizedPayload) {
+      return {
+        promptPrefix: exactProviderPrefixBytes(sanitizedPayload),
+        systemOptions: providerSystemOptions(sanitizedPayload),
+        toolOptions: providerToolOptions(sanitizedPayload),
+        prefixTokenCount: 32_000,
+        contextTokenCount: 40_000,
+      };
+    },
+  },
+});
+```
+
+`prepare()` receives only the payload returned by adapter privacy enforcement. Remote destinations never enter the local KV path.
+
+## Exact eligibility
+
+`deriveLocalKvEligibility()` uses `local-kv-eligibility-v1`. An eligible fingerprint includes independent SHA-256 components for:
+
+- exact provider, model, and model revision;
+- exact UTF-8/string or byte prefix;
+- deterministic JSON-compatible system and tool options;
+- privacy policy version and local destination;
+- runtime identity, runtime revision, and capability implementation version.
+
+Identifiers are not case-folded or wildcard-matched. Prefix bytes are not normalized. Option object keys are ordered only for deterministic serialization; values, array order, missing/undefined values, and system/tool separation remain significant. Functions, symbols, binary option values, accessors, custom prototypes, circular values, and non-finite numbers are ineligible instead of being hashed ambiguously.
+
+Any changed prefix byte, provider/model identity, model revision, system/tool option, privacy version, runtime revision, or capability version produces a different fingerprint. Disabled configuration, unsupported capability, remote destination, invalid identifiers, an empty prefix, or invalid token counts bypass reuse.
+
+## Runtime port and replay
+
+`LocalKvRuntimePort` deliberately exposes no handle:
+
+```ts
+interface LocalKvRuntimePort {
+  tryReuse(request): Promise<
+    | { status: "hit"; output: unknown; savedPrefillTokens: number; prefillLatencyMs: number }
+    | { status: "miss" | "rejected" | "unavailable" }
+  >;
+  fullReplay(request): Promise<{
+    output: unknown;
+    prefillTokens: number;
+    prefillLatencyMs: number;
+  }>;
+  shutdown?(): Promise<void>;
+}
+```
+
+The runtime owns fingerprint-to-handle lookup, eviction, provider transport, and restart cleanup. `LocalKvReuseController` treats thrown lookup errors and malformed lookup results as unavailable state. Every miss, stale rejection, unavailable state, or runtime restart invokes `fullReplay()` with the complete sanitized payload. If the injected KV full replay itself fails, the reference adapter retries the complete sanitized payload through its ordinary native transport.
+
+Adapter shutdown calls optional port shutdown once. Cache deletion, eviction, process loss, or runtime restart therefore changes performance only; it cannot change canonical state or prevent a full replay.
+
+## Aggregate diagnostics
+
+`local-kv-diagnostics-v1` contains numbers only:
+
+- requests, eligible requests, and bypasses;
+- hits, misses, rejected states, unavailable states, full replays, and transport failures;
+- reusable prefix tokens and total context-occupancy tokens;
+- saved prefill tokens;
+- full-replay prefill tokens and runtime-reported prefill latency.
+
+Diagnostics never include provider/model text, prefix or payload content, component fingerprints, runtime handles, credentials, provider response IDs, or output. Per-request completion metadata keeps `contextTokens`, `savedPrefillTokens`, `replayPrefillTokens`, and `prefillLatencyMs` as separate fields; context occupancy is never reported as cache savings.
+
+## Privacy and persistence
+
+Privacy enforcement precedes runtime-specific prefix extraction and hash verification. A remote payload is sanitized and sent through ordinary transport without consulting local KV state. An enabled local policy is still applied before extraction. A prior cached state cannot authorize material excluded by the current privacy policy because the policy version and sanitized exact prefix are both part of eligibility.
+
+No KV handle or prefix copy is written to:
+
+- Pi JSONL or reference canonical JSONL;
+- Context Manifests;
+- DS4 SQLite;
+- learned-ranking artifacts;
+- adapter/core diagnostics.
+
+There is no M20 database migration. Deleting all volatile runtime KV state requires no DS4 rebuild and no canonical-history migration.
+
+## Verification and benchmark
+
+Unit and reference-adapter integration tests cover exact hits, changed bytes/options, provider/model/privacy/runtime invalidation, cache loss, stale rejection, unavailable state, full replay, privacy-before-verification, aggregate-only diagnostics, idempotent shutdown, and unchanged canonical JSONL.
+
+`tests/benchmarks/local-kv.bench.ts` hashes a synthetic 32,000-token reusable prefix inside a 40,000-token context and separately benchmarks a warm completion whose simulated runtime metadata reports 32,000 saved prefill tokens and `0.5 ms` prefill latency. On the development host, exact eligibility averaged about `0.259 ms` and the warm controller path about `0.248 ms`. These are observational, not portable provider-latency guarantees; the benchmark intentionally reports runtime prefill latency/token savings separately from context occupancy.

package/docs/PORTABLE_CORE.md

@@ -1,6 +1,6 @@
 # Portable Core
 
-M13 extracts the runtime-neutral implementation into the independently buildable `ds4-context-core` workspace package. The root `ds4-context-engine` package remains the Pi integration. M19 adds the versioned adapter contract/conformance kit in core and a separately compiled non-Pi callback/JSONL reference adapter.
+M13 extracts the runtime-neutral implementation into the independently buildable `ds4-context-core` workspace package. The root `ds4-context-engine` package remains the Pi integration. M19 adds the versioned adapter contract/conformance kit in core and a separately compiled non-Pi callback/JSONL reference adapter. M20 adds exact local-KV eligibility and replay orchestration while leaving every provider SDK and native cache handle in the runtime adapter.
 
 ## Dependency rule
 
@@ -30,6 +30,7 @@ The core may use Node.js standard-library facilities such as `node:sqlite`, file
 - memory/pin materialization;
 - privacy classification and provider policy;
 - native-continuation eligibility and hash state;
+- exact local-KV eligibility, handle-free runtime port types, replay policy and aggregate diagnostics;
 - rebuildable SQLite repositories;
 - stable serialization, hashing and logging.
 
@@ -54,10 +55,11 @@ Every `runtime-adapter-v1` implementation must:
 6. append memory/pin mutations to canonical runtime history before materializing derived state;
 7. invoke model completion at the adapter boundary for generated summaries;
 8. enforce privacy immediately before provider transport;
-9. discard or rebuild SQLite and artifact projections safely;
-10. fall back to native runtime behavior when operational integration fails.
+9. retain optional local-KV handles inside its volatile runtime port and replay the full sanitized payload after every non-hit;
+10. discard or rebuild SQLite and artifact projections safely;
+11. fall back to native runtime behavior when operational integration fails.
 
-The executable contract, independent capability negotiation and framework-neutral seven-case conformance runner are exported from `ds4-context-core/adapter/runtime-adapter` and `ds4-context-core/adapter/conformance`. See [Runtime Adapter Kit](RUNTIME_ADAPTER_KIT.md).
+The executable contract, independent capability negotiation and framework-neutral seven-case conformance runner are exported from `ds4-context-core/adapter/runtime-adapter` and `ds4-context-core/adapter/conformance`. M20's handle-free port and controller are exported from `ds4-context-core/adapter/local-kv`. See [Runtime Adapter Kit](RUNTIME_ADAPTER_KIT.md) and [Local KV Reuse](LOCAL_KV_REUSE.md).
 
 ## Build and exports
 
@@ -91,6 +93,7 @@ Extraction does not change DS4 state semantics:
 - Pi JSONL remains canonical for Pi sessions;
 - SQLite remains disposable and rebuildable;
 - compaction remains non-destructive and strictly validated;
-- provider continuation handles remain volatile;
+- provider continuation and local-KV handles remain volatile and adapter-owned;
+- local-KV cache loss changes only prefill performance and transparently replays the full sanitized payload;
 - planner, retrieval, compaction and persistence failures still fail open at the adapter boundary;
 - enabled privacy enforcement still fails closed before remote transport.

package/docs/ROADMAP_0.2.0.md

@@ -163,7 +163,7 @@ If the gate is not met, 0.2.0 ships shadow mode but keeps static ranking active.
 
 ## M19 — Runtime Adapter Kit
 
-Status: **implemented on `main` for `0.2.0-beta.2`**. Core ships `runtime-adapter-v1` plus a framework-neutral conformance runner; Pi exposes contract capability diagnostics, and the separately packaged callback/JSONL reference adapter passes all seven conformance cases.
+Status: **implemented on `main` and released in `0.2.0-beta.1`**. Core ships `runtime-adapter-v1` plus a framework-neutral conformance runner; Pi exposes contract capability diagnostics, and the separately packaged callback/JSONL reference adapter passes all seven conformance cases.
 
 ### Deliverables
 
@@ -182,6 +182,8 @@ Status: **implemented on `main` for `0.2.0-beta.2`**. Core ships `runtime-adapte
 
 ## M20 — Local KV Capability
 
+Status: **implemented on `main` and released in `0.2.0-beta.2` behind `localKvReuse.enabled`**. Core derives exact metadata-only eligibility fingerprints and guarantees full replay on every non-hit; injected runtime ports retain all volatile handles and transport. Pi remains explicitly unsupported.
+
 ### Deliverables
 
 - An optional adapter capability for local inference runtimes that expose reusable prefix/KV state.
@@ -231,10 +233,10 @@ SQLite schema changes use forward migrations plus complete rebuild tests from ca
 
 - M18 learned ranker in shadow mode.
 - Privacy, rebuild, corruption and performance hardening for M14–M18.
+- M19 adapter contract, conformance kit and reference adapter.
 
 ### `0.2.0-beta.2`
 
-- M19 adapter contract, conformance kit and reference adapter.
 - M20 local KV capability for runtimes that support it.
 
 ### `0.2.0-rc.1`

package/docs/RUNTIME_ADAPTER_KIT.md

@@ -41,6 +41,8 @@ Applying a DS4 context plan must not write provider-facing synthetic messages ba
 
 Completion output remains runtime-owned and is not automatically canonical. An adapter must append a final runtime-native message through its ordinary canonical history API if the host chooses to persist it.
 
+M20-capable adapters may additionally expose `localKvPort` and aggregate `localKvDiagnostics()`. Both are optional because most runtimes, including Pi, expose no native KV state. The port interface carries eligibility hashes and complete sanitized replay payloads but never returns or accepts a cache handle.
+
 ## Tool atomicity
 
 `buildCanonicalToolAtomicGroups()` connects every canonical `toolCall` block to all matching `toolResult` blocks. Calls sharing one assistant message form one component, so parallel tool batches cannot be split. `validateRuntimeHistorySnapshot()` rejects missing, overlapping, unknown, or mismatched groups. An incomplete live call is represented by a group with `complete: false`; it cannot be treated as a complete selectable exchange.
@@ -62,7 +64,7 @@ A supported capability requires a non-empty implementation version. Unsupported
 - a duplicate, missing, or unversioned declaration is malformed and disabled;
 - no failure in one capability disables canonical history, privacy, completion fallback, or another valid capability.
 
-M19 only negotiates `local-kv-reuse`; M20 defines its eligibility and handle lifecycle. KV handles are never part of canonical history or these diagnostics.
+M19 introduced negotiation for `local-kv-reuse`; M20 adds `local-kv-eligibility-v1`, `LocalKvReuseController`, and the handle-free `LocalKvRuntimePort`. KV handles are never part of canonical history, core state, manifests, or diagnostics. See [Local KV Reuse](LOCAL_KV_REUSE.md).
 
 Pi advertises versioned compaction, OpenAI Responses continuation, and embedding-port support. It explicitly reports local KV reuse as unavailable. `/context adapter` shows the complete negotiation; `/context status` shows aggregate enabled/disabled counts.
 
@@ -113,7 +115,7 @@ The callback JSONL target was selected because it covers the full contract while
 
 Its `ds4-runtime-session-v1` file is canonical and append-only. The header binds runtime ID, session ID, and canonical project root. Message records contain DS4 canonical messages. `createReferenceHistory()` refuses overwrite, `appendReferenceHistoryMessage()` checks provenance before append, and `rebuildDerivedState()` discards only the in-memory snapshot. File size and message count are bounded. Files are mode `0600` where supported.
 
-The reference adapter provides a callback completion transport, enabled fail-closed privacy by default, optional `EmbeddingPort`, and explicit unsupported declarations for native compaction, provider continuation, and local KV state.
+The reference adapter provides a callback completion transport, enabled fail-closed privacy by default, and optional `EmbeddingPort`. Native compaction and provider continuation remain explicitly unsupported. Local KV reuse is unsupported by default but becomes a versioned supported capability when the host injects a `LocalKvRuntimePort`; configuration remains disabled until explicitly enabled.
 
 ## Packaging rules
 
@@ -138,6 +140,6 @@ npm pack --dry-run
 
 ## Limitations and rollback
 
-The reference adapter is intentionally synchronous-history/callback-completion infrastructure: it does not implement streaming, native compaction, branch editing, provider continuation, or KV reuse. Unsupported features remain disabled and visible rather than emulated.
+The reference adapter is intentionally synchronous-history/callback-completion infrastructure: it does not implement streaming, native compaction, branch editing, provider continuation, or a built-in provider-specific KV cache. Its optional KV path requires a host-owned port that retains handles and transport. Unsupported features remain disabled and visible rather than emulated.
 
-Removing the reference package does not affect Pi or core. A runtime can roll back its adapter by stopping it and returning to native history/context behavior; no canonical migration or SQLite downgrade is required. Deleting adapter caches is safe. Never delete the runtime-owned JSONL file as part of DS4 rollback.
+Removing the reference package does not affect Pi or core. A runtime can roll back its adapter by stopping it and returning to native history/context behavior; no canonical migration or SQLite downgrade is required. Deleting adapter caches is safe and produces a transparent full replay. Never delete the runtime-owned JSONL file as part of DS4 rollback.

package/docs/STORAGE.md

@@ -12,6 +12,8 @@ The extension never edits or rewrites Pi JSONL or project source files. Manual m
 
 The M19 non-Pi reference adapter owns a separate `ds4-runtime-session-v1` JSONL source selected by its host runtime. Its header binds runtime/session identity and the exact canonical project root; following records contain provenance-checked canonical messages. DS4 snapshots and capability diagnostics are disposable. `createReferenceHistory()` refuses overwrite, append uses a dedicated provenance-checked operation, files are mode `0600` where supported, and rebuild never edits this runtime-owned canonical file. Reference JSONL is not imported into Pi or `context.db`.
 
+M20 local KV state is entirely runtime-owned and volatile. Core returns only an in-memory eligibility fingerprint to the runtime port; it has no cache-handle field or serialization API. Prefixes, fingerprints, handles and provider outputs are absent from Pi/reference JSONL, Context Manifests, ranking artifacts and every SQLite table. Aggregate hit/miss/prefill counters live only on the adapter controller, and a restart safely resets them with the runtime cache. M20 adds no database migration.
+
 ## Session index
 
 Each parsed entry stores:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ds4-context-engine",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.2",
   "description": "Non-destructive, provider-independent context management for Pi.",
   "type": "module",
   "license": "MIT",
@@ -55,7 +55,7 @@
     ]
   },
   "dependencies": {
-    "ds4-context-core": "0.2.0-beta.1"
+    "ds4-context-core": "0.2.0-beta.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "0.84.3",

package/src/pi-adapter/version.ts

@@ -1,4 +1,4 @@
-export const EXTENSION_VERSION = "0.2.0-beta.1";
+export const EXTENSION_VERSION = "0.2.0-beta.2";
 export const SUPPORTED_PI_VERSION = "0.84.3";
 export const OBSERVER_PLANNER_VERSION = "observer-model-aware-v1";
 export const PLANNER_VERSION = "managed-learned-ranking-v1";