ds4-context-engine 0.2.0-rc.1 → 0.3.0-alpha.1

package/README.md

@@ -16,7 +16,7 @@ bounded active context with provenance
 Pi provider
 ```
 
-> **Project status:** M0–M20 and release-candidate hardening are available in prerelease `0.2.0-rc.1`: quality measurement, structural/hybrid retrieval, cross-session project memory, learned-ranking shadow evaluation, the runtime adapter kit, opt-in local KV reuse, schema-10 upgrades, long-session gates, and frozen 0.2 contracts. Stable `0.1.2` remains available; all lines target Pi `0.84.3`.
+> **Project status:** Stable `0.2.0` includes M0–M20 and frozen 0.2 contracts. Development is on `0.3.0-alpha.1`, adding the confirmation-gated `context_persistence` tool without changing canonical Pin/Memory records, SQLite schema 15, or the reference history contract. The maintenance line targets Pi `0.84.3`.
 
 ## Why DS4
 
@@ -31,6 +31,7 @@ It provides:
 - trust-gated structural project indexing, Git-aware invalidation and bounded source snippets;
 - hierarchical, validated, non-destructive compaction summaries;
 - persistent pins and append-only durable memory stored canonically in Pi JSONL;
+- a bounded, metadata-only `context_persistence` tool with local confirmation for every model-callable write;
 - opt-in checkpointed project-memory replay across exact trusted Pi project sessions;
 - content-addressed storage and bounded references for large tool results;
 - privacy classifications, secret redaction and provider-specific allow rules;
@@ -86,13 +87,7 @@ Install the latest stable public npm package with:
 pi install npm:ds4-context-engine
 ```
 
-Install the opt-in 0.2 release candidate from the `rc` dist-tag with:
-
-```bash
-pi install npm:ds4-context-engine@rc
-```
-
-All prerelease packages (`ds4-context-engine`, `ds4-context-core`, and `ds4-context-reference-adapter`) use the same exact version.
+The stable `0.2.0` packages (`ds4-context-engine`, `ds4-context-core`, and `ds4-context-reference-adapter`) use the same exact version. Both adapters require the matching core version.
 
 ### Local checkout
 
@@ -204,6 +199,19 @@ Project configuration and project source indexing are disabled when Pi reports t
 
 Valid privacy classifications are `normal`, `internal`, `sensitive` and `local-only`.
 
+### LLM-callable tools
+
+DS4 registers two model-callable tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `context_artifact_search` | Search a known DS4 artifact reference with bounded quoted excerpts |
+| `context_persistence` | Inspect Pins, Memory, and project-memory sources; perform explicitly requested persistence mutations |
+
+`context_persistence` read actions return bounded metadata and sanitized find previews. Every write requires a fresh local `ctx.ui.confirm()` decision. In print/JSON or any other no-UI mode, reads remain available and writes fail closed with `confirmation-required`. Sessions without a persistent Pi JSONL destination (for example `--no-session`) fail closed with `runtime-unavailable` before confirmation. Destructive writes require an exact ID or volatile source reference plus the `targetRevision` returned by a prior read; fuzzy writes are not supported.
+
+Canonical Pin and Memory changes append Pi custom entries and reconcile disposable SQLite projections. Project-memory source include/exclude is derived local SQLite policy and never appends a fake canonical entry. See [`docs/CONTEXT_PERSISTENCE_TOOL.md`](docs/CONTEXT_PERSISTENCE_TOOL.md).
+
 Learned-ranking feedback and local training are explicit:
 
 ```text
@@ -340,7 +348,7 @@ The following example shows the main configuration groups. Omitted values use th
 }
 ```
 
-Invalid or unknown values are ignored with a warning. Model overrides merge deterministically from `*` to `provider/*` to an exact `provider/model` profile. The 0.2 release line freezes this additive surface as `ds4-context-config-v1`; existing keys, validation, and defaults are pinned by the compatibility golden.
+Invalid or unknown values are ignored with a warning. Model overrides merge deterministically from `*` to `provider/*` to an exact `provider/model` profile. Routine session open/close, database, rebuild, and project-index summaries are emitted only at `debug`, so the default `info` level keeps session changes quiet while preserving actionable warnings. The 0.2 release line freezes this additive surface as `ds4-context-config-v1`; existing keys, validation, and defaults are pinned by the compatibility golden.
 
 ## Privacy and provider storage
 
@@ -396,9 +404,11 @@ npm run typecheck
 npm test
 npm run check
 npm run quality:compare
+npm run schema:context-persistence
+npm run latency:check -- /path/to/exact/ds4-context-core@0.1.2
 npm run pack:check
 # Post-publication, with an exact version rather than a dist-tag:
-npm run registry:check -- 0.2.0-rc.1
+npm run registry:check -- 0.3.0-alpha.1
 npm pack --dry-run
 npm pack --dry-run --workspace ds4-context-core
 npm pack --dry-run --workspace ds4-context-reference-adapter
@@ -436,6 +446,7 @@ scripts             package and release-readiness checks
 - [Project knowledge](docs/PROJECT_KNOWLEDGE.md)
 - [Artifacts](docs/ARTIFACTS.md)
 - [Memory and pins](docs/MEMORY_AND_PINS.md)
+- [Context persistence tool](docs/CONTEXT_PERSISTENCE_TOOL.md)
 - [Privacy](docs/PRIVACY.md)
 - [Model awareness](docs/MODEL_AWARENESS.md)
 - [Native continuation](docs/NATIVE_CONTINUATION.md)
@@ -446,7 +457,9 @@ scripts             package and release-readiness checks
 - [Roadmap 0.2.0](docs/ROADMAP_0.2.0.md)
 - [Release process](docs/RELEASING.md)
 - [0.2.0 release readiness](docs/RELEASE_READINESS_0.2.0.md)
+- [0.2.0 release notes](docs/releases/0.2.0.md)
 - [0.2.0-rc.1 release notes](docs/releases/0.2.0-rc.1.md)
+- [0.3.0-alpha.1 prerelease notes](docs/releases/0.3.0-alpha.1.md)
 - [Architecture decisions](docs/ADR/README.md)
 - [Original development plan](DS4_Context_Engine_Extension_Piano_Sviluppo.md)
 
@@ -454,7 +467,7 @@ scripts             package and release-readiness checks
 
 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 [0.2.0 roadmap](docs/ROADMAP_0.2.0.md) is in release-candidate hardening. The [readiness record](docs/RELEASE_READINESS_0.2.0.md) maps every release gate to tests and operator commands. 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) is complete. Development `0.3.0-alpha.1` adds the [context persistence tool](docs/CONTEXT_PERSISTENCE_TOOL.md) while retaining the stable canonical/configuration/SQLite/runtime contracts. The [0.2 readiness record](docs/RELEASE_READINESS_0.2.0.md) remains the compatibility baseline. Sensitive or transport-specific behavior remains opt-in, and the 0.1 lexical planner stays available as the deterministic fallback.
 
 ## Contributing
 

package/docs/ADR/README.md

@@ -56,5 +56,10 @@ The initial decisions from the development plan are accepted:
 | 050 | Retry rejected stale continuation state once with the complete managed replay before exposing output | Accepted |
 | 051 | Keep continuation handles volatile and exclude them from manifests, logs, and DS4 persistence | Accepted |
 | 052 | Compile `ds4-context-core` as ESM and keep the Pi adapter dependency one-way | Accepted |
+| 053 | Dispatch `context_persistence` directly through `Ds4ContextRuntime`, never through slash-command parsing | Accepted |
+| 054 | Use fresh local Pi UI confirmation as the V1 authorization boundary for every model-callable write | Accepted |
+| 055 | Enforce a dedicated metadata-only tool egress guard independently of `privacy.enabled` | Accepted |
+| 056 | Keep project-memory source exclusion as disposable derived SQLite policy | Accepted |
+| 057 | Derive mutation provenance from the active branch and exclude model-supplied source IDs from V1 | Accepted |
 
 Each decision will receive a dedicated record when implementation pressure introduces alternatives or consequences not already covered by the development plan.

package/docs/ARCHITECTURE.md

@@ -156,6 +156,14 @@ session_tree / shutdown
   -> transactional reconciliation from canonical JSONL, memory/pin replay, artifact regeneration and forced project rescan
 ```
 
+## Context persistence tool boundary
+
+`context_persistence` is a Pi-adapter capability, not a portable-core or reference-adapter API. Its controller calls `Ds4ContextRuntime` directly rather than relaying slash commands. Read actions use bounded keyset/visible-item APIs and emit only allowlisted metadata plus policy-sanitized find previews. Every LLM-callable write fails closed without Pi UI and requires a fresh local confirmation; model-provided consent fields are not accepted.
+
+Pin and Memory mutations resolve provenance from the active Pi branch, revalidate it after confirmation, append the existing `ds4-context-pin-v1` or `ds4-context-memory-v1` record through `pi.appendEntry()`, and then reconcile the disposable projection. Exact revisions bind target state to active session/project/branch context. Project-source include/exclude resolves a volatile `sourceRef` to an internal session identity and updates only coordinated SQLite policy—never Pi JSONL.
+
+Historical tool arguments and results are a provider-egress surface even when general privacy is disabled. A dedicated guard removes content, query, key, reason, paths and raw errors while preserving only action linkage and safe IDs/revisions. Provenance IDs and source paths are runtime-derived; the model cannot supply them in the V1 schema. Post-append failures distinguish an indeterminate append from a known canonical commit with pending projection, so callers are never encouraged to retry blindly.
+
 ## Boundaries
 
 Dependency direction is one-way:
@@ -198,7 +206,7 @@ Adapters may import core exports. Core source must never import `@earendil-works
 
 ## Canonical and derived state
 
-The Pi session JSONL remains canonical for conversation/tool state, inline classification markers, append-only classified memory/pin mutations and metadata-only learned-ranking feedback/replay labels; live files remain canonical for project knowledge. Native continuation keeps only volatile request/response-item hashes plus the minimum response handle and creates no continuation table or custom entry. SQLite and content-addressed object files store only rebuildable indexes, source-hash/model-keyed vectors, summary nodes/edges, metadata-only manifests, project file/snippet projections, artifact copies/references, materialized memory/pins, calibration data, and bounded metadata-only quality samples. The checksummed learned-ranking model is a separate disposable local artifact reconstructed from canonical labels; it contains bounded weights and aggregate gate metadata, never raw text. Each aggregate's active text is the Pi compaction summary; non-active nodes created by the same operation are embedded in its details, while older ancestors remain in earlier entries. Deleting the database must never damage or alter a Pi session or project. Reopening a source session replays its memory/pin mutations. Ephemeral sessions keep manifests and graph nodes in memory, disable durable memory/pins/artifacts, and may share the project index because files—not session JSONL—are its durable source.
+The Pi session JSONL remains canonical for conversation/tool state, inline classification markers, append-only classified memory/pin mutations and metadata-only learned-ranking feedback/replay labels; live files remain canonical for project knowledge. Volatile `context_persistence` source-reference/revision maps and derived project-source exclusion policy are local process/SQLite state and are never canonical. Native continuation keeps only volatile request/response-item hashes plus the minimum response handle and creates no continuation table or custom entry. SQLite and content-addressed object files store only rebuildable indexes, source-hash/model-keyed vectors, summary nodes/edges, metadata-only manifests, project file/snippet projections, artifact copies/references, materialized memory/pins, calibration data, and bounded metadata-only quality samples. The checksummed learned-ranking model is a separate disposable local artifact reconstructed from canonical labels; it contains bounded weights and aggregate gate metadata, never raw text. Each aggregate's active text is the Pi compaction summary; non-active nodes created by the same operation are embedded in its details, while older ancestors remain in earlier entries. Deleting the database must never damage or alter a Pi session or project. Reopening a source session replays its memory/pin mutations. Ephemeral sessions keep manifests and graph nodes in memory, disable durable memory/pins/artifacts, and may share the project index because files—not session JSONL—are its durable source.
 
 ## Lifecycle
 

package/docs/CONTEXT_PERSISTENCE_TOOL.md

@@ -0,0 +1,126 @@
+# Context Persistence Tool
+
+`context_persistence` is DS4's bounded model-callable interface for inspecting and explicitly updating Persistent Pins, Durable Memory, and cross-session project-memory source policy. It is available in the Pi adapter only; the portable core and reference adapter do not expose this Pi-specific tool.
+
+Contract identifiers:
+
+```text
+tool:   ds4-context-persistence-tool-v1
+result: ds4-context-persistence-result-v1
+```
+
+The tool declares `executionMode: "sequential"`. This orders sibling calls from one model response; SQLite writes still use the shared coordinator and every targeted mutation still checks its revision.
+
+## Pins and Memory
+
+Pins are confirmed constraints or instructions that should remain prominent. They may use `session`, `branch`, or trusted `project` scope. Branch Pins can remain lifecycle-active while not applying to the active branch.
+
+Memory is quoted durable factual, decision, or historical data. It supports `session` and trusted `project` scope, never `branch` scope. DS4 does not automatically extract either concept from ordinary conversation.
+
+## Actions
+
+| Action | Class | Purpose |
+| --- | --- | --- |
+| `pins_list` | read | List visible Pins with metadata and revisions |
+| `pins_find` | read | Bounded Pin search with sanitized previews |
+| `pin_add` | canonical write | Append a new Pin |
+| `pin_supersede` | canonical write | Replace one exact active Pin immutably |
+| `pin_unpin` | canonical write | Append a deleted lifecycle status |
+| `memory_list` | read | List visible Memory with metadata and revisions |
+| `memory_find` | read | Bounded Memory search with sanitized previews |
+| `memory_add` | canonical write | Append session/project Memory |
+| `memory_supersede` | canonical write | Replace one exact active Memory item immutably |
+| `memory_invalidate` | canonical write | Append an invalid lifecycle status |
+| `memory_expire` | canonical write | Append an expired lifecycle status |
+| `memory_sources` | read | List cross-session sources through volatile references |
+| `memory_source_exclude` | derived write | Exclude one source in local SQLite policy |
+| `memory_source_include` | derived write | Restore one source in local SQLite policy |
+
+Read results are keyset-bounded and metadata-only. List results never include Pin content, Memory claims, keys, paths, source session IDs, reasons, complete errors, or totals requiring an unbounded count. Find results may include a short provider-safe preview in text; `details.items` remains metadata-only.
+
+## Read before a targeted write
+
+Supersede, lifecycle, include, and exclude operations require:
+
+```text
+exact id or sourceRef
+targetRevision from a prior read
+```
+
+A revision is a process-local HMAC token bound to the item fingerprint and active session/project/branch context. It expires and is invalid after restart. A changed target, switched context, expired token, unknown reference, or non-active target is rejected. The tool never converts a fuzzy query or a high-scoring match into a write target.
+
+`memory_sources` returns `sourceRef`, not a session ID or file path. The mapping is process-local, TTL/cap-bounded, and never persisted. The opaque reference itself may remain in Pi's normal tool-result history so a subsequent exact call can use it.
+
+## Confirmation and no-UI behavior
+
+Every model-callable write requires a fresh local Pi UI decision:
+
+```ts
+await ctx.ui.confirm("DS4 Context Persistence", message)
+```
+
+The dialog identifies the action and persistence class. Canonical add/supersede dialogs show bounded full content and effective classification; lifecycle dialogs show a bounded local target preview and optional reason. Source-policy dialogs show only the volatile reference and safe status/counters. Confirmation text is never copied into the tool result or logs.
+
+A model cannot provide `confirmed=true`; it is not in the schema. If `ctx.hasUI` is false, all writes return:
+
+```text
+outcome=unavailable
+errorCode=confirmation-required
+```
+
+Reads remain available. Refusal, dialog closure, or abort before dispatch causes no write. Pi `0.84.3` RPC can advertise UI capability even when no client is currently answering UI requests. In that case the confirmation request remains pending in Pi's RPC transport; DS4 does not infer consent or refusal, and no append occurs before a positive response. RPC clients that expose UI capability must answer the request explicitly. If the active Pi session has no persistent JSONL destination (for example `--no-session`), reads and writes both fail closed with `runtime-unavailable`; no confirmation is shown and no canonical commit is claimed.
+
+## Canonical and derived persistence
+
+Pin and Memory mutations call `Ds4ContextRuntime`, append the existing versioned custom entry through `pi.appendEntry()`, and reconcile SQLite:
+
+```text
+ds4-context-pin-v1
+ds4-context-memory-v1
+```
+
+The tool never inserts canonical Pin or Memory state directly into SQLite and never rewrites Pi JSONL. Provenance is derived from the latest preceding user message on the active branch, not from model-supplied source IDs, and is revalidated after confirmation.
+
+Project-memory source exclusion is intentionally different. It updates `project_memory_source_exclusions` through the coordinated runtime repository and reports `persistenceClass=derived-local-policy`. It does not append a fake Pi entry. Deleting `context.db` resets this policy; replay restores source contributions from unchanged sibling JSONL.
+
+## Privacy and provider policy
+
+The tool enforces its own egress policy even when general privacy is disabled:
+
+- current and historical content, query, key, reason, preview, path, source identity, and raw errors are removed unless explicitly allowed;
+- results use deterministic metadata-only templates;
+- marker/credential detection may raise a mutation classification;
+- an explicit supersede classification cannot lower the target's effective protection;
+- remote-disallowed or `local-only` writes are rejected before append;
+- provider/trust/provenance/target state is checked again after confirmation.
+
+Selecting `local-only` does not prove that a remote model never saw the original message or tool arguments. Use the direct `/context` command surface or a verified local provider when data must never be disclosed remotely.
+
+## Outcomes and recovery
+
+| Outcome | Meaning |
+| --- | --- |
+| `ok` | Read succeeded, add was duplicate, or source policy already matched |
+| `committed` | Canonical append/materialization or derived policy update succeeded |
+| `rejected` | Validation, policy, trust, provenance, conflict, target, or revision check failed |
+| `cancelled` | User refusal/dialog closure or abort before dispatch |
+| `unavailable` | Runtime/capability/UI unavailable; no commit is claimed |
+| `committed_projection_pending` | Canonical append succeeded but projection/result materialization did not complete safely |
+| `indeterminate` | The append call did not return, so completion cannot be established |
+
+Never automatically retry `committed_projection_pending` or `indeterminate`. Inspect with a read, `/context health`, or `/context rebuild-index` first. SQLite is disposable; canonical Pin/Memory state reappears after replay. Source exclusions intentionally do not.
+
+## `/context` relationship
+
+`/context` remains the direct local administrative and inspection surface. It can show local detail that must not enter a provider-visible tool result. `context_persistence` calls the same runtime mutation primitives but has a narrower schema, automatic branch provenance, exact-revision requirements, confirmation on every write, and a dedicated historical egress guard.
+
+Useful diagnostics:
+
+```text
+/context pins
+/context memory
+/context memory sources
+/context privacy
+/context health
+/context rebuild-index
+```

package/docs/MEMORY_AND_PINS.md

@@ -1,6 +1,6 @@
 # Memory and Persistent Pins
 
-M9 separates durable, user-curated state from conversation history while keeping Pi JSONL canonical. M17 optionally reconstructs explicit project-scoped mutations from sibling Pi sessions for the same trusted canonical project.
+DS4 separates durable, user-curated state from conversation history while keeping Pi JSONL canonical. Cross-session replay optionally reconstructs explicit project-scoped mutations from sibling Pi sessions for the same trusted canonical project.
 
 ## Authority and scope
 
@@ -37,7 +37,7 @@ Pins remain subordinate to system/developer instructions. Memory tells the model
 
 Arguments support single/double quotes and backslash escaping. `--` ends option parsing. Source entry IDs must be on Pi's active branch. Project scope requires Pi project trust. Source exclusion affects only project-scoped contributions and persists until `include`; the active session cannot be newly excluded but can restore a prior exclusion.
 
-Mutations are manual-first. Repeating the same normalized pin/claim returns its existing ID without appending another entry.
+Mutations are manual-first: persistence requires an explicit user request, and every LLM-tool write additionally requires local UI confirmation. DS4 never harvests ordinary conversation into Pins or Memory automatically. `/context` remains the direct local command surface; `context_persistence` is the bounded model-callable surface and requires a prior exact read plus revision for destructive operations. Repeating the same normalized pin/claim returns its existing ID without appending another entry.
 
 ## Canonical append-only mutations
 
@@ -63,7 +63,7 @@ No row is silently overwritten. SQLite mutation and materialized tables are disp
 3. replays all known mutations in timestamp + canonical entry order;
 4. rebuilds memory, pin, source, lifecycle, and FTS rows transactionally.
 
-Deleting `context.db` and reopening the canonical source session reconstructs its state. With `memory.crossSession: true`, DS4 discovers bounded sibling `.jsonl` files, accepts only headers whose `cwd` resolves to the exact trusted canonical project identity, incrementally indexes each source, and reconstructs project items without opening every session manually. No claim is extracted from ordinary conversation text.
+Deleting `context.db` and reopening the canonical source session reconstructs its state. With `memory.crossSession: true`, DS4 discovers bounded sibling `.jsonl` files, accepts only headers whose `cwd` resolves to the exact trusted canonical project identity, incrementally indexes each source, and reconstructs project items without opening every session manually. No claim is extracted from ordinary conversation text. Source exclusions are deliberately derived local policy: deleting the database removes them, replay restores the source from unchanged canonical JSONL, and no source-policy operation rewrites a session file.
 
 ## Supersession and contradiction handling
 

package/docs/PRIVACY.md

@@ -34,7 +34,7 @@ Persistent pin and memory commands also accept an explicit classification:
 
 The classification is part of the canonical Pi custom-entry mutation and survives SQLite deletion, session resume, branch changes, and compaction. Existing unclassified mutations use `privacy.defaultClassification` at selection time.
 
-Automatic sensitivity classification remains disabled. M10 uses explicit markers, explicit pin/memory metadata, and the configured default.
+Automatic harvesting/classification of ordinary conversation remains disabled. Persistent commands use explicit markers, explicit Pin/Memory metadata, and the configured default. For a confirmed `context_persistence` content-bearing mutation, marker and credential-like detection may only raise the stored classification floor; it can never lower an existing target classification.
 
 ## Provider destination and allow rules
 
@@ -91,6 +91,14 @@ Pi's fallback compactor is still covered by the final provider-payload hook.
 
 The local content-addressed object may retain exact restricted bytes because Pi JSONL is canonical and object hashes require exact recovery. Artifact references persist the derived classification in `metadata_json`. Context selection hides prohibited tool results before offload/reference injection. `context_artifact_search` applies the stored artifact classification to every returned excerpt; a remote request receives no matches/content for a prohibited artifact.
 
+### Context persistence tool egress
+
+`context_persistence` treats both its current result and historical Pi tool-call/result records as provider-egress surfaces independently of `privacy.enabled`. List/source results contain only bounded IDs or volatile references, scope/lifecycle/classification/timestamps, revisions and safe counters. Find previews are sanitized across the complete bounded source before Unicode-scalar truncation; prohibited previews become metadata-only omissions. Mutation results never echo content, claim, key or reason.
+
+A dedicated historical guard preserves provider-specific tool-call/result linkage while replacing `content`, `query`, `key`, `reason`, unknown fields, raw previews and malformed payloads with a fixed omission sentinel. IDs and revisions must match their opaque grammars; paths, source session identity, complete errors and UI confirmation text are never copied. Local `sourceRef` mappings, revision HMAC secrets and target fingerprints are volatile and contain no content.
+
+Every write is policy-checked before local confirmation and checked again immediately before dispatch, covering provider or trust changes while the dialog is open. `local-only` supplied by a model is not proof that earlier input stayed local; remote-denied writes return only `provider-policy-denied` and do not append.
+
 ### Final provider payload
 
 `before_provider_request` runs after provider-specific serialization. DS4 recursively checks known provider content containers (`system`, `messages`, `input`, `contents`, `context`, tool descriptions/arguments, and related text fields), strips classification markers, removes prohibited blocks, and redacts credential-like values. Structural provider fields remain unchanged.

package/docs/RELEASE_READINESS_0.2.0.md

@@ -1,6 +1,6 @@
 # DS4 0.2.0 Release Readiness
 
-This document is the release-candidate hardening record for the 0.2 line. A prerelease is not a stable-release declaration. A candidate is complete only after the commands below pass on a clean commit and the exact published registry artifacts pass the post-publication check.
+This document is the completed hardening record for the stable 0.2 line. The `0.2.0-rc.1` candidate passed the commands below on a clean commit, and the stable release requires the same gates plus exact verification of the published `0.2.0` registry artifacts.
 
 ## Frozen compatibility surface
 
@@ -93,7 +93,7 @@ rm -rf "$BASELINE_DIR"
 After publishing all three packages in dependency order, verify registry bytes rather than local tarballs:
 
 ```bash
-npm run registry:check -- 0.2.0-rc.1
+npm run registry:check -- 0.2.0
 ```
 
 The registry check accepts an exact version, never a mutable dist-tag. It installs all three public packages plus the supported Pi SDK into a fresh project, validates matching exact core dependencies, imports core and local-KV exports, runs compiled reference conformance, runs the packaged quality corpus, and starts the published Pi extension through isolated offline RPC state.

package/docs/RELEASING.md

@@ -23,12 +23,14 @@ The automated package check enforces matching versions, exact core dependencies,
 ```bash
 npm ci
 npm run check
+npm run quality:compare
+npm run schema:context-persistence
 npm run pack:check
 git diff --check
 git status --short
 ```
 
-For a 0.2 release candidate, compare feature-disabled planning against exact stable `ds4-context-core@0.1.2` on the same host:
+For a 0.2 release candidate or the coordinated `0.3.0-alpha.1` prerelease, compare feature-disabled planning against exact stable `ds4-context-core@0.1.2` on the same host:
 
 ```bash
 BASELINE_DIR="$(mktemp -d)"
@@ -39,7 +41,7 @@ npm run latency:check -- "$BASELINE_DIR/node_modules/ds4-context-core"
 rm -rf "$BASELINE_DIR"
 ```
 
-The check rejects a candidate p95 above 110% of the exact 0.1.2 baseline. See [`RELEASE_READINESS_0.2.0.md`](RELEASE_READINESS_0.2.0.md) for the complete gate matrix and rollback procedure.
+The check rejects a candidate p95 above 110% of the exact 0.1.2 baseline. Run latency measurements on an otherwise idle host and repeat an anomalous run before drawing a release conclusion. See [`RELEASE_READINESS_0.2.0.md`](RELEASE_READINESS_0.2.0.md) for the stable-line gate matrix and [`releases/0.3.0-alpha.1.md`](releases/0.3.0-alpha.1.md) for prerelease-specific evidence and remaining publication gates.
 
 CI runs the same checks on the minimum supported Node.js version and the current Node.js LTS line. `npm run pack:check` uses a temporary directory and removes it when complete. Set `DS4_KEEP_PACK_TMP=1` only when diagnosing a failed package check.
 
@@ -65,11 +67,13 @@ npm install --package-lock-only
 npm run pack:check
 ```
 
-Review `package.json`, both workspace package manifests, and `package-lock.json` before committing the release change.
+Review `package.json`, both workspace package manifests, and `package-lock.json` before committing the release change. For `0.3.0-alpha.1`, all three manifests and both exact adapter dependencies must use precisely that prerelease version; do not publish only the root package without a separate release-policy decision.
 
 ## Publish
 
-Authenticate with npm, verify the active account, and publish in dependency order:
+Publishing is manual-only. GitHub Actions workflows must remain validation-only: do not add npm credentials, `NODE_AUTH_TOKEN`, `NPM_TOKEN`, `id-token: write`, `packages: write`, or an `npm publish` step. The CI workflow explicitly denies OIDC and package-write permissions.
+
+Authenticate with npm using an interactive OTP or a granular publish token with bypass 2FA, verify the active account, and publish in dependency order. Stable releases may use npm's default `latest` tag:
 
 ```bash
 npm whoami
@@ -78,7 +82,15 @@ npm publish --workspace ds4-context-reference-adapter --access public
 npm publish --access public
 ```
 
-If core succeeds but an adapter publication fails, fix that adapter release and retry it with the same version. Do not rewrite or unpublish a valid core release merely to make the commands appear atomic.
+Prereleases must pass the same explicit channel tag to all three commands so they cannot move `latest`. For `0.3.0-alpha.1`:
+
+```bash
+npm publish --workspace ds4-context-core --access public --tag alpha
+npm publish --workspace ds4-context-reference-adapter --access public --tag alpha
+npm publish --access public --tag alpha
+```
+
+After prerelease publication, verify both the exact artifacts and that `latest` still resolves to the intended stable version. If core succeeds but an adapter publication fails, fix that adapter release and retry it with the same version and channel tag. Do not rewrite or unpublish a valid core release merely to make the commands appear atomic.
 
 After all registry packages are available:
 

package/docs/ROADMAP_0.2.0.md

@@ -1,6 +1,6 @@
 # DS4 0.2.0 Roadmap
 
-Status: **release candidate published**. `0.2.0-rc.1` is the latest prerelease; no stable release date is committed.
+Status: **complete**. Stable `0.2.0` is released with all compatibility and release gates satisfied.
 
 Version 0.2.0 focuses on evidence quality, safe project-wide reuse and runtime portability. It extends the released 0.1.0 architecture without changing its canonical-state or failure guarantees.
 
@@ -248,6 +248,14 @@ Status: **implemented and released in `0.2.0-rc.1`**. See [`RELEASE_READINESS_0.
 - Registry package smoke tests, documentation and release notes.
 - Freeze config, database and adapter-contract schemas for 0.2.0.
 
+### `0.2.0`
+
+Status: **stable release completed**. See the [release notes](releases/0.2.0.md) and the final [`RELEASE_READINESS_0.2.0.md`](RELEASE_READINESS_0.2.0.md) evidence record.
+
+- Promotes the validated release candidate without changing frozen 0.2 contracts or default behavior.
+- Publishes matching stable versions of the core, reference adapter and Pi adapter.
+- Verifies exact registry artifacts in a clean consumer after publication.
+
 ## Release gates
 
 Version 0.2.0 is ready only when (the live evidence matrix is maintained in [`RELEASE_READINESS_0.2.0.md`](RELEASE_READINESS_0.2.0.md)):

package/docs/STORAGE.md

@@ -8,7 +8,7 @@ Pi's session JSONL is canonical for conversations and live project files are can
 /context rebuild-index
 ```
 
-The extension never edits or rewrites Pi JSONL or project source files. Manual memory/pin commands and learned-ranking feedback append versioned classified Pi `CustomEntry` records through Pi's official `appendEntry()` API.
+The extension never edits or rewrites Pi JSONL or project source files. Manual memory/pin commands, confirmed `context_persistence` canonical writes, and learned-ranking feedback append versioned classified Pi `CustomEntry` records through Pi's official `appendEntry()` API. The tool does not write SQLite as a substitute for a canonical Pin or Memory append.
 
 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`.
 
@@ -73,7 +73,7 @@ Schema v9 adds append-only `memory_mutations` and `pin_mutations`, each keyed to
 
 Before replay, the current session's mutation rows are replaced from its complete Pi entry tree. Other indexed sessions remain available, preserving the 0.1 project-scope behavior.
 
-Schema v15 adds `project_memory_sessions`, `project_memory_source_exclusions`, and mutation creation-parent columns. When `memory.crossSession` is opted in, DS4 enumerates at most `memory.maxProjectSessions` sibling Pi JSONL files, validates each header against the exact trusted canonical project path, indexes only changed suffixes, and materializes their explicit mutations. Source rows retain header/checkpoint hashes, offsets, record/mutation counts, malformed-line counts, status and bounded error text. Exclusions are local derived policy; mutation content remains only in canonical JSONL and existing local projection tables.
+Schema v15 adds `project_memory_sessions`, `project_memory_source_exclusions`, and mutation creation-parent columns. When `memory.crossSession` is opted in, DS4 enumerates at most `memory.maxProjectSessions` sibling Pi JSONL files, validates each header against the exact trusted canonical project path, indexes only changed suffixes, and materializes their explicit mutations. Source rows retain header/checkpoint hashes, offsets, record/mutation counts, malformed-line counts, status and bounded error text. Exclusions are local derived policy; mutation content remains only in canonical JSONL and existing local projection tables. `context_persistence` exposes a process-local `sourceRef` instead of the session ID/path. Source-reference and revision mappings are TTL/cap-bounded, never written to SQLite, manifests, logs or JSONL, and disappear at restart. Deleting `context.db` deliberately removes exclusions; replay then restores contributions from unchanged canonical sibling JSONL.
 
 A missing, moved, truncated, identity-mismatched or corrupt sibling source stops contributing unverifiable project-scoped mutations without discarding its isolated session-scoped projection. The active session retains its last transactional projection if an auxiliary cross-session refresh fails. Restored files rebuild deterministically. Deleting the database loses no canonical mutation; source discovery recreates the complete project projection without opening every source session. Unbacked legacy pre-v9 materialized rows are inspectable immediately after migration but are not treated as canonical during a later full replay.
 

package/docs/releases/0.2.0.md

@@ -0,0 +1,43 @@
+# DS4 Context Engine 0.2.0
+
+Status: **stable release under the npm `latest` dist-tag**.
+
+DS4 Context Engine 0.2.0 promotes the validated `0.2.0-rc.1` candidate without changing its frozen contracts, safe defaults, or canonical-state guarantees.
+
+## Highlights since 0.1.2
+
+- deterministic metadata-only context-quality metrics and comparison corpus;
+- structural project chunks and richer symbol relations;
+- opt-in local or explicitly consented remote hybrid semantic retrieval;
+- opt-in cross-session project memory replay from canonical Pi JSONL;
+- learned ranking with `off`, shadow, promotion-gated active, and static fallback modes;
+- `runtime-adapter-v1`, a reusable conformance kit, and the callback/JSONL reference adapter;
+- opt-in exact local prefix/KV reuse for adapters with a host-owned volatile runtime port;
+- shared-SQLite WAL/write coordination and renewable fenced project-index leases.
+
+## Stable-release evidence
+
+- exact schema-v10 (0.1) to schema-v15 upgrade coverage;
+- complete rebuild coverage from canonical session, adapter, and project sources;
+- full configuration, migration, adapter, capability, and local-KV compatibility golden;
+- 1,201-message repeated-planning coverage for hard limits, canonical integrity, and bounded derived retention;
+- local/remote provider-switch, privacy, continuation, and cache-invalidation coverage;
+- feature-disabled p95 comparison against exact `ds4-context-core@0.1.2` within the 10% release threshold;
+- clean package-consumer validation and exact-version post-publication registry verification for all three packages.
+
+## Compatibility and defaults
+
+- Node.js `>=22.19.0`;
+- Pi `0.84.3`;
+- configuration contract `ds4-context-config-v1`;
+- SQLite projection schema `15`;
+- runtime adapter contract `runtime-adapter-v1`;
+- matching `0.2.0` versions are required for adapters and `ds4-context-core`.
+
+Existing 0.1 configuration remains valid. Semantic retrieval, cross-session memory, context-quality recording, learned ranking, and local KV reuse remain disabled by default. Pi JSONL, reference-adapter JSONL, and live project files remain canonical; SQLite, embeddings, ranking models, artifacts, and runtime KV state remain local and disposable.
+
+## Upgrade and rollback
+
+Opening a 0.1 database applies forward migrations 11–15 without rewriting canonical history. A 0.1 binary cannot open schema 15. To roll back, stop every process using the shared database, retain canonical JSONL and project files, and let 0.1 create a fresh derived database or use a different `storage.databasePath`. Never alter migration checksums or delete reference-adapter canonical JSONL.
+
+See [`../RELEASE_READINESS_0.2.0.md`](../RELEASE_READINESS_0.2.0.md) for the complete gate matrix, limitations, and rollback procedure.

package/docs/releases/0.3.0-alpha.1.md

@@ -0,0 +1,83 @@
+# DS4 Context Engine 0.3.0-alpha.1
+
+Status: development prerelease candidate; not published by this change.
+
+This prerelease adds a confirmation-gated, model-callable persistence surface while preserving the stable 0.2 canonical and projection contracts.
+
+## Added
+
+- `context_persistence` with contract `ds4-context-persistence-tool-v1` and sequential execution.
+- Result envelope `ds4-context-persistence-result-v1` with bounded metadata-only read and mutation DTOs.
+- Fourteen actions covering Pin/Memory list, find, canonical mutations, project-memory sources, and derived source include/exclude policy.
+- Bounded keyset repository APIs, exact visible-item reads, scan caps, stable process-local revisions, and volatile project source references.
+- Local Pi UI confirmation for every model-callable write; all writes fail closed with `confirmation-required` when no UI is available.
+- Active-branch provenance derivation and post-confirmation revalidation for content-bearing mutations.
+- Fail-closed `runtime-unavailable` behavior when no persistent Pi session JSONL destination exists.
+- Tracked canonical append outcomes distinguishing committed state, projection pending, and indeterminate append completion.
+- Provider-specific historical tool-call/result sanitization for Anthropic-, Google-, and generic-shaped payloads.
+- Integration coverage for real extension registration, Pi append-only custom entries, projection, lifecycle replay, derived-policy reset, and metadata-only logging.
+
+## Persistence guarantees
+
+Canonical Pin and Memory writes continue to use the unchanged records:
+
+```text
+ds4-context-pin-v1
+ds4-context-memory-v1
+```
+
+They pass through `Ds4ContextRuntime` and `pi.appendEntry()` before projection reconciliation. SQLite remains disposable and rebuildable. Project-memory source exclusion remains derived SQLite policy and deliberately disappears when the database is deleted. No migration was added; schema remains 15 and migrations 1–15 are unchanged.
+
+The reference adapter remains on its append-only `ds4-runtime-session-v1` history contract. Local-KV handles/state, ranking models, revisions, source-reference mappings, SQLite projections, and source exclusion policy remain local and non-canonical.
+
+## Authorization and privacy
+
+- Ordinary conversation never creates a Pin or Memory automatically.
+- Targeted writes require a prior exact ID/reference and `targetRevision`; fuzzy writes are rejected by construction.
+- Confirmation is obtained only from `ctx.ui.confirm()` and is revalidated against current provider, trust, provenance, capability, and target state before dispatch.
+- Explicit supersession cannot lower the target's effective classification. Markers and credential-like detection may only elevate it.
+- Tool results, historical arguments/results, errors, diagnostics, and logs are bounded and allowlisted. Content, claims, keys, reasons, paths, source identity, raw errors, and confirmation text are not echoed.
+- `local-only` is denied to remote/unknown providers and is never presented as proof that prior input stayed local.
+
+## Package/version policy
+
+The coordinated prerelease version is `0.3.0-alpha.1` for:
+
+```text
+ds4-context-core
+ds4-context-reference-adapter
+ds4-context-engine
+```
+
+Both adapters retain an exact dependency on `ds4-context-core@0.3.0-alpha.1`. Publication remains manual-only under the explicit npm `alpha` dist-tag so `latest` continues to resolve to stable `0.2.0`; GitHub Actions remains validation-only with OIDC and package-write permissions denied.
+
+## Validation evidence
+
+Latest local verification:
+
+- `npm run check`: 64 files, 283 tests passed.
+- `npm run quality:compare`: candidate quality score `0.9875` versus static baseline `0.808156` on `ds4-quality-corpus-v1`.
+- `npm run schema:context-persistence`: 1,197 bytes, 300 estimated tokens; below both the 1,500-token absolute and 320-token relative gates.
+- `npm run latency:check -- <exact ds4-context-core@0.1.2>`: isolated run ratio `0.880399`, below `1.10` (`0.495890` ms baseline p95, `0.436581` ms candidate p95).
+- `npm run pack:check`: verified `ds4-context-core@0.3.0-alpha.1` (203 files), `ds4-context-reference-adapter@0.3.0-alpha.1` (7 files), and `ds4-context-engine@0.3.0-alpha.1` (57 files) in a clean consumer.
+- `npm pack --dry-run --json` for all three packages: passed with the same bounded inventories.
+- The complete candidate change set was replayed onto a detached clean checkout at `f130115`; offline install, `npm run check`, schema gate, package verification, and `git diff --check` all passed there.
+- `git diff --check`: passed.
+
+Isolated Pi `0.84.3` smoke with the configured `openai-codex` provider passed:
+
+- TUI read/add and exact-revision unpin committed only after confirmation; refusal produced no append; remote `local-only` input was denied before confirmation.
+- RPC confirmation acceptance/refusal produced the expected committed/cancelled envelopes with no result-content leak; `--no-session` returned `runtime-unavailable` before confirmation. Pi `0.84.3` advertises UI capability even when no RPC UI client answers, so an unanswered request remains pending without append rather than being treated as `confirmation-required`.
+- Print/JSON reads remained available and writes returned `confirmation-required` with no append.
+- A natural explicit persistence request selected `memory_add`; an ordinary suggestion did not call the tool.
+
+No live local provider was configured for this smoke; the local-provider privacy path remains covered by automated policy/tool tests. Exact registry verification remains a post-publication gate. Do not tag or publish before an explicit release decision.
+
+## Documentation
+
+- [`../CONTEXT_PERSISTENCE_TOOL.md`](../CONTEXT_PERSISTENCE_TOOL.md)
+- [`../MEMORY_AND_PINS.md`](../MEMORY_AND_PINS.md)
+- [`../PRIVACY.md`](../PRIVACY.md)
+- [`../STORAGE.md`](../STORAGE.md)
+- [`../ARCHITECTURE.md`](../ARCHITECTURE.md)
+- [`../RELEASING.md`](../RELEASING.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ds4-context-engine",
-  "version": "0.2.0-rc.1",
+  "version": "0.3.0-alpha.1",
   "description": "Non-destructive, provider-independent context management for Pi.",
   "type": "module",
   "license": "MIT",
@@ -46,6 +46,7 @@
     "test:watch": "npm run build:core && npm run build:adapters && vitest",
     "check": "npm run build:core && npm run build:adapters && tsc --noEmit && vitest run",
     "quality:compare": "node scripts/compare-context-quality.mjs",
+    "schema:context-persistence": "node scripts/measure-context-persistence-schema.mjs",
     "latency:check": "npm run build:core && node scripts/compare-disabled-planning-latency.mjs",
     "pack:check": "node scripts/verify-packages.mjs",
     "registry:check": "node scripts/verify-registry-packages.mjs",
@@ -57,7 +58,7 @@
     ]
   },
   "dependencies": {
-    "ds4-context-core": "0.2.0-rc.1"
+    "ds4-context-core": "0.3.0-alpha.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "0.84.3",