@staix/agent-mem 0.12.0 → 0.14.0

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,9 +8,10 @@ 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";
 
 const USER = Symbol("shared-user-shard");
 type Destination = string | typeof USER;
@@ -18,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";
@@ -66,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");
@@ -502,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);
@@ -560,3 +562,40 @@ export async function migrateShards(options: ShardMigrationOptions): Promise<Sha
     return { mode: options.mode, generation, active: true, ...(alreadyActive ? { alreadyActive: true } : {}), counts: counts(plan), ...refusalSummary(plan), consequence: CONSEQUENCE, ...removalEvidence(journal) };
   });
 }
+
+/** Render a shard migration result for a person; JSON output remains owned by the CLI. */
+export function shardMigrationText(result: ShardMigrationResult, s: Style = PLAIN): string {
+  const counts = result.counts;
+  const groupRows = (name: string, value: Record<string, number>) => Object.entries(value).sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, count]) => `${label(s, "ok")} ${name} ${singleLine(key)} ${count}`);
+  const countRows = [
+    ["rows", counts.rows], ["skipped", counts.skippedRows], ["userRows", counts.userRows], ["tailBytes", counts.tailBytes],
+    ["legacyRows", counts.legacyRows], ["generationRows", counts.generationRows], ["generationLocalRows", counts.generationLocalRows],
+    ["legacyLocalRows", counts.legacyLocalRows], ["legacyMainRows", counts.legacyMainRows], ["pruneRows", counts.pruneRows],
+    ["translatedPruneRows", counts.translatedPruneRows], ["refusedRows", counts.refusedRows],
+    ["sharedSupersededByPrivate", counts.sharedSupersededByPrivate], ["crossPrivateReplacement", counts.crossPrivateReplacement],
+    ["danglingRows", counts.danglingRows],
+  ].map(([key, value]) => {
+    const flagged = key === "refusedRows" && counts.refusedRows > 0 || key === "sharedSupersededByPrivate" && counts.sharedSupersededByPrivate > 0
+      || key === "crossPrivateReplacement" && counts.crossPrivateReplacement > 0 || key === "danglingRows" && counts.danglingRows > 0;
+    return `${label(s, flagged ? "attention" : "ok")} ${key} ${value}`;
+  });
+  const warnings = result.refusals ?? [];
+  const attention = warnings.length > 0 || counts.refusedRows > 0 || counts.danglingRows > 0 || (!result.active && result.mode === "resume");
+  const state = attention ? "attention" : result.mode === "dry-run" ? "preview" : result.active ? "complete" : "attention";
+  const action = warnings.length || counts.refusedRows > 0 || counts.danglingRows > 0 ? "resolve the listed refusals or flagged rows before retrying"
+    : result.mode === "dry-run" && (!result.active || counts.rows > 0) ? "apply shard migration: amem migrate --shards --apply"
+    : result.mode === "resume" && !result.active ? "resume shard migration: amem migrate --shards --resume"
+      : "none";
+  return [
+    `${s.bold("amem migrate --shards:")} ${state}${result.alreadyActive ? " (already active)" : ""}`,
+    `${label(s, "ok")} generation ${result.generation.slice(0, 8)}`,
+    ...countRows,
+    ...groupRows("shard rows", counts.byShard),
+    ...groupRows("project rows", counts.byProject),
+    ...(result.deadLeasesRemoved?.length ? [`${label(s, "ok")} dead reader leases removed ${result.deadLeasesRemoved.length}`] : []),
+    ...(warnings.length ? ["Refusals:", ...warnings.map(reason => `  ${label(s, "attention")} ${singleLine(reason)}`)] : []),
+    `${label(s, "ok")} effect ${singleLine(result.consequence)}`,
+    `Next action: ${action}`,
+  ].join("\n");
+}

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

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

@@ -0,0 +1,87 @@
+/** Bounded selected-path acquisition only. Transport admission and receiving binding stay with the caller. */
+import { createHash } from "node:crypto";
+import { PUBLIC_PRUNE_GRAPH_MAX_BYTES, PUBLIC_PRUNE_GRAPH_MAX_OBJECTS, PUBLIC_PRUNE_INPUT_MAX_BYTES, PublicPruneInputError, type PublicPruneObject } from "./public-prune-inputs.ts";
+import { decodeShardDescriptor, decodeShardManifest, SHARD_PACK_MAX_BYTES, type ShardSyncRealm } from "./shard-sync-format.ts";
+import { PUBLIC_PRUNE_MAX_PACKS, PUBLIC_PRUNE_MAX_WITNESSES, verifyPublicPruneWitness } from "./public-prune-witness.ts";
+
+type ObjectType = "commit" | "tree" | "blob";
+export interface PublicPruneGitGraphOptions {
+  commit: string; manifestPath: string; manifestBlob: string; realm: ShardSyncRealm;
+  readObject: (oid: string) => Promise<{ type: ObjectType; body: Uint8Array }>;
+}
+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);
+function guard(ok: unknown, resource = false): asserts ok { if (!ok) throw new PublicPruneInputError(resource ? "resource" : "unavailable"); }
+interface TreeEntry { mode: "40000" | "100644"; oid: string }
+function parseTree(body: Buffer): Map<string, TreeEntry> {
+  const entries = new Map<string, TreeEntry>();
+  for (let offset = 0; offset < body.length;) {
+    const space = body.indexOf(32, offset); guard(space > offset);
+    const end = body.indexOf(0, space + 1); guard(end > space + 1 && end + 21 <= body.length);
+    const modeBytes = body.subarray(offset, space), mode = modeBytes.toString("ascii");
+    guard((mode === "40000" || mode === "100644") && modeBytes.equals(Buffer.from(mode)));
+    const rawName = body.subarray(space + 1, end), name = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(rawName);
+    guard(name.length > 0 && name !== "." && name !== ".." && !name.includes("/") && !entries.has(name));
+    entries.set(name, { mode, oid: body.subarray(end + 1, end + 21).toString("hex") }); offset = end + 21;
+  }
+  return entries;
+}
+
+/** Complete raw object graph for one manifest. Unsupported lineage still returns its complete verified public proof. */
+export async function collectPublicPruneGitGraph(options: PublicPruneGitGraphOptions): Promise<PublicPruneObject[]> {
+  try {
+    const { commit, manifestPath, manifestBlob, readObject } = options, realm = structuredClone(options.realm);
+    guard(hex(commit, 40) && hex(manifestBlob, 40));
+    guard(typeof manifestPath === "string" && manifestPath.length === 85 && /^prune-witnesses\/[a-f0-9]{64}\.json$/.test(manifestPath));
+    const objects = new Map<string, { type: ObjectType; body: Buffer; bytes: Buffer }>(), trees = new Map<string, Map<string, TreeEntry>>(); let total = 0;
+    const get = async (oid: string, type: ObjectType) => {
+      guard(hex(oid, 40)); let found = objects.get(oid);
+      if (!found) {
+        guard(objects.size < PUBLIC_PRUNE_GRAPH_MAX_OBJECTS, true);
+        const value = await readObject(oid);
+        guard(value && ["commit", "tree", "blob"].includes(value.type) && value.body instanceof Uint8Array);
+        guard(value.body.byteLength <= (value.type === "commit" ? PUBLIC_PRUNE_INPUT_MAX_BYTES : SHARD_PACK_MAX_BYTES), true);
+        const header = Buffer.from(`${value.type} ${value.body.byteLength}\0`);
+        guard(header.length + value.body.byteLength <= SHARD_PACK_MAX_BYTES + 64 && total + header.length + value.body.byteLength <= PUBLIC_PRUNE_GRAPH_MAX_BYTES, true);
+        const body = Buffer.from(value.body), bytes = Buffer.concat([header, body]);
+        guard(createHash("sha1").update(bytes).digest("hex") === oid);
+        found = { type: value.type, body, bytes }; total += bytes.length; objects.set(oid, found);
+      }
+      guard(found.type === type); return found;
+    };
+    const commitBody = (await get(commit, "commit")).body, lf = commitBody.indexOf(10);
+    // Only the ASCII tree header is interpreted; arbitrary commit message bytes remain exact.
+    guard(lf === 45 && commitBody.subarray(0, 5).equals(Buffer.from("tree ")));
+    const rootBytes = commitBody.subarray(5, lf), root = rootBytes.toString("ascii");
+    guard(hex(root, 40) && rootBytes.equals(Buffer.from(root)));
+    const path = async (name: string) => {
+      const parts = name.split("/"); guard(parts.length > 0 && parts.every(part => part && part !== "." && part !== ".."));
+      let oid = root;
+      for (let i = 0; i < parts.length; i++) {
+        let entries = trees.get(oid);
+        if (!entries) { entries = parseTree((await get(oid, "tree")).body); trees.set(oid, entries); }
+        const entry = entries.get(parts[i]!); guard(entry && entry.mode === (i === parts.length - 1 ? "100644" : "40000")); oid = entry.oid;
+      }
+      const value = await get(oid, "blob"); return { oid, body: value.body };
+    };
+    guard(decodeShardDescriptor((await path("shard.json")).body, realm) === "v2");
+    const manifest = await path(manifestPath); guard(manifest.oid === manifestBlob);
+    const raw = decodeShardManifest(manifestPath, manifest.body);
+    guard(object(raw) && object(raw.pruneOccurrence) && Array.isArray(raw.witnesses));
+    guard(raw.witnesses.length <= PUBLIC_PRUNE_MAX_WITNESSES, true);
+    const packs = new Map<string, { pack: string; blob: string; bytes: Buffer }>();
+    for (const ref of [raw.pruneOccurrence, ...raw.witnesses]) {
+      guard(object(ref) && typeof ref.pack === "string" && ref.pack.length === 140 && /^rows\/[a-f0-9]{64}\/[a-f0-9]{64}\.jsonl$/.test(ref.pack) && hex(ref.blob, 40));
+      const previous = packs.get(ref.pack);
+      if (previous) { guard(previous.blob === ref.blob); continue; }
+      guard(packs.size < PUBLIC_PRUNE_MAX_PACKS, true);
+      const found = await path(ref.pack); guard(found.oid === ref.blob && found.body.length <= SHARD_PACK_MAX_BYTES);
+      packs.set(ref.pack, { pack: ref.pack, blob: ref.blob, bytes: found.body });
+    }
+    const proof = verifyPublicPruneWitness(raw, { realm, packs: [...packs.values()] }); guard(proof.status !== "invalid");
+    return [...objects].map(([oid, item]) => ({ oid, bytes: item.bytes }));
+  } catch (error) {
+    if (error instanceof PublicPruneInputError) throw error;
+    throw new PublicPruneInputError();
+  }
+}