@staix/agent-mem 0.20.3 → 0.21.0

package/src/memory/shard.ts

@@ -1,3 +1,6 @@
+import { readActivePlacementBinding } from "./sync-placement-active.ts";
+import { validatePlacementProfile, validatePlacementShards } from "./sync-placement-format.ts";
+import { assertPlacementRuntime, SyncPlacementRuntimeError } from "./sync-placement-guard.ts";
 import { assertNoPublicPruneIntent, readPublicPruneView } from "./public-prune-view.ts";
 import { indexFileName } from "./index-file.ts";
 import { createHash, randomBytes } from "node:crypto";
@@ -84,31 +87,46 @@ export function captureShardDir(base: string, key: string, machine: string): str
 export const SHARDED_SCHEMA = "agent-mem.shards/v1";
 export const SHARDED_V2_SCHEMA = "agent-mem.shards/v2";
 export const SHARDED_V2_FIELDS = ["schema", "generation", "phase", "selectorRevision", "sourceGeneration", "sources", "machine", "legacyCommit", "deadLeasesRemoved"] as const;
-export interface ShardedSelection { schema: typeof SHARDED_SCHEMA | typeof SHARDED_V2_SCHEMA; generation: string; phase: "active"; selectorRevision: string }
+export interface ShardedSelection { schema: typeof SHARDED_SCHEMA | typeof SHARDED_V2_SCHEMA | "agent-mem.shards/v3"; generation: string; phase: "active"; selectorRevision: string }
 
 export function userShardDir(base: string): string {
   return join(base, "user");
 }
 
 type ShardedJournal = Record<string, unknown> & ShardedSelection;
+/** Keep the existing active reader shape and the migration's captured-v1/v2 state distinct from v3. */
+export function legacyShardMarkerShape(value: unknown): boolean {
+  if (value === undefined) return true;
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const row = value as Record<string, unknown>;
+  return (row.schema === SHARDED_SCHEMA || row.schema === SHARDED_V2_SCHEMA) && validGeneration(row.generation)
+    && typeof row.phase === "string" && ["captured", "active"].includes(row.phase) && typeof row.selectorRevision === "string"
+    && (row.schema !== SHARDED_V2_SCHEMA || !Object.keys(row).some(key => !(SHARDED_V2_FIELDS as readonly string[]).includes(key)));
+}
 function shardJournal(memoryDir: string): ShardedJournal {
   const value = readProfileJSON(join(memoryDir, "shards.json")) as Record<string, unknown> | undefined;
+  if (value?.schema === "agent-mem.shards/v3") {
+    const profile = validatePlacementProfile(readProfileJSON(join(memoryDir, "profile.json")));
+    return validatePlacementShards(value, profile) as unknown as ShardedJournal;
+  }
   if (!value || (value.schema !== SHARDED_SCHEMA && value.schema !== SHARDED_V2_SCHEMA) || !validGeneration(value.generation) || value.phase !== "active" || typeof value.selectorRevision !== "string") throw new Error("no active curated shard migration");
   if (value.schema === SHARDED_V2_SCHEMA && Object.keys(value).some(key => !(SHARDED_V2_FIELDS as readonly string[]).includes(key))) throw new Error("unsupported curated shard view");
   return value as ShardedJournal;
 }
 function compatibleShardAdvance(before: ShardedJournal, after: ShardedJournal): boolean {
-  if (before.schema !== SHARDED_V2_SCHEMA || after.schema !== SHARDED_V2_SCHEMA) return false;
+  if (![SHARDED_V2_SCHEMA, "agent-mem.shards/v3"].includes(before.schema) || after.schema !== before.schema) return false;
   const { selectorRevision: _old, ...old } = before, { selectorRevision: _next, ...next } = after;
   return canonicalJSON(old) === canonicalJSON(next);
 }
 function shardSnapshot(memoryDir: string, deadline: number) {
+  assertPlacementRuntime(memoryDir);
   assertNoPublicPruneIntent(memoryDir, deadline);
   let journal = shardJournal(memoryDir);
   for (let attempt = 0; attempt < 6 && Date.now() <= deadline; attempt++) {
     let selector: ReturnType<typeof readSelector>;
     try { selector = readSelector(memoryDir, deadline); }
     catch (error) {
+      if (error instanceof SyncPlacementRuntimeError) throw error;
       // The writer's spent wait budget or unavailable proof is never restarted here.
       if (error instanceof Error && error.message === "public prune view unavailable") throw error;
       const current = shardJournal(memoryDir);
@@ -120,8 +138,8 @@ function shardSnapshot(memoryDir: string, deadline: number) {
       if (!compatibleShardAdvance(journal, current)) throw new Error("curated shard selector changed");
       journal = current; continue;
     }
-    if ((journal.schema === SHARDED_V2_SCHEMA) !== (selector.selector?.schema === "agent-mem.profile/v2")) throw new Error("curated shard selector changed");
-    if (journal.schema === SHARDED_V2_SCHEMA && (selector.revision !== journal.selectorRevision || selector.selector?.generation !== journal.generation)) continue;
+    if ((journal.schema === SHARDED_V2_SCHEMA || journal.schema === "agent-mem.shards/v3") !== (selector.selector?.schema === "agent-mem.profile/v2" || selector.selector?.schema === "agent-mem.profile/v3")) throw new Error("curated shard selector changed");
+    if ((journal.schema === SHARDED_V2_SCHEMA || journal.schema === "agent-mem.shards/v3") && (selector.revision !== journal.selectorRevision || selector.selector?.generation !== journal.generation)) continue;
     return { journal, selector };
   }
   throw new Error("curated shard selector changed");
@@ -135,6 +153,14 @@ export function readShardedSelection(memoryDir: string): ShardedSelection {
  * ponytail: same-user concurrent parent replacement needs descriptor-relative opens; fixed preflight does not claim that fence.
  */
 export function assertCuratedShardPaths(memoryDir: string, opts: { project?: string; user?: boolean }): void {
+  assertPlacementRuntime(memoryDir);
+  const selector = readProfileJSON(join(memoryDir, "profile.json")) as {schema?:unknown} | undefined;
+  if (selector?.schema === "agent-mem.profile/v3") {
+    const active = readActivePlacementBinding(memoryDir, selector, readProfileJSON(join(memoryDir, "shards.json")));
+    const keyHash = opts.user ? undefined : createHash("sha256").update(opts.project!).digest("hex");
+    if (!active || !active.activation.realms.some(realm => opts.user ? realm.scope === "user" : realm.scope === "project" && realm.keyHash === keyHash))
+      throw new Error("sync placement realm is outside the activated inventory; review its activation before opening it");
+  }
   const dir = opts.user === true ? userShardDir(memoryDir) : shardDir(memoryDir, opts.project!);
   const check = (path: string, directory: boolean) => {
     try {
@@ -169,10 +195,10 @@ export function resolveShardProfile(memoryDir: string, opts: { project?: string;
   const final = shardSnapshot(memoryDir, deadline), selector = final.selector;
   if (canonicalJSON(final.journal) !== canonicalJSON(initial.journal) && !compatibleShardAdvance(initial.journal, final.journal)
     || selector.revision !== final.journal.selectorRevision) throw new Error("curated shard selector changed; resume or inspect migration state");
-  if (selector.selector?.schema === "agent-mem.profile/v2") readPublicPruneView(memoryDir, selector.selector.pruneInputSetHash, generation, deadline);
+  if (selector.selector?.schema === "agent-mem.profile/v2" || selector.selector?.schema === "agent-mem.profile/v3") readPublicPruneView(memoryDir, selector.selector.pruneInputSetHash, generation, deadline);
   const legacyMainHome = join(dir, "legacy-main");
   const hasLegacyMain = existsSync(legacyMainHome) || sources.sources.some(source => !!source && typeof source === "object" && "source" in source && source.source === "legacy-main");
   return { kind: "generation", home: memoryDir, dir, generation, selectorRevision: selector.revision,
-    ...(selector.selector?.schema === "agent-mem.profile/v2" ? { foreignPruneFormat: selector.selector.foreignPruneFormat, pruneInputSetHash: selector.selector.pruneInputSetHash } : {}),
+    ...((selector.selector?.schema === "agent-mem.profile/v2" || selector.selector?.schema === "agent-mem.profile/v3") ? { foreignPruneFormat: selector.selector.foreignPruneFormat, pruneInputSetHash: selector.selector.pruneInputSetHash, ...(selector.selector.schema === "agent-mem.profile/v3" ? { publicationFormat: selector.selector.publicationFormat, placementHead: selector.selector.placementHead } : {}) } : {}),
     legacyHome: join(dir, "legacy"), ...(hasLegacyMain ? { legacyMainHome } : {}), sharded: true, ...(opts.user === true ? { shardUser: true } : { shardKey: opts.project! }) };
 }

package/src/memory/store.ts

@@ -1,3 +1,4 @@
+import { assertPlacementRuntime, placementSelectorRefusal, SyncPlacementRuntimeError } from "./sync-placement-guard.ts";
 import { assertFormatFloor } from "./formats.ts";
 import { readPublicPruneView } from "./public-prune-view.ts";
 import { INDEX_VERSION, indexFileName } from "./index-file.ts";
@@ -234,7 +235,10 @@ export class MemoryStore {
     if (opts.memoryDir !== undefined && (opts.home !== undefined || typeof opts.memoryDir !== "string" || !opts.memoryDir.trim())) throw new Error("choose a memory home or one explicit memory directory");
     const home = bootstrap?.profile.home ?? opts.memoryDir ?? (opts.home === undefined ? memoryHome() : join(opts.home, "memory"));
     assertFormatFloor(home, "curated");
+    const placementRefusal = placementSelectorRefusal(home);
+    if (placementRefusal) throw new SyncPlacementRuntimeError(placementRefusal);
     if (!bootstrap && lstatSync(join(home, "shards.json"), { throwIfNoEntry: false })) throw new Error("memory home has a curated split; hosts must use openShardStore({ project }) or openShardStore({ user: true }); finish an incomplete split with amem migrate --shards --resume");
+    if (bootstrap) assertPlacementRuntime(home);
     this.profile = bootstrap?.profile ?? resolveProfile(home, opts.profile);
     if (bootstrap && (this.profile.kind !== "generation" || !this.profile.generation
       || (!this.profile.sharded && this.profile.dir !== generationDir(this.profile.home, this.profile.generation))
@@ -1561,6 +1565,14 @@ export class MemoryStore {
     });
   }
 
+  /** Canonical generation outbound sources only; no refresh, rebind or derived-state write.
+   * Call the returned bounded recheck after visiting all opened targets, before declaring completeness.
+   */
+  inspectOutboundRows(visit: (row: Record<string, unknown>) => void, limits: { maxBytes: number; maxRows: number }): () => void {
+    if (!this.generationIndex) throw Object.assign(new Error("outbound generation input unavailable"), { code: "input-unavailable" });
+    return this.generationIndex.inspectOutboundRows(visit, limits);
+  }
+
   /** Person-local diagnostic receipt; malformed legacy bodies are never included. */
   bridgeStatus(): { skippedRows: number } | undefined {
     return this.generationIndex ? { skippedRows: this.generationIndex.skippedRows() } : undefined;
@@ -1622,7 +1634,7 @@ function initializeShard(home: string, opts: { project?: string; user?: boolean
   writeProfileJSON(join(dir, "migration-sources.json"), { schema: "agent-mem.migration-sources/v1", sources });
   const selected = readSelector(home).selector;
   const profile: BoundProfile = { kind: "generation", home, dir, generation, selectorRevision: selection.selectorRevision,
-    ...(selected?.schema === "agent-mem.profile/v2" ? {foreignPruneFormat: selected.foreignPruneFormat, pruneInputSetHash: selected.pruneInputSetHash} : {}),
+    ...((selected?.schema === "agent-mem.profile/v2" || selected?.schema === "agent-mem.profile/v3") ? {foreignPruneFormat: selected.foreignPruneFormat, pruneInputSetHash: selected.pruneInputSetHash, ...(selected.schema === "agent-mem.profile/v3" ? {publicationFormat:selected.publicationFormat,placementHead:selected.placementHead} : {})} : {}),
     legacyHome, legacyMainHome: join(dir, "legacy-main"), sharded: true, ...(opts.user === true ? { shardUser: true } : { shardKey: opts.project! }) };
   buildGenerationIndex(profile, sources);
   writeProfileJSON(join(dir, "generation-seal.json"), { schema: "agent-mem.generation-seal/v1", generation,
@@ -1645,6 +1657,7 @@ export function openShardStore(opts: StoreOptions & { project?: string; user?: b
   const missing = !existsSync(join(dir, "generation.json"));
   if (missing) {
     const selected = readSelector(home).selector;
+    if (selected?.schema === "agent-mem.profile/v3") throw new Error("sync placement realm was not activated; review a complete realm inventory before opening a new curated shard");
     if (selected?.schema === "agent-mem.profile/v2") {
       const view = readPublicPruneView(home, selected.pruneInputSetHash, selected.generation), key = opts.user ? "user" : `project:${opts.project}`;
       if (view.realms[key] || ["generation-seal.json", "migration-sources.json", "machine.json"].some(name => existsSync(join(dir, name)))) throw new Error("v2 generation input unavailable; reader cannot repair committed inputs");

package/src/memory/sync-binding.ts

@@ -0,0 +1,63 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, type BigIntStats } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join, relative, sep } from "node:path";
+import type { MemoryStore } from "./store.ts";
+
+/** Metadata-only sharded sync epoch. Hash complete source bytes, never notes or unopened shards. */
+export function shardSyncBinding(store: MemoryStore): string { return captureShardSyncBinding(store, true); }
+/** Selection bytes may change only after this sync commits; source/policy identity remains pinned across that commit. */
+export function shardSyncSourceBinding(store: MemoryStore): string { return captureShardSyncBinding(store, false); }
+function captureShardSyncBinding(store: MemoryStore, selection: boolean): string {
+  const unavailable = (): never => { throw new Error("sharded sync binding unavailable"); };
+  if (!store.profile.sharded) return unavailable();
+  const uid = process.getuid?.(); if (uid === undefined) return unavailable();
+  const same = (a: BigIntStats, b: BigIntStats) => a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs;
+  const owned = (stat: BigIntStats, directory: boolean, privateMode = true) => {
+    if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1n)
+      || stat.uid !== BigInt(uid) || privateMode && (stat.mode & 0o077n) !== 0n) unavailable();
+  };
+  const home = store.profile.home, digest = createHash("sha256"), directories = new Map<string, BigIntStats>(), checks: (() => void)[] = [];
+  const emit = (value: unknown) => { digest.update(JSON.stringify(value) + "\n"); };
+  const directory = (dir: string): void => {
+    if (directories.has(dir)) return;
+    const rel = relative(home, dir); if (rel === ".." || rel.startsWith(".." + sep)) unavailable();
+    if (dir !== home) directory(dirname(dir));
+    const before = lstatSync(dir, { bigint: true }); owned(before, true); directories.set(dir, before);
+    emit(["directory", dir, String(before.dev), String(before.ino)]);
+    checks.push(() => { const now = lstatSync(dir, { bigint: true }); owned(now, true); if (!same(before, now)) unavailable(); });
+  };
+  // Policy config keeps its established file modes inside this already-private owned home. Its complete bytes/inode still bind the epoch.
+  const source = (file: string, privateMode = true): void => {
+    directory(dirname(file));
+    let before: BigIntStats;
+    try { before = lstatSync(file, { bigint: true }); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      emit(["source", file, "absent"]);
+      checks.push(() => { if (lstatSync(file, { bigint: true, throwIfNoEntry: false }) !== undefined) unavailable(); }); return;
+    }
+    owned(before, false, privateMode);
+    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+      const opened = fstatSync(fd, { bigint: true }); owned(opened, false, privateMode); if (!same(before, opened)) unavailable();
+      const content = createHash("sha256"), buffer = Buffer.allocUnsafe(65_536); let bytes = 0n;
+      for (;;) { const n = readSync(fd, buffer, 0, buffer.length, null); if (!n) break; content.update(buffer.subarray(0, n)); bytes += BigInt(n); }
+      const after = fstatSync(fd, { bigint: true }); owned(after, false, privateMode);
+      if (bytes !== before.size || !same(before, after) || !same(before, lstatSync(file, { bigint: true }))) unavailable();
+      emit(["source", file, "present", String(before.dev), String(before.ino), String(before.size), String(before.mtimeNs), String(before.ctimeNs), content.digest("hex")]);
+    } finally { closeSync(fd); }
+    checks.push(() => { const now = lstatSync(file, { bigint: true }); owned(now, false, privateMode); if (!same(before, now)) unavailable(); });
+  };
+  try {
+    directory(home);
+    for (const name of [...(selection ? ["profile.json", "shards.json"] : []), "aliases.jsonl", "amem.config.json", "machine.json"]) source(join(home, name), name !== "amem.config.json");
+    const targets = [...store.openedSyncTargets()].sort((a, b) => a.dir.localeCompare(b.dir));
+    for (const target of targets) {
+      directory(target.dir);
+      emit(["target", target.dir, target.profile.generation ?? null, target.machine.id, target.profile.shardUser ?? false, target.profile.shardKey ?? null]);
+      for (const name of ["project.json", "generation.json", "generation-seal.json", "machine.json"]) source(join(target.dir, name));
+    }
+    for (const check of checks) check();
+    return digest.digest("hex");
+  } catch { return unavailable(); }
+}

package/src/memory/sync-placement-active.ts

@@ -0,0 +1,75 @@
+/** Metadata-only v3 admission. Publication still requires the complete journal/source/policy proof. */
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, type BigIntStats } from "node:fs";
+import { join } from "node:path";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { realPath } from "./platform.ts";
+import { validatePlacementProfile, validatePlacementShards, type PlacementProfile, type PlacementShards } from "./sync-placement-format.ts";
+import { validatePlacementPlan, type SyncPlacementActivationPlan } from "./sync-placement-plan.ts";
+import { placementEpochHash, validatePlacementEpoch, validatePlacementActiveFence, type PlacementEpoch } from "./sync-placement-journal-format.ts";
+import { readPublicPruneViewForActivation } from "./public-prune-view.ts";
+import { readPublicPruneInputSetChain } from "./public-prune-input-chain.ts";
+import { shardDir, userShardDir } from "./shard.ts";
+
+export interface ActivePlacementBinding { profile: PlacementProfile; shards: PlacementShards; epoch: PlacementEpoch; activation: SyncPlacementActivationPlan }
+function fail(): never { throw new Error("sync placement activation metadata unavailable or changed; inspect the retained activation before continuing"); }
+const same = (a: BigIntStats, b: BigIntStats) => a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs;
+function owned(s: BigIntStats, directory = false): void {
+  if (s.uid !== BigInt(process.getuid?.() ?? -1) || (s.mode & 0o077n) !== 0n || s.isSymbolicLink()
+    || (directory ? !s.isDirectory() : !s.isFile() || s.nlink !== 1n)) fail();
+}
+/** Initial activation commitments remain authoritative; maintenance may only grow the same-generation prune view. */
+export function assertPlacementViewAdvance(home: string, activation: SyncPlacementActivationPlan, profile: PlacementProfile, shards: PlacementShards): void {
+  const initial = activation.targetProfile;
+  const { pruneInputSetHash: _old, ...before } = initial, { pruneInputSetHash: _next, ...after } = profile;
+  if (canonicalJSON(before) !== canonicalJSON(after)) fail();
+  const initialShards = { ...shards, selectorRevision: hashJSON(initial) };
+  if (hashJSON(initialShards) !== activation.targetShardsHash) fail();
+  if (initial.pruneInputSetHash === profile.pruneInputSetHash) return;
+  const oldView = readPublicPruneViewForActivation(home, initial.pruneInputSetHash, profile.generation);
+  const nextView = readPublicPruneViewForActivation(home, profile.pruneInputSetHash, profile.generation);
+  if (!Object.keys(oldView.realms).every(key => Object.hasOwn(nextView.realms, key))) fail();
+  for (const [key, hash] of Object.entries(nextView.realms)) {
+    const old = oldView.realms[key]; if (old === hash) continue;
+    const dir = key === "user" ? userShardDir(home) : shardDir(home, key.slice(8));
+    const chain = readPublicPruneInputSetChain({ dir, receivingGeneration: profile.generation, inputSetHash: hash });
+    if (old !== undefined && !chain.commitments.includes(old)) fail();
+  }
+}
+/** No mutation/reader registration/index open. Missing preparation is distinct from malformed retained evidence. */
+export function readActivePlacementBinding(homeInput: string, profileInput: unknown, shardsInput: unknown): ActivePlacementBinding | undefined {
+  const profile = validatePlacementProfile(profileInput), shards = validatePlacementShards(shardsInput, profile);
+  const home = realPath(homeInput), root = lstatSync(home, { bigint: true }); owned(root, true);
+  const checks: (() => void)[] = [() => { const now = lstatSync(home, { bigint: true }); owned(now, true); if (now.dev !== root.dev || now.ino !== root.ino) fail(); }];
+  const directory = (dir: string): boolean => {
+    const s = lstatSync(dir, { bigint: true, throwIfNoEntry: false }); if (!s) return false; owned(s, true);
+    checks.push(() => { const now = lstatSync(dir, { bigint: true }); owned(now, true); if (s.dev !== now.dev || s.ino !== now.ino) fail(); }); return true;
+  };
+  const read = (file: string): { value: unknown; text: string } | undefined => {
+    const before = lstatSync(file, { bigint: true, throwIfNoEntry: false }); if (!before) return undefined;
+    owned(before); if (before.size <= 0n || before.size > 262144n) fail();
+    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+      const s = fstatSync(fd, { bigint: true }); owned(s); if (!same(before, s)) fail();
+      const bytes = Buffer.alloc(Number(s.size) + 1); let at = 0;
+      while (at < bytes.length) { const n = readSync(fd, bytes, at, bytes.length - at, at); if (!n) break; at += n; }
+      if (at !== Number(s.size) || !same(s, fstatSync(fd, { bigint: true })) || !same(s, lstatSync(file, { bigint: true }))) fail();
+      const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, at)), value: unknown = JSON.parse(text);
+      if (canonicalJSON(value) + "\n" !== text) fail();
+      checks.push(() => { const now = lstatSync(file, { bigint: true }); owned(now); if (!same(s, now)) fail(); }); return { value, text };
+    } finally { closeSync(fd); }
+  };
+  if (!directory(join(home, "sync-placement")) || !directory(join(home, "sync-placement", "epochs"))) return undefined;
+  const dir = join(home, "sync-placement", "epochs", profile.placementHead);
+  if (!directory(dir)) return undefined;
+  const epochFile = read(join(dir, "epoch.json")), activationFile = read(join(dir, "activation.json")), fenceFile = read(join(home, "sync-placement", "active.json"));
+  if (!epochFile || !activationFile || !fenceFile) return undefined;
+  const epoch = validatePlacementEpoch(epochFile.value), activation = validatePlacementPlan(activationFile.value), fence = validatePlacementActiveFence(fenceFile.value);
+  const homeHash = hashJSON([home, String(root.dev), String(root.ino), String(root.uid)]);
+  if (epoch.homeHash !== homeHash || epoch.generation !== profile.generation || placementEpochHash(epoch) !== profile.placementHead
+    || activation.contextHash !== epoch.contextHash || activation.generation !== epoch.generation || activation.targetProfile.placementHead !== profile.placementHead
+    || fence.epochHash !== profile.placementHead || fence.homeHash !== homeHash || fence.generation !== profile.generation) fail();
+  if (read(join(home, "profile.json"))?.text !== canonicalJSON(profile) + "\n" || read(join(home, "shards.json"))?.text !== canonicalJSON(shards) + "\n") fail();
+  assertPlacementViewAdvance(home, activation, profile, shards);
+  for (const check of checks) check();
+  return { profile, shards, epoch, activation };
+}

package/src/memory/sync-placement-cache.ts

@@ -0,0 +1,32 @@
+/** Shared private cache metadata validation. These checks never initialize, repair or publish a repository. */
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { canonicalJSON } from "./generation.ts";
+import { SyncPlacementJournalError } from "./sync-placement-journal-format.ts";
+
+function fail(): never { throw new SyncPlacementJournalError("corrupt"); }
+export function placementCacheRootStamp(home: string): string {
+  const stat = lstatSync(join(home, "shard-sync-placement"), { bigint: true });
+  if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== BigInt(process.getuid?.() ?? -1) || (stat.mode & 0o077n) !== 0n) fail();
+  return canonicalJSON([String(stat.dev), String(stat.ino), String(stat.uid), String(stat.mode)]);
+}
+export function placementCacheConfigStamp(cache: string): string {
+  const stat = lstatSync(join(cache, "config"), { bigint: true });
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1n || stat.uid !== BigInt(process.getuid?.() ?? -1)
+    || (stat.mode & 0o077n) !== 0n || stat.size > 65536n) fail();
+  return canonicalJSON([String(stat.dev), String(stat.ino), String(stat.size), String(stat.mtimeNs), String(stat.ctimeNs)]);
+}
+export function validatePlacementCacheConfig(output: string): ReadonlyMap<string, string> {
+  const seen = new Map<string, string>();
+  const booleans = new Set(["core.filemode", "core.bare", "core.ignorecase", "core.precomposeunicode", "core.protecthfs", "core.protectntfs", "core.logallrefupdates", "core.symlinks"]);
+  for (const row of output.split("\0").filter(Boolean)) {
+    const at = row.indexOf("\n"); if (at < 1) fail();
+    const key = row.slice(0, at), value = row.slice(at + 1);
+    if (seen.has(key)) fail(); seen.set(key, value);
+    if (booleans.has(key)) { if (value !== "true" && value !== "false") fail(); }
+    else if (key === "core.repositoryformatversion") { if (value !== "0" && value !== "1") fail(); }
+    else if (key === "extensions.objectformat") { if (value !== "sha1") fail(); }
+    else if (!["remote.origin.url", "remote.origin.fetch", "remote.origin.pushurl"].includes(key)) fail();
+  }
+  return seen;
+}

package/src/memory/sync-placement-capture.ts

@@ -0,0 +1,292 @@
+import type { PlacementPublicationSource } from "./sync-placement-publication-plan.ts";
+import { validatePlacementKey, type PlacementRealm } from "./sync-placement-journal-format.ts";
+import { types } from "node:util";
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, opendirSync, readSync, type BigIntStats } from "node:fs";
+import { join } from "node:path";
+import { canonicalJSON, generationDescriptor, hashJSON, validateVaultLinkRow, type BoundProfile, type VaultLinkRow } from "./generation.ts";
+import { validatePlacementBaseV2, validatePlacementProfile, validatePlacementShards, PLACEMENT_PROFILE_SCHEMA } from "./sync-placement-format.ts";
+import { planSyncPlacementActivation, type SyncPlacementActivationContext, type SyncPlacementWriterAttestation } from "./sync-placement-plan.ts";
+import { readPublicPruneViewForActivation, PUBLIC_PRUNE_INTENT } from "./public-prune-view.ts";
+import { realPath, DENY_NAMES, DENY_SEGMENTS } from "./platform.ts";
+import { loadAmemConfig } from "./config.ts";
+import { memoryPolicySnapshot } from "./policy.ts";
+import { SegmentReader, SegmentReadBudgetError, checkedEntry, completeLines } from "./bridge.ts";
+import { readShardLegacySnapshot } from "./shard-bridge.ts";
+import { coalesceGenerationSource } from "./generation-index.ts";
+import { validatePruneRow, type PruneSourceRow, type PruneRow } from "./prune.ts";
+import { shardKeyHash, SHARD_SCHEMA } from "./shard.ts";
+import { SyncPlacementJournalError, placementKeyId, type PlacementKey } from "./sync-placement-journal-format.ts";
+import type { Entry } from "./store.ts";
+
+/** Host authentication/compatibility facts are re-read at every effect boundary, never inferred from a session marker. */
+export interface PlacementCapturePort {
+  attest(): { writers: readonly SyncPlacementWriterAttestation[]; legacySyncQuiesced: true };
+  /** Required when a caller adds a policy callback; must change whenever its policy changes. */
+  policyVersion?(): string;
+}
+/** Internal actual-transport proof, admitted only after the native pending plan and fetched original were validated. */
+export interface PlacementPendingSource { realm: PlacementRealm; pathHash: string; offset: number; prefixHash: string; line: string }
+export interface PlacementSourceRow { key: PlacementKey; row: Entry; sourcePlacement: "local" | "synced"; intrinsicLocal: boolean }
+export interface PlacementSpecialSourceRow { key: PlacementKey; row: PruneRow | VaultLinkRow; sourcePlacement: "local" | "synced"; intrinsicLocal: boolean }
+export interface PlacementCapture {
+  home: string; context: SyncPlacementActivationContext; activeHead?: string;
+  markerHash: string; fingerprint: string; directories: string[]; prefixes: PlacementPublicationSource[]; rows: Map<string, PlacementSourceRow>;
+  /** Diagnostic inventory only; these rows never enter the ordinary transport/capture row map implicitly. */
+  specialRows: Map<string, PlacementSpecialSourceRow>;
+  sourceRowsByRealm: Map<string, readonly PruneSourceRow[]>;
+  assertCurrent(): void;
+  /** Under live writer fences, inode/ctime/size checks protect the already-hashed prefixes across callbacks without reparsing rows. */
+  assertUnchanged(): void;
+}
+function fail(code: "changed" | "invalid" | "bound" = "changed"): never { throw new SyncPlacementJournalError(code); }
+const digest = (bytes: Uint8Array | string) => createHash("sha256").update(bytes).digest("hex");
+const stamp = (s: BigIntStats) => [s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs].map(String);
+const same = (a: BigIntStats, b: BigIntStats) => canonicalJSON(stamp(a)) === canonicalJSON(stamp(b));
+function ownedDirectory(dir: string): BigIntStats {
+  const s = lstatSync(dir, { bigint: true });
+  if (!s.isDirectory() || s.isSymbolicLink() || s.uid !== BigInt(process.getuid!()) || (s.mode & 0o022n) !== 0n) fail();
+  return s;
+}
+/** ponytail: capture is capped at 256 metadata objects and 8 MiB/20000 source rows across all realms.
+ * Larger homes need a reviewed chunked activation proof; no input is silently omitted at this ceiling. */
+function capture(homeInput: string, port: PlacementCapturePort, selected?: readonly PlacementRealm[], pending: readonly PlacementPendingSource[] = []): Omit<PlacementCapture, "assertCurrent"> {
+  let selection: PlacementRealm[] | undefined;
+  if (selected !== undefined) {
+    if (!Array.isArray(selected) || types.isProxy(selected) || selected.length > 256) fail("bound");
+    const copied = memoryPolicySnapshot(selected); if (!copied) fail();
+    selection = copied.map(realm => validatePlacementKey({ realm, id: "0".repeat(32), rowHash: "0".repeat(64) }).realm);
+    if (!selection.length || new Set(selection.map(realm => canonicalJSON(realm))).size !== selection.length) fail();
+  }
+  // All host callouts precede filesystem capture: a callback cannot alter input after its final proof.
+  const attestation = memoryPolicySnapshot(port.attest()), policyVersion = port.policyVersion?.();
+  if (!attestation) fail();
+  if (port.policyVersion && typeof policyVersion !== "string") fail();
+  const home = realPath(homeInput), root = ownedDirectory(home);
+  let metadataObjects = 0, metadataBytes = 0;
+  const facts: unknown[] = [], sourceChecks: (() => void)[] = [];
+  const pendingByPath = new Map(pending.map(item => [canonicalJSON(item.realm)+":"+item.pathHash,item]));
+  if (pendingByPath.size !== pending.length) fail();
+  const directoryFact = (dir: string) => {
+    const stat = ownedDirectory(dir); facts.push([dir, "directory", String(stat.dev), String(stat.ino), String(stat.uid)]);
+    sourceChecks.push(() => { const now=ownedDirectory(dir); if(now.dev!==stat.dev||now.ino!==stat.ino) fail(); });
+  };
+  const bytes = (file: string, optional = false): Buffer | undefined => {
+    const before = lstatSync(file, { bigint: true, throwIfNoEntry: false });
+    if (!before) { if (!optional) fail(); facts.push([file, null]); sourceChecks.push(() => { if(lstatSync(file,{throwIfNoEntry:false})) fail(); }); return undefined; }
+    if (++metadataObjects > 256 || before.size > 262144n || metadataBytes + Number(before.size) > 8 * 1024 * 1024) fail("bound");
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1n || before.uid !== root.uid || (before.mode & 0o022n) !== 0n) fail();
+    const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+      const opened = fstatSync(fd, { bigint: true }); if (!same(before, opened)) fail();
+      const out = Buffer.alloc(Number(opened.size)); let at = 0;
+      while (at < out.length) { const count = readSync(fd, out, at, out.length - at, at); if (!count) fail(); at += count; }
+      const after = lstatSync(file, { bigint: true }); if (!same(opened, fstatSync(fd, { bigint: true })) || !same(opened, after)) fail();
+      metadataBytes += out.length; facts.push([file, stamp(opened), digest(out)]);
+      sourceChecks.push(() => { const now=lstatSync(file,{bigint:true}); if(!now.isFile()||now.isSymbolicLink()||now.nlink!==1n||!same(opened,now)) fail(); }); return out;
+    } finally { closeSync(fd); }
+  };
+  const json = (file: string, optional = false): any => {
+    const input = bytes(file, optional); if (!input) return undefined;
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input));
+  };
+  const rawProfile = json(join(home, "profile.json")), rawShards = json(join(home, "shards.json"));
+  let activeHead: string | undefined;
+  let base: ReturnType<typeof validatePlacementBaseV2>;
+  if (rawProfile?.schema === PLACEMENT_PROFILE_SCHEMA) {
+    const profile = validatePlacementProfile(rawProfile), shards = validatePlacementShards(rawShards, profile);
+    activeHead = profile.placementHead;
+    const { publicationFormat: _pf, placementHead: _ph, ...p } = profile;
+    const profile2 = { ...p, schema: "agent-mem.profile/v2" };
+    const { publicationFormat: _sf, placementHead: _sh, ...s } = shards;
+    base = validatePlacementBaseV2(profile2, { ...s, schema: "agent-mem.shards/v2", selectorRevision: hashJSON(profile2) });
+  } else base = validatePlacementBaseV2(rawProfile, rawShards);
+  const markerHash = hashJSON({ profile: rawProfile, shards: rawShards });
+  bytes(join(home, "public-prune-input-sets", `${base.profile.pruneInputSetHash}.json`));
+  readPublicPruneViewForActivation(home, base.profile.pruneInputSetHash, base.profile.generation);
+  const aliases = bytes(join(home, "aliases.jsonl"), true);
+  bytes(join(home, "amem.config.json"), true);
+  const machine = json(join(home, "machine.json"));
+  if (machine?.id !== base.shards.machine.id) fail();
+  // An in-flight migration/prune is never accepted as a stable placement source.
+  for (const name of ["profile.lock", PUBLIC_PRUNE_INTENT]) if (lstatSync(join(home, name), { throwIfNoEntry: false })) fail();
+  const reader = new SegmentReader(16 * 1024 * 1024, { maxSourceBytes: 8 * 1024 * 1024, maxRows: 20000 });
+  const rows = new Map<string, PlacementSourceRow>(), specialRows = new Map<string, PlacementSpecialSourceRow>(), sourceRowsByRealm = new Map<string, readonly PruneSourceRow[]>();
+  const directories = [home], prefixes: PlacementPublicationSource[] = [];
+  const realms: SyncPlacementActivationContext["realms"][number][] = [];
+  const listing = (dir: string, optional = false): string[] => {
+    const s = lstatSync(dir, { throwIfNoEntry: false });
+    if (!s) { if (!optional) fail(); facts.push([dir, null]); sourceChecks.push(() => {if(lstatSync(dir,{throwIfNoEntry:false}))fail();}); return []; }
+    directoryFact(dir); const listStamp = lstatSync(dir,{bigint:true});
+    sourceChecks.push(() => { if(!same(listStamp,lstatSync(dir,{bigint:true}))) fail(); });
+    const iterator = opendirSync(dir), names: string[] = [];
+    try { for (;;) { const item = iterator.readSync(); if (!item) break; if (names.length >= 256) fail("bound"); names.push(item.name); } }
+    finally { iterator.closeSync(); }
+    names.sort(); facts.push([dir, names]); return names;
+  };
+  const realm = (dir: string, identity: PlacementKey["realm"], project?: string) => {
+    directories.push(dir);
+    const beforeFacts = facts.length; directoryFact(dir);
+    if (project !== undefined) {
+      const descriptor = json(join(dir, "project.json"));
+      if (descriptor?.schema !== SHARD_SCHEMA || descriptor.key !== project || typeof descriptor.local !== "boolean") fail();
+    }
+    const descriptor = json(join(dir, "generation.json")), sources = json(join(dir, "migration-sources.json")), seal = json(join(dir, "generation-seal.json"));
+    if (canonicalJSON(descriptor) !== canonicalJSON(generationDescriptor(base.profile.generation)) || !Array.isArray(sources?.sources)
+      || sources.schema !== "agent-mem.migration-sources/v1" || seal?.schema !== "agent-mem.generation-seal/v1"
+      || seal.generation !== base.profile.generation || seal.descriptorHash !== hashJSON(descriptor)
+      || seal.sourceDigest !== hashJSON({ sources: sources.sources, legacyCommit: sources.legacyCommit })
+      || json(join(dir, "machine.json"))?.id !== machine.id) fail();
+    const hasMain = !!lstatSync(join(dir, "legacy-main"), { throwIfNoEntry: false });
+    const profile: BoundProfile = { kind: "generation", home, dir, generation: base.profile.generation, selectorRevision: hashJSON(base.profile),
+      sharded: true, legacyHome: join(dir, "legacy"), ...(hasMain ? { legacyMainHome: join(dir, "legacy-main") } : {}) };
+    for (const root of [profile.legacyHome!, ...(hasMain ? [profile.legacyMainHome!] : [])]) {
+      directoryFact(root); bytes(join(root, "machine.json"), true);
+      for(const folder of ["log","local"]) {
+        const file=join(root,folder), s=lstatSync(file,{bigint:true,throwIfNoEntry:false});
+        sourceChecks.push(() => { const now=lstatSync(file,{bigint:true,throwIfNoEntry:false}); if(s ? !now||!same(s,now) : now!==undefined) fail(); });
+      }
+    }
+    const segments = readShardLegacySnapshot(profile, { reader });
+    for (const folder of ["log", "local"]) {
+      directoryFact(join(dir, folder));
+      const folderPath=join(dir,folder), folderStamp=lstatSync(folderPath,{bigint:true});
+      sourceChecks.push(() => { if(!same(folderStamp,lstatSync(folderPath,{bigint:true}))) fail(); });
+      if(folder === "local") bytes(join(dir,folder,`publisher-boundary-${machine.id}.json`),true);
+      for (const name of reader.listFiles(join(dir, folder))) {
+        if (!name.endsWith(".jsonl")) continue;
+        if ( !/^[A-Za-z0-9][A-Za-z0-9._-]*\.jsonl$/.test(name)) fail();
+        segments.push({ ...reader.read(join(dir, folder, name), undefined, true), source: "generation", path: `${folder}/${name}`, local: folder === "local" });
+      }
+    }
+    const presence = new Map<string, PruneSourceRow>();
+    const special = new Map<string, PlacementSpecialSourceRow>();
+    const retainSpecial = (row: PruneRow | VaultLinkRow, local: boolean) => {
+      const key = { realm: identity, id: row.id, rowHash: hashJSON(row) }, prior = special.get(row.id);
+      if (prior && (prior.key.rowHash !== key.rowHash || prior.sourcePlacement !== (local ? "local" : "synced"))) fail();
+      special.set(row.id, { key, row, sourcePlacement: local ? "local" : "synced", intrinsicLocal: row.op === "vault_link" });
+    };
+    for (const segment of segments) {
+      const file = join(segment.source === "generation" ? dir : segment.source === "legacy-main" ? profile.legacyMainHome! : profile.legacyHome!, segment.path);
+      const fileStat = lstatSync(file);
+      if (!fileStat.isFile() || fileStat.isSymbolicLink() || fileStat.nlink !== 1 || fileStat.uid !== process.getuid?.() || (fileStat.mode & 0o022) !== 0) fail();
+      let sourceHash = segment.hash, sourceLength = segment.offset;
+      if (segment.tailBytes) {
+        const proof = pendingByPath.get(canonicalJSON(identity)+":"+digest(segment.path));
+        if (segment.source !== "generation" || !proof || proof.offset !== segment.offset || proof.prefixHash !== segment.hash
+          || segment.tailBytes >= Buffer.byteLength(proof.line) || segment.tailBytes > 16384) fail();
+        const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+          const opened = fstatSync(fd, { bigint: true });
+          if (canonicalJSON(stamp(opened)) !== segment.stamp) fail();
+          const tail = Buffer.alloc(segment.tailBytes); let at = 0;
+          while (at < tail.length) { const n = readSync(fd, tail, at, tail.length-at, segment.offset+at); if (!n) fail(); at+=n; }
+          if (!tail.equals(Buffer.from(proof.line).subarray(0,tail.length)) || !same(opened,fstatSync(fd,{bigint:true})) || !same(opened,lstatSync(file,{bigint:true}))) fail();
+          sourceHash = createHash("sha256").update(segment.bytes).update(tail).digest("hex"); sourceLength += tail.length;
+        } finally { closeSync(fd); }
+      }
+      facts.push([dir, segment.source, segment.path, sourceLength, sourceHash, segment.stamp]);
+      const fileStamp=lstatSync(file,{bigint:true});
+      if(canonicalJSON(stamp(fileStamp))!==segment.stamp) fail();
+      sourceChecks.push(() => { const now=lstatSync(file,{bigint:true}); if(now.isSymbolicLink()||!now.isFile()||now.nlink!==1n||!same(fileStamp,now)) fail(); });
+      if (!segment.stamp || !["generation", "legacy-local", "legacy-main"].includes(segment.source)) fail();
+      const physical: unknown = JSON.parse(segment.stamp);
+      if (!Array.isArray(physical) || physical.length !== 5 || !physical.every(value => typeof value === "string" && /^[0-9]+$/.test(value))) fail();
+      prefixes.push({ realm: identity, source: segment.source as PlacementPublicationSource["source"], pathHash: digest(segment.path),
+        dev: physical[0] as string, ino: physical[1] as string, byteLength: sourceLength, hash: sourceHash,
+        mtimeNs: physical[3] as string, ctimeNs: physical[4] as string });
+      for (const line of completeLines(segment.bytes)) {
+        if (!line.length) continue;
+        const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(line));
+        if (segment.source === "generation" && parsed?.op === "prune") {
+          const row = validatePruneRow(parsed, profile.generation, segment.local ? "local" : "synced");
+          if (segment.path !== `${segment.local ? "local" : "log"}/${row.machine}.jsonl`) fail();
+          retainSpecial(row, segment.local);
+          continue;
+        }
+        if (segment.source === "generation" && parsed?.op === "vault_link") {
+          const row = validateVaultLinkRow(parsed, profile.generation, segment.local ? "local" : "synced");
+          if (segment.path !== `local/${row.machine}.jsonl`) fail();
+          retainSpecial(row, true);
+          continue;
+        }
+        const entry = checkedEntry(parsed);
+        presence.set(entry.id, coalesceGenerationSource(presence.get(entry.id), entry, segment));
+      }
+    }
+    for (const source of special.values()) {
+      if (presence.has(source.key.id)) fail();
+      specialRows.set(placementKeyId(source.key), source);
+    }
+    sourceRowsByRealm.set(canonicalJSON(identity), [...presence.values()]);
+    for (const source of presence.values()) {
+      const key = { realm: identity, id: source.row.id, rowHash: hashJSON(source.row) };
+      rows.set(placementKeyId(key), { key, row: source.row, sourcePlacement: source.placement,
+        intrinsicLocal: source.row.op === "settle" || source.row.op === "note" && source.row.tier === "short" });
+    }
+    const bindingHash = hashJSON(facts.slice(beforeFacts));
+    realms.push({ ...identity, bindingHash });
+  };
+  if (!selection || selection.some(item => item.scope === "user")) realm(join(home, "user"), { scope: "user" });
+  for (const name of listing(join(home, "projects"), true)) {
+    if (!/^[a-f0-9]{16}$/.test(name)) fail();
+    if (selection && !selection.some(item => item.scope === "project" && item.keyHash.slice(0,16) === name)) continue;
+    const dir = join(home, "projects", name), project = json(join(dir, "project.json"));
+    if (typeof project?.key !== "string" || shardKeyHash(project.key) !== name) fail();
+    // Capture scaffolds are not curated realms, but their identity still binds this inventory.
+    if (!lstatSync(join(dir, "generation.json"), { throwIfNoEntry: false })) continue;
+    const keyHash = digest(project.key);
+    if (selection && !selection.some(item => item.scope === "project" && item.keyHash === keyHash)) fail();
+    realm(dir, { scope: "project", keyHash }, project.key);
+  }
+  if (selection && realms.length !== selection.length) fail();
+  const defaults = memoryPolicySnapshot({ names: DENY_NAMES, segments: DENY_SEGMENTS }); if (!defaults) fail();
+  const configuration = loadAmemConfig(home).config;
+  const context: SyncPlacementActivationContext = { ...base, homeHash: hashJSON([home, String(root.dev), String(root.ino), String(root.uid)]), sourceHash: hashJSON(facts),
+    aliasesHash: digest(aliases ?? Buffer.alloc(0)), policyHash: hashJSON({ config: configuration, defaults, policyVersion }), realms,
+    writers: attestation.writers, legacySyncQuiesced: attestation.legacySyncQuiesced };
+  // Reuse the closed stage-1 context validator, including writer/version/realm bounds.
+  const validated = planSyncPlacementActivation(context, "0".repeat(64));
+  context.writers = validated.writers; context.realms = validated.realms;
+  // ponytail: fast rechecks rely on held mutation fences plus native inode/size/ctime identity for the already-hashed prefixes.
+  // A hostile same-user raw writer is outside that contract; descriptor-bound immutable source blocks are the upgrade path.
+  const assertUnchanged = () => {
+    try {
+    // Host callbacks run first; the final filesystem proof never invokes caller code afterwards.
+    const currentAttestation=memoryPolicySnapshot(port.attest()), currentVersion=port.policyVersion?.();
+    if(!currentAttestation) fail();
+    const checked=planSyncPlacementActivation({...context,writers:currentAttestation.writers,legacySyncQuiesced:currentAttestation.legacySyncQuiesced},"0".repeat(64));
+    const currentDefaults=memoryPolicySnapshot({names:DENY_NAMES,segments:DENY_SEGMENTS});
+    if(!currentDefaults)fail();
+    if(canonicalJSON(checked.writers)!==canonicalJSON(context.writers)||hashJSON({config:configuration,defaults:currentDefaults,policyVersion:currentVersion})!==context.policyHash) fail();
+    const now=ownedDirectory(home); if(now.dev!==root.dev||now.ino!==root.ino) fail();
+    for(const check of sourceChecks)check();
+    } catch { fail(); }
+  };
+  return { home, context, assertUnchanged, ...(activeHead ? { activeHead } : {}), markerHash, fingerprint: hashJSON({ context, markerHash }), directories: directories.sort(), prefixes, rows, specialRows, sourceRowsByRealm };
+}
+export function captureSyncPlacementContext(home: string, port: PlacementCapturePort, selected?: readonly PlacementRealm[], pendingInput: readonly PlacementPendingSource[] = []): PlacementCapture {
+  try {
+    const selection = selected === undefined ? undefined : memoryPolicySnapshot(selected);
+    if (selected !== undefined && !selection) fail();
+    if (!Array.isArray(pendingInput) || types.isProxy(pendingInput) || pendingInput.length > 20000) fail("bound");
+    const pending = pendingInput.map(item => {
+      if (!item || typeof item !== "object" || types.isProxy(item)) fail();
+      const fields = Object.getOwnPropertyDescriptors(item);
+      if (Object.keys(fields).sort().join() !== "line,offset,pathHash,prefixHash,realm" || Object.values(fields).some(field => !("value" in field) || !field.enumerable)) fail();
+      const realm = validatePlacementKey({realm:fields.realm!.value,id:"0".repeat(32),rowHash:"0".repeat(64)}).realm;
+      const line: unknown = fields.line!.value, offset: unknown = fields.offset!.value, pathHash: unknown = fields.pathHash!.value, prefixHash: unknown = fields.prefixHash!.value;
+      if (typeof line !== "string" || Buffer.byteLength(line)>16384 || !line.endsWith("\n") || typeof offset!=="number" || !Number.isSafeInteger(offset) || offset<0
+        || typeof pathHash!=="string" || pathHash.length!==64 || !/^[a-f0-9]+$/.test(pathHash) || typeof prefixHash!=="string" || prefixHash.length!==64 || !/^[a-f0-9]+$/.test(prefixHash)) fail();
+      return {realm,line,offset,pathHash,prefixHash};
+    });
+    const before = capture(home, port, selection, pending);
+    return { ...before, assertCurrent: () => { try { if (capture(home, port, selection, pending).fingerprint !== before.fingerprint) fail(); } catch { fail(); } } };
+  } catch (error) {
+    if (error && typeof error === "object" && !types.isProxy(error)) {
+      if (error instanceof SyncPlacementJournalError) throw error;
+      if (error instanceof SegmentReadBudgetError) return fail("bound");
+    }
+    return fail();
+  }
+}