@staix/agent-mem 0.13.0 → 0.14.0

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

@@ -0,0 +1,139 @@
+/** Root selector commitment only; this module never writes or activates a profile. */
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync, type Stats } from "node:fs";
+import { join } from "node:path";
+import { canonicalJSON, hashJSON, PROFILE_LOCK_TIMEOUT_MS } from "./generation.ts";
+import { realPath } from "./platform.ts";
+
+export const PUBLIC_PRUNE_INTENT = "public-prune-view.intent.json";
+const MAX_BYTES = 65_536;
+export interface PublicPruneViewV1 {
+  schema: "agent-mem.public-prune-view/v1";
+  receivingGeneration: string;
+  realms: Record<string, string>;
+}
+const unavailable = (): never => { throw new Error("public prune view unavailable"); };
+function guard(ok: unknown): asserts ok { if (!ok) unavailable(); }
+function protectedCall<T>(work: () => T): T { try { return work(); } catch { return unavailable(); } }
+const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value)
+  && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+const hex = (value: unknown, size: number): value is string => typeof value === "string" && value.length === size && /^[a-f0-9]+$/.test(value);
+function realmKey(value: string): boolean {
+  if (!value.isWellFormed()) return false;
+  if (value === "user") return true;
+  if (!value.startsWith("project:")) return false;
+  const key = value.slice("project:".length);
+  return key.length > 0 && key === key.trim() && !/\p{Cc}/u.test(key);
+}
+export function validatePublicPruneView(input: unknown): PublicPruneViewV1 {
+  return protectedCall(() => {
+    guard(object(input) && Reflect.ownKeys(input).length === 3 && ["schema", "receivingGeneration", "realms"].every(key => Object.hasOwn(input, key)));
+    guard(input.schema === "agent-mem.public-prune-view/v1" && hex(input.receivingGeneration, 32) && object(input.realms));
+    const keys = Object.keys(input.realms).sort();
+    guard(Reflect.ownKeys(input.realms).length === keys.length && keys.length <= Math.floor(MAX_BYTES / 64));
+    const realms: Record<string, string> = {}; let minimumBytes = 0;
+    for (const key of keys) {
+      minimumBytes += Buffer.byteLength(key, "utf8") + 64; guard(minimumBytes <= MAX_BYTES);
+      const hash = input.realms[key]; guard(realmKey(key) && hex(hash, 64));
+      Object.defineProperty(realms, key, { value: hash, enumerable: true, writable: true, configurable: true });
+    }
+    const value: PublicPruneViewV1 = { schema: input.schema, receivingGeneration: input.receivingGeneration, realms };
+    guard(Buffer.byteLength(canonicalJSON(value), "utf8") <= MAX_BYTES);
+    return value;
+  });
+}
+export function publicPruneViewHash(view: PublicPruneViewV1): string { return hashJSON(validatePublicPruneView(view)); }
+/** A v2 reader may wait for a short cooperating writer, never authorize or repair one.
+ * No liveness helper, network call, PID exemption or mutation occurs on this path. */
+export function waitForPublicPruneWriter(home: string, absoluteDeadline?: number): void {
+  protectedCall(() => {
+    const deadline = Math.min(absoluteDeadline ?? Infinity, Date.now() + PROFILE_LOCK_TIMEOUT_MS);
+    const intentFile = join(home, PUBLIC_PRUNE_INTENT), lockFile = join(home, "profile.lock");
+    if (!lstatSync(intentFile, { throwIfNoEntry: false }) && !lstatSync(lockFile, { throwIfNoEntry: false })) return;
+    const small = (file: string, limit: number): Record<string, unknown> => {
+      const before = lstatSync(file); privateStat(before); guard(before.size > 0 && before.size <= limit);
+      const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+      try {
+        const opened = fstatSync(fd); privateStat(opened); guard(opened.size > 0 && opened.size <= limit);
+        const bytes = Buffer.alloc(opened.size + 1); let count = 0;
+        while (count < bytes.length) { const read = readSync(fd, bytes, count, bytes.length - count, count); if (!read) break; count += read; }
+        const after = fstatSync(fd); privateStat(after); guard(count === opened.size && same(opened, after));
+        const parsed: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes.subarray(0, count))); guard(object(parsed)); return parsed;
+      } finally { closeSync(fd); }
+    };
+    const profileFile = join(home, "profile.json");
+    if (!lstatSync(profileFile, { throwIfNoEntry: false })) return; // Implicit shared-v1 has no selector marker.
+    const profile = small(profileFile, MAX_BYTES);
+    if (profile.schema !== "agent-mem.profile/v2") return; // v1 admission/intent behavior is unchanged.
+    for (;;) {
+      try {
+        const intent = lstatSync(intentFile, { throwIfNoEntry: false }), lock = lstatSync(lockFile, { throwIfNoEntry: false });
+        if (!intent && !lock) return;
+        if (lock) {
+          privateStat(lock);
+          if (lock.size) {
+            const owner = small(lockFile, 4096);
+            guard(Reflect.ownKeys(owner).length === 3 && Number.isSafeInteger(owner.pid) && Number(owner.pid) > 0 && hex(owner.signature, 64) && hex(owner.token, 32));
+          }
+        }
+        if (intent?.nlink === 2) {
+          // Create-once publication briefly links the complete staging inode to its final
+          // name before fsync/unlink. Wait under an owned complete writer lock, without
+          // reading or trusting that not-yet-independent intent as published evidence.
+          guard(lock && lock.size > 0 && intent.isFile() && !intent.isSymbolicLink()
+            && intent.uid === process.getuid?.() && (intent.mode & 0o077) === 0
+            && intent.size > 0 && intent.size <= 1024 * 1024);
+        } else if (intent) {
+          const pending = small(intentFile, 1024 * 1024);
+          guard(pending.schema === "agent-mem.public-prune-advance/v1" && pending.home === realPath(home) && pending.generation === profile.generation);
+        }
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; // Publication disappeared normally; retry the bounded observation.
+      }
+      const remaining = deadline - Date.now(); guard(remaining > 0); Bun.sleepSync(Math.min(5, remaining));
+    }
+  });
+}
+/** Any unresolved intent blocks reads. Never remove it, including malformed bytes. */
+export function assertNoPublicPruneIntent(home: string, absoluteDeadline?: number): void {
+  protectedCall(() => { waitForPublicPruneWriter(home, absoluteDeadline); guard(!lstatSync(join(home, PUBLIC_PRUNE_INTENT), { throwIfNoEntry: false })); });
+}
+function privateStat(stat: Stats, directory = false): void {
+  guard(!stat.isSymbolicLink() && (directory ? stat.isDirectory() : stat.isFile() && stat.nlink === 1));
+  guard(stat.uid === process.getuid?.() && (stat.mode & 0o077) === 0);
+}
+function same(left: Stats, right: Stats): boolean {
+  return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs;
+}
+/** Trusted activation bootstrap reads the artifact while intent fences ordinary readers. */
+export function readPublicPruneViewForActivation(home: string, hash: string, generation: string): PublicPruneViewV1 {
+  return protectedCall(() => {
+    guard(hex(hash, 64) && hex(generation, 32));
+    const original = lstatSync(home); privateStat(original, true);
+    const root = realPath(home), rootStat = lstatSync(root); privateStat(rootStat, true); guard(rootStat.dev === original.dev && rootStat.ino === original.ino);
+    const directory = join(root, "public-prune-input-sets"), dirStat = lstatSync(directory); privateStat(dirStat, true);
+    const file = join(directory, `${hash}.json`), before = lstatSync(file); privateStat(before); guard(before.size > 0 && before.size <= MAX_BYTES);
+    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const opened = fstatSync(fd); privateStat(opened); guard(same(before, opened));
+      const bytes = Buffer.alloc(before.size + 1); let count = 0;
+      while (count < bytes.length) { const read = readSync(fd, bytes, count, bytes.length - count, count); if (read === 0) break; count += read; }
+      guard(count === before.size);
+      const after = fstatSync(fd), named = lstatSync(file); privateStat(after); privateStat(named); guard(same(before, after) && same(after, named));
+      const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes.subarray(0, count));
+      const view = validatePublicPruneView(JSON.parse(text)), canonical = canonicalJSON(view);
+      guard(text === canonical || text === canonical + "\n");
+      guard(view.receivingGeneration === generation && hashJSON(view) === hash);
+      const currentRoot = lstatSync(root), currentDir = lstatSync(directory), currentHome = lstatSync(home);
+      privateStat(currentRoot, true); privateStat(currentDir, true); privateStat(currentHome, true);
+      guard(currentRoot.dev === rootStat.dev && currentRoot.ino === rootStat.ino && currentHome.dev === original.dev && currentHome.ino === original.ino
+        && currentDir.dev === dirStat.dev && currentDir.ino === dirStat.ino);
+      return view;
+    } finally { closeSync(fd); }
+  });
+}
+
+export function readPublicPruneView(home: string, hash: string, generation: string, absoluteDeadline?: number): PublicPruneViewV1 {
+  assertNoPublicPruneIntent(home, absoluteDeadline);
+  const result = readPublicPruneViewForActivation(home, hash, generation);
+  assertNoPublicPruneIntent(home, absoluteDeadline); return result;
+}

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

@@ -0,0 +1,168 @@
+/** Layer 1 only: pure complete public-pack proof, never publication or an active mask. */
+import { createHash } from "node:crypto";
+import { types } from "node:util";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { reducePruneRows, validatePruneRow, pruneRowHash, type PruneRow, type PruneSourceRow } from "./prune.ts";
+import { decodeShardPack, SHARD_PACK_MAX_BYTES, type ShardSyncRealm } from "./shard-sync-format.ts";
+
+export const PUBLIC_PRUNE_MANIFEST_MAX_BYTES = 65_536;
+export const PUBLIC_PRUNE_MAX_WITNESSES = 64, PUBLIC_PRUNE_MAX_PACKS = 65;
+export type PublicPruneLineage = { kind: "native-generation"; seal: string } | { kind: "post-seal"; seal: string; end: number };
+interface Occurrence { pack: string; blob: string }
+export interface PublicPruneWitnessV1 {
+  schema: "agent-mem.public-prune-witness/v1";
+  realm: ShardSyncRealm;
+  prune: PruneRow;
+  lineage: PublicPruneLineage;
+  pruneOccurrence: Occurrence;
+  witnesses: (Occurrence & { id: string; rowHash: string })[];
+}
+/** Supplied only from the owned, audited selected-realm source path (Layer 4).
+ * Raw bytes prove content, not private-remote consent or authenticity. A flag,
+ * outgoing row selection or old hold receipt cannot substitute for these packs.
+ */
+export interface PublicPruneEvidence {
+  realm: ShardSyncRealm;
+  packs: readonly (Occurrence & { bytes: Uint8Array })[];
+}
+export interface VerifiedPublicPruneWitness {
+  status: "verified"; manifest: PublicPruneWitnessV1; hash: string;
+}
+export type PublicPruneVerification = VerifiedPublicPruneWitness | { status: "invalid" }
+  | { status: "unsupported_lineage"; reason: "lineage_missing" | "lineage_unsupported" };
+type Candidate = Omit<PublicPruneWitnessV1, "lineage"> & { lineage?: unknown };
+const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+const exact = (v: Record<string, unknown>, keys: string[]): boolean => Object.keys(v).length === keys.length && keys.every(k => Object.hasOwn(v, k));
+const hex = (v: unknown, n: number): v is string => typeof v === "string" && v.length === n && new RegExp(`^[a-f0-9]{${n}}$`).test(v);
+const bad = (): never => { throw new Error("public prune witness invalid or unavailable"); };
+function guard(ok: unknown): asserts ok { if (!ok) bad(); }
+function realm(input: unknown): ShardSyncRealm {
+  guard(object(input));
+  if (input.scope === "user") { guard(exact(input, ["scope"])); return { scope: "user" }; }
+  guard(input.scope === "project" && exact(input, ["scope", "key"]) && typeof input.key === "string" && input.key.length > 0);
+  guard(Buffer.byteLength(input.key, "utf8") <= PUBLIC_PRUNE_MANIFEST_MAX_BYTES);
+  return { scope: "project", key: input.key };
+}
+function occurrence(input: unknown, witness = false): Occurrence {
+  guard(object(input) && exact(input, witness ? ["pack", "blob", "id", "rowHash"] : ["pack", "blob"]));
+  guard(typeof input.pack === "string" && input.pack.length === 140 && /^rows\/[a-f0-9]{64}\/[a-f0-9]{64}\.jsonl$/.test(input.pack) && hex(input.blob, 40));
+  return { pack: input.pack, blob: input.blob };
+}
+/** Check the portable JSON shape and exact encoded size before cloning unknown lineage.
+ * Iterative traversal bounds cycles, giant scalars and shared subtrees without a new depth ceiling. */
+function boundLineage(input: unknown, budget: number): void {
+  guard(budget >= 0);
+  const active = new WeakSet<object>(), stack: { value: unknown; exit?: boolean }[] = [{ value: input }];
+  const spend = (bytes: number) => { budget -= bytes; guard(budget >= 0); };
+  const stringBytes = (value: string) => { guard(value.length <= budget); return Buffer.byteLength(JSON.stringify(value), "utf8"); };
+  while (stack.length) {
+    const frame = stack.pop()!, value = frame.value;
+    if (frame.exit) { active.delete(value as object); continue; }
+    if (typeof value === "string") { spend(stringBytes(value)); continue; }
+    if (value === null || typeof value === "boolean") { spend(value === null || value === true ? 4 : 5); continue; }
+    if (typeof value === "number") { guard(Number.isFinite(value)); spend(JSON.stringify(value).length); continue; }
+    guard(value && typeof value === "object" && !types.isProxy(value) && !active.has(value));
+    const array = Array.isArray(value), prototype = Object.getPrototypeOf(value);
+    guard(array ? prototype === Array.prototype : prototype === Object.prototype || prototype === null);
+    active.add(value); stack.push({ value, exit: true }); spend(2);
+    let count = 0;
+    if (array) { guard(value.length <= budget); if (value.length) spend(value.length - 1); }
+    for (const key in value) {
+      if (!Object.hasOwn(value, key)) continue;
+      const field = Object.getOwnPropertyDescriptor(value, key)!;
+      guard("value" in field && field.enumerable);
+      if (array) { const index = Number(key); guard(Number.isInteger(index) && index >= 0 && index < value.length && String(index) === key); }
+      else spend(stringBytes(key) + 1 + (count ? 1 : 0));
+      count++; stack.push({ value: field.value });
+    }
+    if (array) guard(count === value.length); // JSON arrays have no holes or extra enumerable fields.
+  }
+}
+function candidate(input: unknown): Candidate {
+  guard(object(input));
+  guard(exact(input, ["schema", "realm", "prune", "pruneOccurrence", "witnesses", ...(Object.hasOwn(input, "lineage") ? ["lineage"] : [])]));
+  guard(input.schema === "agent-mem.public-prune-witness/v1" && Array.isArray(input.witnesses) && input.witnesses.length <= PUBLIC_PRUNE_MAX_WITNESSES);
+  guard(object(input.prune) && Array.isArray(input.prune.targets) && input.prune.targets.length <= 32);
+  const prune = validatePruneRow(input.prune, undefined, "synced"), selected = realm(input.realm);
+  guard(hex(prune.generation, 32) && hex(prune.machine, 16));
+  const needed = new Map<string, string>();
+  for (const target of prune.targets) for (const ref of [target, target.basis]) {
+    guard(!needed.has(ref.id) || needed.get(ref.id) === ref.rowHash); needed.set(ref.id, ref.rowHash);
+  }
+  let previous = "";
+  const witnesses = input.witnesses.map(value => {
+    const where = occurrence(value, true); guard(object(value) && hex(value.id, 32) && hex(value.rowHash, 64));
+    guard(value.id > previous && needed.get(value.id) === value.rowHash); previous = value.id;
+    return { ...where, id: value.id, rowHash: value.rowHash };
+  });
+  guard(witnesses.length === needed.size);
+  const result: Candidate = { schema: input.schema, realm: selected, prune, pruneOccurrence: occurrence(input.pruneOccurrence), witnesses };
+  const baseBytes = Buffer.byteLength(canonicalJSON(result), "utf8");
+  guard(baseBytes <= PUBLIC_PRUNE_MANIFEST_MAX_BYTES);
+  const origin = Object.getOwnPropertyDescriptor(input, "lineage");
+  if (origin) {
+    guard("value" in origin);
+    const value: unknown = origin.value;
+    if (value !== undefined) {
+      boundLineage(value, PUBLIC_PRUNE_MANIFEST_MAX_BYTES - baseBytes - Buffer.byteLength(',"lineage":'));
+      result.lineage = structuredClone(value);
+    }
+  }
+  guard(Buffer.byteLength(canonicalJSON(result), "utf8") <= PUBLIC_PRUNE_MANIFEST_MAX_BYTES);
+  return result;
+}
+function lineage(input: unknown): PublicPruneLineage | undefined {
+  if (!object(input) || !["native-generation", "post-seal"].includes(String(input.kind))) return undefined;
+  guard(exact(input, input.kind === "native-generation" ? ["kind", "seal"] : ["kind", "seal", "end"]) && hex(input.seal, 64));
+  if (input.kind === "native-generation") return { kind: input.kind, seal: input.seal };
+  guard(Number.isSafeInteger(input.end) && (input.end as number) >= 0);
+  return { kind: "post-seal", seal: input.seal, end: input.end as number };
+}
+export function validatePublicPruneWitness(input: unknown): PublicPruneWitnessV1 {
+  try { const value = candidate(input), origin = lineage(value.lineage); guard(origin); return { ...value, lineage: origin }; }
+  catch { return bad(); }
+}
+export function publicPruneWitnessHash(input: PublicPruneWitnessV1): string { return hashJSON(validatePublicPruneWitness(input)); }
+
+export function verifyPublicPruneWitness(input: unknown, evidence: PublicPruneEvidence): PublicPruneVerification {
+  try {
+    const value = candidate(input);
+    guard(object(evidence) && exact(evidence, ["realm", "packs"]) && canonicalJSON(realm(evidence.realm)) === canonicalJSON(value.realm));
+    guard(Array.isArray(evidence.packs) && evidence.packs.length <= PUBLIC_PRUNE_MAX_PACKS);
+    const required = new Map<string, string>();
+    for (const ref of [value.pruneOccurrence, ...value.witnesses]) {
+      guard(!required.has(ref.pack) || required.get(ref.pack) === ref.blob); required.set(ref.pack, ref.blob);
+    }
+    guard(evidence.packs.length === required.size);
+    const packs = new Map<string, Map<string, PruneRow | PruneSourceRow["row"]>>(), seen = new Map<string, string>();
+    for (const pack of evidence.packs) {
+      guard(object(pack) && exact(pack, ["pack", "blob", "bytes"]) && typeof pack.pack === "string" && typeof pack.blob === "string");
+      guard(required.get(pack.pack) === pack.blob && !packs.has(pack.pack));
+      guard(pack.bytes instanceof Uint8Array && pack.bytes.byteLength > 0 && pack.bytes.byteLength <= SHARD_PACK_MAX_BYTES);
+      const bytes = Buffer.from(pack.bytes);
+      const blob = createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex");
+      guard(blob === pack.blob);
+      const rows = decodeShardPack(pack.pack, bytes, value.realm, value.prune.generation);
+      const contents = new Map<string, PruneRow | PruneSourceRow["row"]>();
+      for (let i = 0; i < rows.length; i++) {
+        const row = rows[i]!, canonical = canonicalJSON(row);
+        guard(!seen.has(row.id) || seen.get(row.id) === canonical);
+        seen.set(row.id, canonical); contents.set(row.id, row);
+      }
+      packs.set(pack.pack, contents);
+    }
+    guard(canonicalJSON(packs.get(value.pruneOccurrence.pack)?.get(value.prune.id)) === canonicalJSON(value.prune));
+    const sources: PruneSourceRow[] = [];
+    for (const witness of value.witnesses) {
+      const row = packs.get(witness.pack)?.get(witness.id);
+      guard(row && row.op !== "prune" && pruneRowHash(row) === witness.rowHash);
+      sources.push({ row, placement: "synced", publicWitness: true }); // only after complete public pack proof
+    }
+    const proof = reducePruneRows([{ row: value.prune, placement: "synced" }], { rows: sources, expiries: [] }, value.prune.generation);
+    guard(proof.invalid === 0 && proof.pending.length === 0 && proof.targets.size === value.prune.targets.length);
+    const origin = lineage(value.lineage);
+    if (!origin) return { status: "unsupported_lineage", reason: value.lineage === undefined ? "lineage_missing" : "lineage_unsupported" };
+    const manifest: PublicPruneWitnessV1 = { ...value, lineage: origin };
+    return { status: "verified", manifest, hash: hashJSON(manifest) };
+  } catch { return { status: "invalid" }; }
+}

package/src/memory/reader-lease.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { readProfileJSON, writeProfileJSON } from "./generation.ts";
 import { readerAdmissionDatabase } from "./mutation.ts";
 import { processLiveness, processSignature } from "./platform.ts";
+import { waitForPublicPruneWriter } from "./public-prune-view.ts";
 
 const READER_LEASE_SCHEMA = "agent-mem.reader-lease/v1";
 const RENEW_MS = 25_000;
@@ -12,7 +13,9 @@ interface OpenLease { refs: number; timer: ReturnType<typeof setInterval>; busyT
 const open = new Map<string, OpenLease>();
 let activeIdentity: { pid: number; signature: string } | undefined;
 
-const fileFor = (memoryDir: string, pid: number, signature: string) => join(memoryDir, "readers", `${pid}-${signature}.json`);
+type LeaseScope = "legacy" | "shard";
+const leaseFolder = (scope: LeaseScope) => scope === "shard" ? "shard-readers" : "readers";
+const fileFor = (memoryDir: string, pid: number, signature: string, scope: LeaseScope) => join(memoryDir, leaseFolder(scope), `${pid}-${signature}.json`);
 const record = (pid: number, signature: string): Lease => ({ schema: READER_LEASE_SCHEMA, pid, signature, renewedAt: new Date().toISOString() });
 
 function withFence<T>(memoryDir: string, work: () => T, busyTimeoutMs = 3000): T {
@@ -20,27 +23,27 @@ function withFence<T>(memoryDir: string, work: () => T, busyTimeoutMs = 3000): T
   try { return db.transaction(work).immediate(); } finally { db.close(); }
 }
 
-function checkReadersDir(memoryDir: string): string {
-  const dir = join(memoryDir, "readers");
+function checkReadersDir(memoryDir: string, scope: LeaseScope): string {
+  const dir = join(memoryDir, leaseFolder(scope));
   const stat = lstatSync(dir, { throwIfNoEntry: false });
   if (stat && (stat.isSymbolicLink() || !stat.isDirectory())) throw new Error("reader lease directory is not a regular directory");
   return dir;
 }
 
-function readLease(memoryDir: string, file: string): Lease | undefined {
+function readLease(memoryDir: string, file: string, scope: LeaseScope): Lease | undefined {
   try {
     const value = readProfileJSON(file) as Partial<Lease> | undefined;
     if (value === undefined) return undefined;
     if (!value || value.schema !== READER_LEASE_SCHEMA || !Number.isSafeInteger(value.pid) || value.pid! <= 0
       || typeof value.signature !== "string" || !/^[0-9a-f]{64}$/.test(value.signature)
-      || fileFor(memoryDir, value.pid!, value.signature) !== file || typeof value.renewedAt !== "string" || Number.isNaN(Date.parse(value.renewedAt))) throw new Error();
+      || fileFor(memoryDir, value.pid!, value.signature, scope) !== file || typeof value.renewedAt !== "string" || Number.isNaN(Date.parse(value.renewedAt))) throw new Error();
     return value as Lease;
   } catch { throw new Error("reader lease is unreadable or unverifiable"); }
 }
 
-function ownedLease(memoryDir: string, file: string, signature: string): void {
-  checkReadersDir(memoryDir);
-  const lease = readLease(memoryDir, file);
+function ownedLease(memoryDir: string, file: string, signature: string, scope: LeaseScope): void {
+  checkReadersDir(memoryDir, scope);
+  const lease = readLease(memoryDir, file, scope);
   if (!lease || lease.pid !== process.pid || lease.signature !== signature) throw new Error("reader lease ownership is unavailable");
 }
 
@@ -48,12 +51,17 @@ function admitReader(memoryDir: string): void {
   // The profile lock is created under the same reader admission fence, then held across migration awaits.
   // Even a malformed or stale marker refuses admission; only the profile-lock owner may reclaim it.
   try {
+    waitForPublicPruneWriter(memoryDir);
     if (lstatSync(join(memoryDir, "profile.lock"), { throwIfNoEntry: false })) throw new Error("profile lock prevents reader admission; finish or resume the migration with amem migrate --resume");
   } catch { throw new Error("profile lock prevents reader admission; finish or resume the migration with amem migrate --resume"); }
 }
 
-/** One lease per process, reference-counted across handles; an unref'd timer does not keep the process resident. */
-export function registerReaderLease(memoryDir: string, options: { busyTimeoutMs?: number; signature?: string } = {}): ReaderLease {
+/** One lease per process/home/namespace, reference-counted across handles.
+ * Shard scope shares root admission and native identity; it grants no authority.
+ * An unref'd timer does not keep the process resident. */
+export function registerReaderLease(memoryDir: string, options: { busyTimeoutMs?: number; signature?: string; scope?: "shard" } = {}): ReaderLease {
+  if (options.scope !== undefined && options.scope !== "shard") throw new Error("invalid reader lease scope");
+  const scope: LeaseScope = options.scope === "shard" ? "shard" : "legacy";
   const requestedTimeout = options.busyTimeoutMs ?? 3000;
   if (!Number.isSafeInteger(requestedTimeout) || requestedTimeout < 0 || requestedTimeout > 3000) throw new Error("invalid reader admission busy timeout");
   if (options.signature !== undefined && (typeof options.signature !== "string" || !/^[a-f0-9]{64}$/.test(options.signature))) throw new Error("invalid reader lease identity");
@@ -65,28 +73,28 @@ export function registerReaderLease(memoryDir: string, options: { busyTimeoutMs?
   // Host-only: the supplied hash must already describe this process's pinned native ps identity.
   const signature = inherited ?? options.signature ?? processSignature(pid);
   if (!signature) throw new Error("cannot establish reader lease identity");
-  const file = fileFor(memoryDir, process.pid, signature);
+  const file = fileFor(memoryDir, process.pid, signature, scope);
   const busyTimeoutMs = open.get(file)?.busyTimeoutMs ?? requestedTimeout;
   mkdirSync(memoryDir, { recursive: true, mode: 0o700 });
   withFence(memoryDir, () => {
     admitReader(memoryDir);
     const current = open.get(file);
     if (current) {
-      ownedLease(memoryDir, file, signature);
+      ownedLease(memoryDir, file, signature, scope);
       current.refs++;
       return;
     }
-    const dir = checkReadersDir(memoryDir);
+    const dir = checkReadersDir(memoryDir, scope);
     mkdirSync(dir, { recursive: true, mode: 0o700 });
     // A failed earlier close may have retained evidence. Never overwrite an unverifiable replacement.
-    const existing = readLease(memoryDir, file);
+    const existing = readLease(memoryDir, file, scope);
     if (existing && (existing.pid !== process.pid || existing.signature !== signature)) throw new Error("reader lease ownership is unavailable");
     writeProfileJSON(file, record(process.pid, signature));
     const timer = setInterval(() => {
       if (!open.has(file)) return;
       try {
         withFence(memoryDir, () => {
-          ownedLease(memoryDir, file, signature);
+          ownedLease(memoryDir, file, signature, scope);
           writeProfileJSON(file, record(process.pid, signature));
         }, busyTimeoutMs);
       } catch { /* keep unknown evidence; migration admission remains fail-closed */ }
@@ -107,7 +115,7 @@ export function registerReaderLease(memoryDir: string, options: { busyTimeoutMs?
     open.delete(file);
     try {
       withFence(memoryDir, () => {
-        ownedLease(memoryDir, file, signature);
+        ownedLease(memoryDir, file, signature, scope);
         rmSync(file);
       }, held.busyTimeoutMs);
     } catch { /* Contention or replacement keeps evidence; never remove another actor's lease. */ }
@@ -118,30 +126,34 @@ export function registerReaderLease(memoryDir: string, options: { busyTimeoutMs?
       // The held lifetime lease blocks legitimate migration. Verification reads only: no ps, DB fence or refcount mutation.
       // ponytail: no atomic same-user concurrent path-swap claim; descriptor-relative ownership checks are the upgrade path.
       admitReader(memoryDir);
-      ownedLease(memoryDir, file, signature);
+      ownedLease(memoryDir, file, signature, scope);
     },
   });
 }
 
-/** Fail closed on a live or unverifiable lease; remove only a pid confirmed gone, never by TTL. */
-export function assertNoLiveReaders(memoryDir: string, options: { onDeadLeaseRemoved?: (event: { pid: number; lease: string }) => void } = {}): { removed: number } {
+/** Default migration checks legacy readers only; v2 activation opts into both
+ * namespaces under the same root admission fence. Scope is cooperation, not authentication. */
+export function assertNoLiveReaders(memoryDir: string, options: { includeShards?: boolean; onDeadLeaseRemoved?: (event: { pid: number; lease: string }) => void } = {}): { removed: number } {
   return withFence(memoryDir, () => {
-    const dir = checkReadersDir(memoryDir);
-    let names: string[] = [];
-    try { names = readdirSync(dir).filter((name) => name.endsWith(".json")).sort(); }
-    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return { removed: 0 }; throw new Error("reader lease directory is unreadable"); }
     let removed = 0;
-    for (const name of names) {
-      if (!/^[1-9][0-9]*-[0-9a-f]{64}\.json$/.test(name)) throw new Error("unverifiable reader lease filename");
-      const file = join(dir, name);
-      const lease = readLease(memoryDir, file);
-      if (!lease) throw new Error("reader lease is unreadable or unverifiable");
-      const liveness = processLiveness(lease.pid, lease.signature);
-      if (liveness === "live") throw new Error(`legacy reader is live (pid ${lease.pid}); close it before migration`);
-      if (liveness === "unknown") throw new Error(`legacy reader liveness is unknown (pid ${lease.pid})`);
-      rmSync(file);
-      removed++;
-      options.onDeadLeaseRemoved?.({ pid: lease.pid, lease: name });
+    const scopes: LeaseScope[] = options.includeShards === true ? ["legacy", "shard"] : ["legacy"];
+    for (const scope of scopes) {
+      const dir = checkReadersDir(memoryDir, scope);
+      let names: string[] = [];
+      try { names = readdirSync(dir).filter((name) => name.endsWith(".json")).sort(); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") continue; throw new Error("reader lease directory is unreadable"); }
+      for (const name of names) {
+        if (!/^[1-9][0-9]*-[0-9a-f]{64}\.json$/.test(name)) throw new Error("unverifiable reader lease filename");
+        const file = join(dir, name);
+        const lease = readLease(memoryDir, file, scope);
+        if (!lease) throw new Error("reader lease is unreadable or unverifiable");
+        const liveness = processLiveness(lease.pid, lease.signature);
+        if (liveness === "live") throw new Error(`legacy reader is live (pid ${lease.pid}); close it before migration`);
+        if (liveness === "unknown") throw new Error(`legacy reader liveness is unknown (pid ${lease.pid})`);
+        rmSync(file);
+        removed++;
+        options.onDeadLeaseRemoved?.({ pid: lease.pid, lease: name });
+      }
     }
     return { removed };
   });

package/src/memory/shard-migration.ts

@@ -8,7 +8,7 @@ import { pruneId, prunePayloadHash, reducePruneRows, validatePruneRow, type Prun
 import { acquireMutation } from "./mutation.ts";
 import { canonicalPath, realPath } from "./platform.ts";
 import { assertNoLiveReaders } from "./reader-lease.ts";
-import { assertCuratedShardPaths, ensureShardDescriptor, shardDir, SHARDED_SCHEMA, userShardDir, SHARD_SCHEMA } from "./shard.ts";
+import { assertCuratedShardPaths, ensureShardDescriptor, shardDir, SHARDED_SCHEMA, SHARDED_V2_SCHEMA, userShardDir, SHARD_SCHEMA } from "./shard.ts";
 import { buildGenerationIndex, type Entry } from "./store.ts";
 import { readMigrationSources, type SourcePrefix } from "./migrate.ts";
 import { label, PLAIN, singleLine, type Style } from "./style.ts";
@@ -19,7 +19,7 @@ const JOURNAL = "shards.json";
 const CONSEQUENCE = "Legacy bytes are never rewritten; unannounced older readers cannot be detected and remain safe only because of that rule. Before splitting a live home, ensure every installed host uses openShardStore; ordinary new MemoryStore opens are refused once the shard marker exists. No host capability registry is available to prove an absent host safe.";
 
 interface ShardJournal {
-  schema: typeof SHARDED_SCHEMA;
+  schema: typeof SHARDED_SCHEMA | typeof SHARDED_V2_SCHEMA;
   generation: string;
   sourceGeneration?: string;
   phase: "captured" | "active";
@@ -67,7 +67,7 @@ function readJournal(memoryDir: string, optional = false): ShardJournal | undefi
     if (optional) return undefined;
     throw new Error("no resumable shard migration journal");
   }
-  if (value.schema !== SHARDED_SCHEMA || !validGeneration(value.generation) || !["captured", "active"].includes(value.phase ?? "")
+  if ((value.schema !== SHARDED_SCHEMA && value.schema !== SHARDED_V2_SCHEMA) || !validGeneration(value.generation) || !["captured", "active"].includes(value.phase ?? "")
     || value.sourceGeneration !== undefined && (!validGeneration(value.sourceGeneration) || value.sourceGeneration !== value.generation)
     || typeof value.selectorRevision !== "string" || !Array.isArray(value.sources) || !value.machine
     || typeof value.machine.id !== "string" || typeof value.machine.label !== "string") throw new Error("invalid shard migration journal");
@@ -503,6 +503,7 @@ function preflight(memoryDir: string, options: ShardMigrationOptions, chosen?: s
 }
 
 export async function migrateShards(options: ShardMigrationOptions): Promise<ShardMigrationResult> {
+  if (readSelector(options.memoryDir).selector?.schema === "agent-mem.profile/v2") throw new Error("public prune view is forward-only; use migrate --public-prune-view --resume");
   if (options.authorizedPerson !== true || options.tty !== true) throw new Error("shard migration requires an authorized person in a terminal");
   if (!["dry-run", "apply", "resume"].includes(options.mode) || options.generation !== undefined && !validGeneration(options.generation)) throw new Error("invalid shard migration request");
   const memoryDir = existsSync(options.memoryDir) ? realPath(options.memoryDir) : canonicalPath(options.memoryDir);

package/src/memory/shard-sync-format.ts

@@ -3,11 +3,15 @@ import { legacyEntries } from "./bridge.ts";
 import { canonicalJSON, validGeneration } from "./generation.ts";
 import { validatePruneRow, type PruneRow } from "./prune.ts";
 import { shardKeyHash } from "./shard.ts";
+import { validatePublicPruneWitness, type PublicPruneWitnessV1 } from "./public-prune-witness.ts";
 import type { Entry } from "./store.ts";
 
 export type ShardSyncRealm = { scope: "project"; key: string } | { scope: "user" };
 export type ShardSyncRow = Entry | PruneRow;
 export const SHARD_SYNC_SCHEMA = "agent-mem.shard-sync/v1";
+export const SHARD_SYNC_V2_SCHEMA = "agent-mem.shard-sync/v2";
+const METADATA_MAX_BYTES = 65_536;
+const MANIFEST = /^prune-witnesses\/([a-f0-9]{64})\.json$/;
 export const SHARD_PACK_MAX_BYTES = 1024 * 1024;
 const PACK = /^rows\/([a-f0-9]{64})\/([a-f0-9]{64})\.jsonl$/;
 const hash = (value: string | Uint8Array): string => createHash("sha256").update(value).digest("hex");
@@ -28,9 +32,43 @@ export function shardSyncRef(realm: ShardSyncRealm): string {
   checkRealm(realm);
   return realm.scope === "user" ? "refs/heads/amem/u" : `refs/heads/amem/p/${shardKeyHash(realm.key)}`;
 }
-export function shardSyncDescriptor(realm: ShardSyncRealm): string {
+export function shardSyncDescriptor(realm: ShardSyncRealm, version: "v1" | "v2" = "v1"): string {
   checkRealm(realm);
-  return canonicalJSON(realm.scope === "user" ? { schema: SHARD_SYNC_SCHEMA, scope: "user" } : { schema: SHARD_SYNC_SCHEMA, scope: "project", key: realm.key }) + "\n";
+  if (version !== "v1" && version !== "v2") throw new ShardSyncFormatError("shard", "unsupported descriptor version");
+  const schema = version === "v1" ? SHARD_SYNC_SCHEMA : SHARD_SYNC_V2_SCHEMA;
+  return canonicalJSON(realm.scope === "user" ? { schema, scope: "user" } : { schema, scope: "project", key: realm.key }) + "\n";
+}
+
+/** Closed canonical metadata, including its single complete newline terminator. */
+function decodeMetadata(bytes: Uint8Array, label: string): Record<string, unknown> {
+  try {
+    if (!bytes.byteLength || bytes.byteLength > METADATA_MAX_BYTES) throw new Error("bound");
+    const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes), value: unknown = JSON.parse(text);
+    if (!value || typeof value !== "object" || Array.isArray(value) || canonicalJSON(value) + "\n" !== text) throw new Error("canonical");
+    return value as Record<string, unknown>;
+  } catch { throw new ShardSyncFormatError(label, "invalid canonical metadata or bound"); }
+}
+export function decodeShardDescriptor(bytes: Uint8Array, realm: ShardSyncRealm): "v1" | "v2" {
+  const label = shardSyncLabel(realm), value = decodeMetadata(bytes, label);
+  const version = value.schema === SHARD_SYNC_SCHEMA ? "v1" : value.schema === SHARD_SYNC_V2_SCHEMA ? "v2" : undefined;
+  if (!version || canonicalJSON(value) + "\n" !== shardSyncDescriptor(realm, version)) throw new ShardSyncFormatError(label, "descriptor realm or schema mismatch");
+  return version;
+}
+export function isShardManifestPath(path: string): boolean { return MANIFEST.exec(path)?.[0] === path; }
+/** Shape and lineage classification belong to Layer 1 after complete pack acquisition. */
+export function decodeShardManifest(path: string, bytes: Uint8Array): unknown {
+  const match = MANIFEST.exec(path), label = "shard manifest";
+  if (!match || match[0] !== path) throw new ShardSyncFormatError(label, "invalid manifest path");
+  const value = decodeMetadata(bytes, label);
+  if (value.schema !== "agent-mem.public-prune-witness/v1" || hash(canonicalJSON(value)) !== match[1]) throw new ShardSyncFormatError(label, "invalid manifest schema or hash");
+  return value;
+}
+export function encodeShardManifest(manifest: PublicPruneWitnessV1): { path: string; bytes: Buffer } {
+  try {
+    const value = validatePublicPruneWitness(manifest), body = canonicalJSON(value), bytes = Buffer.from(body + "\n");
+    if (bytes.byteLength > METADATA_MAX_BYTES) throw new Error("bound");
+    return { path: `prune-witnesses/${hash(body)}.json`, bytes };
+  } catch { throw new ShardSyncFormatError("shard manifest", "invalid supported manifest or bound"); }
 }
 
 /** Only row shape/public placement here. The sync engine must prove target/basis realm ownership across the full source set. */