ds4-context-engine 0.2.0 → 0.3.0-alpha.2

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 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)"
@@ -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, 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.
 
@@ -65,13 +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 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
 
 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:
+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
@@ -80,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 a 0.3 alpha:
+
+```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/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.3.0-alpha.1.md

@@ -0,0 +1,89 @@
+# DS4 Context Engine 0.3.0-alpha.1
+
+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.
+
+## 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.
+
+## 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.
+
+## 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`. 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
+
+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.
+- `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.
+
+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 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)
+- [`../ARCHITECTURE.md`](../ARCHITECTURE.md)
+- [`../RELEASING.md`](../RELEASING.md)

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

@@ -0,0 +1,61 @@
+# DS4 Context Engine 0.3.0-alpha.2
+
+Status: release candidate approved for manual publication.
+
+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`. 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.
+
+## 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.
+
+Exact registry verification, annotated tag, and GitHub prerelease creation remain post-publication gates.
+
+## 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/package.json

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

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

@@ -0,0 +1,159 @@
+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.",
+  "Before superseding, removing, invalidating, expiring, excluding, or including, read first and use the exact ID or reference plus targetRevision; never mutate from a fuzzy query.",
+  "Do not claim local-only protection if a remote model already saw the input; use /context or a local provider for data that must never reach a remote provider.",
+] as const;
+
+export const CONTEXT_PERSISTENCE_ACTIONS = [
+  "pins_list",
+  "pins_find",
+  "pin_add",
+  "pin_supersede",
+  "pin_unpin",
+  "memory_list",
+  "memory_find",
+  "memory_add",
+  "memory_supersede",
+  "memory_invalidate",
+  "memory_expire",
+  "memory_sources",
+  "memory_source_exclude",
+  "memory_source_include",
+] as const;
+
+export type ContextPersistenceAction = typeof CONTEXT_PERSISTENCE_ACTIONS[number];
+
+export const CONTEXT_PERSISTENCE_READ_ACTIONS = [
+  "pins_list",
+  "pins_find",
+  "memory_list",
+  "memory_find",
+  "memory_sources",
+] as const satisfies readonly ContextPersistenceAction[];
+
+export type ContextPersistenceReadAction = typeof CONTEXT_PERSISTENCE_READ_ACTIONS[number];
+
+export const CONTEXT_PERSISTENCE_WRITE_ACTIONS = CONTEXT_PERSISTENCE_ACTIONS.filter(
+  (action): action is Exclude<ContextPersistenceAction, ContextPersistenceReadAction> =>
+    !(CONTEXT_PERSISTENCE_READ_ACTIONS as readonly string[]).includes(action),
+);
+
+export const CONTEXT_PERSISTENCE_PARAMS = Type.Object({
+  action: StringEnum(CONTEXT_PERSISTENCE_ACTIONS),
+  scope: Type.Optional(StringEnum(["session", "branch", "project"] as const, {
+    description: "Add only; Memory excludes branch",
+  })),
+  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 })),
+  key: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+  query: Type.Optional(Type.String({ minLength: 2, maxLength: 200 })),
+  reason: Type.Optional(Type.String({
+    minLength: 1,
+    maxLength: 500,
+    description: "Lifecycle or source exclusion only",
+  })),
+  classification: Type.Optional(StringEnum([
+    "normal",
+    "internal",
+    "sensitive",
+    "local-only",
+  ] as const)),
+  activeOnly: Type.Optional(Type.Boolean()),
+  maxResults: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+}, { additionalProperties: false });
+
+export type ContextPersistenceParams = Static<typeof CONTEXT_PERSISTENCE_PARAMS>;
+
+const ALLOWED_FIELDS = {
+  pins_list: ["action", "activeOnly", "maxResults"],
+  pins_find: ["action", "query", "activeOnly", "maxResults"],
+  pin_add: ["action", "content", "scope", "classification"],
+  pin_supersede: ["action", "id", "targetRevision", "content", "classification"],
+  pin_unpin: ["action", "id", "targetRevision", "reason"],
+  memory_list: ["action", "activeOnly", "maxResults"],
+  memory_find: ["action", "query", "activeOnly", "maxResults"],
+  memory_add: ["action", "content", "scope", "key", "classification"],
+  memory_supersede: ["action", "id", "targetRevision", "content", "classification"],
+  memory_invalidate: ["action", "id", "targetRevision", "reason"],
+  memory_expire: ["action", "id", "targetRevision", "reason"],
+  memory_sources: ["action", "maxResults"],
+  memory_source_exclude: ["action", "id", "targetRevision", "reason"],
+  memory_source_include: ["action", "id", "targetRevision"],
+} as const satisfies Record<ContextPersistenceAction, readonly (keyof ContextPersistenceParams)[]>;
+
+const REQUIRED_FIELDS = {
+  pins_list: [],
+  pins_find: ["query"],
+  pin_add: ["content"],
+  pin_supersede: ["id", "targetRevision", "content"],
+  pin_unpin: ["id", "targetRevision"],
+  memory_list: [],
+  memory_find: ["query"],
+  memory_add: ["content"],
+  memory_supersede: ["id", "targetRevision", "content"],
+  memory_invalidate: ["id", "targetRevision"],
+  memory_expire: ["id", "targetRevision"],
+  memory_sources: [],
+  memory_source_exclude: ["id", "targetRevision"],
+  memory_source_include: ["id", "targetRevision"],
+} as const satisfies Record<ContextPersistenceAction, readonly (keyof ContextPersistenceParams)[]>;
+
+export type ContextPersistenceValidationCode =
+  | "invalid-parameters"
+  | "invalid-scope"
+  | "egress-placeholder";
+
+export type ContextPersistenceValidation =
+  | { ok: true; value: ContextPersistenceParams }
+  | { ok: false; errorCode: ContextPersistenceValidationCode };
+
+function isAction(value: unknown): value is ContextPersistenceAction {
+  return typeof value === "string"
+    && (CONTEXT_PERSISTENCE_ACTIONS as readonly string[]).includes(value);
+}
+
+export function isReadAction(action: ContextPersistenceAction): action is ContextPersistenceReadAction {
+  return (CONTEXT_PERSISTENCE_READ_ACTIONS as readonly string[]).includes(action);
+}
+
+/**
+ * Action-specific validation performed after TypeBox transport validation.
+ * Values are never included in failures so provider-visible errors stay metadata-only.
+ */
+export function validateContextPersistenceParams(
+  params: ContextPersistenceParams,
+): 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" };
+  }
+  if (params.scope === "branch" && params.action === "memory_add") {
+    return { ok: false, errorCode: "invalid-scope" };
+  }
+  return { ok: true, value: params };
+}

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

@@ -0,0 +1,224 @@
+import {
+  CONTEXT_PERSISTENCE_ACTIONS,
+  CONTEXT_PERSISTENCE_EGRESS_SENTINEL,
+  CONTEXT_PERSISTENCE_TOOL_NAME,
+} from "./context-persistence-contract.ts";
+import {
+  renderHistoricalContextPersistenceResult,
+  sanitizeHistoricalContextPersistenceDetails,
+} from "./context-persistence-result.ts";
+
+export { CONTEXT_PERSISTENCE_EGRESS_SENTINEL } from "./context-persistence-contract.ts";
+
+const ACTIONS = new Set<string>(CONTEXT_PERSISTENCE_ACTIONS);
+const SAFE_ARGUMENT_KEYS = new Set([
+  "action",
+  "scope",
+  "id",
+  "targetRevision",
+  "classification",
+  "activeOnly",
+  "maxResults",
+]);
+const SENSITIVE_ARGUMENT_KEYS = new Set(["content", "query", "key", "reason"]);
+const OPAQUE_ID = /^(?:source_[A-Za-z0-9_-]{22,57}|[A-Za-z0-9._:-]{1,128})$/u;
+const REVISION = /^rev_[A-Za-z0-9_-]{1,60}$/u;
+const SAFE_ENUM = /^(?:session|branch|project|normal|internal|sensitive|local-only)$/u;
+const SAFE_METADATA_LINE = /^(?:pin|memory|project-memory-source) (?:source_[A-Za-z0-9_-]{22,57}|[A-Za-z0-9._:-]{1,128})(?:; (?:scope|status|classification|applicable|createdAt|updatedAt|revision|match|score|indexedMutations|activeProjectMemories|activeProjectPins|hasMalformedLines|error)=[A-Za-z0-9_-]+)+$/u;
+const SAFE_SUMMARY_LINE = /^(?:pins_list|pins_find|memory_list|memory_find|memory_sources): \d{1,3} (?:item\(s\)|match\(es\)); truncated=(?:true|false); incomplete=(?:true|false)\.$/u;
+const PREVIEW_LINE = /^(pin|memory) ([\x21-\x7e]{1,128}): /u;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function safeArgumentValue(key: string, value: unknown): unknown {
+  if (key === "action") return typeof value === "string" && ACTIONS.has(value)
+    ? value
+    : CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  if (key === "activeOnly") return typeof value === "boolean"
+    ? value
+    : CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  if (key === "maxResults") return Number.isInteger(value) && Number(value) >= 1 && Number(value) <= 100
+    ? value
+    : CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  if (key === "scope" || key === "classification") {
+    return typeof value === "string" && SAFE_ENUM.test(value)
+      ? value
+      : CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  }
+  if (key === "id") {
+    return typeof value === "string" && OPAQUE_ID.test(value)
+      ? value
+      : CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  }
+  if (key === "targetRevision") {
+    return typeof value === "string" && REVISION.test(value)
+      ? value
+      : CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  }
+  return CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+}
+
+/** Arguments are reduced without retaining raw content in temporary result objects. */
+export function sanitizeHistoricalContextPersistenceArguments(value: unknown): Record<string, unknown> {
+  if (!isRecord(value)) return {};
+  const sanitized: Record<string, unknown> = {};
+  for (const [key, candidate] of Object.entries(value)) {
+    if (SAFE_ARGUMENT_KEYS.has(key)) sanitized[key] = safeArgumentValue(key, candidate);
+    else if (SENSITIVE_ARGUMENT_KEYS.has(key)) sanitized[key] = CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+    else sanitized[key] = CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  }
+  return sanitized;
+}
+
+function sanitizeArgumentContainer(value: unknown): unknown {
+  if (typeof value === "string") {
+    try {
+      return JSON.stringify(sanitizeHistoricalContextPersistenceArguments(JSON.parse(value)));
+    } catch {
+      return JSON.stringify({ omitted: CONTEXT_PERSISTENCE_EGRESS_SENTINEL });
+    }
+  }
+  return sanitizeHistoricalContextPersistenceArguments(value);
+}
+
+/** Preserves only the fixed metadata grammar emitted by the V1 result renderer. */
+export function sanitizeHistoricalContextPersistenceText(value: unknown): string {
+  if (typeof value !== "string" || value.length > 96 * 1024) return CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+  const output: string[] = [];
+  for (const line of value.split("\n").slice(0, 205)) {
+    if (SAFE_SUMMARY_LINE.test(line)
+      || SAFE_METADATA_LINE.test(line)
+      || line === "Search incomplete; refine the query or use an exact opaque ID.") {
+      output.push(line);
+      continue;
+    }
+    const preview = PREVIEW_LINE.exec(line);
+    if (preview) {
+      output.push(`${preview[1]} ${preview[2]}: preview omitted by policy`);
+      continue;
+    }
+    if (/^(?:pins_|pin_|memory_)[a-z_]+ (?:ok|rejected|cancelled|unavailable|committed|committed_projection_pending|indeterminate)(?:: [a-z0-9-]{1,64})?\.$/u.test(line)) {
+      output.push(line);
+      continue;
+    }
+    output.push(CONTEXT_PERSISTENCE_EGRESS_SENTINEL);
+  }
+  return output.join("\n") || CONTEXT_PERSISTENCE_EGRESS_SENTINEL;
+}
+
+function toolName(record: Record<string, unknown>): string | undefined {
+  if (typeof record.name === "string") return record.name;
+  if (typeof record.toolName === "string") return record.toolName;
+  return undefined;
+}
+
+function identifiers(record: Record<string, unknown>): string[] {
+  return [
+    record.id,
+    record.call_id,
+    record.toolCallId,
+    record.tool_call_id,
+    record.toolUseId,
+    record.tool_use_id,
+  ].filter((value): value is string => typeof value === "string");
+}
+
+function collectToolCallIds(value: unknown, ids: Set<string>, seen: WeakSet<object>): void {
+  if (!value || typeof value !== "object" || seen.has(value)) return;
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const child of value) collectToolCallIds(child, ids, seen);
+    return;
+  }
+  const record = value as Record<string, unknown>;
+  if (toolName(record) === CONTEXT_PERSISTENCE_TOOL_NAME) {
+    for (const id of identifiers(record)) ids.add(id);
+  }
+  for (const child of Object.values(record)) collectToolCallIds(child, ids, seen);
+}
+
+function sanitizeContent(value: unknown, safeText: string): unknown {
+  if (typeof value === "string") return safeText;
+  if (!Array.isArray(value)) return [{ type: "text", text: safeText }];
+  return [{ type: "text", text: safeText }];
+}
+
+function sanitizeNode(
+  value: unknown,
+  toolCallIds: ReadonlySet<string>,
+  seen: WeakMap<object, unknown>,
+): { value: unknown; changed: boolean } {
+  if (!value || typeof value !== "object") return { value, changed: false };
+  const prior = seen.get(value);
+  if (prior !== undefined) return { value: prior, changed: false };
+  if (Array.isArray(value)) {
+    const output: unknown[] = [];
+    seen.set(value, output);
+    let changed = false;
+    for (const child of value) {
+      const sanitized = sanitizeNode(child, toolCallIds, seen);
+      output.push(sanitized.value);
+      changed ||= sanitized.changed;
+    }
+    return changed ? { value: output, changed: true } : { value, changed: false };
+  }
+
+  const record = value as Record<string, unknown>;
+  const directToolCall = toolName(record) === CONTEXT_PERSISTENCE_TOOL_NAME;
+  const linkedResult = identifiers(record).some((id) => toolCallIds.has(id))
+    || (record.role === "toolResult" && record.toolName === CONTEXT_PERSISTENCE_TOOL_NAME);
+  let changed = false;
+  const output: Record<string, unknown> = {};
+  seen.set(value, output);
+
+  for (const [key, child] of Object.entries(record)) {
+    if (directToolCall && (key === "arguments" || key === "args" || key === "input")) {
+      output[key] = sanitizeArgumentContainer(child);
+      changed = true;
+      continue;
+    }
+    if (linkedResult && key === "details") {
+      const details = sanitizeHistoricalContextPersistenceDetails(child);
+      output[key] = details ?? {};
+      changed = true;
+      continue;
+    }
+    if (linkedResult && (key === "content" || key === "output")) {
+      const details = sanitizeHistoricalContextPersistenceDetails(record.details);
+      const text = details
+        ? renderHistoricalContextPersistenceResult(details)
+        : sanitizeHistoricalContextPersistenceText(
+          typeof child === "string"
+            ? child
+            : Array.isArray(child)
+              ? child.flatMap((block) => isRecord(block) && typeof block.text === "string" ? [block.text] : []).join("\n")
+              : undefined,
+        );
+      output[key] = sanitizeContent(child, text);
+      changed = true;
+      continue;
+    }
+    if (linkedResult && key === "response") {
+      const response = isRecord(child) ? child : {};
+      const responseKey = "error" in response ? "error" : "output";
+      output[key] = {
+        [responseKey]: sanitizeHistoricalContextPersistenceText(response[responseKey]),
+      };
+      changed = true;
+      continue;
+    }
+    const sanitized = sanitizeNode(child, toolCallIds, seen);
+    output[key] = sanitized.value;
+    changed ||= sanitized.changed;
+  }
+  return changed ? { value: output, changed: true } : { value, changed: false };
+}
+
+export function sanitizeContextPersistenceHistory<T>(value: T): { value: T; changed: boolean } {
+  const ids = new Set<string>();
+  collectToolCallIds(value, ids, new WeakSet());
+  const sanitized = sanitizeNode(value, ids, new WeakMap());
+  return { value: sanitized.value as T, changed: sanitized.changed };
+}