@staix/agent-mem 0.20.3 → 0.22.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-cadence.ts

@@ -88,8 +88,9 @@ export function endLikeSignal(name: string): void {
  */
 function syncRepository(home: string): string | undefined {
   try {
-    if (lstatSync(join(home, "shards.json"), { throwIfNoEntry: false })) return join(home, "shard-sync", "objects.git", "config");
     const { selector } = readSelector(home);
+    if (selector?.schema === "agent-mem.profile/v3") return join(home,"shard-sync-placement","objects.git","config");
+    if (lstatSync(join(home, "shards.json"), { throwIfNoEntry: false })) return join(home, "shard-sync", "objects.git", "config");
     if (selector?.kind === "generation") return join(generationDir(home, selector.generation!), ".git", "config");
     return join(home, ".git", "config");
   } catch { return undefined; }

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

@@ -0,0 +1,142 @@
+/** Person coordinator's precommit-only metadata cleanup. No rollback, source rewrite, renewal or package measurement. */
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync, opendirSync, readSync, rmdirSync, unlinkSync, type BigIntStats } from "node:fs";
+import { dirname, join } from "node:path";
+import { types } from "node:util";
+import { canonicalJSON } from "./generation.ts";
+import { realPath } from "./platform.ts";
+import { assertMutationHandle, type MutationHandle } from "./mutation.ts";
+import { placementEpochHash, SyncPlacementJournalError, type SyncPlacementJournalErrorCode } from "./sync-placement-journal-format.ts";
+import { validatePlacementActivationIntent, readPlacementActivationIntent, clearPlacementActivationIntent, PLACEMENT_ACTIVATION_INTENT_FILE, type PlacementActivationIntent } from "./sync-placement-activation-storage.ts";
+import { planSyncPlacementWriterRoots, SYNC_PLACEMENT_WRITER_ROOTS_FILE } from "./sync-placement-writer-roots.ts";
+import { syncPlacementWriterId } from "./sync-placement-writers.ts";
+import { SYNC_SCREEN_MAX_BYTES, SYNC_SCREEN_MAX_ROWS } from "./sync-screen.ts";
+
+export interface PlacementAbandonOptions { mutation: MutationHandle; assertCurrent(): void }
+export class PlacementActivationAbandonError extends Error {
+  readonly code: "forward" | "metadata" | "bound";
+  constructor(code: "forward" | "metadata" | "bound" = "metadata") {
+    super(code === "forward"
+      ? "activation markers or active fence changed; use forward --resume with a compatible recovery release"
+      : code === "bound" ? "activation cleanup metadata exceeds the supported bound; inspect it with a compatible recovery release"
+      : "activation cleanup metadata is unsafe, changed or unknown; inspect it with a compatible recovery release before deleting anything");
+    this.name = "PlacementActivationAbandonError"; this.code = code;
+  }
+}
+function fail(code: SyncPlacementJournalErrorCode = "corrupt"): never { throw new SyncPlacementJournalError(code); }
+const bytes = (value: unknown) => Buffer.from(canonicalJSON(value) + "\n");
+const hash = (value: Uint8Array) => createHash("sha256").update(value).digest("hex");
+const identity = (s: BigIntStats) => [s.dev, s.ino, s.uid, s.mode].map(String).join(":");
+const stamp = (s: BigIntStats) => [s.dev, s.ino, s.uid, s.mode, s.nlink, s.size, s.mtimeNs, s.ctimeNs].map(String).join(":");
+function owned(s: BigIntStats, directory = false, links: readonly bigint[] = [1n], marker = false): void {
+  if (s.isSymbolicLink() || s.uid !== BigInt(process.getuid?.() ?? -1)
+    || (directory ? !s.isDirectory() || (s.mode & 0o077n) !== 0n : !s.isFile() || !links.includes(s.nlink) || (marker ? (s.mode & 0o022n) !== 0n : (s.mode & 0o777n) !== 0o600n))) fail();
+}
+interface Member { stat: BigIntStats; expected: Buffer }
+interface State { files: Map<string, Member>; dirs: Map<string, BigIntStats> }
+function readMember(file: string, expected: Buffer, prefix = false, links: readonly bigint[] = [1n], marker = false): Member | undefined {
+  const before = lstatSync(file, { bigint: true, throwIfNoEntry: false }); if (!before) return undefined;
+  owned(before, false, links, marker); if (before.size > BigInt(expected.length)) fail("bound");
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const opened = fstatSync(fd, { bigint: true }); if (stamp(opened) !== stamp(before)) fail("changed");
+    const data = Buffer.alloc(Number(opened.size) + 1); let at = 0;
+    while (at < data.length) { const n = readSync(fd, data, at, data.length - at, at); if (!n) break; at += n; }
+    if (at !== Number(opened.size) || stamp(fstatSync(fd, { bigint: true })) !== stamp(opened) || stamp(lstatSync(file, { bigint: true })) !== stamp(opened)) fail("changed");
+    if ((!prefix && at !== expected.length) || !data.subarray(0, at).equals(expected.subarray(0, at))) fail("conflict");
+    return { stat: opened, expected };
+  } finally { closeSync(fd); }
+}
+function directory(path: string): BigIntStats | undefined {
+  const value = lstatSync(path, { bigint: true, throwIfNoEntry: false }); if (value) owned(value, true); return value;
+}
+function names(path: string, maximum: number): string[] {
+  const result: string[] = [], iterator = opendirSync(path); let size = 2;
+  try { for (;;) { const entry = iterator.readSync(); if (!entry) break; if (result.length >= maximum) fail("bound");
+    size += Buffer.byteLength(JSON.stringify(entry.name)) + 1; if (size > SYNC_SCREEN_MAX_BYTES) fail("bound"); result.push(entry.name);
+  } } finally { iterator.closeSync(); } return result.sort();
+}
+/** Called only after person approval and under activation's existing live profile/readers/sync/mutation fences. */
+export function abandonPlacementActivation(homeInput: string, input: PlacementActivationIntent, options: PlacementAbandonOptions): void {
+  try {
+    const intent = validatePlacementActivationIntent(input), initialHome = lstatSync(homeInput, { bigint: true }); owned(initialHome, true);
+    const home = realPath(homeInput); if (home !== intent.home || identity(directory(home)!) !== identity(initialHome)) fail("changed");
+    const epochHash = placementEpochHash(intent.epoch), storage = join(home, "sync-placement"), epochs = join(storage, "epochs"), epochDir = join(epochs, epochHash);
+    const intentFile = join(home, PLACEMENT_ACTIVATION_INTENT_FILE), intentBytes = bytes(intent), intentTemp = intentFile + ".pending-" + hash(intentBytes);
+    const roots = intent.roots.map(root => {
+      const writerId = syncPlacementWriterId(root), writer = intent.plan.writers.find(value => value.writerId === writerId); if (!writer) fail("conflict");
+      return { root, writerId, version: writer.version, pin: writer.pin };
+    });
+    const locatorBytes = bytes(planSyncPlacementWriterRoots({ epochHash, homeHash: intent.epoch.homeHash, activationHash: intent.plan.seal, roots },
+      { epochHash, homeHash: intent.epoch.homeHash, activationHash: intent.plan.seal, writers: intent.plan.writers }));
+    const locator = join(home, SYNC_PLACEMENT_WRITER_ROOTS_FILE), locatorTemp = locator + ".pending-" + hash(locatorBytes);
+    const expectedEpoch = new Map([["epoch.json", bytes(intent.epoch)], ["activation.json", bytes(intent.plan)]]);
+    let clearing = false;
+    const proof = () => {
+      assertMutationHandle(options.mutation, home); options.assertCurrent(); assertMutationHandle(options.mutation, home);
+      if (identity(directory(home)!) !== identity(initialHome)) fail("changed");
+      try {
+        if (!readMember(join(home, "profile.json"), Buffer.from(intent.previousProfile), false, [1n], true)
+          || !readMember(join(home, "shards.json"), Buffer.from(intent.previousShards), false, [1n], true)) throw new PlacementActivationAbandonError("forward");
+      } catch { throw new PlacementActivationAbandonError("forward"); }
+      if (directory(storage) && lstatSync(join(storage, "active.json"), { throwIfNoEntry: false })) throw new PlacementActivationAbandonError("forward");
+      const actual = readPlacementActivationIntent(home);
+      if (actual ? canonicalJSON(actual) !== canonicalJSON(intent) : !clearing) fail("changed");
+    };
+    const scan = (): State => {
+      const files = new Map<string, Member>(), dirs = new Map<string, BigIntStats>([[home, directory(home)!]]);
+      for (const path of [storage, epochs, epochDir]) { const stat = directory(path); if (stat) dirs.set(path, stat); }
+      if (dirs.has(storage)) for (const name of names(storage, 2)) if (name !== "epochs") fail("corrupt");
+      const knownTemps = new Set([intentTemp, locatorTemp]);
+      for (const name of names(home, SYNC_SCREEN_MAX_ROWS)) if (name.startsWith(PLACEMENT_ACTIVATION_INTENT_FILE + ".pending-") || name.startsWith(SYNC_PLACEMENT_WRITER_ROOTS_FILE + ".pending-"))
+        if (!knownTemps.has(join(home, name))) fail("corrupt");
+      const add = (path: string, expected: Buffer, prefix = false, links: readonly bigint[] = [1n]) => { const value = readMember(path, expected, prefix, links); if (value) files.set(path, value); return value; };
+      const final = add(locator, locatorBytes, false, [1n, 2n]), temp = add(locatorTemp, locatorBytes, true, [1n, 2n]);
+      if (final?.stat.nlink === 2n || temp?.stat.nlink === 2n) {
+        if (!final || !temp || final.stat.size !== BigInt(locatorBytes.length) || temp.stat.size !== BigInt(locatorBytes.length) || stamp(final.stat) !== stamp(temp.stat)) fail("corrupt");
+      }
+      if (dirs.has(epochDir)) for (const name of names(epochDir, 3)) { const expected = expectedEpoch.get(name); if (!expected) fail("corrupt"); add(join(epochDir, name), expected, true); }
+      const current = add(intentFile, intentBytes, false, [1n, 2n]), companion = add(intentTemp, intentBytes, false, [1n, 2n]);
+      if (current?.stat.nlink === 2n || companion) {
+        if (!current || !companion || current.stat.nlink !== 2n || companion.stat.nlink !== 2n || stamp(current.stat) !== stamp(companion.stat)) fail("corrupt");
+      }
+      if (!current && !clearing) fail("changed"); return { files, dirs };
+    };
+    proof(); let state = scan();
+    const check = () => {
+      proof(); const next = scan();
+      const expectedFiles = [...state.files.keys()].filter(path => !clearing || path !== intentFile).sort(), foundFiles = [...next.files.keys()].filter(path => !clearing || path !== intentFile).sort();
+      if (canonicalJSON(expectedFiles) !== canonicalJSON(foundFiles) || canonicalJSON([...state.dirs.keys()].sort()) !== canonicalJSON([...next.dirs.keys()].sort())) fail("changed");
+      for (const [path, before] of state.files) { const after = next.files.get(path); if (clearing && path === intentFile && !after) continue; if (!after || stamp(before.stat) !== stamp(after.stat)) fail("changed"); }
+      for (const [path, before] of state.dirs) if (identity(before) !== identity(next.dirs.get(path)!)) fail("changed");
+    };
+    const sync = (path: string) => {
+      check(); const expected = state.dirs.get(path); if (!expected) fail("changed"); const fd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+      try { if (identity(fstatSync(fd, { bigint: true })) !== identity(expected)) fail("changed"); fsyncSync(fd); } finally { closeSync(fd); } check();
+    };
+    const remove = (path: string) => {
+      if (!state.files.has(path)) return; check(); const before = state.files.get(path)!; unlinkSync(path); state.files.delete(path);
+      for (const [peer, item] of state.files) if (item.stat.dev === before.stat.dev && item.stat.ino === before.stat.ino) {
+        const now = lstatSync(peer, { bigint: true }); owned(now);
+        if (before.stat.nlink !== 2n || now.nlink !== 1n || now.dev !== item.stat.dev || now.ino !== item.stat.ino || now.uid !== item.stat.uid || now.mode !== item.stat.mode || now.size !== item.stat.size || now.mtimeNs !== item.stat.mtimeNs) fail("changed");
+        item.stat = now;
+      }
+      sync(dirname(path));
+    };
+    remove(locatorTemp); remove(locator);
+    for (const name of ["activation.json", "epoch.json"]) remove(join(epochDir, name));
+    if (state.dirs.has(epochDir)) { check(); if (names(epochDir, 1).length) fail("changed"); rmdirSync(epochDir); state.dirs.delete(epochDir); sync(epochs); }
+    remove(intentTemp);
+    // A prior owner may have unlinked a member or removed this epoch before its directory fsync.
+    // Reassert every retained parent before the intent can acknowledge that cleanup as complete.
+    for (const path of [epochs, storage, home]) if (state.dirs.has(path)) sync(path);
+    check(); clearing = true;
+    clearPlacementActivationIntent(home, intent, { mutation: options.mutation, assertCurrent: check }); state.files.delete(intentFile); check();
+  } catch (error) {
+    if (error && typeof error === "object" && !types.isProxy(error) && error instanceof PlacementActivationAbandonError) throw error;
+    if (error && typeof error === "object" && !types.isProxy(error) && error instanceof SyncPlacementJournalError) {
+      const value = Object.getOwnPropertyDescriptor(error, "code"); if (value && "value" in value && ["invalid", "corrupt", "bound", "conflict", "pending", "changed", "authorization", "policy", "local", "busy"].includes(value.value)) throw new PlacementActivationAbandonError(value.value === "bound" ? "bound" : "metadata");
+    }
+    throw new PlacementActivationAbandonError();
+  }
+}

package/src/memory/sync-placement-activation-locks.ts

@@ -0,0 +1,28 @@
+/** Shared person-migration fences. No serialized value grants ownership. */
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { withProfileLock } from "./generation.ts";
+import { acquireMutation, type MutationHandle } from "./mutation.ts";
+import { generationSyncLock } from "./generation-sync.ts";
+import { assertNoLiveReaders } from "./reader-lease.ts";
+import { createPlacementActivationOwner } from "./sync-placement-activation-proof.ts";
+export class PlacementInventoryFenceError extends Error{
+  constructor(readonly causeClass:"readers"|"busy"){super(`Sync placement migration is ${causeClass}; close cooperating readers/writers, then run amem migrate --sync-placement --dry-run before retrying.`);this.name="PlacementInventoryFenceError";}
+}
+function fail(cause:"readers"|"busy"):never{throw new PlacementInventoryFenceError(cause);}
+export async function withPlacementActivationFences<T>(home:string,directories:readonly string[],work:(mutation:MutationHandle,owner:ReturnType<typeof createPlacementActivationOwner>)=>Promise<T>):Promise<T> {
+  return withProfileLock(home,async()=>{
+    const releases:(()=>void)[]=[];
+    try {
+      const transports=["shard-sync","shard-sync-placement"].map(name=>join(home,name)).filter(dir=>lstatSync(dir,{throwIfNoEntry:false})!==undefined);
+      const dirs=[...new Set([home,...directories,...transports])].sort();let mutation:MutationHandle|undefined;
+      for(const dir of dirs){
+        try{assertNoLiveReaders(dir,{includeShards:true});}catch{fail("readers");}
+        const handle=acquireMutation(dir);if(!handle)fail("busy");releases.push(handle);if(dir===home)mutation=handle;
+      }
+      if(!mutation)fail("busy");
+      for(const dir of [home,...transports]){const release=generationSyncLock(dir);if(!release)fail("busy");releases.push(release);}
+      const owner=createPlacementActivationOwner(home,mutation);return await work(mutation,owner);
+    }finally{for(const release of releases.reverse())release();}
+  });
+}

package/src/memory/sync-placement-activation-path.ts

@@ -0,0 +1,2 @@
+/** Pending coordinator metadata, outside the closed placement-journal namespace. */
+export const PLACEMENT_ACTIVATION_INTENT = "sync-placement-activation.json";

package/src/memory/sync-placement-activation-proof.ts

@@ -0,0 +1,68 @@
+/** Internal activation-owner proof. No serialized object or boolean grants lock bypass authority. */
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, type BigIntStats } from "node:fs";
+import { join } from "node:path";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { assertMutationHandle, type MutationHandle } from "./mutation.ts";
+import { processSignature, realPath } from "./platform.ts";
+import type { PlacementActivationMarkerSnapshot } from "./sync-placement-capture.ts";
+import { readPlacementActivationIntent, validatePlacementActivationIntent, placementActivationFinalMarkers, type PlacementActivationIntent } from "./sync-placement-activation-storage.ts";
+
+declare const ownerBrand: unique symbol, captureBrand: unique symbol;
+export interface PlacementActivationOwner { readonly [ownerBrand]: true }
+export interface PlacementActivationCaptureProof { readonly [captureBrand]: true }
+interface Owner { home: string; mutation: MutationHandle; root: BigIntStats; lock: string; lockStamp: string }
+const owners = new WeakMap<PlacementActivationOwner, Owner>();
+const captures = new WeakMap<PlacementActivationCaptureProof, { owner: PlacementActivationOwner; intent: PlacementActivationIntent }>();
+const stamp = (s: BigIntStats) => [s.dev,s.ino,s.size,s.mtimeNs,s.ctimeNs].map(String).join(":");
+function fail(): never { throw Error("Sync placement activation ownership or retained evidence changed; close cooperating writers and run amem migrate --sync-placement --resume after person inspection."); }
+function lockBytes(home: string): { text: string; stamp: string } {
+  const file = join(home,"profile.lock"), before = lstatSync(file,{bigint:true});
+  if (!before.isFile() || before.isSymbolicLink() || before.uid !== BigInt(process.getuid?.() ?? -1) || (before.mode & 0o077n) !== 0n || before.nlink !== 1n || before.size < 1n || before.size > 4096n) fail();
+  const fd = openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
+  try {
+    const opened = fstatSync(fd,{bigint:true}); if (stamp(opened) !== stamp(before)) fail();
+    const out = Buffer.alloc(Number(opened.size)); let at = 0;
+    while (at < out.length) { const n = readSync(fd,out,at,out.length-at,at); if (!n) fail(); at += n; }
+    if (stamp(fstatSync(fd,{bigint:true})) !== stamp(opened) || stamp(lstatSync(file,{bigint:true})) !== stamp(opened)) fail();
+    return { text: new TextDecoder("utf-8",{fatal:true}).decode(out), stamp: stamp(opened) };
+  } finally { closeSync(fd); }
+}
+export function createPlacementActivationOwner(homeInput: string, mutation: MutationHandle): PlacementActivationOwner {
+  try {
+    const home = realPath(homeInput); assertMutationHandle(mutation,home);
+    const root = lstatSync(home,{bigint:true}), lock = lockBytes(home), value = JSON.parse(lock.text) as Record<string,unknown>;
+    if (!root.isDirectory() || root.isSymbolicLink() || root.uid !== BigInt(process.getuid?.() ?? -1) || (root.mode & 0o077n) !== 0n
+      || Object.keys(value).sort().join() !== "pid,signature,token" || value.pid !== process.pid || value.signature !== processSignature(process.pid)
+      || typeof value.signature !== "string" || !value.signature || typeof value.token !== "string" || !/^[a-f0-9]{32}$/.test(value.token)) fail();
+    const token = Object.freeze({}) as PlacementActivationOwner;
+    owners.set(token,{home,mutation,root,lock:lock.text,lockStamp:lock.stamp}); return token;
+  } catch { return fail(); }
+}
+export function assertPlacementActivationOwner(token: PlacementActivationOwner, home?: string): void {
+  try {
+    const owner = owners.get(token); if (!owner) fail(); assertMutationHandle(owner.mutation,owner.home);
+    if(home!==undefined&&realPath(home)!==owner.home)fail();
+    const root = lstatSync(owner.home,{bigint:true}), lock = lockBytes(owner.home);
+    if (!root.isDirectory() || root.isSymbolicLink() || root.dev !== owner.root.dev || root.ino !== owner.root.ino || root.uid !== owner.root.uid || (root.mode & 0o077n) !== 0n
+      || lock.text !== owner.lock || lock.stamp !== owner.lockStamp) fail();
+    assertMutationHandle(owner.mutation,owner.home);
+  } catch { fail(); }
+}
+export function createPlacementActivationCaptureProof(owner: PlacementActivationOwner, input: PlacementActivationIntent): PlacementActivationCaptureProof {
+  assertPlacementActivationOwner(owner);
+  const state = owners.get(owner)!;
+  const intent = validatePlacementActivationIntent(input), actual = readPlacementActivationIntent(state.home);
+  if (!intent || !actual || canonicalJSON(intent) !== canonicalJSON(actual)
+    || actual.home !== state.home || actual.epoch.homeHash !== hashJSON([state.home,String(state.root.dev),String(state.root.ino),String(state.root.uid)])) fail();
+  const token = Object.freeze({}) as PlacementActivationCaptureProof; captures.set(token,{owner,intent:actual}); return token;
+}
+export function activationSourceMarkers(token: PlacementActivationCaptureProof, home: string, markers: { profileText: string; shardsText: string; profileStamp: readonly string[]; shardsStamp: readonly string[] }): PlacementActivationMarkerSnapshot {
+  const scope = captures.get(token); if (!scope) fail(); assertPlacementActivationOwner(scope.owner);
+  const state = owners.get(scope.owner)!, actual = readPlacementActivationIntent(home), intent = scope.intent;
+  if (home !== state.home || !actual || canonicalJSON(actual) !== canonicalJSON(intent)) fail();
+  const { profileText, shardsText } = markers;
+  const final = placementActivationFinalMarkers(intent), oldProfile = profileText === intent.previousProfile, oldShards = shardsText === intent.previousShards;
+  if ((!oldProfile && profileText !== final.profile) || (!oldShards && shardsText !== final.shards) || !oldProfile && shardsText !== final.shards) fail();
+  if (oldProfile && canonicalJSON(markers.profileStamp) !== canonicalJSON(intent.profileStamp) || oldShards && canonicalJSON(markers.shardsStamp) !== canonicalJSON(intent.shardsStamp)) fail();
+  return { profileText:intent.previousProfile,shardsText:intent.previousShards,profileStamp:[...intent.profileStamp],shardsStamp:[...intent.shardsStamp] };
+}