@staix/agent-mem 0.13.0 → 0.14.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mem",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Bounded project memory tools and seven deterministic capture hooks, without a resident worker.",
   "mcpServers": {
     "agent-mem": {

package/README.md

@@ -2,7 +2,7 @@
 
 Curated memory with append-only JSONL logs, a derived SQLite index, short- and long-term tiers, a typed graph, goals with leases, and git sync between machines. Extracted from [agent-hub](https://github.com/STAIxBWLB/agent-hub), with compatible storage and entry IDs.
 
-Version: 0.13.0. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.14.0. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Quick start
 
@@ -300,7 +300,7 @@ Prune apply still requires a sealed JSON plan. Save `amem prune --dry-run --cuto
 
 Intake runs at the end of each Codex, Kimi, Pi and Qwen session once `amem setup <cli> --apply` has registered it. Sync is off unless you ask for it: amem registers no sync hook and runs nothing between sessions. To sync on a schedule you have authorized, call `amem sync --if-due` from the chosen shell or scheduler; it has no TTY gate. This release registers no sync schedule or hook, and the configured privacy and remote-visibility checks still apply. It syncs at most hourly, backs off 15 minutes doubling to a day after failures, stops after 30 seconds, and does nothing without a remote set by `amem sync --remote <private git url>`. `--force` skips the schedule and the backoff.
 
-Split-home sync durably holds verified foreign-generation prunes with a "held, not applied" warning while unrelated sync continues; targets can remain visible, and full cross-generation removal remains a separate ceiling (see [the sync contract](docs/contracts.md#per-shard-private-sync-15-t3)).
+V1 split-home sync durably holds verified foreign-generation prunes with a "held, not applied" warning. The opt-in v2 path below applies eligible complete same-realm public prunes across generations after durable proof and root-map commitment. Unsupported historical lineage and multi-realm translations remain held; targets can remain visible and agent-mem#15 AC4 stays open (see [the sync contract](docs/contracts.md#per-shard-private-sync-15-t3)).
 
 ## Native transcript intake
 
@@ -481,3 +481,22 @@ Run `amem consolidate [--project <current-key>]` (another project is refused) to
 The CLI runs the deterministic pass only. A library host may explicitly enable an injected model callback for the person; no provider is built in. It has batch, byte, deadline and persistent daily limits. Model answers remain marked machine-local candidates that cannot be accepted; `amem note add` is the separate path for an independently authored note. A non-answer is never saved.
 
 Agents use `amem_evidence` with a question to get cited, live curated entries, not an answer. The complete JSON bundle is byte-capped (`maxBytes`, default 4096, range 256..8192); excerpted entries retain an exact `mem:` reference for fetching the full note. Capture, repository-only rows, pending candidates and model answers are excluded. amem makes no model call for this tool. Rendering a citation in the bundle records only `rendered` after successful output, never `delivered` or `cited`.
+
+### Public prune view and v2 sync (opt-in)
+
+On an active curated split, the person can preview and enable the forward-only v2 reader floor. This keeps the receiving generation and native logs/seals, builds a separate `index-v2.db`, and preserves every native/local mask. Once activated, explicit sync uses the v2 transport and can install complete generation-neutral public-prune proof; historical hold receipts alone never authorize a mask.
+
+```sh
+AMEM_HOME=/path/to/synthetic-memory amem migrate --public-prune-view --dry-run
+AMEM_HOME=/path/to/synthetic-memory amem migrate --public-prune-view --apply
+# Finish an interrupted activation, using its exact recorded forward state.
+AMEM_HOME=/path/to/synthetic-memory amem migrate --public-prune-view --resume
+```
+
+Dry-run writes nothing and reports mask building as deferred. Close cooperating reader handles for initial v1-to-v2 activation or its resume, and install compatible hosts first: older readers reject the new markers and transport tip. Initial activation preserves all native/local masks and currently performs ten old/new comparison rebuilds per realm across five verification passes, plus snapshot/index work. Deactivation is refused because v1 would omit foreign masks. Unannounced historical readers can still inspect unchanged old bytes; this is logical masking, not erasure.
+
+The first explicit v2 `amem sync` primes a private create-once publisher boundary for each selected shard/current machine. Only complete own prune rows appended after that boundary can receive new `post-seal` lineage; all earlier rows and unsupported historical lineage stay ineligible. Sync never infers a native-generation claim or rewrites native seals/rows. Both machines need compatible v2 readers and explicit sync. Stable exact project/user refs make a one-way v1-to-v2 history transition; returning a ref to v1 is refused.
+
+Sync validates all selected history and complete raw Git proof, and checks each realm's aggregate input/archive capacity before atomic publication. It then fsyncs immutable inputs and commits the root map before ordinary/native imports, preventing an unmasked first import. Already-v2 map advances preserve generation/format and monotone ancestry, use a forward-only intent and rebind existing readers without requiring them to close. A reader waits at most 3000 ms for a v2 writer; an unresolved intent, incompatible marker pair or missing committed proof reports unavailable. The same `--resume` command completes an interrupted advance forward. Read and capture never activate, prime a boundary or repair a pending operation.
+
+`SyncResult.pruneApplication` reports transport durability, complete-proof count, neutral projection activity, native application, held count and phase separately. Transport durability alone does not establish completed local application. Historical multi-realm translations and older unsupported lineage retain "held, not applied" warnings, so agent-mem#15 AC4 remains open. The [full contract](docs/generation-neutral-prune-witness.md) states the owned-source integrity and resource ceilings; this source behavior does not establish release or live-host verification.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Curated, shared memory for coding agents: append-only logs, a derived index, tiers and a typed graph.",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,8 @@
     "@staix/agent-mem-v02": "npm:@staix/agent-mem@0.2.0",
     "@staix/agent-mem-pre-vault": "npm:@staix/agent-mem@0.3.1",
     "@staix/agent-mem-v011": "npm:@staix/agent-mem@0.11.0",
-    "@staix/agent-mem-v012": "npm:@staix/agent-mem@0.12.0"
+    "@staix/agent-mem-v012": "npm:@staix/agent-mem@0.12.0",
+    "@staix/agent-mem-v013": "npm:@staix/agent-mem@0.13.0"
   },
   "exports": {
     ".": "./src/index.ts",

package/src/cli.ts

@@ -1,3 +1,4 @@
+import { activatePublicPruneView } from "./memory/public-prune-activation.ts";
 import { agentCliRead } from "./cli-agent-reads.ts";
 import { cliAttribution, withCliAttribution } from "./memory/cli-attribution.ts";
 import { randomUUID } from "node:crypto";
@@ -344,6 +345,12 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
     if (modes.length > 1) throw new Error("migration modes are mutually exclusive");
     const mode = options["--apply"] ? "apply" : options["--resume"] ? "resume" : options["--deactivate"] ? "deactivate" : "dry-run";
     const common = { memoryDir: memoryHome(), ...(options["--generation"] ? { generation: String(options["--generation"]) } : {}), authorizedPerson: true, tty: true };
+    if (options["--public-prune-view"] === true) {
+      if (options["--deactivate"] || options["--generation"] || options["--shards"]) throw new Error("public prune view is forward-only on an active split; no deactivate, generation replacement or new split");
+      if (actor === "agent" && mode !== "dry-run") administrative({ command: "migrate --public-prune-view", mode });
+      const result = await activatePublicPruneView({ memoryDir: memoryHome(), mode: mode as "dry-run" | "apply" | "resume", authorizedPerson: true, tty: true });
+      return options["--json"] ? JSON.stringify(result, null, 2) : `public prune view: ${result.mode}; generation ${result.generation}; mask build ${result.maskBuildCheck}; forward-only, no deactivation`;
+    }
     const shardRequested = options["--shards"] === true || (mode === "resume" && shardStatePresent());
     if (shardRequested) {
       if (mode === "deactivate") throw new Error("--deactivate is not a shard migration mode");
@@ -882,7 +889,7 @@ async function runCliCommand(argv: readonly string[], context: CliContext): Prom
   const stop = ifDue ? stopSignal(context.syncDeadlineMs ?? SYNC_IF_DUE_DEADLINE_MS, process) : undefined;
   try {
     output = await withRepoRows(await rawMemoryCommand(memoryArgs, cwd, { person: identity.actor === "person", rankedSearch: identity.actor === "person" && !legacySearch, ...(explainSearch ? { explainSearch: true } : {}), project: boundProject(), open, readable: notes => identity.actor === "person" ? notes : notes.filter(view => view.project === boundProject() && policyOf().screenStandalone(view)), stale: createRecallStalenessProbe({ cwd: recallRoot ?? cwd, rootConfirmed, policy: () => configured }), outputReady: notes => outputReady(notes.map(view => view.id)), importPolicy: () => text => configured.declinesPersonal(text),
-      sync: { screen: row => configured.screenStandalone(row), ...(stop ? { signal: stop.signal } : {}) },   // the repository-narrowed policy binds what sync publishes too
+      sync: { screen: row => configured.screenStandalone(row), policyVersion: () => JSON.stringify(configuredPolicyOptions(memoryHome(), policyCwd)), ...(stop ? { signal: stop.signal } : {}) },   // the repository-narrowed policy binds what sync publishes too
       onBridgeStatus: status => { receipt.bridgeStatus = status; } }));
   } catch (error) {
     if (sub === "sync") stampSync((error as Error).message, stop?.cause());

package/src/commands-table.ts

@@ -107,6 +107,7 @@ export const COMMANDS: Record<string, CommandDefinition> = {
     ...json, "--apply": flag("Apply the previewed migration"), "--dry-run": flag("Read-only migration receipt (default; kept as an alias)"), "--generation": text("Explicit 32-hex generation ID"),
     "--resume": flag("Resume the recorded migration"), "--deactivate": flag("Select shared v1 without deleting a generation"),
     "--shards": flag("Migrate the curated home into project and user shards"),
+    "--public-prune-view": flag("Enable the forward-only v2 public prune view on an active split"),
   } },
   status: { description: "Report shard migration and pending old-layout appends", options: json },
   doctor: { description: "One read-only report (F15): duplicates and stale notes, pending candidates, capture freshness per CLI, the brief's token cost, index equals rebuild, reader leases, the policy in effect, ingest and sync cadence", options: json },

package/src/memory/catalog.ts

@@ -2,7 +2,7 @@ import { Database } from "bun:sqlite";
 import { chmodSync, existsSync, lstatSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { memoryBase } from "./home.ts";
-import { effectiveAliases, readShardDescriptor, SHARDED_SCHEMA } from "./shard.ts";
+import { effectiveAliases, readShardDescriptor, SHARDED_SCHEMA, SHARDED_V2_SCHEMA } from "./shard.ts";
 import { readProfileJSON, validGeneration } from "./generation.ts";
 import { captureShardStats, readCaptureConfig } from "./capture.ts";
 import { openShardStore } from "./store.ts";
@@ -36,7 +36,7 @@ const fromRow = (r: CatalogRow): CatalogProject => ({ hash: r.hash, key: r.key,
 function capturedSelection(base: string): boolean {
   const value = readProfileJSON(join(base, "shards.json")) as { schema?: unknown; generation?: unknown; phase?: unknown; selectorRevision?: unknown } | undefined;
   if (value === undefined) return false;
-  if (!value || value.schema !== SHARDED_SCHEMA || !validGeneration(value.generation) || (value.phase !== "captured" && value.phase !== "active") || typeof value.selectorRevision !== "string") throw new Error("curated shard selection is unavailable or invalid");
+  if (!value || (value.schema !== SHARDED_SCHEMA && value.schema !== SHARDED_V2_SCHEMA) || !validGeneration(value.generation) || (value.phase !== "captured" && value.phase !== "active") || typeof value.selectorRevision !== "string") throw new Error("curated shard selection is unavailable or invalid");
   return value.phase === "captured";
 }
 
@@ -48,10 +48,10 @@ function curatedStats(base: string, hash: string, key: string, captured: boolean
   if (!existsSync(join(dir, "generation.json")) && !existsSync(join(dir, "generation-seal.json"))) return { entries: 0, lastAt: null };
   const store = openShardStore({ memoryDir: base, project: key, deferPromotions: true, lifecycle: "ignore" });
   try {
-    const db = new Database(join(dir, "index.db"), { readonly: true });
+    const db = new Database(join(dir, store.profile.foreignPruneFormat ? "index-v2.db" : "index.db"), { readonly: true });
     try {
       db.run("PRAGMA busy_timeout = 0");
-      const row = db.query("SELECT COUNT(*) AS n, MAX(at) AS last FROM entries WHERE scope = 'project' AND project = ?").get(key) as { n: number; last: string | null };
+      const row = db.query("SELECT COUNT(*) AS n, MAX(at) AS last FROM entries WHERE scope = 'project' AND project = ?" + (store.profile.foreignPruneFormat ? " AND id NOT IN (SELECT id FROM generation_targets)" : "")).get(key) as { n: number; last: string | null };
       return { entries: row.n, lastAt: row.last };
     } finally { db.close(); }
   } finally { store.close(); }

package/src/memory/commands.ts

@@ -197,6 +197,10 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
         const r = await syncMemory(store, { ...opts.sync, ...(remote ? { remote } : {}) });
         if (json) return JSON.stringify(r, null, 2);
         if (!r.ok) fail(`${names.memory} sync: ${r.error}`);
+        if (r.pruneApplication) {
+          const a = r.pruneApplication;
+          return `synced${r.pushed ? " and pushed" : ""}: ${r.entries} long-term entries transported; ${a.proofComplete} prune proofs complete, ${a.projectionActive ?? "pending"} foreign projections active, ${a.nativeApplied ?? "pending"} native prunes applied, ${a.held} held${r.warning ? `\nnote: ${r.warning}` : ""}`;
+        }
         return `synced${r.pushed ? " and pushed" : ""}: ${r.entries} long-term entries visible here${r.warning ? `\nnote: ${r.warning}` : ""}`;
       }
       case "dedupe": {

package/src/memory/doctor.ts

@@ -1,6 +1,6 @@
-import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { Database } from "bun:sqlite";
 import { sessionStartBrief } from "../session-brief.ts";
 import { pendingSummary } from "./candidate-pending.ts";
@@ -87,8 +87,10 @@ class TooBig extends Error {}
 function copyTree(from: string, to: string, budget: { bytes: number }, skipNames: ReadonlySet<string> = new Set()): void {
   mkdirSync(to, { recursive: true, mode: 0o700 });
   for (const name of readdirSync(from)) {
-    if (SKIP.test(name) || skipNames.has(name)) continue;
+    const proofObject = basename(from) === "public-prune-objects" && /^[a-f0-9]{40}\.git$/.exec(name)?.[0] === name;
+    if (SKIP.test(name) && !proofObject || skipNames.has(name)) continue;
     const source = join(from, name), stat = lstatSync(source);
+    if (proofObject && !stat.isFile()) throw new Error("a public prune object is not a plain file");
     if (stat.isSymbolicLink()) throw new Error("the memory home holds a link where a plain file or directory is expected");
     if (stat.isDirectory()) copyTree(source, join(to, name), budget, skipNames);
     else if (stat.isFile()) { budget.bytes += stat.size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig(); copyFileSync(source, join(to, name)); }
@@ -103,6 +105,14 @@ function copyCurated(options: DoctorOptions, layout: Layout, scratch: string, bu
     const stat = statSync(join(home, name)); budget.bytes += stat.size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig();
     copyFileSync(join(home, name), join(scratch, name));
   }
+  const selected = readSelector(home).selector;
+  if (selected?.schema === "agent-mem.profile/v2") {
+    const name = `${selected.pruneInputSetHash}.json`, source = join(home, "public-prune-input-sets", name), stat = lstatSync(source);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) throw new Error("the committed public prune view is not a plain file");
+    budget.bytes += stat.size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig();
+    const directory = join(scratch, "public-prune-input-sets"); mkdirSync(directory, { mode: 0o700 });
+    copyFileSync(source, join(directory, name)); chmodSync(join(directory, name), 0o600);
+  }
   if (layout === "split") {
     for (const key of [options.project, ...options.aliases]) {
       const dir = shardDir(home, key);

package/src/memory/generation-index.ts

@@ -1,16 +1,20 @@
-import { SHARDED_SCHEMA } from "./shard.ts";
+import { createPublicPruneReplayCache, type PublicPruneProjection } from "./public-prune-inputs.ts";
+import { readPublicPruneView, readPublicPruneViewForActivation } from "./public-prune-view.ts";
+import { SHARDED_SCHEMA, SHARDED_V2_SCHEMA } from "./shard.ts";
 import { readShardLegacySnapshot } from "./shard-bridge.ts";
 import type { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import { closeSync, constants, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeSync } from "node:fs";
 import { join } from "node:path";
-import { canonicalJSON, hashJSON, fsyncDirectory, readProfileJSON, selectorRevision, writeProfileJSON, type BoundProfile, validateVaultLinkRow, type VaultLink } from "./generation.ts";
+import { canonicalJSON, hashJSON, fsyncDirectory, readProfileJSON, selectorRevision, writeProfileJSON, type BoundProfile, validateVaultLinkRow, type VaultLink, rebindPublicPruneProfile } from "./generation.ts";
 import { legacyEntries, legacyHead, readLegacySnapshot, SegmentReader, type LegacyCheckpoint, type LegacySegment } from "./bridge.ts";
 import { reducePruneRows, validatePruneRow, type PrunePlan, type PruneRow, type PruneSnapshot, type PruneSourceRow, type PruneStorePort } from "./prune.ts";
 import { PROMOTED_KINDS, type Entry } from "./store.ts";
 
+const FOREIGN_TABLES = ["generation_foreign_inputs", "generation_foreign_rows", "generation_foreign_targets"] as const;
 const digest = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex");
 const fail = (): never => { throw new Error("generation input unavailable or changed; person inspection required"); };
+class PublicPruneViewChanged extends Error { constructor() { super("public prune view changed repeatedly; retry the read"); } }
 export const GENERATION_TABLES = ["generation_vault_links", "generation_rows", "generation_prunes", "generation_targets", "generation_segments", "generation_state"] as const;
 export interface GenerationIndexOptions {
   profile: BoundProfile; db: Database; now: () => number;
@@ -65,9 +69,17 @@ export class GenerationIndex {
   private fullCapture = false;
   private retainedTail = false;
   private replayProvenance = false;
+  private foreignStamp?: string;
+  private foreignCache?: { set: string; load: () => PublicPruneProjection };
   constructor(private readonly options: GenerationIndexOptions) {
     this.profile = options.profile;
     const db = options.db;
+    if (this.profile.foreignPruneFormat) {
+      db.run("CREATE TABLE IF NOT EXISTS generation_foreign_inputs (id TEXT PRIMARY KEY)");
+      db.run("CREATE TABLE IF NOT EXISTS generation_foreign_rows (id TEXT PRIMARY KEY, hash TEXT NOT NULL)");
+      db.run("CREATE TABLE IF NOT EXISTS generation_foreign_targets (id TEXT PRIMARY KEY)");
+      this.replayProvenance = true; // persistent SQLite never supplies foreign membership
+    }
     db.run("CREATE TABLE IF NOT EXISTS generation_rows (id TEXT PRIMARY KEY, line TEXT NOT NULL, local INTEGER NOT NULL, public INTEGER NOT NULL, own INTEGER NOT NULL, legacy INTEGER NOT NULL)");
     if (!(db.query("PRAGMA table_info(generation_rows)").all() as { name: string }[]).some(row => row.name === "legacy")) { db.run("ALTER TABLE generation_rows ADD COLUMN legacy INTEGER NOT NULL DEFAULT 0"); this.replayProvenance = true; }
     db.run("CREATE TABLE IF NOT EXISTS generation_vault_links (id TEXT PRIMARY KEY, target TEXT NOT NULL, row_hash TEXT NOT NULL, project TEXT NOT NULL, path TEXT NOT NULL, at TEXT NOT NULL)");
@@ -93,9 +105,14 @@ export class GenerationIndex {
   /** Authoring handles cannot read or append a partially resumed split; migration index bootstraps use captured limits. */
   private shardFrontier(): string | undefined {
     if (!this.profile.sharded || this.options.limits !== undefined) return undefined;
-    const value = readProfileJSON(join(this.profile.home, "shards.json")) as { schema?: unknown; phase?: unknown; generation?: unknown; selectorRevision?: unknown } | undefined;
-    if (!value || value.schema !== SHARDED_SCHEMA || value.phase !== "active" || value.generation !== this.profile.generation || value.selectorRevision !== this.profile.selectorRevision) return fail();
-    return hashJSON(value);
+    for (let attempt = 0; attempt < 6; attempt++) {
+      rebindPublicPruneProfile(this.profile);
+      const value = readProfileJSON(join(this.profile.home, "shards.json")) as { schema?: unknown; phase?: unknown; generation?: unknown; selectorRevision?: unknown } | undefined;
+      if (selectorRevision(this.profile.home) !== this.profile.selectorRevision) { if (this.profile.foreignPruneFormat) continue; return fail(); }
+      if (!value || value.schema !== (this.profile.foreignPruneFormat ? SHARDED_V2_SCHEMA : SHARDED_SCHEMA) || value.phase !== "active" || value.generation !== this.profile.generation || value.selectorRevision !== this.profile.selectorRevision) return fail();
+      return hashJSON(value);
+    }
+    return fail();
   }
   private capture(reader: SegmentReader = this.reader): { segments: LegacySegment[]; commit?: string } {
     const shardBefore = this.shardFrontier();
@@ -119,7 +136,7 @@ export class GenerationIndex {
       const segment = own.find(s => s.path === old.path);
       if (!segment || segment.offset < old.offset) fail();
     }
-    if (this.shardFrontier() !== shardBefore) return fail();
+    if (this.shardFrontier() !== shardBefore) { if (this.profile.foreignPruneFormat) throw new PublicPruneViewChanged(); return fail(); }
     return { segments: [...legacy, ...own], ...(commit ? { commit } : {}) };
   }
   private index(captured: { segments: LegacySegment[]; commit?: string }): void {
@@ -161,7 +178,35 @@ export class GenerationIndex {
     const reduced = reducePruneRows(prunes, snapshot, this.profile.generation!);
     db.run("DELETE FROM generation_targets");
     for (const id of [...reduced.targets].sort()) db.query("INSERT INTO generation_targets VALUES (?)").run(id);
-    this.pruned = reduced.targets;
+    this.applyForeign(true);
+    this.pruned = new Set((db.query("SELECT id FROM generation_targets").all() as {id:string}[]).map(row => row.id));
+  }
+  private applyForeign(validateRows = false): void {
+    if (!this.profile.foreignPruneFormat) return;
+    const profile = this.profile;
+    if (!profile.pruneInputSetHash || !profile.generation || !profile.sharded) return fail();
+    const view = (this.options.limits !== undefined ? readPublicPruneViewForActivation : readPublicPruneView)(profile.home, profile.pruneInputSetHash, profile.generation);
+    const key = profile.shardUser ? "user" : `project:${profile.shardKey}`, set = view.realms[key];
+    const db = this.options.db;
+    if (!set) {
+      if ((db.query("SELECT COUNT(*) AS n FROM generation_foreign_inputs").get() as {n:number}).n) return fail();
+      return;
+    }
+    if (!this.foreignCache || this.foreignCache.set !== set) this.foreignCache = { set, load: createPublicPruneReplayCache({ dir: profile.dir,
+      realm: profile.shardUser ? { scope: "user" } : { scope: "project", key: profile.shardKey! }, receivingGeneration: profile.generation, inputSetHash: set }) };
+    const proof = this.foreignCache.load();
+    if (validateRows || this.foreignStamp !== set) for (const item of db.query("SELECT id,line FROM generation_rows").all() as {id:string;line:string}[]) {
+      const expected = proof.rowHashes.get(item.id); if (expected && hashJSON(JSON.parse(item.line)) !== expected) return fail();
+    }
+    if (validateRows || this.foreignStamp !== set) {
+    for (const table of FOREIGN_TABLES) db.run(`DELETE FROM ${table}`);
+    for (const id of proof.inputs) db.query("INSERT INTO generation_foreign_inputs VALUES (?)").run(id);
+    for (const [id, hash] of proof.rowHashes) db.query("INSERT INTO generation_foreign_rows VALUES (?,?)").run(id, hash);
+    for (const id of proof.targets) db.query("INSERT INTO generation_foreign_targets VALUES (?)").run(id);
+    this.foreignStamp = set;
+    }
+    const current = new Set((db.query("SELECT id FROM generation_targets").all() as {id:string}[]).map(row => row.id));
+    for (const id of proof.targets) if (!current.has(id)) db.query("INSERT INTO generation_targets VALUES (?)").run(id);
   }
   private recordSkipped(segment: LegacySegment): void {
     this.options.db.query("INSERT INTO generation_state VALUES (?,'1') ON CONFLICT(key) DO UPDATE SET value=CAST(CAST(value AS INTEGER)+1 AS TEXT)").run(`skipped:${segment.source}:${segment.path}`);
@@ -183,12 +228,12 @@ export class GenerationIndex {
     const before = this.frontier(), db = this.options.db;
     let input: ReturnType<GenerationIndex["capture"]>;
     try { input = this.capture(reader); }
-    catch (error) { if (attempt < 5 && this.frontier() !== before) return this.refresh(attempt + 1, reader); throw error; }
+    catch (error) { if (attempt < 5 && (error instanceof PublicPruneViewChanged || this.frontier() !== before)) return this.refresh(attempt + 1, reader); throw error; }
     if (this.frontier() !== before) { if (attempt < 5) return this.refresh(attempt + 1, reader); return fail(); }
     const known = db.query("SELECT source,path,offset,hash,commit_id,stamp FROM generation_segments").all() as { source: string; path: string; offset: number; hash: string; commit_id: string | null; stamp: string | null }[];
     const currentCommit = (db.query("SELECT value FROM generation_state WHERE key='legacyCommit'").get() as { value: string } | null)?.value;
     const unchanged = known.length === input.segments.length && currentCommit === input.commit && input.segments.every(segment => known.some(row => row.source === segment.source && row.path === segment.path && row.offset === segment.offset && row.hash === segment.hash && row.commit_id === (segment.commit ?? null) && row.stamp === (segment.stamp ?? null)));
-    if (unchanged) { this.retainedTail = input.segments.some(segment => segment.tailBytes > 0); this.pruned = new Set((db.query("SELECT id FROM generation_targets").all() as { id: string }[]).map(row => row.id)); return; }
+    if (unchanged) { if (this.profile.foreignPruneFormat) db.transaction(() => this.applyForeign()).deferred(); this.retainedTail = input.segments.some(segment => segment.tailBytes > 0); this.pruned = new Set((db.query("SELECT id FROM generation_targets").all() as { id: string }[]).map(row => row.id)); return; }
     const committed = db.transaction(() => { if (this.frontier() !== before) return false; this.index(input); return true; }).immediate();
     if (!committed) { if (attempt < 5) return this.refresh(attempt + 1, reader); return fail(); }
     this.retainedTail = input.segments.some(segment => segment.tailBytes > 0);
@@ -197,11 +242,11 @@ export class GenerationIndex {
     const before = this.frontier();
     let input: ReturnType<GenerationIndex["capture"]>;
     try { this.fullCapture = true; input = this.capture(reader); }
-    catch (error) { this.fullCapture = false; if (attempt < 5 && this.frontier() !== before) return this.rebuild(attempt + 1, reader); throw error; }
+    catch (error) { this.fullCapture = false; if (attempt < 5 && (error instanceof PublicPruneViewChanged || this.frontier() !== before)) return this.rebuild(attempt + 1, reader); throw error; }
     finally { this.fullCapture = false; }
     const committed = this.options.db.transaction(() => {
       if (this.frontier() !== before) return false;
-      for (const table of ["entries", "ops", "edges", "goals", "segments", "heads", ...GENERATION_TABLES]) this.options.db.run(`DELETE FROM ${table}`);
+      for (const table of ["entries", "ops", "edges", "goals", "segments", "heads", ...GENERATION_TABLES, ...(this.profile.foreignPruneFormat ? FOREIGN_TABLES : [])]) this.options.db.run(`DELETE FROM ${table}`);
       this.index(input); return true;
     }).immediate();
     if (!committed) { if (attempt < 5) return this.rebuild(attempt + 1, reader); return fail(); }

package/src/memory/generation.ts

@@ -1,9 +1,12 @@
+import { assertNoPublicPruneIntent, readPublicPruneView, waitForPublicPruneWriter, PUBLIC_PRUNE_INTENT } from "./public-prune-view.ts";
 import { createHash, randomBytes } from "node:crypto";
 import { types } from "node:util";
 import { closeSync, existsSync, fsyncSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { readerAdmissionDatabase } from "./mutation.ts";
 import { dirname, join } from "node:path";
 import { canonicalPath, processLiveness, processSignature, realPath } from "./platform.ts";
+import { shardDir, userShardDir } from "./shard.ts";
+import { readPublicPruneInputSetChain } from "./public-prune-input-chain.ts";
 
 export interface BoundProfile {
   kind: "shared-v1" | "generation";
@@ -12,6 +15,9 @@ export interface BoundProfile {
   dir: string;
   generation?: string;
   selectorRevision: string;
+  /** Explicit v2 projection only, never inferred from an archive or caller flag. */
+  foreignPruneFormat?: "agent-mem.public-prune-witness/v1";
+  pruneInputSetHash?: string;
   /** Sharded profiles read only their own legacy input; the root home remains the machine/selector identity. */
   legacyHome?: string;
   /** Public legacy witnesses stay distinct from same-machine private bridge input. */
@@ -21,7 +27,8 @@ export interface BoundProfile {
   shardUser?: boolean;
 }
 export type ProfileInput = "shared-v1" | { generation: string };
-export interface ProfileSelector { schema: "agent-mem.profile/v1"; kind: "shared-v1" | "generation"; generation?: string }
+export type ProfileSelector = { schema: "agent-mem.profile/v1"; kind: "shared-v1" | "generation"; generation?: string }
+  | { schema: "agent-mem.profile/v2"; kind: "generation"; generation: string; foreignPruneFormat: "agent-mem.public-prune-witness/v1"; pruneInputSetHash: string };
 export interface GenerationDescriptor { schema: "agent-mem.generation/v1"; generation: string; legacySchema: "agent-hub.memory/v1" }
 export interface GenerationSeal { schema: "agent-mem.generation-seal/v1"; generation: string; descriptorHash: string; sourceDigest: string }
 export const PROFILE_LOCK_TIMEOUT_MS = 3000;
@@ -44,16 +51,69 @@ export function readProfileJSON(path: string, limit = LOCAL_METADATA_MAX_BYTES):
   } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; return unavailable(); }
 }
 function keys(value: object, allowed: string[]): boolean { return Object.keys(value).every(key => allowed.includes(key)); }
-export function readSelector(memoryDir: string): { selector?: ProfileSelector; revision: string } {
+function selectorSnapshot(memoryDir: string, deadline: number): { selector?: ProfileSelector; revision: string } {
+  assertNoPublicPruneIntent(memoryDir, deadline);
   const value = readProfileJSON(join(memoryDir, "profile.json"));
   if (value === undefined) return { revision: "absent" };
-  if (!value || typeof value !== "object" || Array.isArray(value) || !keys(value, ["schema", "kind", "generation"])) return unavailable();
+  if (!value || typeof value !== "object" || Array.isArray(value)) return unavailable();
   const selector = value as ProfileSelector;
-  if (selector.schema !== "agent-mem.profile/v1" || !["shared-v1", "generation"].includes(selector.kind)
-    || (selector.kind === "generation" ? !validGeneration(selector.generation) : selector.generation !== undefined)) return unavailable();
+  if (selector.schema === "agent-mem.profile/v2") {
+    if (Object.keys(selector).length !== 5 || !keys(selector, ["schema", "kind", "generation", "foreignPruneFormat", "pruneInputSetHash"])
+      || selector.kind !== "generation" || !validGeneration(selector.generation) || selector.generation.length !== 32
+      || selector.foreignPruneFormat !== "agent-mem.public-prune-witness/v1" || typeof selector.pruneInputSetHash !== "string"
+      || selector.pruneInputSetHash.length !== 64 || !/^[a-f0-9]+$/.test(selector.pruneInputSetHash)) return unavailable();
+    const shard = readProfileJSON(join(memoryDir, "shards.json")) as Record<string, unknown> | undefined;
+    if (!shard || shard.schema !== "agent-mem.shards/v2" || shard.phase !== "active" || shard.generation !== selector.generation || shard.selectorRevision !== hashJSON(selector)) return unavailable();
+    readPublicPruneView(memoryDir, selector.pruneInputSetHash, selector.generation, deadline);
+  } else if (selector.schema !== "agent-mem.profile/v1" || !keys(selector, ["schema", "kind", "generation"])
+    || !["shared-v1", "generation"].includes(selector.kind) || (selector.kind === "generation" ? !validGeneration(selector.generation) : selector.generation !== undefined)) return unavailable();
+  else if ((readProfileJSON(join(memoryDir, "shards.json")) as {schema?:unknown}|undefined)?.schema === "agent-mem.shards/v2") return unavailable();
   return { selector, revision: hashJSON(selector) };
 }
+
+/** A v2 writer can replace its two markers between individual reads. Retry its
+ * bounded completed publication rather than exposing a transient mixed pair. */
+export function readSelector(memoryDir: string, absoluteDeadline?: number): { selector?: ProfileSelector; revision: string } {
+  const deadline = Math.min(absoluteDeadline ?? Infinity, Date.now() + PROFILE_LOCK_TIMEOUT_MS);
+  for (let attempt = 0; attempt < 6 && Date.now() <= deadline; attempt++) {
+    try {
+      const result = selectorSnapshot(memoryDir, deadline); assertNoPublicPruneIntent(memoryDir, deadline);
+      const current = readProfileJSON(join(memoryDir, "profile.json"));
+      if (result.revision === (current === undefined ? "absent" : hashJSON(current))) return result;
+    } catch (error) {
+      if (error instanceof Error && error.message === "public prune view unavailable") throw error; // A spent wait budget is never restarted.
+      if (!lstatSync(join(memoryDir, PUBLIC_PRUNE_INTENT), { throwIfNoEntry: false }) && !lstatSync(join(memoryDir, "profile.lock"), { throwIfNoEntry: false })) throw error;
+      waitForPublicPruneWriter(memoryDir, deadline);
+    }
+  }
+  return unavailable();
+}
+
 export const selectorRevision = (memoryDir: string): string => readSelector(memoryDir).revision;
+/** Refresh the same shared profile object only across proved monotone same-generation v2 views.
+ * Unopened realms contribute set metadata only; their descriptors and bodies stay unopened. */
+export function rebindPublicPruneProfile(profile: BoundProfile): void {
+  if (!profile.foreignPruneFormat) return;
+  for (let attempt = 0; attempt < 6; attempt++) {
+    const current = readSelector(profile.home), selector = current.selector;
+    if (current.revision === profile.selectorRevision) return;
+    if (!profile.sharded || profile.kind !== "generation" || !profile.generation || !profile.pruneInputSetHash
+      || selector?.schema !== "agent-mem.profile/v2" || selector.generation !== profile.generation || selector.foreignPruneFormat !== profile.foreignPruneFormat) return unavailable();
+    const previous = readPublicPruneView(profile.home, profile.pruneInputSetHash, profile.generation);
+    const next = readPublicPruneView(profile.home, selector.pruneInputSetHash, profile.generation);
+    if (!Object.keys(previous.realms).every(key => Object.hasOwn(next.realms, key))) return unavailable();
+    for (const [key, hash] of Object.entries(next.realms)) {
+      const old = previous.realms[key]; if (old === hash) continue;
+      const dir = key === "user" ? userShardDir(profile.home) : shardDir(profile.home, key.slice(8));
+      const chain = readPublicPruneInputSetChain({ dir, receivingGeneration: profile.generation, inputSetHash: hash });
+      if (old !== undefined && !chain.commitments.includes(old)) return unavailable();
+    }
+    if (readSelector(profile.home).revision !== current.revision) continue;
+    profile.selectorRevision = current.revision; profile.pruneInputSetHash = selector.pruneInputSetHash;
+    return;
+  }
+  return unavailable();
+}
 export function generationDescriptor(generation: string): GenerationDescriptor {
   if (!validGeneration(generation)) return unavailable();
   return { schema: "agent-mem.generation/v1", generation, legacySchema: "agent-hub.memory/v1" };
@@ -83,8 +143,9 @@ export function validateGeneration(memoryDir: string, generation: string): strin
 export function resolveProfile(memoryDir: string, explicit?: ProfileInput): BoundProfile {
   const home = existsSync(memoryDir) ? realPath(memoryDir) : canonicalPath(memoryDir), selected = readSelector(home);
   if (explicit !== undefined && explicit !== "shared-v1" && (!explicit || typeof explicit !== "object" || !keys(explicit, ["generation"]) || !validGeneration(explicit.generation))) return unavailable();
+  if (selected.selector?.schema === "agent-mem.profile/v2" && explicit !== undefined) return unavailable();
   const generation = explicit === "shared-v1" ? undefined : explicit?.generation ?? (selected.selector?.kind === "generation" ? selected.selector.generation : undefined);
-  return generation ? { kind: "generation", home, dir: validateGeneration(home, generation), generation, selectorRevision: selected.revision }
+  return generation ? { kind: "generation", home, dir: validateGeneration(home, generation), generation, selectorRevision: selected.revision, ...(selected.selector?.schema === "agent-mem.profile/v2" ? { foreignPruneFormat: selected.selector.foreignPruneFormat, pruneInputSetHash: selected.selector.pruneInputSetHash } : {}) }
     : { kind: "shared-v1", home, dir: home, selectorRevision: selected.revision };
 }
 
@@ -142,7 +203,12 @@ export async function withProfileLock<T>(memoryDir: string, work: () => T | Prom
       await new Promise(resolve => setTimeout(resolve, Math.min(25, Math.max(1, deadline - Date.now()))));
       continue;
     }
-    try { return await work(); }
+    try {
+      const result = work();
+      // A synchronous publisher must release its lock before a queued sync reader can block this event loop.
+      if (result !== null && (typeof result === "object" || typeof result === "function") && typeof (result as PromiseLike<T>).then === "function") return await result;
+      return result;
+    }
     finally {
       // A live owner's token cannot be reclaimed; do not remove a file another actor replaced.
       if (existsSync(file) && !lstatSync(file).isSymbolicLink() && readFileSync(file, "utf8") === owner) { unlinkSync(file); fsyncDirectory(memoryDir); }

package/src/memory/migrate.ts

@@ -105,6 +105,7 @@ function refuseShardSelection(memoryDir: string): void {
 }
 
 export async function migrate(options: MigrateOptions): Promise<MigrationResult> {
+  if (readSelector(options.memoryDir).selector?.schema === "agent-mem.profile/v2") throw new Error("public prune view is forward-only; deactivation is unavailable");
   if (options.authorizedPerson !== true || options.tty !== true) throw new Error("migration requires an authorized person in a terminal");
   if (!["dry-run", "apply", "resume", "deactivate"].includes(options.mode) || options.generation !== undefined && !validGeneration(options.generation)) throw new Error("invalid migration request");
   const memoryDir = existsSync(options.memoryDir) ? realPath(options.memoryDir) : canonicalPath(options.memoryDir);

package/src/memory/mutation.ts

@@ -1,6 +1,7 @@
 import { Database } from "bun:sqlite";
 import { chmodSync, lstatSync } from "node:fs";
 import { join } from "node:path";
+import { realPath } from "./platform.ts";
 
 export const MUTATION_BUSY_TIMEOUT_MS = 3000;
 // ponytail: older hubs (before consuming this agent-mem), raw/legacy log writers and any segment editor
@@ -14,12 +15,31 @@ export function mutationDatabase(dir: string, busyTimeoutMs = MUTATION_BUSY_TIME
   return db;
 }
 
-/** Sync holds a separate connection across awaits; an unrelated call on the same MemoryStore cannot bypass it. */
-export function acquireMutation(dir: string): (() => void) | undefined {
-  const db = mutationDatabase(dir);
+declare const mutationBrand: unique symbol;
+/** Callable for compatibility; authority exists only in the module-private live registry. */
+export interface MutationHandle { (): void; readonly [mutationBrand]: true }
+const mutations = new WeakMap<MutationHandle, { dir: string; dev: number; ino: number; db: Database; active: boolean }>();
+export function assertMutationHandle(handle: MutationHandle, dir: string): void {
+  const state = mutations.get(handle), stat = lstatSync(dir);
+  if (!state || !state.active || !state.db.inTransaction || stat.isSymbolicLink() || !stat.isDirectory()
+    || realPath(dir) !== state.dir || stat.dev !== state.dev || stat.ino !== state.ino) throw new Error("mutation handle unavailable or directory changed");
+}
+/** Sync holds a separate connection across awaits; an unrelated call cannot bypass it. */
+export function acquireMutation(dir: string): MutationHandle | undefined {
+  const stat = lstatSync(dir);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("mutation directory unavailable");
+  const canonical = realPath(dir), db = mutationDatabase(canonical);
   try { db.run("BEGIN IMMEDIATE"); }
   catch { db.close(); return undefined; }
-  return () => { try { db.run("ROLLBACK"); } finally { db.close(); } };
+  const release = (() => {
+    const state = mutations.get(release)!;
+    if (!state.active) return;
+    state.active = false;
+    try { db.run("ROLLBACK"); } finally { db.close(); }
+  }) as MutationHandle;
+  mutations.set(release, { dir: canonical, dev: stat.dev, ino: stat.ino, db, active: true });
+  try { assertMutationHandle(release, dir); } catch (error) { release(); throw error; }
+  return release;
 }
 
 /** Short local admission fence, never held across sync/network or data mutations. */