@staix/agent-mem 0.20.3 → 0.22.0

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

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