ds4-context-engine 0.3.0-alpha.1 → 0.3.0-alpha.3

package/README.md

@@ -16,7 +16,7 @@ bounded active context with provenance
 Pi provider
 ```
 
-> **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`.
+> **Project status:** Stable `0.2.0` includes M0–M20 and frozen 0.2 contracts. Published prerelease `0.3.0-alpha.2` hardens the confirmation-gated `context_persistence` tool by rejecting its output-only historical egress sentinel on input, without changing canonical Pin/Memory records, SQLite schema 15, or the reference history contract. npm `alpha` points to `0.3.0-alpha.2`, `latest` remains `0.2.0`, and the maintenance line targets Pi `0.84.3`.
 
 ## Why DS4
 
@@ -89,6 +89,14 @@ pi install npm:ds4-context-engine
 
 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.
 
+To dogfood the published alpha without replacing a global stable installation, pin it in a disposable project:
+
+```bash
+pi install -l npm:ds4-context-engine@0.3.0-alpha.2
+```
+
+Follow the [0.3 alpha dogfooding runbook](docs/DOGFOODING_0.3.0_ALPHA.md); use synthetic data and a dedicated session directory.
+
 ### Local checkout
 
 ```bash
@@ -408,7 +416,7 @@ 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.3.0-alpha.1
+npm run registry:check -- 0.3.0-alpha.2
 npm pack --dry-run
 npm pack --dry-run --workspace ds4-context-core
 npm pack --dry-run --workspace ds4-context-reference-adapter
@@ -447,6 +455,7 @@ scripts             package and release-readiness checks
 - [Artifacts](docs/ARTIFACTS.md)
 - [Memory and pins](docs/MEMORY_AND_PINS.md)
 - [Context persistence tool](docs/CONTEXT_PERSISTENCE_TOOL.md)
+- [0.3 alpha dogfooding runbook](docs/DOGFOODING_0.3.0_ALPHA.md)
 - [Privacy](docs/PRIVACY.md)
 - [Model awareness](docs/MODEL_AWARENESS.md)
 - [Native continuation](docs/NATIVE_CONTINUATION.md)
@@ -459,6 +468,7 @@ scripts             package and release-readiness checks
 - [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.2 prerelease notes](docs/releases/0.3.0-alpha.2.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)
@@ -467,7 +477,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 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.
+The [0.2.0 roadmap](docs/ROADMAP_0.2.0.md) is complete. Prerelease `0.3.0-alpha.2` hardens the [context persistence tool](docs/CONTEXT_PERSISTENCE_TOOL.md) delivered in alpha.1 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/COMPACTION.md

@@ -32,7 +32,9 @@ Any mapping, model, output-limit, validation, or storage error returns `undefine
 ## Critical Exact Values
 ```
 
-Every section must occur once, in order, and contain content or `- None`. DS4 replaces each unique `Files Read` and `Files Modified` section with one exact path per bullet from Pi's sanitized file-operation inventory before validation; missing or duplicate sections still fail. Backticked exact values must occur in the serialized segment source, ordered child-summary content, or those known file-operation paths. A bounded unsupported exact-value bullet is removed as a whole and recorded as a validation warning; unsupported prose, more than eight affected bullets, or removal above 25% still fails closed to Pi. Segment and aggregate outputs are validated independently; either unrepaired failure prevents the whole graph batch from being installed.
+Every section must occur once, in order, and contain content or `- None`. DS4 replaces each unique `Files Read` and `Files Modified` section with one exact path per bullet from Pi's sanitized file-operation inventory before validation; missing or duplicate sections still fail. Backticked exact values must occur in the serialized segment source, ordered child-summary content, or those known file-operation paths. A bounded unsupported exact-value bullet is removed as a whole and recorded as a validation warning; unsupported prose, more than eight affected bullets, or removal above 25% still fails closed to Pi. The prompt explicitly asks the model to omit a bullet whose complete backticked span cannot be copied verbatim. Segment and aggregate outputs are validated independently; either unrepaired failure prevents the whole graph batch from being installed.
+
+An unrepaired exact-value failure reports only the stage, issue code, categorical repair status, unsupported-span count, and affected-bullet count. Repair statuses distinguish an unsupported location, more than eight bullets, removal above 25%, and an unexpected invalid second validation. The disputed text is intentionally absent from logs, UI notifications, and diagnostics because it may contain sensitive source material.
 
 ## Provenance and recovery
 

package/docs/CONTEXT_PERSISTENCE_TOOL.md

@@ -88,6 +88,7 @@ Project-memory source exclusion is intentionally different. It updates `project_
 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;
+- the fixed historical omission sentinel is output-only; any incoming string argument containing it is rejected as `egress-placeholder` before runtime access, confirmation, or persistence, so retries must use fresh user-provided text;
 - 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;
@@ -124,3 +125,7 @@ Useful diagnostics:
 /context health
 /context rebuild-index
 ```
+
+## Alpha dogfooding
+
+Use the published package with synthetic data and exercise TUI, RPC, print, and JSON behavior through the dedicated [`0.3 alpha dogfooding runbook`](DOGFOODING_0.3.0_ALPHA.md). The runbook distinguishes RPC's UI request/response bridge from genuinely no-UI print/JSON modes and includes a metadata-only canonical append audit.

package/docs/DOGFOODING_0.3.0_ALPHA.md

@@ -0,0 +1,304 @@
+# Dogfooding DS4 0.3.0 Alpha
+
+This runbook validates the published `ds4-context-engine@0.3.0-alpha.2` package through sustained real Pi use. It complements automated tests and release smoke checks; it does not replace them.
+
+The primary target is the model-callable `context_persistence` surface. Pi JSONL must remain canonical and append-only, SQLite must remain rebuildable, and no model-callable write may occur without a fresh positive local UI decision.
+
+## Safety and scope
+
+- Use the exact prerelease version, not the mutable `alpha` dist-tag.
+- Use a disposable trusted project and a dedicated session directory.
+- Use synthetic, non-secret Pin/Memory content. Local TUI dialogs and JSON event streams may display current tool arguments.
+- Published alpha.1 had a retry limitation: copying `[omitted-by-ds4-egress-policy]` from sanitized history could present a confirmation for the literal marker. Alpha.2 reserves that output-only marker and must reject it as `egress-placeholder` before runtime access, confirmation, canonical append, or derived-policy update.
+- Do not use `--no-session` except for the explicit fail-closed test. Without a persistent Pi JSONL destination, both reads and writes return `runtime-unavailable`.
+- Do not retry `committed_projection_pending` or `indeterminate`. Inspect state with a read, `/context health`, or `/context rebuild-index` first.
+- Use `/context` only for local inspection and recovery. Mutations under test must go through `context_persistence` so the confirmation and provider-egress boundaries are exercised.
+- Never edit a Pi session JSONL file during the run.
+
+Recommended minimum before promoting the alpha: three normal work sessions, two process restarts, one branch change, one projection rebuild, the TUI/RPC/print/JSON matrix, one configured remote provider, and—when available—one verified local provider.
+
+## Isolated setup
+
+Pi packages execute with the user's full permissions. Review the package before installation.
+
+```bash
+mkdir -p /tmp/ds4-alpha-dogfood
+cd /tmp/ds4-alpha-dogfood
+git init
+mkdir -p sessions evidence
+pi install -l npm:ds4-context-engine@0.3.0-alpha.2
+pi list
+pi --version
+```
+
+The `-l` installation is project-local and the exact npm version is pinned. Run Pi from this directory. Use `--approve` only after trusting this disposable project; non-interactive modes cannot show the project-trust dialog.
+
+Use the same dedicated session directory throughout:
+
+```bash
+export DS4_DOGFOOD_SESSIONS="$PWD/sessions"
+```
+
+Record the Pi version, DS4 version, provider/model, mode, session name, expected result, observed result, and pass/fail status for every scenario.
+
+## Synthetic test data
+
+Use unique non-sensitive values so duplicates from earlier runs cannot hide a failure. Example run label:
+
+```text
+alpha2-run-01
+```
+
+Example Pin:
+
+```text
+For alpha2-run-01 verification, use Node.js 22 in this disposable project.
+```
+
+Example Memory:
+
+```text
+For alpha2-run-01, the synthetic release channel is amber.
+```
+
+Never use real credentials, customer data, private paths, or production policy in dogfooding prompts.
+
+## TUI procedure
+
+Start a persistent interactive session:
+
+```bash
+pi --approve --session-dir "$DS4_DOGFOOD_SESSIONS" \
+  --name "ds4-alpha-tui"
+```
+
+Run these scenarios in order:
+
+1. Inspect `/context health`, `/context pins`, `/context memory`, and `/context privacy`.
+2. Send an ordinary suggestion without asking to persist it, for example: `The synthetic release channel amber seems useful.` No `context_persistence` call or confirmation dialog should appear.
+3. Explicitly request the synthetic Memory: `Remember for this session that the synthetic release channel for alpha2-run-01 is amber.` Verify that the dialog identifies the action and canonical persistence class. Accept it. Expect one committed Memory mutation.
+4. Ask the model to use `context_persistence` to list active Memory. Verify bounded metadata and no complete claim, key, reason, path, or raw error in the result.
+5. Explicitly request the synthetic Pin, but reject or close the confirmation dialog. Verify with `/context pins` that it was not created.
+6. Ask the model to retry using the sanitized value remaining in history. If it copies `[omitted-by-ds4-egress-policy]`, expect `rejected / egress-placeholder` before any new confirmation, runtime mutation, or append. If it asks for fresh text instead, record that safe routing result and run the exact-marker case from the JSON procedure.
+7. Request the Pin again with fresh synthetic text and accept it. Ask the model to list Pins, then use the exact returned Pin ID and `targetRevision` to unpin it in the same process. Accept the destructive confirmation. Fuzzy targeting must not be used.
+8. With a remote provider, request a `local-only` Pin. Expect provider-policy denial before confirmation and no append.
+9. Restart Pi and continue the session:
+
+   ```bash
+   pi --approve --session-dir "$DS4_DOGFOOD_SESSIONS" -c
+   ```
+
+   Verify the accepted Memory remains visible. Revision handles from the previous process are intentionally invalid; perform a fresh read before any targeted write.
+10. Run `/context rebuild-index`, then verify the same canonical Memory/Pin lifecycle state is reconstructed.
+
+TUI passes when accepted writes append once, refusal/closure appends nothing, destructive writes require an exact fresh revision, ordinary conversation does not persist, and rebuild preserves canonical state.
+
+## RPC procedure
+
+RPC mode exposes extension dialogs through a JSON request/response protocol. It reports `ctx.hasUI=true` because a client can answer those requests; the client is the UI bridge.
+
+Start a persistent RPC process from the disposable project:
+
+```bash
+pi --mode rpc --approve \
+  --session-dir "$DS4_DOGFOOD_SESSIONS" \
+  --name "ds4-alpha-rpc" \
+  2>evidence/rpc.stderr.log
+```
+
+Enter one JSON object per line on stdin. First request a read:
+
+```json
+{"id":"read-1","type":"prompt","message":"Use context_persistence with action pins_list to inspect active Pins. Do not perform a write."}
+```
+
+Wait for the turn to end before sending the next prompt. For a write:
+
+```json
+{"id":"write-1","type":"prompt","message":"Persist a session Pin for alpha2-run-01 stating that this disposable project uses Node.js 22 for verification."}
+```
+
+Pi should emit a request shaped like:
+
+```json
+{"type":"extension_ui_request","id":"<dynamic-id>","method":"confirm","title":"DS4 Context Persistence","message":"..."}
+```
+
+After inspecting the request, approve it with the exact dynamic ID:
+
+```json
+{"type":"extension_ui_response","id":"<dynamic-id>","confirmed":true}
+```
+
+Expect the `context_persistence` tool result to report a committed outcome without echoing complete Pin content. Repeat with a different synthetic value and reject it:
+
+```json
+{"type":"extension_ui_response","id":"<dynamic-id>","confirmed":false}
+```
+
+The rejected call must report cancellation and append nothing. `{"cancelled":true}` is also a valid dialog dismissal response.
+
+### RPC without a responding UI client
+
+Start a separate disposable RPC process, request a write, and do not send an `extension_ui_response`. In Pi `0.84.3`, the confirmation remains pending because RPC still advertises UI capability. This is not converted to `confirmation-required`; no append may occur before a positive response. Terminate the disposable process after recording the pending request, then inspect the session from TUI.
+
+### RPC without a persistent session
+
+Start a separate process:
+
+```bash
+pi --mode rpc --approve --no-session
+```
+
+Send a read and a write prompt. Both must return `runtime-unavailable`; no `extension_ui_request` should be emitted and no canonical commit should be claimed.
+
+RPC passes when positive confirmation commits once, negative/cancelled confirmation appends nothing, an unanswered dialog remains pending without append, `--no-session` fails before confirmation, and result content/details remain bounded and metadata-only.
+
+## Print-mode procedure
+
+Print mode has no extension UI. Keep session persistence enabled:
+
+```bash
+pi -p --approve --session-dir "$DS4_DOGFOOD_SESSIONS" \
+  "Use context_persistence with action memory_list to inspect active Memory. Do not write."
+```
+
+The read should complete. Then request a write:
+
+```bash
+pi -p --approve --session-dir "$DS4_DOGFOOD_SESSIONS" \
+  "Use context_persistence to add a session Memory saying that alpha2-run-01 uses the synthetic channel amber."
+```
+
+Expected behavior:
+
+```text
+outcome=unavailable
+errorCode=confirmation-required
+```
+
+No dialog can appear and no canonical custom entry may be appended. The assistant's final wording can vary; use JSON mode or the canonical audit below when the exact tool envelope is needed. If the model does not call the tool, record that separately as a routing observation and repeat with the explicit action name to isolate runtime behavior.
+
+Adding `--no-session` changes the expected error to `runtime-unavailable` for both reads and writes.
+
+## JSON event-stream procedure
+
+JSON mode is also non-interactive, but it exposes authoritative tool lifecycle events. Capture the complete local stream; it may include current non-secret tool arguments.
+
+Read case:
+
+```bash
+pi --mode json --approve --session-dir "$DS4_DOGFOOD_SESSIONS" \
+  "Use context_persistence with action pins_list to inspect active Pins. Do not write." \
+  2>evidence/json-read.stderr.log | tee evidence/json-read.jsonl
+```
+
+Write case:
+
+```bash
+pi --mode json --approve --session-dir "$DS4_DOGFOOD_SESSIONS" \
+  "Use context_persistence to add a session Pin for alpha2-run-01 stating that this disposable project uses Node.js 22." \
+  2>evidence/json-write.stderr.log | tee evidence/json-write.jsonl
+```
+
+Reserved historical-placeholder regression:
+
+```bash
+pi --mode json --approve --session-dir "$DS4_DOGFOOD_SESSIONS" \
+  "Call context_persistence exactly once with action pin_add, scope session, classification normal, and content exactly [omitted-by-ds4-egress-policy]." \
+  2>evidence/json-placeholder.stderr.log | tee evidence/json-placeholder.jsonl
+```
+
+Extract tool completions:
+
+```bash
+jq -c '
+  select(.type == "tool_execution_end" and .toolName == "context_persistence")
+  | {isError, result}
+' evidence/json-*.jsonl
+```
+
+The read should succeed. The ordinary write must return `confirmation-required` and append nothing. The placeholder case must return `rejected / egress-placeholder`, not request confirmation, and append nothing. Inspect `result.content` and `result.details` for bounded allowlisted metadata; they must not echo complete content, claims, keys, reasons, paths, source-session identity, confirmation text, or raw errors.
+
+The local `tool_execution_start.args` event can contain the current synthetic arguments supplied to the tool. That local event is not the provider-facing result contract, which is why dogfooding must use non-sensitive data and evidence files must not be published blindly.
+
+## Canonical append audit
+
+List only metadata for canonical Pin/Memory entries in the dedicated sessions:
+
+```bash
+find "$DS4_DOGFOOD_SESSIONS" -name '*.jsonl' -print0 \
+  | xargs -0 -r jq -r '
+      select(
+        .type == "custom"
+        and (
+          .customType == "ds4-context-pin-v1"
+          or .customType == "ds4-context-memory-v1"
+        )
+      )
+      | [.customType, .id, .timestamp, (.data.operation // "unknown")]
+      | @tsv
+    '
+```
+
+Expected invariants:
+
+- each accepted canonical add/supersede/status operation contributes exactly one append-only custom entry;
+- cancelled, rejected, unavailable, and unanswered-confirmation operations contribute none;
+- print/JSON writes contribute none;
+- `--no-session` contributes none;
+- source include/exclude policy contributes no Pin/Memory custom entry because it is derived local SQLite policy;
+- rebuild changes projections, not the JSONL mutation sequence.
+
+Do not publish the session files: they are canonical local history and may contain prompt/tool argument text even when tool results are metadata-only.
+
+## Extended provider and lifecycle matrix
+
+After the basic mode matrix passes, repeat the relevant TUI/RPC cases with:
+
+- a configured remote provider;
+- a verified local provider whose exact provider ID is listed in `privacy.localProviders`;
+- privacy enabled and disabled;
+- a provider switch between read and targeted write;
+- a branch switch between read and targeted write;
+- trusted and untrusted project state;
+- two simultaneous Pi sessions using the shared SQLite database;
+- cross-session project Memory when `memory.crossSession` is explicitly enabled.
+
+Provider, trust, branch, provenance, capability, target state, and classification changes after confirmation must fail safely. A model-supplied `local-only` classification is never evidence that earlier input stayed local.
+
+## Result record
+
+Use one record per scenario:
+
+```text
+Run ID:
+Date:
+Pi version:
+DS4 exact version:
+Provider/model:
+Mode and session persistence:
+Scenario:
+Expected outcome:
+Observed outcome:
+Confirmation shown/answered:
+Canonical entries before/after:
+Projection/rebuild observation:
+Result leak check:
+Pass/fail:
+Issue/reference:
+```
+
+## Promotion criteria
+
+Do not promote the alpha if any run shows:
+
+- a write without a fresh positive local UI decision;
+- canonical JSONL rewrite, loss, duplication, or a false commit claim;
+- complete persistent content or prohibited metadata in provider-facing results/history;
+- fuzzy destructive targeting or acceptance of a stale revision;
+- failure to reconstruct canonical state from JSONL;
+- an actionable warning hidden as routine debug output;
+- a reproducible regression above the release latency/quality/schema gates.
+
+A missing live local-provider run should remain explicitly recorded rather than inferred from remote-provider or automated-test results.

package/docs/PRIVACY.md

@@ -95,7 +95,7 @@ The local content-addressed object may retain exact restricted bytes because Pi
 
 `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.
+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 the fixed omission sentinel `[omitted-by-ds4-egress-policy]`. That sentinel is output-only and reserved: any incoming `context_persistence` string argument containing it is rejected with `egress-placeholder` before runtime lookup, UI confirmation, canonical append, or derived-policy update. A follow-up call must use fresh user-provided text rather than copying the historical placeholder. 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.
 

package/docs/RELEASING.md

@@ -30,7 +30,7 @@ git diff --check
 git status --short
 ```
 
-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:
+For a 0.2 release candidate or a coordinated 0.3 prerelease, compare feature-disabled planning against exact stable `ds4-context-core@0.1.2` on the same host:
 
 ```bash
 BASELINE_DIR="$(mktemp -d)"
@@ -41,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. 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.
+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, the versioned notes under [`releases/`](releases/) for prerelease evidence, and [`DOGFOODING_0.3.0_ALPHA.md`](DOGFOODING_0.3.0_ALPHA.md) for the post-publication operating matrix.
 
 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.
 
@@ -67,7 +67,7 @@ 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. 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.
+Review `package.json`, both workspace package manifests, and `package-lock.json` before committing the release change. For every coordinated prerelease, all three manifests and both exact adapter dependencies must use precisely the intended version; do not publish only the root package without a separate release-policy decision.
 
 ## Publish
 
@@ -82,7 +82,7 @@ npm publish --workspace ds4-context-reference-adapter --access public
 npm publish --access public
 ```
 
-Prereleases must pass the same explicit channel tag to all three commands so they cannot move `latest`. For `0.3.0-alpha.1`:
+Prereleases must pass the same explicit channel tag to all three commands so they cannot move `latest`. For a 0.3 alpha:
 
 ```bash
 npm publish --workspace ds4-context-core --access public --tag alpha

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

@@ -1,6 +1,6 @@
 # DS4 Context Engine 0.3.0-alpha.1
 
-Status: development prerelease candidate; not published by this change.
+Status: published prerelease on 2026-08-27; tag `v0.3.0-alpha.1`.
 
 This prerelease adds a confirmation-gated, model-callable persistence surface while preserving the stable 0.2 canonical and projection contracts.
 
@@ -39,6 +39,10 @@ The reference adapter remains on its append-only `ds4-runtime-session-v1` histor
 - 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.
 
+## Known alpha.1 limitation
+
+The published alpha.1 historical sanitizer replaces sensitive tool arguments with `[omitted-by-ds4-egress-policy]`. If a model copies that output-only marker into a later write—most plausibly after a cancelled confirmation—alpha.1 can show a new confirmation for the literal marker. Dogfooders must refuse that dialog; accepting it can append the marker as content or metadata, although it does not recover the omitted value. Published `0.3.0-alpha.2` rejects any incoming string argument containing the marker as `egress-placeholder` before confirmation or persistence. The immutable alpha.1 package is not replaced.
+
 ## Package/version policy
 
 The coordinated prerelease version is `0.3.0-alpha.1` for:
@@ -49,7 +53,7 @@ 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.
+Both adapters retain an exact dependency on `ds4-context-core@0.3.0-alpha.1`. The packages were published manually under the explicit npm `alpha` dist-tag, while `latest` continues to resolve to stable `0.2.0`; GitHub Actions remains validation-only with OIDC and package-write permissions denied.
 
 ## Validation evidence
 
@@ -61,6 +65,7 @@ Latest local verification:
 - `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.
+- `npm run registry:check -- 0.3.0-alpha.1`: passed against all three exact published versions; `alpha` resolves to `0.3.0-alpha.1` and `latest` remains `0.2.0` for every package.
 - 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.
 
@@ -71,11 +76,12 @@ Isolated Pi `0.84.3` smoke with the configured `openai-codex` provider passed:
 - 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.
+No live local provider was configured for this smoke; the local-provider privacy path remains covered by automated policy/tool tests. Exact registry verification passed before the annotated tag and GitHub prerelease were created.
 
 ## Documentation
 
 - [`../CONTEXT_PERSISTENCE_TOOL.md`](../CONTEXT_PERSISTENCE_TOOL.md)
+- [`../DOGFOODING_0.3.0_ALPHA.md`](../DOGFOODING_0.3.0_ALPHA.md)
 - [`../MEMORY_AND_PINS.md`](../MEMORY_AND_PINS.md)
 - [`../PRIVACY.md`](../PRIVACY.md)
 - [`../STORAGE.md`](../STORAGE.md)

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

@@ -0,0 +1,62 @@
+# DS4 Context Engine 0.3.0-alpha.2
+
+Status: published prerelease on 2026-08-27; tag `v0.3.0-alpha.2`.
+
+This coordinated prerelease hardens the `context_persistence` provider-egress boundary discovered during alpha.1 dogfooding. It adds no new persistence format, migration, default-on feature, or model-callable action.
+
+## Fixed
+
+- Reserves `[omitted-by-ds4-egress-policy]` as an output-only historical sanitization sentinel.
+- Rejects any incoming string argument containing that sentinel as `egress-placeholder` before runtime access, local confirmation, canonical append, projection, or derived source-policy mutation.
+- Prevents a model from turning a sanitized cancelled-call argument into a new confirmation for the literal omission marker.
+- Centralizes the sentinel constant across the tool contract, historical egress sanitizer, and historical result renderer.
+- Adds a prompt guideline requiring fresh user-provided text instead of reusing an egress omission marker.
+
+## Compatibility and persistence
+
+The tool and result contracts remain `ds4-context-persistence-tool-v1` and `ds4-context-persistence-result-v1`. The fourteen actions and sequential execution contract are unchanged. `egress-placeholder` is an additive validation error code.
+
+Canonical Pin and Memory records remain `ds4-context-pin-v1` and `ds4-context-memory-v1`. Pi JSONL remains canonical and append-only; SQLite remains a disposable projection. Schema 15, migrations 1–15, `ds4-context-config-v1`, `runtime-adapter-v1`, and the reference adapter's append-only `ds4-runtime-session-v1` history contract are unchanged.
+
+## Package/version policy
+
+The coordinated version is `0.3.0-alpha.2` for:
+
+```text
+ds4-context-core
+ds4-context-reference-adapter
+ds4-context-engine
+```
+
+Both adapters depend exactly on `ds4-context-core@0.3.0-alpha.2`. The packages were published manually under the explicit npm `alpha` dist-tag while `latest` remains `0.2.0`. GitHub Actions remains validation-only with OIDC and package-write permissions denied.
+
+## Dogfood evidence
+
+The operator completed the alpha.1 TUI/RPC/print/JSON dogfood matrix, including canonical append audits, with one identified issue: a sanitized historical marker could be copied into a retry. Alpha.2 addresses that finding. Automated unit and extension-integration tests prove the marker retry is rejected before a second confirmation, runtime mutation, projection, or canonical append. The published alpha.2 artifact should receive the focused regression procedure in [`../DOGFOODING_0.3.0_ALPHA.md`](../DOGFOODING_0.3.0_ALPHA.md) before beta promotion.
+
+## Validation evidence
+
+Local candidate verification on Node.js `26.5.1`:
+
+- `npm ci`: passed.
+- `npm run check`: 64 files and 286 tests passed.
+- `npm run quality:compare`: candidate quality `0.9875` versus baseline `0.808156`.
+- `npm run schema:context-persistence`: 1,197 bytes and 300 estimated tokens; below the 1,500 absolute and 320 relative limits.
+- `npm run latency:check -- <exact ds4-context-core@0.1.2>`: after one anomalous noisy sample, three consecutive repetitions passed with ratios `1.051605`, `1.059638`, and `1.087275`, all at or below `1.10`.
+- `npm run pack:check`: verified core (203 files), reference adapter (7 files), and Pi adapter (59 files) in a clean consumer.
+- `npm pack --dry-run --json` for all three packages: passed with the same bounded inventories.
+- The committed candidate was replayed from detached clean checkout `30a5f0f`; `npm ci`, the 64-file/286-test suite, schema gate, package verification, and `git diff --check` passed.
+- `git diff --check`: passed.
+- Protected CI, compatibility golden, Pi fixture, and migration files: unchanged.
+- `npm run registry:check -- 0.3.0-alpha.2`: passed against all three exact published versions; `alpha` resolves to `0.3.0-alpha.2` and `latest` remains `0.2.0` for every package.
+
+Exact registry verification passed before the annotated tag and GitHub prerelease were created.
+
+## Documentation
+
+- [`../CONTEXT_PERSISTENCE_TOOL.md`](../CONTEXT_PERSISTENCE_TOOL.md)
+- [`../DOGFOODING_0.3.0_ALPHA.md`](../DOGFOODING_0.3.0_ALPHA.md)
+- [`../PRIVACY.md`](../PRIVACY.md)
+- [`../MEMORY_AND_PINS.md`](../MEMORY_AND_PINS.md)
+- [`../RELEASING.md`](../RELEASING.md)
+- [`0.3.0-alpha.1.md`](0.3.0-alpha.1.md)

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

@@ -0,0 +1,58 @@
+# DS4 Context Engine 0.3.0-alpha.3
+
+Status: release candidate on 2026-08-30; publication and tag pending.
+
+This coordinated prerelease hardens proactive compaction after investigation of an intermittent `unsupported-exact-value` fallback. It preserves strict exact-value grounding and Pi fallback behavior while making repair failures diagnosable without exposing disputed source text.
+
+## Fixed
+
+- Tells the summary model to verify every complete backticked span verbatim and omit the whole bullet when the span is unsupported.
+- Distinguishes bounded repair outcomes as `unsupported-location`, `too-many-bullets`, `removal-too-large`, and `post-prune-invalid`.
+- Reports only compaction stage, validation issue code, categorical repair status, unsupported-span count, and affected-bullet count.
+- Keeps rejected exact values out of logs, UI notifications, and diagnostics because they may contain sensitive source material.
+- Preserves the existing limit of eight affected bullets, the 25% removal ceiling, strict second validation, and fallback to Pi default compaction.
+
+No verbatim-comparison false positive was reproduced. A remaining unrepaired `unsupported-exact-value` result therefore continues to indicate unsupported prose, exceeded repair bounds, or an invalid post-prune summary rather than being accepted speculatively.
+
+## Compatibility and persistence
+
+The summary contract and canonical compaction storage format are unchanged. Pi JSONL remains canonical and append-only; an invalid DS4 summary is never installed. SQLite remains a disposable projection. Schema 15, migrations 1–15, `ds4-context-config-v1`, `runtime-adapter-v1`, `ds4-context-persistence-tool-v1`, and `ds4-context-persistence-result-v1` are unchanged.
+
+The change adds metadata-only diagnostic categories and no model-callable action, persistence mutation, default-on feature, or weaker validation path.
+
+## Package/version policy
+
+The coordinated version is `0.3.0-alpha.3` for:
+
+```text
+ds4-context-core
+ds4-context-reference-adapter
+ds4-context-engine
+```
+
+Both adapters depend exactly on `ds4-context-core@0.3.0-alpha.3`. Publication uses the explicit npm `alpha` dist-tag so `latest` remains `0.2.0`. GitHub Actions remains validation-only with OIDC and package-write permissions denied.
+
+## Validation evidence
+
+Local candidate verification on Node.js `26.5.1`:
+
+- `npm ci`: passed.
+- `npm run check`: 64 files and 288 tests passed.
+- Focused compaction coverage: prompt grounding, bounded repair categories, second validation, privacy-safe diagnostics, and Pi fallback passed.
+- `npm run quality:compare`: candidate quality `0.9875` versus baseline `0.808156`.
+- `npm run schema:context-persistence`: 1,197 bytes and 300 estimated tokens; below the 1,500 absolute and 320 relative limits.
+- `npm run latency:check -- <exact ds4-context-core@0.1.2>`: passed with ratio `1.052586`, at or below `1.10`.
+- `npm run pack:check`: verified core (203 files), reference adapter (7 files), and Pi adapter (60 files) in a clean consumer.
+- `npm pack --dry-run --json` for all three packages: passed with the same bounded inventories.
+- The committed candidate was replayed from detached clean checkout `3e7bb32`; `npm ci`, the 64-file/288-test suite, quality, schema, package verification, and `git diff --check` passed.
+- `git diff --check`: passed.
+- Protected CI, compatibility golden, Pi fixture, migration, canonical Pin/Memory, and persistence-tool contract files: unchanged.
+
+Exact registry verification, annotated tag creation, and GitHub prerelease creation remain pending until all three packages are published.
+
+## Documentation
+
+- [`../COMPACTION.md`](../COMPACTION.md)
+- [`../PRIVACY.md`](../PRIVACY.md)
+- [`../RELEASING.md`](../RELEASING.md)
+- [`0.3.0-alpha.2.md`](0.3.0-alpha.2.md)

package/package.json

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

package/src/extension/context-persistence-contract.ts

@@ -2,12 +2,14 @@ import { StringEnum, Type, type Static } from "@earendil-works/pi-ai";
 
 export const CONTEXT_PERSISTENCE_TOOL_CONTRACT = "ds4-context-persistence-tool-v1" as const;
 export const CONTEXT_PERSISTENCE_RESULT_CONTRACT = "ds4-context-persistence-result-v1" as const;
+export const CONTEXT_PERSISTENCE_EGRESS_SENTINEL = "[omitted-by-ds4-egress-policy]" as const;
 export const CONTEXT_PERSISTENCE_TOOL_NAME = "context_persistence" as const;
 export const CONTEXT_PERSISTENCE_DESCRIPTION = "Inspect DS4 Pins/Memory. Write only after an explicit user request; writes require local user confirmation." as const;
 export const CONTEXT_PERSISTENCE_PROMPT_SNIPPET = "Inspect or manage user-confirmed DS4 pins and durable memory" as const;
 export const CONTEXT_PERSISTENCE_PROMPT_GUIDELINES = [
   "Use context_persistence only to inspect DS4 persistent state or when the user explicitly requests a persistence mutation.",
   "After an explicit persistence request, call the write action directly; context_persistence itself obtains the required local UI confirmation, so do not ask for separate confirmation in chat.",
+  "Never reuse an egress omission marker as tool input; use fresh user-provided text or ask the user to restate it.",
   "Never create a pin or memory merely because information appears useful.",
   "Use pins for confirmed constraints or instructions that must remain prominent. Use memory for durable facts, decisions, and historical knowledge.",
   "Default new persistence to session scope. Use project or branch scope only when explicitly requested or unambiguous; durable Memory does not support branch scope.",
@@ -112,7 +114,8 @@ const REQUIRED_FIELDS = {
 
 export type ContextPersistenceValidationCode =
   | "invalid-parameters"
-  | "invalid-scope";
+  | "invalid-scope"
+  | "egress-placeholder";
 
 export type ContextPersistenceValidation =
   | { ok: true; value: ContextPersistenceParams }
@@ -143,6 +146,12 @@ export function validateContextPersistenceParams(
   if (REQUIRED_FIELDS[params.action].some((key) => params[key] === undefined)) {
     return { ok: false, errorCode: "invalid-parameters" };
   }
+  if (keys.some((key) => {
+    const value = params[key];
+    return typeof value === "string" && value.includes(CONTEXT_PERSISTENCE_EGRESS_SENTINEL);
+  })) {
+    return { ok: false, errorCode: "egress-placeholder" };
+  }
   if (params.scope === "branch" && params.action === "memory_add") {
     return { ok: false, errorCode: "invalid-scope" };
   }

package/src/extension/context-persistence-egress.ts

@@ -1,5 +1,6 @@
 import {
   CONTEXT_PERSISTENCE_ACTIONS,
+  CONTEXT_PERSISTENCE_EGRESS_SENTINEL,
   CONTEXT_PERSISTENCE_TOOL_NAME,
 } from "./context-persistence-contract.ts";
 import {
@@ -7,7 +8,7 @@ import {
   sanitizeHistoricalContextPersistenceDetails,
 } from "./context-persistence-result.ts";
 
-export const CONTEXT_PERSISTENCE_EGRESS_SENTINEL = "[omitted-by-ds4-egress-policy]" as const;
+export { CONTEXT_PERSISTENCE_EGRESS_SENTINEL } from "./context-persistence-contract.ts";
 
 const ACTIONS = new Set<string>(CONTEXT_PERSISTENCE_ACTIONS);
 const SAFE_ARGUMENT_KEYS = new Set([

package/src/extension/context-persistence-result.ts

@@ -2,6 +2,7 @@ import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
 import type { PrivacyClassification } from "ds4-context-core/privacy/privacy-policy";
 import {
   CONTEXT_PERSISTENCE_ACTIONS,
+  CONTEXT_PERSISTENCE_EGRESS_SENTINEL,
   CONTEXT_PERSISTENCE_RESULT_CONTRACT,
   type ContextPersistenceAction,
   type ContextPersistenceReadAction,
@@ -434,7 +435,7 @@ export function sanitizeHistoricalContextPersistenceDetails(
 
 /** Historical provider replay never includes previews, even when the original result did. */
 export function renderHistoricalContextPersistenceResult(details: ContextPersistenceDetails | undefined): string {
-  if (!details) return "[omitted-by-ds4-egress-policy]";
+  if (!details) return CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
   if (details.items && typeof details.count === "number") {
     return renderReadContent({
       action: details.action as ContextPersistenceReadAction,

package/src/pi-adapter/summary-generator.ts

@@ -5,8 +5,8 @@ import type {
   SessionBeforeCompactEvent,
 } from "@earendil-works/pi-coding-agent";
 import {
+  analyzeUnsupportedExactValueBullets,
   groundSummaryFileSections,
-  pruneUnsupportedExactValueBullets,
   validateSummary,
   type SummaryValidationInput,
   type SummaryValidationResult,
@@ -102,13 +102,16 @@ export async function generateValidatedSummary(
           message: "Deterministic validation disabled by configuration",
         }],
       };
+  let exactRepair: ReturnType<typeof analyzeUnsupportedExactValueBullets> | undefined;
+  let exactRepairFailure: "post-prune-invalid" | undefined;
   if (validation.status === "invalid") {
     const errors = validation.issues.filter((issue) => issue.severity === "error");
     const exactOnly = errors.length > 0
       && errors.every((issue) => issue.code === "unsupported-exact-value");
-    const pruned = exactOnly
-      ? pruneUnsupportedExactValueBullets(content, validationInput)
+    exactRepair = exactOnly
+      ? analyzeUnsupportedExactValueBullets(content, validationInput)
       : undefined;
+    const pruned = exactRepair?.result;
     if (pruned) {
       const repairedValidation = validateSummary(pruned.content, validationInput);
       if (repairedValidation.status !== "invalid") {
@@ -124,12 +127,18 @@ export async function generateValidatedSummary(
             },
           ],
         };
+      } else {
+        validation = repairedValidation;
+        exactRepairFailure = "post-prune-invalid";
       }
     }
   }
   if (validation.status === "invalid") {
     const codes = unique(validation.issues.map((issue) => issue.code)).join(", ");
-    throw new Error(`Compaction ${input.stage} summary validation failed: ${codes}`);
+    const repairDiagnostics = exactRepair
+      ? `; repair=${exactRepairFailure ?? exactRepair.status}; unsupportedSpans=${exactRepair.unsupportedSpans}; affectedBullets=${exactRepair.affectedBullets}`
+      : "";
+    throw new Error(`Compaction ${input.stage} summary validation failed: ${codes}${repairDiagnostics}`);
   }
   return { content, validation, usage: response.usage };
 }

package/src/pi-adapter/version.ts

@@ -1,4 +1,4 @@
-export const EXTENSION_VERSION = "0.3.0-alpha.1";
+export const EXTENSION_VERSION = "0.3.0-alpha.3";
 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";