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

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. 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`.
+> **Project status:** Stable `0.2.0` includes M0–M20 and frozen 0.2 contracts. Published prerelease `0.3.0-alpha.3` adds privacy-safe exact-value repair diagnostics and tighter summary prompting while preserving strict compaction validation, Pi fallback, canonical records, SQLite schema 15, and runtime contracts. npm `alpha` points to `0.3.0-alpha.3`, `latest` remains `0.2.0`, and the maintenance line targets Pi `0.84.3`.
 
 ## Why DS4
 
@@ -92,7 +92,7 @@ The stable `0.2.0` packages (`ds4-context-engine`, `ds4-context-core`, and `ds4-
 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
+pi install -l npm:ds4-context-engine@0.3.0-alpha.3
 ```
 
 Follow the [0.3 alpha dogfooding runbook](docs/DOGFOODING_0.3.0_ALPHA.md); use synthetic data and a dedicated session directory.
@@ -416,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.2
+npm run registry:check -- 0.3.0-alpha.3
 npm pack --dry-run
 npm pack --dry-run --workspace ds4-context-core
 npm pack --dry-run --workspace ds4-context-reference-adapter
@@ -468,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.3 prerelease notes](docs/releases/0.3.0-alpha.3.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)
@@ -477,7 +478,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. 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.
+The [0.2.0 roadmap](docs/ROADMAP_0.2.0.md) is complete. Prerelease `0.3.0-alpha.3` retains the confirmed [context persistence tool](docs/CONTEXT_PERSISTENCE_TOOL.md) hardening from alpha.2 and adds privacy-safe [compaction](docs/COMPACTION.md) repair diagnostics without weakening exact-value grounding or Pi fallback. Stable canonical/configuration/SQLite/runtime contracts remain unchanged. 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

@@ -76,4 +76,4 @@ It requests compaction at most once per session leaf. Pi's native threshold and
 /context summaries
 ```
 
-The preview reports thresholds and eligibility; Pi remains authoritative for the exact cut point.
+The preview reports thresholds and eligibility; Pi remains authoritative for the exact cut point. Routine `summary_graph_prepared` and `summary_graph_committed` lifecycle events are emitted only at `debug`; fallback, failure, persistence, and reconciliation problems remain actionable warnings. The proactive-threshold TUI notification remains a user-visible `info` notice because it explains why an automatic compaction started.

package/docs/CONTEXT_PERSISTENCE_TOOL.md

@@ -19,22 +19,24 @@ Memory is quoted durable factual, decision, or historical data. It supports `ses
 
 ## 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 |
+| Action | Class | Parameters | Purpose |
+| --- | --- | --- | --- |
+| `pins_list` | read | optional `activeOnly`, `maxResults` | List visible Pins with metadata and revisions |
+| `pins_find` | read | `query`; optional `activeOnly`, `maxResults` | Bounded Pin search with sanitized previews |
+| `pin_add` | canonical write | `content`; optional `scope`, `classification` | Append a new Pin |
+| `pin_supersede` | canonical write | `id`, `targetRevision`, `content`; optional `classification` | Replace one exact active Pin immutably |
+| `pin_unpin` | canonical write | `id`, `targetRevision`; optional `reason` | Append a deleted lifecycle status |
+| `memory_list` | read | optional `activeOnly`, `maxResults` | List visible Memory with metadata and revisions |
+| `memory_find` | read | `query`; optional `activeOnly`, `maxResults` | Bounded Memory search with sanitized previews |
+| `memory_add` | canonical write | `content`; optional `scope`, `key`, `classification` | Append session/project Memory |
+| `memory_supersede` | canonical write | `id`, `targetRevision`, `content`; optional `classification` | Replace one exact active Memory item immutably |
+| `memory_invalidate` | canonical write | `id`, `targetRevision`; optional `reason` | Append an invalid lifecycle status |
+| `memory_expire` | canonical write | `id`, `targetRevision`; optional `reason` | Append an expired lifecycle status |
+| `memory_sources` | read | optional `maxResults` | List cross-session sources through volatile references |
+| `memory_source_exclude` | derived write | `id`, `targetRevision`; optional `reason` | Exclude one source in local SQLite policy |
+| `memory_source_include` | derived write | `id`, `targetRevision` | Restore one source in local SQLite policy |
+
+The transport schema stays flat for compatibility across supported providers, but DS4 applies the parameter matrix above before runtime access. A known action with an inapplicable field returns `unsupported-parameter`; a known action missing an action-required field returns `missing-required-parameter`. These diagnostics never identify or echo fields or values. Malformed transport input retains the generic `invalid-parameters` category. The output-only egress sentinel is checked before action-specific categorization so it remains `egress-placeholder` even when supplied in an inapplicable field.
 
 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.
 

package/docs/DOGFOODING_0.3.0_ALPHA.md

@@ -1,6 +1,6 @@
 # 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.
+This runbook validates the published `ds4-context-engine@0.3.0-alpha.3` 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.
 
@@ -9,7 +9,8 @@ The primary target is the model-callable `context_persistence` surface. Pi JSONL
 - 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.
+- 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 and later reserve that output-only marker and must reject it as `egress-placeholder` before runtime access, confirmation, canonical append, or derived-policy update.
+- Alpha.3 keeps exact-value summary validation strict. An unrepaired failure may expose only its stage, issue code, repair category, and counts; disputed exact text must not appear in diagnostics.
 - 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.
@@ -26,7 +27,7 @@ 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 install -l npm:ds4-context-engine@0.3.0-alpha.3
 pi list
 pi --version
 ```

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

@@ -1,6 +1,6 @@
 # DS4 Context Engine 0.3.0-alpha.3
 
-Status: release candidate on 2026-08-30; publication and tag pending.
+Status: published prerelease on 2026-08-30; tag `v0.3.0-alpha.3`.
 
 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.
 
@@ -30,7 +30,7 @@ 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.
+Both adapters depend exactly on `ds4-context-core@0.3.0-alpha.3`. 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.
 
 ## Validation evidence
 
@@ -48,7 +48,9 @@ Local candidate verification on Node.js `26.5.1`:
 - `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.
+- `npm run registry:check -- 0.3.0-alpha.3`: passed against all three exact published versions; `alpha` resolves to `0.3.0-alpha.3` and `latest` remains `0.2.0` for every package.
+
+Exact registry verification passed before the annotated tag and GitHub prerelease were created.
 
 ## Documentation
 

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

@@ -0,0 +1,59 @@
+# DS4 Context Engine 0.3.0-alpha.4
+
+Status: validated release candidate; not yet published.
+
+This coordinated prerelease improves model-callable `context_persistence` guidance and categorical validation diagnostics, and removes routine successful compaction lifecycle events from normal `info` output. It preserves strict persistence confirmation, canonical Pi JSONL semantics, privacy-safe egress, compaction validation, and Pi fallback behavior.
+
+## Fixed
+
+- Describes the valid parameter set for every `context_persistence` action in the tool guidance and public action matrix.
+- Distinguishes a known action with an inapplicable field as `unsupported-parameter` and a missing action-required field as `missing-required-parameter`.
+- Keeps validation failures categorical: rejected field names and values are absent from current results, sanitized history, diagnostics, and logs.
+- Continues to reject the output-only egress sentinel before action-specific validation, including when it appears in an otherwise inapplicable field.
+- Emits routine `compaction.summary_graph_prepared` and `compaction.summary_graph_committed` lifecycle events only at `debug` instead of the default `info` level.
+- Preserves actionable compaction fallback, failure, persistence, and reconciliation events at `warn`; the proactive-threshold TUI notice remains user-visible because it explains why automatic compaction started.
+
+## Compatibility and persistence
+
+The flat tool schema, fourteen actions, `ds4-context-persistence-tool-v1`, and `ds4-context-persistence-result-v1` identifiers are unchanged. The new validation categories are metadata-only and do not add a write path or alter confirmation requirements.
+
+Pi JSONL remains canonical and append-only. All model-callable writes still require fresh local UI confirmation and fail closed without UI or canonical persistence. SQLite remains a disposable projection. Schema 15, migrations 1–15, `ds4-context-config-v1`, and `runtime-adapter-v1` are unchanged. Strict compaction validation and fallback to Pi default compaction are unchanged.
+
+## Package/version policy
+
+The coordinated version is `0.3.0-alpha.4` for:
+
+```text
+ds4-context-core
+ds4-context-reference-adapter
+ds4-context-engine
+```
+
+Both adapters depend exactly on `ds4-context-core@0.3.0-alpha.4`. Publication must use 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 290 tests passed.
+- Focused persistence coverage: action-field guidance, unsupported/missing parameter categories, egress-sentinel priority, metadata-only failures, and sanitized historical diagnostics passed.
+- Focused compaction coverage: successful lifecycle events are absent at `info`, present at `debug`, and fallback remains `warn`.
+- `npm run quality:compare`: candidate quality `0.9875` versus baseline `0.808156`.
+- `npm run schema:context-persistence`: 1,266 bytes and 317 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 `0.923285`, at or below `1.10`.
+- `npm run pack:check`: verified core (203 files), reference adapter (7 files), and Pi adapter (61 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 `6fcf514`; `npm ci`, the 64-file/290-test suite, quality, schema, package verification, tarball review, and `git diff --check` passed.
+- `git diff --check`: passed.
+- Protected CI, compatibility golden, Pi fixture, migration, canonical Pin/Memory, and persistence result-contract files: unchanged.
+
+Clean committed-candidate replay and exact registry verification are required before tag or GitHub prerelease creation.
+
+## Documentation
+
+- [`../CONTEXT_PERSISTENCE_TOOL.md`](../CONTEXT_PERSISTENCE_TOOL.md)
+- [`../COMPACTION.md`](../COMPACTION.md)
+- [`../PRIVACY.md`](../PRIVACY.md)
+- [`../RELEASING.md`](../RELEASING.md)
+- [`0.3.0-alpha.3.md`](0.3.0-alpha.3.md)

package/package.json

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

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

@@ -4,12 +4,13 @@ export const CONTEXT_PERSISTENCE_TOOL_CONTRACT = "ds4-context-persistence-tool-v
 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_DESCRIPTION = "Inspect DS4 Pins/Memory. Use action fields only. Writes require explicit user request and local UI 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.",
+  "Send only fields valid for the selected action: find requires query; add requires content; supersede requires id, targetRevision, and content; lifecycle and source-policy changes require id and targetRevision.",
   "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.",
@@ -58,9 +59,17 @@ export const CONTEXT_PERSISTENCE_PARAMS = Type.Object({
   })),
   id: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
   targetRevision: Type.Optional(Type.String({ minLength: 1, maxLength: 64 })),
-  content: Type.Optional(Type.String({ minLength: 1, maxLength: 20_000 })),
+  content: Type.Optional(Type.String({
+    minLength: 1,
+    maxLength: 20_000,
+    description: "Add/replace only",
+  })),
   key: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
-  query: Type.Optional(Type.String({ minLength: 2, maxLength: 200 })),
+  query: Type.Optional(Type.String({
+    minLength: 2,
+    maxLength: 200,
+    description: "Find; required",
+  })),
   reason: Type.Optional(Type.String({
     minLength: 1,
     maxLength: 500,
@@ -114,6 +123,8 @@ const REQUIRED_FIELDS = {
 
 export type ContextPersistenceValidationCode =
   | "invalid-parameters"
+  | "missing-required-parameter"
+  | "unsupported-parameter"
   | "invalid-scope"
   | "egress-placeholder";
 
@@ -139,19 +150,19 @@ export function validateContextPersistenceParams(
 ): ContextPersistenceValidation {
   if (!params || !isAction(params.action)) return { ok: false, errorCode: "invalid-parameters" };
   const keys = Object.keys(params) as (keyof ContextPersistenceParams)[];
-  const allowed = new Set<keyof ContextPersistenceParams>(ALLOWED_FIELDS[params.action]);
-  if (keys.some((key) => !allowed.has(key))) {
-    return { ok: false, errorCode: "invalid-parameters" };
-  }
-  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" };
   }
+  const allowed = new Set<keyof ContextPersistenceParams>(ALLOWED_FIELDS[params.action]);
+  if (keys.some((key) => !allowed.has(key))) {
+    return { ok: false, errorCode: "unsupported-parameter" };
+  }
+  if (REQUIRED_FIELDS[params.action].some((key) => params[key] === undefined)) {
+    return { ok: false, errorCode: "missing-required-parameter" };
+  }
   if (params.scope === "branch" && params.action === "memory_add") {
     return { ok: false, errorCode: "invalid-scope" };
   }

package/src/pi-adapter/compaction-coordinator.ts

@@ -360,7 +360,7 @@ export class CompactionCoordinator {
         tokensBefore: event.preparation.tokensBefore,
         requestedAt,
       };
-      this.dependencies.logger.info("compaction.summary_graph_prepared", {
+      this.dependencies.logger.debug("compaction.summary_graph_prepared", {
         activeSummaryId: activeNode.id,
         segmentSummaryId: segmentId,
         graphLevel: activeNode.graphLevel,
@@ -460,7 +460,7 @@ export class CompactionCoordinator {
       requestedAt: metadata.generatedAt,
       completedAt: this.dependencies.now(),
     };
-    this.dependencies.logger.info("compaction.summary_graph_committed", {
+    this.dependencies.logger.debug("compaction.summary_graph_committed", {
       activeSummaryId: metadata.summaryId,
       segmentSummaryId: metadata.segmentSummaryId,
       graphLevel: metadata.graphLevel,

package/src/pi-adapter/version.ts

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