@staix/agent-mem 0.13.0 → 0.15.0

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. */

package/src/memory/prune-publisher-lineage.ts

@@ -0,0 +1,139 @@
+/** Private local publication authority, never a transport object or a native-row rewrite. */
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, readSync, readdirSync, unlinkSync, writeFileSync, type Stats } from "node:fs";
+import { join } from "node:path";
+import { canonicalJSON, fsyncDirectory, type BoundProfile } from "./generation.ts";
+import { assertMutationHandle, type MutationHandle } from "./mutation.ts";
+import { realPath } from "./platform.ts";
+import { validatePruneRow, type PruneRow } from "./prune.ts";
+import type { PublicPruneLineage } from "./public-prune-witness.ts";
+import { resolveShardProfile } from "./shard.ts";
+
+export interface PublisherBoundaryV1 {
+  schema: "agent-mem.prune-publisher-boundary/v1";
+  generation: string; sealHash: string; machine: string; end: number; prefixSha256: string;
+}
+const fail = (): never => { throw new Error("prune publisher boundary unavailable or changed"); };
+function guard(value: unknown): asserts value { if (!value) fail(); }
+function owned(stat: Stats, directory = false, links = 1): void {
+  guard(!stat.isSymbolicLink() && (directory ? stat.isDirectory() : stat.isFile() && stat.nlink === links)
+    && stat.uid === process.getuid?.() && (stat.mode & 0o077) === 0);
+}
+function same(a: Stats, b: Stats): boolean { return a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs; }
+function bytes(file: string, limit: number, links = 1): Buffer {
+  const before = lstatSync(file); owned(before, false, links); guard(before.size <= limit);
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const opened = fstatSync(fd); owned(opened, false, links); guard(same(before, opened));
+    const value = readFileSync(fd); guard(value.length === before.size && same(opened, fstatSync(fd)) && same(opened, lstatSync(file))); return value;
+  } finally { closeSync(fd); }
+}
+function context(profile: BoundProfile, mutation: MutationHandle): { machine: string; sealHash: string; log: string; file: string; local: string } {
+  assertMutationHandle(mutation, profile.dir);
+  guard(profile.kind === "generation" && profile.sharded && profile.foreignPruneFormat === "agent-mem.public-prune-witness/v1");
+  const current = resolveShardProfile(profile.home, profile.shardUser ? { user: true } : { project: profile.shardKey });
+  guard(current.generation === profile.generation && current.foreignPruneFormat === profile.foreignPruneFormat
+    && current.selectorRevision === profile.selectorRevision && realPath(current.dir) === realPath(profile.dir));
+  for (const dir of [profile.home, profile.dir, join(profile.dir, "local"), join(profile.dir, "log")]) owned(lstatSync(dir), true);
+  const rootMachine = JSON.parse(bytes(join(profile.home, "machine.json"), 4096).toString("utf8")) as { id?: unknown };
+  const shardMachine = JSON.parse(bytes(join(profile.dir, "machine.json"), 4096).toString("utf8")) as { id?: unknown };
+  guard(typeof rootMachine.id === "string" && /^[a-f0-9]{16}$/.test(rootMachine.id) && rootMachine.id === shardMachine.id);
+  // resolveShardProfile checks descriptor/sourceDigest; hash the original complete seal bytes too.
+  const sealHash = createHash("sha256").update(bytes(join(profile.dir, "generation-seal.json"), 4096)).digest("hex");
+  bytes(join(profile.dir, "generation.json"), 4096); bytes(join(profile.dir, "migration-sources.json"), 262144);
+  const machine = rootMachine.id, local = join(profile.dir, "local");
+  return { machine, sealHash, local, file: join(local, `publisher-boundary-${machine}.json`), log: join(profile.dir, "log", `${machine}.jsonl`) };
+}
+/** Streaming complete prefix and bounded line scan; no lifetime byte/row omission. */
+function inspect(log: string, end?: number, rows?: ReadonlyMap<string, { row: PruneRow; canonical: string }>): { end: number; hash: string; found: Set<string> } {
+  const before = lstatSync(log, { throwIfNoEntry: false });
+  if (!before) { guard(end === undefined || end === 0); return { end: 0, hash: createHash("sha256").digest("hex"), found: new Set() }; }
+  owned(before); const bound = end ?? before.size; guard(Number.isSafeInteger(bound) && bound >= 0 && bound <= before.size);
+  const fd = openSync(log, constants.O_RDONLY | constants.O_NOFOLLOW), digest = createHash("sha256"), chunk = Buffer.alloc(65536);
+  let position = 0, lineStart = 0, line: number[] = [], last = -1, boundaryNewline = bound === 0;
+  const found = new Set<string>(), older = new Set<string>();
+  try {
+    guard(same(before, fstatSync(fd)));
+    while (position < before.size) {
+      const count = readSync(fd, chunk, 0, Math.min(chunk.length, before.size - position), position); guard(count > 0);
+      if (position < bound) digest.update(chunk.subarray(0, Math.min(count, bound - position)));
+      for (let i = 0; i < count; i++) {
+        const byte = chunk[i]!; last = byte;
+        if (position + i + 1 === bound) boundaryNewline = byte === 10;
+        if (rows) {
+          if (byte === 10) {
+            guard(line.length > 0);
+            const value: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(line)));
+            const id = value && typeof value === "object" && "id" in value && typeof value.id === "string" ? value.id : undefined;
+            const candidate = id === undefined ? undefined : rows.get(id);
+            const canonical = lineStart >= bound ? canonicalJSON(value) : undefined;
+            if (candidate) {
+              if (lineStart < bound) older.add(candidate.row.id);
+              else if (canonical === candidate.canonical) { validatePruneRow(value, candidate.row.generation, "synced"); found.add(candidate.row.id); }
+            }
+            line = []; lineStart = position + i + 1;
+          } else { line.push(byte); guard(line.length <= 1024 * 1024); }
+        }
+      }
+      position += count;
+      if (!rows && position === before.size) break;
+    }
+    guard(boundaryNewline && (before.size === 0 || last === 10) && same(before, fstatSync(fd)) && same(before, lstatSync(log)));
+    for (const id of older) found.delete(id);
+    return { end: bound, hash: digest.digest("hex"), found };
+  } finally { closeSync(fd); }
+}
+function decode(value: Buffer): PublisherBoundaryV1 {
+  const text = new TextDecoder("utf-8", { fatal: true }).decode(value), v = JSON.parse(text) as PublisherBoundaryV1;
+  guard(v && Object.keys(v).sort().join(",") === "end,generation,machine,prefixSha256,schema,sealHash"
+    && v.schema === "agent-mem.prune-publisher-boundary/v1" && /^[a-f0-9]{32}$/.test(v.generation)
+    && /^[a-f0-9]{16}$/.test(v.machine) && /^[a-f0-9]{64}$/.test(v.sealHash) && /^[a-f0-9]{64}$/.test(v.prefixSha256)
+    && Number.isSafeInteger(v.end) && v.end >= 0 && text === canonicalJSON(v) + "\n"); return v;
+}
+/** Recover only an exact private temp/final inode pair while holding the real kernel fence. */
+function recover(file: string, local: string): void {
+  const final = lstatSync(file, { throwIfNoEntry: false }); if (!final || final.nlink === 1) return;
+  owned(final, false, 2); decode(bytes(file, 4096, 2));
+  const candidates = readdirSync(local).filter(name => /^\.publisher-boundary-[a-f0-9]{32}\.tmp$/.test(name))
+    .map(name => join(local, name)).filter(name => { const stat = lstatSync(name); return stat.dev === final.dev && stat.ino === final.ino; });
+  guard(candidates.length === 1); const temp = candidates[0]!; owned(lstatSync(temp), false, 2);
+  guard(same(final, lstatSync(file)) && same(final, lstatSync(temp))); unlinkSync(temp); fsyncDirectory(local);
+}
+export function assertPublisherBoundary(profile: BoundProfile, mutation: MutationHandle): PublisherBoundaryV1 {
+  const ctx = context(profile, mutation); recover(ctx.file, ctx.local);
+  const value = decode(bytes(ctx.file, 4096));
+  guard(value.generation === profile.generation && value.machine === ctx.machine && value.sealHash === ctx.sealHash);
+  guard(inspect(ctx.log, value.end).hash === value.prefixSha256); assertMutationHandle(mutation, profile.dir); return value;
+}
+/** Explicit sync-only admission: existing complete own log is a conservative migration upper bound. */
+export function ensurePublisherBoundary(profile: BoundProfile, mutation: MutationHandle): PublisherBoundaryV1 {
+  const ctx = context(profile, mutation); recover(ctx.file, ctx.local);
+  if (lstatSync(ctx.file, { throwIfNoEntry: false })) return assertPublisherBoundary(profile, mutation);
+  const prefix = inspect(ctx.log), value: PublisherBoundaryV1 = { schema: "agent-mem.prune-publisher-boundary/v1", generation: profile.generation!,
+    sealHash: ctx.sealHash, machine: ctx.machine, end: prefix.end, prefixSha256: prefix.hash };
+  const temp = join(ctx.local, `.publisher-boundary-${randomBytes(16).toString("hex")}.tmp`), fd = openSync(temp, "wx", 0o600);
+  try { writeFileSync(fd, canonicalJSON(value) + "\n"); fsyncSync(fd); } finally { closeSync(fd); }
+  // A crash leaves either a harmless unregistered temp or an exact recoverable pair.
+  linkSync(temp, ctx.file); fsyncDirectory(ctx.local); unlinkSync(temp); fsyncDirectory(ctx.local);
+  return assertPublisherBoundary(profile, mutation);
+}
+/** Verify one candidate set with one complete JSONL parse, independent of the candidate count. */
+export function publisherPruneLineages(profile: BoundProfile, mutation: MutationHandle, rows: readonly PruneRow[]): Map<string, PublicPruneLineage> {
+  const boundary = assertPublisherBoundary(profile, mutation), candidates = new Map<string, { row: PruneRow; canonical: string }>();
+  for (const row of rows) {
+    if (row.machine !== boundary.machine || row.generation !== boundary.generation || row.placement !== "synced") continue;
+    validatePruneRow(row, boundary.generation, "synced");
+    const canonical = canonicalJSON(row), previous = candidates.get(row.id);
+    guard(!previous || previous.canonical === canonical); candidates.set(row.id, { row, canonical });
+  }
+  const result = new Map<string, PublicPruneLineage>();
+  if (!candidates.size) return result;
+  const ctx = context(profile, mutation), proof = inspect(ctx.log, boundary.end, candidates);
+  guard(proof.hash === boundary.prefixSha256); assertPublisherBoundary(profile, mutation);
+  for (const id of proof.found) result.set(id, { kind: "post-seal", seal: boundary.sealHash, end: boundary.end });
+  return result;
+}
+/** Compatibility entry point; batch callers avoid rescanning once per original. */
+export function publisherPruneLineage(profile: BoundProfile, mutation: MutationHandle, row: PruneRow): PublicPruneLineage | undefined {
+  return publisherPruneLineages(profile, mutation, [row]).get(row.id);
+}

package/src/memory/public-prune-activation.ts

@@ -0,0 +1,260 @@
+/** Explicit person-only, forward-only v2 activation. No read/capture path calls this API.
+ * Checkpoints are fault seams after intent, shard marker, selector and intent removal.
+ * A caller resumes an interrupted operation from its immutable direct-profile journal. */
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { canonicalJSON, fsyncDirectory, hashJSON, readSelector, withProfileLock, writeProfileJSON, type BoundProfile } from "./generation.ts";
+import { readShardDescriptor, resolveShardProfile, shardDir, shardKeyHash, userShardDir, SHARDED_V2_FIELDS } from "./shard.ts";
+import { acquireMutation } from "./mutation.ts";
+import { assertNoLiveReaders } from "./reader-lease.ts";
+import { aliasLogPath } from "./aliases.ts";
+import { realPath } from "./platform.ts";
+import { buildPublicPruneIndex } from "./store.ts";
+import { reducePublicPruneInputs } from "./public-prune-inputs.ts";
+import { PUBLIC_PRUNE_INTENT, publicPruneViewHash, readPublicPruneViewForActivation, validatePublicPruneView, type PublicPruneViewV1 } from "./public-prune-view.ts";
+
+export type PublicPruneActivationStage = "after-intent" | "after-shards" | "after-profile" | "after-remove";
+export interface PublicPruneActivationOptions {
+  memoryDir: string; mode: "dry-run" | "apply" | "resume"; authorizedPerson: boolean; tty: boolean;
+  view?: PublicPruneViewV1; checkpoint?: (stage: PublicPruneActivationStage) => void | Promise<void>;
+}
+export interface PublicPruneActivationResult { mode: PublicPruneActivationOptions["mode"]; generation: string; active: boolean; alreadyActive?: boolean; realms: number; viewHash: string; maskBuildCheck: "deferred" | "verified" }
+interface Realm { key: string; profile: BoundProfile; metadata: string; sourceHash: string; native: string[] }
+interface Intent {
+  schema: "agent-mem.public-prune-activation/v1"; home: string; generation: string; aliases: string;
+  previousProfile: string; previousShards: string; finalProfile: string; finalShards: string; finalProfileHash: string; finalShardsHash: string;
+  view: PublicPruneViewV1; realms: Realm[];
+}
+// ponytail: one complete 1 MiB journal; a larger installation needs a versioned segmented intent.
+const MAX = 1024 * 1024;
+const fail = (): never => { throw new Error("public prune activation unavailable; inspect or resume the pending activation"); };
+function guard(ok: unknown): asserts ok { if (!ok) fail(); }
+const hex = (v: unknown, n: number): v is string => typeof v === "string" && v.length === n && /^[a-f0-9]+$/.test(v);
+const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+const exact = (v: Record<string, unknown>, keys: string[]) => Reflect.ownKeys(v).length === keys.length && keys.every(key => Object.hasOwn(v, key));
+function owned(path: string, directory = false, links = 1) {
+  const stat = lstatSync(path); guard(!stat.isSymbolicLink() && (directory ? stat.isDirectory() : stat.isFile() && stat.nlink === links)
+    && stat.uid === process.getuid?.() && (stat.mode & 0o077) === 0); return stat;
+}
+function raw(path: string, optional = false, links = 1): string {
+  if (optional && !lstatSync(path, { throwIfNoEntry: false })) return "absent";
+  const stat = owned(path, false, links); guard((optional || stat.size > 0) && stat.size <= MAX);
+  const bytes = readFileSync(path); guard(bytes.length === stat.size); const next = owned(path, false, links);
+  guard(next.dev === stat.dev && next.ino === stat.ino && next.mtimeMs === stat.mtimeMs);
+  return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+}
+function readProfileBytes(home: string): string {
+  const file = join(home, "profile.json"); if (!lstatSync(file, { throwIfNoEntry: false })) return "absent";
+  const text = raw(file); guard(text !== "absent"); return text;
+}
+const optionalBytes = (file: string) => lstatSync(file, {throwIfNoEntry:false}) ? {exists:true,bytes:raw(file)} : {exists:false};
+const aliases = (home: string) => { const stat = owned(home, true); return hashJSON({ aliases: optionalBytes(aliasLogPath(home)), machine: raw(join(home, "machine.json")), dev: stat.dev, ino: stat.ino }); };
+function metadata(profile: BoundProfile): string {
+  const stat = owned(profile.dir, true);
+  return hashJSON({ dev: stat.dev, ino: stat.ino, files: ["project.json", "generation.json", "generation-seal.json", "migration-sources.json", "machine.json"].map(name => [name, name === "project.json" ? optionalBytes(join(profile.dir, name)) : {exists:true,bytes:raw(join(profile.dir, name))}]) });
+}
+function enumerate(home: string): { key: string; profile: BoundProfile }[] {
+  const result: { key: string; profile: BoundProfile }[] = [], projects = join(home, "projects");
+  if (lstatSync(projects, { throwIfNoEntry: false })) {
+    owned(projects, true); const names = readdirSync(projects).sort(); guard(names.length <= 1024);
+    for (const hash of names) {
+      guard(hex(hash, 16)); const dir = join(projects, hash); owned(dir, true);
+      if (!lstatSync(join(dir, "generation.json"), { throwIfNoEntry: false })) continue;
+      const descriptor = readShardDescriptor(home, hash); guard(descriptor && shardKeyHash(descriptor.key) === hash);
+      result.push({ key: `project:${descriptor.key}`, profile: resolveShardProfile(home, { project: descriptor.key }) });
+    }
+  }
+  if (lstatSync(join(userShardDir(home), "generation.json"), { throwIfNoEntry: false })) result.push({ key: "user", profile: resolveShardProfile(home, { user: true }) });
+  guard(result.length > 0); return result.sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+}
+function realmBinding(home: string, realms: Realm[]): void {
+  const expected = new Set(realms.map(realm => realm.profile.dir)), found = new Set<string>(), projects = join(home, "projects");
+  if (lstatSync(projects, { throwIfNoEntry: false })) for (const name of readdirSync(projects)) {
+    guard(hex(name, 16)); const dir = join(projects, name);
+    if (lstatSync(join(dir, "generation.json"), { throwIfNoEntry: false })) { owned(dir, true); found.add(dir); }
+  }
+  const user = userShardDir(home); if (lstatSync(join(user, "generation.json"), { throwIfNoEntry: false })) { owned(user, true); found.add(user); }
+  guard(found.size === expected.size && [...expected].every(dir => found.has(dir)));
+  for (const realm of realms) guard(metadata(realm.profile) === realm.metadata);
+}
+/** Atomic create-once publication, recovering only this exact complete staging pair. */
+function immutable(file: string, text: string): void {
+  const base = dirname(file); if (!lstatSync(base, { throwIfNoEntry: false })) { mkdirSync(base, { mode: 0o700 }); fsyncDirectory(dirname(base)); } owned(base, true);
+  const bytes = Buffer.from(text), temp = file + ".pending-" + createHash("sha256").update(bytes).digest("hex");
+  if (lstatSync(file, { throwIfNoEntry: false })) {
+    const stat = lstatSync(file);
+    if (stat.nlink === 2) {
+      const pending = owned(temp, false, 2); owned(file, false, 2); guard(stat.dev === pending.dev && stat.ino === pending.ino && stat.size === bytes.length);
+      const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+      try {
+        const opened = fstatSync(fd); guard(opened.dev === stat.dev && opened.ino === stat.ino && opened.nlink === 2 && readFileSync(fd).equals(bytes));
+        for (const name of [file, temp]) { const named = owned(name, false, 2); guard(named.dev === opened.dev && named.ino === opened.ino && named.size === opened.size && named.mtimeMs === opened.mtimeMs); }
+        unlinkSync(temp); fsyncDirectory(base);
+      } finally { closeSync(fd); }
+    }
+    guard(raw(file) === text); return;
+  }
+  if (lstatSync(temp, { throwIfNoEntry: false })) {
+    owned(temp); // Staging is not membership; discard an incomplete crash-left prefix under the profile fence.
+    if (!readFileSync(temp).equals(bytes)) { unlinkSync(temp); fsyncDirectory(base); }
+  }
+  if (!lstatSync(temp, { throwIfNoEntry: false })) {
+    const fd = openSync(temp, "wx", 0o600); try { writeFileSync(fd, bytes); fsyncSync(fd); } finally { closeSync(fd); }
+  } else { const fd = openSync(temp, constants.O_RDONLY | constants.O_NOFOLLOW); try { fsyncSync(fd); } finally { closeSync(fd); } }
+  linkSync(temp, file); fsyncDirectory(base); unlinkSync(temp); fsyncDirectory(base);
+}
+function syncIndex(profile: BoundProfile): void {
+  const file = join(profile.dir, "index-v2.db"); owned(file); const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try { fsyncSync(fd); } finally { closeSync(fd); } fsyncDirectory(profile.dir);
+}
+function nextProfile(realm: Realm, intent: Intent): BoundProfile {
+  return { ...realm.profile, selectorRevision: hashJSON(JSON.parse(intent.finalProfile)), foreignPruneFormat: "agent-mem.public-prune-witness/v1", pruneInputSetHash: publicPruneViewHash(intent.view) };
+}
+/** Existing membership must remain in the new checked cumulative chain, not merely its mask. */
+function validateAdvance(intent: Intent): void {
+  const previous = intent.previousProfile === "absent" ? undefined : JSON.parse(intent.previousProfile);
+  const old = previous?.schema === "agent-mem.profile/v2"
+    ? readPublicPruneViewForActivation(intent.home, previous.pruneInputSetHash, intent.generation)
+    : { realms: {} as Record<string, string> };
+  guard(Object.keys(old.realms).every(key => Object.hasOwn(intent.view.realms, key)));
+  for (const [key, set] of Object.entries(intent.view.realms)) {
+    const realm = intent.realms.find(item => item.key === key); guard(realm);
+    const proof = reducePublicPruneInputs({ dir: realm.profile.dir, realm: key === "user" ? { scope: "user" } : { scope: "project", key: key.slice(8) }, receivingGeneration: intent.generation, inputSetHash: set });
+    const ancestor = old.realms[key]; guard(ancestor === undefined || proof.commitments.includes(ancestor));
+  }
+}
+function verify(intent: Intent, profileBytes: string, shardBytes: string): void {
+  guard(aliases(intent.home) === intent.aliases && readProfileBytes(intent.home) === profileBytes && raw(join(intent.home, "shards.json")) === shardBytes);
+  realmBinding(intent.home, intent.realms);
+  validateAdvance(intent);
+  for (const realm of intent.realms) {
+    const old = buildPublicPruneIndex(realm.profile), next = buildPublicPruneIndex(nextProfile(realm, intent));
+    guard(old.sourceHash === realm.sourceHash && next.sourceHash === realm.sourceHash && realm.native.every(id => old.targets.includes(id) && next.targets.includes(id)));
+  }
+}
+function checkedIntent(value: unknown, home: string): Intent {
+  guard(object(value) && exact(value, ["schema", "home", "generation", "aliases", "previousProfile", "previousShards", "finalProfile", "finalShards", "finalProfileHash", "finalShardsHash", "view", "realms"]));
+  guard(value.schema === "agent-mem.public-prune-activation/v1" && value.home === home && hex(value.generation, 32) && hex(value.aliases, 64));
+  for (const key of ["previousProfile", "previousShards", "finalProfile", "finalShards"]) guard(typeof value[key] === "string" && Buffer.byteLength(value[key] as string) <= MAX);
+  const view = validatePublicPruneView(value.view); guard(view.receivingGeneration === value.generation && Array.isArray(value.realms) && value.realms.length > 0 && value.realms.length <= 1025);
+  const final = JSON.parse(value.finalProfile as string), shards = JSON.parse(value.finalShards as string);
+  const shardFields = new Set<string>(SHARDED_V2_FIELDS);
+  guard(object(shards) && Object.keys(shards).every(key => shardFields.has(key)));
+  guard(hex(value.finalProfileHash, 64) && hex(value.finalShardsHash, 64) && hashJSON(final) === value.finalProfileHash && hashJSON(shards) === value.finalShardsHash);
+  guard(canonicalJSON(final) + "\n" === value.finalProfile && canonicalJSON(shards) + "\n" === value.finalShards
+    && object(final) && exact(final, ["schema", "kind", "generation", "foreignPruneFormat", "pruneInputSetHash"])
+    && final.schema === "agent-mem.profile/v2" && final.generation === value.generation && final.kind === "generation" && final.foreignPruneFormat === "agent-mem.public-prune-witness/v1" && final.pruneInputSetHash === publicPruneViewHash(view)
+    && shards.schema === "agent-mem.shards/v2" && shards.phase === "active" && shards.generation === value.generation && shards.selectorRevision === hashJSON(final));
+  const previousProfile = value.previousProfile === "absent" ? undefined : JSON.parse(value.previousProfile as string), previousShards = JSON.parse(value.previousShards as string);
+  guard(previousProfile === undefined || object(previousProfile)
+    && (previousProfile.schema === "agent-mem.profile/v1" && ["shared-v1", "generation"].includes(String(previousProfile.kind))
+      && (previousProfile.kind === "generation" ? hex(previousProfile.generation, 32) : previousProfile.generation === undefined)
+      || previousProfile.schema === "agent-mem.profile/v2" && previousProfile.kind === "generation" && previousProfile.generation === value.generation));
+  const { schema: _schema, selectorRevision: _revision, ...before } = previousShards;
+  const { schema: _nextSchema, selectorRevision: _nextRevision, ...after } = shards; guard(canonicalJSON(before) === canonicalJSON(after));
+  let previous = "";
+  for (const item of value.realms) {
+    guard(object(item) && exact(item, ["key", "profile", "metadata", "sourceHash", "native"]) && typeof item.key === "string" && item.key > previous && hex(item.metadata, 64) && hex(item.sourceHash, 64)); previous = item.key;
+    guard(object(item.profile)); const profile = item.profile;
+    guard(Object.keys(profile).every(key => ["kind", "home", "dir", "generation", "selectorRevision", "legacyHome", "legacyMainHome", "sharded", "shardKey", "shardUser", "foreignPruneFormat", "pruneInputSetHash"].includes(key)));
+    const key = item.key === "user" ? undefined : item.key.startsWith("project:") ? item.key.slice(8) : fail();
+    const dir = key === undefined ? userShardDir(home) : shardDir(home, key);
+    guard(profile.kind === "generation" && profile.home === home && profile.dir === dir && profile.generation === value.generation && profile.sharded === true
+      && profile.selectorRevision === (previousProfile === undefined ? "absent" : hashJSON(previousProfile))
+      && profile.legacyHome === join(dir, "legacy") && (profile.legacyMainHome === undefined || profile.legacyMainHome === join(dir, "legacy-main"))
+      && (key === undefined ? profile.shardUser === true && profile.shardKey === undefined : profile.shardKey === key && profile.shardUser === undefined));
+    guard(Array.isArray(item.native) && item.native.every(id => hex(id, 32)) && new Set(item.native).size === item.native.length);
+  }
+  guard(Object.keys(view.realms).every(key => (value.realms as Realm[]).some(realm => realm.key === key)));
+  guard(Buffer.byteLength(canonicalJSON(value)) <= MAX); return { ...value, view } as unknown as Intent;
+}
+/** Dry-run reads proof only and defers native/v2 mask building. Apply/resume never roll markers backward. */
+export async function activatePublicPruneView(options: PublicPruneActivationOptions): Promise<PublicPruneActivationResult> {
+  const advanced = lstatSync(join(options.memoryDir,PUBLIC_PRUNE_INTENT),{throwIfNoEntry:false});
+  if (options.mode === "resume" && advanced?.isFile()) {
+    const value=JSON.parse(raw(join(options.memoryDir,PUBLIC_PRUNE_INTENT),false,advanced.nlink));
+    if (value?.schema === "agent-mem.public-prune-advance/v1") {
+      guard(options.authorizedPerson === true && options.tty === true);
+      const {resumePublicPruneAdvance}=await import("./public-prune-advance.ts");
+      const result=await resumePublicPruneAdvance(options.memoryDir,options.checkpoint);
+      return {mode:options.mode,generation:value.generation,active:true,realms:Object.keys(value.view.realms).length,viewHash:result.viewHash,maskBuildCheck:"verified"};
+    }
+  }
+
+  guard(options.authorizedPerson === true && options.tty === true && ["dry-run", "apply", "resume"].includes(options.mode));
+  const home = realPath(options.memoryDir); owned(home, true); const rootStat = lstatSync(home), intentFile = join(home, PUBLIC_PRUNE_INTENT);
+  const pending = lstatSync(intentFile, { throwIfNoEntry: false });
+  let intent: Intent;
+  if (pending) {
+    guard(options.mode === "resume"); const text = raw(intentFile, false, pending.nlink);
+    if (pending.nlink === 2) {
+      const temp = intentFile + ".pending-" + createHash("sha256").update(text).digest("hex"), pair = owned(temp, false, 2);
+      guard(pair.dev === pending.dev && pair.ino === pending.ino);
+    } else guard(pending.nlink === 1);
+    intent = checkedIntent(JSON.parse(text), home); guard(text === canonicalJSON(intent) + "\n");
+    guard(options.view === undefined || canonicalJSON(validatePublicPruneView(options.view)) === canonicalJSON(intent.view));
+  }
+  else {
+    const selection = readSelector(home), previousProfile = readProfileBytes(home), previousShards = raw(join(home, "shards.json")), old = JSON.parse(previousShards);
+    guard(old.phase === "active" && hex(old.generation, 32));
+    const generation = old.generation, view = validatePublicPruneView(options.view ?? (selection.selector?.schema === "agent-mem.profile/v2"
+      ? readPublicPruneViewForActivation(home, selection.selector.pruneInputSetHash, generation)
+      : { schema: "agent-mem.public-prune-view/v1", receivingGeneration: generation, realms: {} })); guard(view.receivingGeneration === generation);
+    const final = { schema: "agent-mem.profile/v2", kind: "generation", generation, foreignPruneFormat: "agent-mem.public-prune-witness/v1", pruneInputSetHash: publicPruneViewHash(view) };
+    const finalShards = { ...old, schema: "agent-mem.shards/v2", selectorRevision: hashJSON(final) };
+    const realms = enumerate(home).map(realm => ({ ...realm, metadata: metadata(realm.profile), sourceHash: "0".repeat(64), native: [] as string[] }));
+    intent = checkedIntent({ schema: "agent-mem.public-prune-activation/v1", home, generation, aliases: aliases(home), previousProfile, previousShards,
+      finalProfile: canonicalJSON(final) + "\n", finalShards: canonicalJSON(finalShards) + "\n", finalProfileHash: hashJSON(final), finalShardsHash: hashJSON(finalShards), view,
+      realms }, home);
+  }
+  validateAdvance(intent);
+  if (options.mode === "dry-run") {
+    guard(readProfileBytes(home) === intent.previousProfile && raw(join(home, "shards.json")) === intent.previousShards && aliases(home) === intent.aliases);
+    realmBinding(home, intent.realms);
+    return { mode: options.mode, generation: intent.generation, active: intent.previousProfile === intent.finalProfile && intent.previousShards === intent.finalShards, realms: intent.realms.length, viewHash: publicPruneViewHash(intent.view), maskBuildCheck: "deferred" };
+  }
+  if (!pending && intent.previousProfile !== "absent" && JSON.parse(intent.previousProfile).schema === "agent-mem.profile/v2") {
+    // Only the first reader-floor transition quiesces. Later views preserve native masks and grow foreign masks in place.
+    const alreadyActive = intent.previousProfile === intent.finalProfile && intent.previousShards === intent.finalShards;
+    if (!alreadyActive) {
+      const { advancePublicPruneView } = await import("./public-prune-advance.ts");
+      await advancePublicPruneView({ memoryDir: home, view: intent.view, expectedRevision: hashJSON(JSON.parse(intent.previousProfile)), checkpoint: options.checkpoint });
+    }
+    return { mode: options.mode, generation: intent.generation, active: true, ...(alreadyActive ? {alreadyActive:true} : {}), realms: intent.realms.length, viewHash: publicPruneViewHash(intent.view), maskBuildCheck: "verified" };
+  }
+  return withProfileLock(home, async () => {
+    const releases: (() => void)[] = [];
+    try {
+      guard(lstatSync(home).dev === rootStat.dev && lstatSync(home).ino === rootStat.ino);
+      const dirs = [...new Set([home, ...intent.realms.map(realm => realm.profile.dir)])].sort();
+      for (const dir of dirs) { assertNoLiveReaders(dir, {includeShards:true}); const release = acquireMutation(dir); guard(release); releases.push(release); }
+      validateAdvance(intent);
+      if (pending) immutable(intentFile, canonicalJSON(intent) + "\n");
+      if (!pending) {
+        guard(readProfileBytes(home) === intent.previousProfile && raw(join(home, "shards.json")) === intent.previousShards && aliases(home) === intent.aliases);
+        realmBinding(home, intent.realms);
+        intent = checkedIntent({ ...intent, realms: intent.realms.map(realm => {
+          const built = buildPublicPruneIndex(realm.profile); return { ...realm, sourceHash: built.sourceHash, native: [...built.targets].sort() };
+        }) }, home);
+      }
+      const viewHash = publicPruneViewHash(intent.view);
+      immutable(join(home, "public-prune-input-sets", viewHash + ".json"), canonicalJSON(intent.view) + "\n");
+      readPublicPruneViewForActivation(home, viewHash, intent.generation);
+      let profile = readProfileBytes(home), shards = raw(join(home, "shards.json"));
+      guard((profile === intent.previousProfile || profile === intent.finalProfile) && (shards === intent.previousShards || shards === intent.finalShards));
+      guard(profile !== intent.finalProfile || shards === intent.finalShards);
+      verify(intent, profile, shards); for (const realm of intent.realms) syncIndex(nextProfile(realm, intent));
+      if (!pending && profile === intent.finalProfile && shards === intent.finalShards) return { mode: options.mode, generation: intent.generation, active: true, alreadyActive: true, realms: intent.realms.length, viewHash, maskBuildCheck: "verified" };
+      immutable(intentFile, canonicalJSON(intent) + "\n");
+      await options.checkpoint?.("after-intent"); verify(intent, profile, shards);
+      if (shards !== intent.finalShards) { writeProfileJSON(join(home, "shards.json"), JSON.parse(intent.finalShards)); shards = intent.finalShards; }
+      await options.checkpoint?.("after-shards"); verify(intent, profile, shards);
+      if (profile !== intent.finalProfile) { writeProfileJSON(join(home, "profile.json"), JSON.parse(intent.finalProfile)); profile = intent.finalProfile; }
+      await options.checkpoint?.("after-profile"); verify(intent, profile, shards);
+      guard(raw(intentFile) === canonicalJSON(intent) + "\n"); unlinkSync(intentFile); fsyncDirectory(home);
+      await options.checkpoint?.("after-remove"); verify(intent, profile, shards);
+      return { mode: options.mode, generation: intent.generation, active: true, realms: intent.realms.length, viewHash, maskBuildCheck: "verified" };
+    } finally { for (const release of releases.reverse()) release(); }
+  });
+}