ds4-context-engine 0.3.0-alpha.2 → 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. 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 `latest` remains `0.2.0`; 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
 

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/releases/0.3.0-alpha.1.md

@@ -41,7 +41,7 @@ The reference adapter remains on its append-only `ds4-runtime-session-v1` histor
 
 ## 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. Current source rejects any incoming string argument containing the marker as `egress-placeholder` before confirmation or persistence. Publishing that hardening requires a new prerelease version; the immutable alpha.1 package is not replaced.
+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
 

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

@@ -1,6 +1,6 @@
 # DS4 Context Engine 0.3.0-alpha.2
 
-Status: release candidate approved for manual publication.
+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.
 
@@ -28,7 +28,7 @@ ds4-context-reference-adapter
 ds4-context-engine
 ```
 
-Both adapters depend exactly on `ds4-context-core@0.3.0-alpha.2`. Publication uses the explicit npm `alpha` dist-tag; `latest` must remain `0.2.0`. GitHub Actions remains validation-only with OIDC and package-write permissions denied.
+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
 
@@ -48,8 +48,9 @@ Local candidate verification on Node.js `26.5.1`:
 - 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, annotated tag, and GitHub prerelease creation remain post-publication gates.
+Exact registry verification passed before the annotated tag and GitHub prerelease were created.
 
 ## Documentation
 

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.2",
+  "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.2"
+    "ds4-context-core": "0.3.0-alpha.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "0.84.3",

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.2";
+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";