@staix/agent-mem 0.21.0 → 0.22.1

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] };
+}

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

@@ -0,0 +1,167 @@
+/** Initial activation metadata only. Caller owns person authority, profile lock, writer inventory and source fences. */
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync, readSync, unlinkSync, type BigIntStats } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { types } from "node:util";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { realPath } from "./platform.ts";
+import { assertMutationHandle, type MutationHandle } from "./mutation.ts";
+import { validatePlacementBaseV2, validatePlacementShards, validatePlacementMarkerTransition, PLACEMENT_FORMAT, PLACEMENT_SHARDS_SCHEMA } from "./sync-placement-format.ts";
+import { validatePlacementPlan, type SyncPlacementActivationPlan } from "./sync-placement-plan.ts";
+import { validatePlacementEpoch, placementEpochHash, SyncPlacementJournalError, type PlacementEpoch, type SyncPlacementJournalErrorCode } from "./sync-placement-journal-format.ts";
+import { writeImmutableActivationMetadata } from "./public-prune-activation.ts";
+import { PLACEMENT_ACTIVATION_INTENT } from "./sync-placement-activation-path.ts";
+
+export const PLACEMENT_ACTIVATION_INTENT_SCHEMA = "agent-mem.sync-placement-activation/v1";
+export const PLACEMENT_ACTIVATION_INTENT_FILE = PLACEMENT_ACTIVATION_INTENT;
+const MAX_BYTES = 1024 * 1024, ROOTS_MAX = 256;
+export type PlacementActivationMarkerStamp = [string, string, string, string, string];
+export interface PlacementActivationIntent {
+  schema: typeof PLACEMENT_ACTIVATION_INTENT_SCHEMA; home: string; epoch: PlacementEpoch; plan: SyncPlacementActivationPlan; roots: string[];
+  previousProfile: string; previousShards: string; profileStamp: PlacementActivationMarkerStamp; shardsStamp: PlacementActivationMarkerStamp; floorHash: string;
+  inputHashes: {sourceHash:string;aliasesHash:string;policyHash:string}; seal: string;
+}
+export type PlacementActivationIntentBody = Omit<PlacementActivationIntent, "seal">;
+export interface PlacementActivationStorageProof { mutation: MutationHandle; assertCurrent(): void }
+function fail(code: SyncPlacementJournalErrorCode = "corrupt"): never { throw new SyncPlacementJournalError(code); }
+const bytes = (value: unknown) => Buffer.from(canonicalJSON(value) + "\n");
+const digest = (value: Uint8Array) => createHash("sha256").update(value).digest("hex");
+const hex = (value: unknown, length = 64): value is string => typeof value === "string" && value.length === length && /^[a-f0-9]+$/.test(value);
+function object(value: unknown, keys: readonly string[]): Record<string, unknown> {
+  if (!value || typeof value !== "object" || types.isProxy(value) || ![null, Object.prototype].includes(Object.getPrototypeOf(value)) || Object.getOwnPropertySymbols(value).length) fail("invalid");
+  const fields = Object.getOwnPropertyDescriptors(value); if (Object.keys(fields).length !== keys.length) fail("invalid");
+  const copied: Record<string, unknown> = Object.create(null);
+  for (const key of keys) { const field = fields[key]; if (!field || !("value" in field) || !field.enumerable) fail("invalid"); copied[key] = field.value; }
+  return copied;
+}
+function array(value: unknown, maximum: number): unknown[] {
+  if (!value || typeof value !== "object" || types.isProxy(value) || !Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype || Object.getOwnPropertySymbols(value).length) fail("invalid");
+  const length = Object.getOwnPropertyDescriptor(value, "length")?.value;
+  if (!Number.isSafeInteger(length) || length < 0 || length > maximum) fail("bound");
+  if (Object.getOwnPropertyNames(value).length !== length + 1) fail("invalid");
+  const output: unknown[] = [];
+  for (let i = 0; i < length; i++) { const field = Object.getOwnPropertyDescriptor(value, String(i)); if (!field || !("value" in field) || !field.enumerable) fail("invalid"); output.push(field.value); }
+  return output;
+}
+function path(value: unknown): string {
+  if (typeof value !== "string" || !isAbsolute(value) || Buffer.byteLength(value) > 4096 || value.includes("\0") || resolve(value) !== value) fail("invalid"); return value;
+}
+function markerStamp(value: unknown, text: string): PlacementActivationMarkerStamp {
+  const fields = array(value, 5);
+  if (fields.length !== 5 || fields.some((value, index) => typeof value !== "string" || value.length > 32 || !/^-?(?:0|[1-9][0-9]*)$/.test(value) || /[\r\n]/.test(value) || index < 3 && value.startsWith("-"))) fail("invalid");
+  if (fields[2] !== String(Buffer.byteLength(text))) fail("invalid"); return fields as PlacementActivationMarkerStamp;
+}
+function baseMarkers(profile: unknown, shards: unknown) {
+  if (typeof profile !== "string" || typeof shards !== "string" || Buffer.byteLength(profile) > 262144 || Buffer.byteLength(shards) > 262144) fail("bound");
+  // Preserve original UTF-8 text/stamps, including whitespace/BOM; only the containing intent and final v3 pair
+  // are canonical. Match the existing fatal UTF-8 marker decoder's BOM behavior without rewriting the source.
+  const decode = (text: string) => JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(text)));
+  return validatePlacementBaseV2(decode(profile), decode(shards));
+}
+function validate(value: unknown, sealed: boolean): PlacementActivationIntent {
+  const v = object(value, ["schema", "home", "epoch", "plan", "roots", "previousProfile", "previousShards", "profileStamp", "shardsStamp", "floorHash", "inputHashes", ...(sealed ? ["seal"] : [])]);
+  if (v.schema !== PLACEMENT_ACTIVATION_INTENT_SCHEMA || !hex(v.floorHash) || sealed && !hex(v.seal)) fail("invalid");
+  const home = path(v.home), epoch = validatePlacementEpoch(v.epoch), plan = validatePlacementPlan(v.plan), base = baseMarkers(v.previousProfile, v.previousShards);
+  const inputs=object(v.inputHashes,["sourceHash","aliasesHash","policyHash"]);
+  if(!hex(inputs.sourceHash)||!hex(inputs.aliasesHash)||!hex(inputs.policyHash))fail("invalid");
+  const inputHashes={sourceHash:inputs.sourceHash,aliasesHash:inputs.aliasesHash,policyHash:inputs.policyHash};
+  if(hashJSON({...base,homeHash:epoch.homeHash,...inputHashes,realms:plan.realms,writers:plan.writers,legacySyncQuiesced:true})!==plan.contextHash)fail("invalid");
+  const roots = array(v.roots, ROOTS_MAX).map(path); if (new Set(roots).size !== roots.length || canonicalJSON([...roots].sort()) !== canonicalJSON(roots)) fail("invalid");
+  if (epoch.contextHash !== plan.contextHash || epoch.generation !== plan.generation || base.profile.generation !== epoch.generation || placementEpochHash(epoch) !== plan.targetProfile.placementHead
+    || hashJSON(base.profile) !== plan.previousProfileHash || hashJSON(base.shards) !== plan.previousShardsHash) fail("invalid");
+  const final = validatePlacementShards({ ...base.shards, schema: PLACEMENT_SHARDS_SCHEMA, selectorRevision: hashJSON(plan.targetProfile), publicationFormat: PLACEMENT_FORMAT, placementHead: plan.targetProfile.placementHead }, plan.targetProfile);
+  validatePlacementMarkerTransition(base.profile, base.shards, plan.targetProfile, final); if (hashJSON(final) !== plan.targetShardsHash) fail("invalid");
+  const body: PlacementActivationIntentBody = { schema: PLACEMENT_ACTIVATION_INTENT_SCHEMA, home, epoch, plan, roots, previousProfile: v.previousProfile as string, previousShards: v.previousShards as string,
+    profileStamp: markerStamp(v.profileStamp, v.previousProfile as string), shardsStamp: markerStamp(v.shardsStamp, v.previousShards as string), floorHash: v.floorHash,inputHashes };
+  const intent = { ...body, seal: hashJSON(body) }; if (sealed && intent.seal !== v.seal) fail("corrupt"); if (bytes(intent).length > MAX_BYTES) fail("bound"); return intent;
+}
+function safe<T>(work: () => T): T {
+  try { return work(); }
+  catch (error) {
+    if (error && typeof error === "object" && !types.isProxy(error) && error instanceof SyncPlacementJournalError) {
+      const field = Object.getOwnPropertyDescriptor(error, "code");
+      if (field && "value" in field && ["invalid", "corrupt", "bound", "conflict", "pending", "changed", "authorization", "policy", "local", "busy"].includes(field.value)) fail(field.value);
+    }
+    return fail();
+  }
+}
+export function sealPlacementActivationIntent(body: PlacementActivationIntentBody): PlacementActivationIntent { return safe(() => validate(body, false)); }
+/** Detached data validation uses intent bounds, never policy-payload string limits. */
+export function validatePlacementActivationIntent(value: unknown): PlacementActivationIntent { return safe(() => validate(value, true)); }
+export function placementActivationFinalMarkers(value: PlacementActivationIntent): { profile: string; shards: string } {
+  return safe(() => {
+    const intent = validate(value, true), old = baseMarkers(intent.previousProfile, intent.previousShards);
+    const shards = validatePlacementShards({ ...old.shards, schema: PLACEMENT_SHARDS_SCHEMA, selectorRevision: hashJSON(intent.plan.targetProfile), publicationFormat: PLACEMENT_FORMAT, placementHead: intent.plan.targetProfile.placementHead }, intent.plan.targetProfile);
+    return { profile: canonicalJSON(intent.plan.targetProfile) + "\n", shards: canonicalJSON(shards) + "\n" };
+  });
+}
+function owned(stat: BigIntStats, directory = false, links: readonly bigint[] = [1n]): void {
+  if (stat.isSymbolicLink() || stat.uid !== BigInt(process.getuid?.() ?? -1) || (directory ? !stat.isDirectory() || (stat.mode & 0o077n) !== 0n : !stat.isFile() || (stat.mode & 0o777n) !== 0o600n || !links.includes(stat.nlink))) fail();
+}
+function same(a: BigIntStats, b: BigIntStats): boolean { return a.dev === b.dev && a.ino === b.ino && a.uid === b.uid && a.mode === b.mode && a.nlink === b.nlink && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs; }
+function root(home: string): { home: string; stat: BigIntStats; file: string } {
+  const stat = lstatSync(home, { bigint: true }); owned(stat, true); const canonical = realPath(home), current = lstatSync(canonical, { bigint: true }); owned(current, true);
+  if (stat.dev !== current.dev || stat.ino !== current.ino) fail("changed"); return { home: canonical, stat, file: join(canonical, PLACEMENT_ACTIVATION_INTENT_FILE) };
+}
+function bindHome(intent: PlacementActivationIntent, current: ReturnType<typeof root>): void {
+  if (intent.home !== current.home || intent.epoch.homeHash !== hashJSON([current.home, String(current.stat.dev), String(current.stat.ino), String(current.stat.uid)])) fail("changed");
+}
+interface Read { intent: PlacementActivationIntent; text: string; stat: BigIntStats }
+function read(current: ReturnType<typeof root>): Read | undefined {
+  const before = lstatSync(current.file, { bigint: true, throwIfNoEntry: false }); if (!before) return undefined;
+  owned(before, false, [1n, 2n]); if (before.size < 1n || before.size > BigInt(MAX_BYTES)) fail("bound");
+  const fd = openSync(current.file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const opened = fstatSync(fd, { bigint: true }); owned(opened, false, [1n, 2n]); if (!same(before, opened)) 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) || !same(opened, fstatSync(fd, { bigint: true })) || !same(opened, lstatSync(current.file, { bigint: true }))) fail("changed");
+    const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(data.subarray(0, at)), intent = validate(JSON.parse(text), true);
+    if (canonicalJSON(intent) + "\n" !== text) fail(); bindHome(intent, current);
+    if (opened.nlink === 2n) {
+      const companion = lstatSync(current.file + ".pending-" + digest(Buffer.from(text)), { bigint: true }); owned(companion, false, [2n]);
+      if (!same(opened, companion) || !same(opened, lstatSync(current.file, { bigint: true }))) fail("changed");
+    }
+    const finalRoot = root(current.home); if (finalRoot.stat.dev !== current.stat.dev || finalRoot.stat.ino !== current.stat.ino) fail("changed");
+    return { intent, text, stat: opened };
+  } finally { closeSync(fd); }
+}
+export function readPlacementActivationIntent(home: string): PlacementActivationIntent | undefined { return safe(() => read(root(home))?.intent); }
+function proof(current: ReturnType<typeof root>, options: PlacementActivationStorageProof): void {
+  try { assertMutationHandle(options.mutation, current.home); } catch { fail("busy"); }
+  try { options.assertCurrent(); } catch { fail("changed"); }
+  try { assertMutationHandle(options.mutation, current.home); } catch { fail("busy"); }
+  const now = root(current.home); if (now.stat.dev !== current.stat.dev || now.stat.ino !== current.stat.ino) fail("changed");
+}
+function syncHome(current: ReturnType<typeof root>, options: PlacementActivationStorageProof): void {
+  proof(current, options); const fd = openSync(current.home, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+  try { const stat = fstatSync(fd, { bigint: true }); owned(stat, true); if (stat.dev !== current.stat.dev || stat.ino !== current.stat.ino) fail("changed"); proof(current, options); fsyncSync(fd); }
+  finally { closeSync(fd); } proof(current, options);
+}
+export function writePlacementActivationIntent(home: string, value: PlacementActivationIntent, options: PlacementActivationStorageProof): void {
+  safe(() => {
+    const current = root(home), intent = validate(value, true); bindHome(intent, current); const expected = canonicalJSON(intent) + "\n";
+    proof(current, options); const prior = read(current); if (prior && prior.text !== expected) fail("conflict");
+    proof(current, options);
+    // The shared helper intentionally keeps its old algorithm; bound its unregistered staging read here first.
+    const temp = lstatSync(current.file + ".pending-" + digest(Buffer.from(expected)), { bigint: true, throwIfNoEntry: false });
+    if (temp) { owned(temp, false, prior?.stat.nlink === 2n ? [2n] : [1n]); if (temp.size > BigInt(MAX_BYTES)) fail("bound"); }
+    writeImmutableActivationMetadata(current.file, expected); proof(current, options);
+    const installed = read(current); if (!installed || installed.stat.nlink !== 1n || installed.text !== expected) fail("changed");
+    const fd = openSync(current.file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try { if (!same(installed.stat, fstatSync(fd, { bigint: true }))) fail("changed"); proof(current, options); if (!same(installed.stat, lstatSync(current.file, { bigint: true }))) fail("changed"); fsyncSync(fd); }
+    finally { closeSync(fd); } syncHome(current, options); proof(current, options);
+    if (read(current)?.text !== expected) fail("changed");
+  });
+}
+export function clearPlacementActivationIntent(home: string, value: PlacementActivationIntent, options: PlacementActivationStorageProof): void {
+  safe(() => {
+    const current = root(home), intent = validate(value, true); bindHome(intent, current); proof(current, options);
+    const prior = read(current);
+    if (prior) {
+      if (prior.text !== canonicalJSON(intent) + "\n") fail("conflict"); if (prior.stat.nlink !== 1n) fail("pending");
+      proof(current, options); if (!same(prior.stat, lstatSync(current.file, { bigint: true }))) fail("changed"); unlinkSync(current.file);
+    }
+    syncHome(current, options); proof(current, options); if (lstatSync(current.file, { throwIfNoEntry: false })) fail("changed");
+  });
+}

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

@@ -0,0 +1,185 @@
+/** Person-only home-wide initial activation. No automatic migration, renewal or transport. */
+import { randomBytes } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, lstatSync, openSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { types } from "node:util";
+import { canonicalJSON, hashJSON, writeProfileJSON, fsyncDirectory } from "./generation.ts";
+import { assertMutationHandle, type MutationHandle } from "./mutation.ts";
+import { withPlacementActivationFences, PlacementInventoryFenceError } from "./sync-placement-activation-locks.ts";
+import { realPath } from "./platform.ts";
+import { planSyncPlacementActivation, validateSyncPlacementActivation, SyncPlacementPlanError } from "./sync-placement-plan.ts";
+import { PLACEMENT_EPOCH_SCHEMA, placementEpochHash, SyncPlacementJournalError, type PlacementEpoch } from "./sync-placement-journal-format.ts";
+import { preparePlacementEpoch, ensurePlacementFence } from "./sync-placement-journal-storage.ts";
+import { readPlacementRuntimeMarkers } from "./sync-placement-guard.ts";
+import { readActivePlacementBinding } from "./sync-placement-active.ts";
+import { PLACEMENT_FORMAT } from "./sync-placement-format.ts";
+import { captureSyncPlacementActivationContext, previewSyncPlacementSources, type PlacementSourcePreview } from "./sync-placement-capture.ts";
+import { createPlacementActivationOwner, assertPlacementActivationOwner, createPlacementActivationCaptureProof } from "./sync-placement-activation-proof.ts";
+import { sealPlacementActivationIntent, readPlacementActivationIntent, writePlacementActivationIntent, clearPlacementActivationIntent, placementActivationFinalMarkers, PLACEMENT_ACTIVATION_INTENT_SCHEMA, type PlacementActivationIntent } from "./sync-placement-activation-storage.ts";
+import { writeSyncPlacementWriterRoots, readSyncPlacementWriterRoots, planSyncPlacementWriterRoots, SYNC_PLACEMENT_WRITER_ROOTS_FILE } from "./sync-placement-writer-roots.ts";
+import { SyncPlacementWriterError } from "./sync-placement-writers.ts";
+import { requirePlacementActivationPrerequisites, requirePlacementHomeFloor } from "./sync-placement-prerequisites.ts";
+import { outboundPolicyEvaluator, type SyncPolicyCategory } from "./sync-screen.ts";
+import { initialPlacementWriterContext, PlacementWriterContextError, type PlacementWriterContext } from "../sync-placement-writer-context.ts";
+import { abandonPlacementActivation, PlacementActivationAbandonError } from "./sync-placement-abandon.ts";
+import { renewSyncPlacementWriters } from "./sync-placement-writer-renewal.ts";
+import type { WriterHistoryPhase } from "./sync-placement-writer-history.ts";
+
+export type PlacementActivationStage = "after-intent"|"after-epoch"|"after-root-map"|"after-shards"|"after-profile"|"after-fence"|"after-remove";
+export interface PlacementActivationOptions {
+  memoryDir: string; mode: "dry-run"|"apply"|"resume"|"abandon"; writerRoots: readonly string[]; ownRoot: string;
+  authorize(binding: Readonly<{seal:string;generation:string;homeHash:string}>): boolean;
+  checkpoint?(stage: PlacementActivationStage): void|Promise<void>;
+  /** Internal renewal fault seam; the CLI never supplies it. */
+  renewalCheckpoint?(stage:WriterHistoryPhase):void;
+  /** Internal fault-test observer, never supplied by CLI options. */
+  testOnlyFailure?(error: unknown): void;
+}
+export class PlacementActivationError extends Error {
+  constructor(readonly causeClass: "readers"|"busy"|"changed"|"metadata"|"authorization"|"pending"|"bound") {
+    super(`Sync placement activation failed (${causeClass}); close cooperating writers and run amem migrate --sync-placement --dry-run before retrying apply. If an activation intent is retained, use --resume, or --abandon only while both markers are still the original v2 bytes. Once a v3 marker exists, resume is forward-only; never restore v2 markers.`);
+    this.name="PlacementActivationError";
+  }
+}
+export class PlacementActivationInputError extends Error {
+  constructor(readonly inputClass:"policy"|"source"|"aliases"|"writer root"|"receipt"|"floor"){
+    super(`Sync placement activation frozen ${inputClass} input changed or is unavailable; restore that input and run amem migrate --sync-placement --resume. If both markers still contain their original v2 bytes, the person may run amem migrate --sync-placement --abandon, then review a fresh --dry-run and --apply. Once any v3 marker exists, only forward resume is supported.`);
+    this.name="PlacementActivationInputError";
+  }
+}
+function writerInputFailure(error:unknown):never {
+  const category=error&&typeof error==="object"&&!types.isProxy(error)&&error instanceof PlacementWriterContextError?Object.getOwnPropertyDescriptor(error,"category")?.value:undefined;
+  throw new PlacementActivationInputError(category==="setup receipt"?"receipt":"writer root");
+}
+function fail(cause: PlacementActivationError["causeClass"]): never { throw new PlacementActivationError(cause); }
+function rethrowActivationFailure(error:unknown):never {
+    if(error&&typeof error==="object"&&!types.isProxy(error)){
+      if(error instanceof PlacementInventoryFenceError)fail(error.causeClass);
+      if(error instanceof PlacementWriterContextError||error instanceof PlacementActivationError||error instanceof PlacementActivationInputError||error instanceof PlacementActivationAbandonError)throw error;
+      if(error instanceof SyncPlacementJournalError||error instanceof SyncPlacementPlanError||error instanceof SyncPlacementWriterError){
+        const code=Object.getOwnPropertyDescriptor(error,"code");
+        if(code&&"value" in code){if(code.value==="bound")fail("bound");if(code.value==="busy")fail("busy");if(code.value==="changed")fail("changed");if(code.value==="authorization")fail("authorization");}
+      }
+    }
+    fail("metadata");
+}
+function counts(source: PlacementSourcePreview) {
+  const evaluate = outboundPolicyEvaluator(source.home), categories: Partial<Record<SyncPolicyCategory,number>> = {};
+  let eligibleOriginals=0,declined=0,intrinsicLocal=0;
+  for (const row of [...source.rows.values(),...source.specialRows.values()]) {
+    if (row.intrinsicLocal || row.sourcePlacement!=="synced") { intrinsicLocal++; continue; }
+    const verdict=evaluate(row.row as unknown as Record<string,unknown>);
+    if (verdict.ok) eligibleOriginals++; else { declined++;categories[verdict.category]=(categories[verdict.category]??0)+1; }
+  }
+  source.assertSourcesUnchanged();
+  return {selected:source.rows.size+source.specialRows.size,policyPermittedOriginals:eligibleOriginals,declined,intrinsicLocal,categories,dependencyDecisions:"deferred-to-sync" as const};
+}
+function committed(home:string,intent:Pick<PlacementActivationIntent,"epoch"|"plan">) {
+  const markers=readPlacementRuntimeMarkers(home);
+  if ((markers.profile as {schema?:string})?.schema!=="agent-mem.profile/v3"||(markers.shards as {schema?:string})?.schema!=="agent-mem.shards/v3") return false;
+  const binding=readActivePlacementBinding(home,markers.profile,markers.shards);
+  return binding?.profile.placementHead===placementEpochHash(intent.epoch)&&binding.activation.seal===intent.plan.seal;
+}
+function syncFile(file:string) {
+  const before=lstatSync(file,{bigint:true});
+  if (!before.isFile()||before.isSymbolicLink()||before.nlink!==1n||before.uid!==BigInt(process.getuid?.()??-1)||(before.mode&0o077n)!==0n) fail("metadata");
+  const fd=openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
+  try { const actual=fstatSync(fd,{bigint:true}); if(actual.dev!==before.dev||actual.ino!==before.ino||actual.size!==before.size)fail("changed");fsyncSync(fd); }
+  finally{closeSync(fd);}fsyncDirectory(join(file,".."));
+}
+function authorize(options:PlacementActivationOptions,intent:Pick<PlacementActivationIntent,"epoch"|"plan">) {
+  let okay=false;try{okay=options.authorize(Object.freeze({seal:intent.plan.seal,generation:intent.epoch.generation,homeHash:intent.epoch.homeHash}))===true;}catch{fail("authorization");}
+  if(!okay)fail("authorization");
+}
+async function finishCommittedActivation(home:string,binding:Pick<PlacementActivationIntent,"epoch"|"plan">,options:PlacementActivationOptions,
+  mutation:MutationHandle,owner:ReturnType<typeof createPlacementActivationOwner>,intent?:PlacementActivationIntent,report?:ReturnType<typeof counts>) {
+  const epochHash=placementEpochHash(binding.epoch);
+  const check=()=>{assertPlacementActivationOwner(owner);requirePlacementHomeFloor(home);if(!committed(home,binding))fail("changed");readSyncPlacementWriterRoots(home);assertMutationHandle(mutation,home);};
+  authorize(options,binding);check();
+  for(const name of ["profile.json","shards.json",SYNC_PLACEMENT_WRITER_ROOTS_FILE,join("sync-placement","epochs",epochHash,"epoch.json"),join("sync-placement","epochs",epochHash,"activation.json")]){check();syncFile(join(home,name));}
+  ensurePlacementFence(home,epochHash,{mutation,assertCurrent:check});check();
+  if(intent)clearPlacementActivationIntent(home,intent,{mutation,assertCurrent:check});else fsyncDirectory(home);
+  await options.checkpoint?.("after-remove");check();
+  return{mode:options.mode,active:true,forwardOnly:true,epochHash,generation:binding.epoch.generation,writers:binding.plan.writers.length,source:report,resumed:options.mode==="resume",alreadyCommitted:!intent,writerProof:"not-claimed-during-committed-cleanup" as const};
+}
+export async function activateSyncPlacement(options:PlacementActivationOptions) {
+  if(!["dry-run","apply","resume","abandon"].includes(options.mode)||typeof options.authorize!=="function")fail("authorization");
+  let home:string;
+  try{home=realPath(options.memoryDir);}catch{throw Error("Sync placement memory home is unavailable; select an existing private home and run amem migrate --sync-placement --dry-run.");}
+  const pending=readPlacementActivationIntent(home);
+  if(!pending&&requirePlacementActivationPrerequisites(home).active){
+    const renewed=await renewSyncPlacementWriters(options);if(renewed)return renewed;
+  }
+  if(options.mode==="abandon"){
+    if(!pending)throw Error("No initial sync placement intent is retained; use amem migrate --sync-placement --dry-run to inspect the home. Active v3 placement cannot be abandoned or downgraded.");
+    const dirs=pending.plan.realms.map(realm=>realm.scope==="user"?join(home,"user"):join(home,"projects",realm.keyHash.slice(0,16)));
+    return withPlacementActivationFences(home,dirs,async(mutation,owner)=>{
+      authorize(options,pending);
+      abandonPlacementActivation(home,pending,{mutation,assertCurrent:()=>assertPlacementActivationOwner(owner)});
+      return{mode:options.mode,active:false,abandoned:true,forwardOnly:true,nextStep:"amem migrate --sync-placement --dry-run"};
+    }).catch(error=>rethrowActivationFailure(error));
+  }
+  const initialBase=pending?undefined:requirePlacementActivationPrerequisites(home);
+  let initialFloorHash:string;
+  try{initialFloorHash=pending?requirePlacementHomeFloor(home):initialBase!.floorHash;}catch(error){if(pending)throw new PlacementActivationInputError("floor");throw error;}
+  if(options.mode==="resume"&&!pending){
+    if(!initialBase?.active)throw Error("No retained sync placement activation exists; run amem migrate --sync-placement --dry-run to review an initial activation.");
+    const active=initialBase.active,dirs=active.activation.realms.map(realm=>realm.scope==="user"?join(home,"user"):join(home,"projects",realm.keyHash.slice(0,16)));
+    return withPlacementActivationFences(home,dirs,(mutation,owner)=>finishCommittedActivation(home,{epoch:active.epoch,plan:active.activation},options,mutation,owner)).catch(error=>rethrowActivationFailure(error));
+  }
+  if(pending&&options.mode!=="resume")throw Error("Sync placement activation is retained; run amem migrate --sync-placement --resume, or person --abandon while both markers retain the original v2 bytes, before reviewing a new --dry-run.");
+  const source=pending?undefined:previewSyncPlacementSources(home);
+  const writer=pending?undefined:initialPlacementWriterContext(home,options.writerRoots,options.ownRoot);
+  const report=source?counts(source):undefined;
+  if(options.mode==="dry-run")return{mode:options.mode,active:false,forwardOnly:true,quiescence:"deferred-to-apply",realms:source!.base.realms.length,writers:writer!.measurement.roots,source:report};
+  if(!pending&&!options.writerRoots.length)throw Error("Initial sync placement apply requires an explicit complete --writer-root inventory; run amem migrate --sync-placement --dry-run, then apply the reviewed roots.");
+  const directories=pending?pending.plan.realms.map(realm=>realm.scope==="user"?join(home,"user"):join(home,"projects",realm.keyHash.slice(0,16))):source!.directories;
+  try{return await withPlacementActivationFences(home,directories,async(mutation,owner)=>{
+    let intent=pending;
+    const initialCheck=()=>{assertPlacementActivationOwner(owner);source!.assertSourcesUnchanged();writer!.attest();if(requirePlacementHomeFloor(home)!==initialFloorHash)fail("changed");};
+    if(!intent){
+      initialCheck();const facts=writer!.attest(),context={...source!.base,writers:facts.writers,legacySyncQuiesced:true as const};
+      const normalized=planSyncPlacementActivation(context,"0".repeat(64));context.writers=normalized.writers;context.realms=normalized.realms;
+      const epoch:PlacementEpoch={schema:PLACEMENT_EPOCH_SCHEMA,publicationFormat:PLACEMENT_FORMAT,generation:(context.profile as {generation:string}).generation,homeHash:context.homeHash,contextHash:hashJSON(context),nonce:randomBytes(16).toString("hex")};
+      const plan=planSyncPlacementActivation(context,placementEpochHash(epoch));
+      intent=sealPlacementActivationIntent({schema:PLACEMENT_ACTIVATION_INTENT_SCHEMA,home,epoch,plan,roots:writer!.measurement.roots.map(row=>row.root).sort(),previousProfile:source!.markers.profileText,previousShards:source!.markers.shardsText,profileStamp:source!.markers.profileStamp,shardsStamp:source!.markers.shardsStamp,floorHash:initialFloorHash,inputHashes:{sourceHash:context.sourceHash,aliasesHash:context.aliasesHash,policyHash:context.policyHash}});
+      // All future initial-locator framing/binding limits must fit before retaining an exclusive activation intent.
+      const epochHash=placementEpochHash(epoch);
+      planSyncPlacementWriterRoots({epochHash,homeHash:epoch.homeHash,activationHash:plan.seal,roots:writer!.measurement.roots},
+        {epochHash,homeHash:epoch.homeHash,activationHash:plan.seal,writers:plan.writers});
+      validateSyncPlacementActivation(plan,{current:()=>{initialCheck();return context;},authorize:()=>{authorize(options,intent!);return true;}});
+      writePlacementActivationIntent(home,intent,{mutation,assertCurrent:initialCheck});
+    }
+    const fixed=intent,epochHash=placementEpochHash(fixed.epoch);
+    const metadataCheck=()=>{assertPlacementActivationOwner(owner);requirePlacementHomeFloor(home);if(!committed(home,fixed))fail("changed");readSyncPlacementWriterRoots(home);assertMutationHandle(mutation,home);};
+    if(committed(home,fixed))return finishCommittedActivation(home,fixed,options,mutation,owner,fixed,report);
+    let current:PlacementWriterContext;
+    try{current=writer??initialPlacementWriterContext(home,fixed.roots,options.ownRoot);}catch(error){writerInputFailure(error);}
+    if(canonicalJSON(current.measurement.writers)!==canonicalJSON(fixed.plan.writers))throw new PlacementActivationInputError("writer root");
+    const proof=createPlacementActivationCaptureProof(owner,fixed);
+    const check=()=>{
+      assertPlacementActivationOwner(owner);
+      try{if(requirePlacementHomeFloor(home)!==fixed.floorHash)throw Error();}catch{throw new PlacementActivationInputError("floor");}
+      try{current.attest();}catch(error){writerInputFailure(error);}
+      let captured:ReturnType<typeof captureSyncPlacementActivationContext>;
+      try{captured=captureSyncPlacementActivationContext(home,{attest:current.attest},proof);}catch(error){if(current.lastRefusal)writerInputFailure(current.lastRefusal);throw new PlacementActivationInputError("source");}
+      if(captured.context.policyHash!==fixed.inputHashes.policyHash)throw new PlacementActivationInputError("policy");
+      if(captured.context.aliasesHash!==fixed.inputHashes.aliasesHash)throw new PlacementActivationInputError("aliases");
+      if(captured.context.sourceHash!==fixed.inputHashes.sourceHash||hashJSON(captured.context)!==fixed.plan.contextHash)throw new PlacementActivationInputError("source");
+      try{captured.assertUnchanged();}catch(error){if(current.lastRefusal)writerInputFailure(current.lastRefusal);throw new PlacementActivationInputError("source");}
+      assertPlacementActivationOwner(owner);
+    };
+    authorize(options,fixed);check();writePlacementActivationIntent(home,fixed,{mutation,assertCurrent:check});await options.checkpoint?.("after-intent");check();
+    preparePlacementEpoch(home,fixed.epoch,fixed.plan,{mutation,assertCurrent:check});await options.checkpoint?.("after-epoch");check();
+    writeSyncPlacementWriterRoots(home,{epochHash,homeHash:fixed.epoch.homeHash,activationHash:fixed.plan.seal,roots:current.measurement.roots},fixed.plan.writers,{mutation,assertCurrent:check});await options.checkpoint?.("after-root-map");check();
+    const final=placementActivationFinalMarkers(fixed),markers=readPlacementRuntimeMarkers(home);
+    if(canonicalJSON(markers.shards)+"\n"!==final.shards)writeProfileJSON(join(home,"shards.json"),JSON.parse(final.shards));else syncFile(join(home,"shards.json"));
+    await options.checkpoint?.("after-shards");check();
+    if(canonicalJSON(readPlacementRuntimeMarkers(home).profile)+"\n"!==final.profile)writeProfileJSON(join(home,"profile.json"),JSON.parse(final.profile));else syncFile(join(home,"profile.json"));
+    await options.checkpoint?.("after-profile");check();
+    ensurePlacementFence(home,epochHash,{mutation,assertCurrent:check});await options.checkpoint?.("after-fence");metadataCheck();return finishCommittedActivation(home,fixed,options,mutation,owner,fixed,report);
+  });}catch(error){
+    try{options.testOnlyFailure?.(error);}catch{/* observers never affect production outcomes */}
+    return rethrowActivationFailure(error);
+  }
+}