@staix/agent-mem 0.21.0 → 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-capture.ts

@@ -18,6 +18,10 @@ import { validatePruneRow, type PruneSourceRow, type PruneRow } from "./prune.ts
 import { shardKeyHash, SHARD_SCHEMA } from "./shard.ts";
 import { SyncPlacementJournalError, placementKeyId, type PlacementKey } from "./sync-placement-journal-format.ts";
 import type { Entry } from "./store.ts";
+import { assertPlacementRuntime } from "./sync-placement-guard.ts";
+import { activationSourceMarkers, assertPlacementActivationOwner, type PlacementActivationOwner, type PlacementActivationCaptureProof } from "./sync-placement-activation-proof.ts";
+import { readEffectiveSyncPlacementWriters, writerBoundPlacementContextHash, writerInventoryEvidence, type EffectiveSyncPlacementWriters } from "./sync-placement-effective-writers.ts";
+import { SharedWriterRevisionError } from "./sync-placement-writer-revision-format.ts";
 
 /** Host authentication/compatibility facts are re-read at every effect boundary, never inferred from a session marker. */
 export interface PlacementCapturePort {
@@ -35,10 +39,22 @@ export interface PlacementCapture {
   /** Diagnostic inventory only; these rows never enter the ordinary transport/capture row map implicitly. */
   specialRows: Map<string, PlacementSpecialSourceRow>;
   sourceRowsByRealm: Map<string, readonly PruneSourceRow[]>;
+  writerInventory?:EffectiveSyncPlacementWriters;
   assertCurrent(): void;
   /** Under live writer fences, inode/ctime/size checks protect the already-hashed prefixes across callbacks without reparsing rows. */
   assertUnchanged(): void;
 }
+export function placementCaptureContextHash(capture:Pick<PlacementCapture,"context"|"writerInventory">):string{return writerBoundPlacementContextHash(capture.context,capture.writerInventory);}
+export interface PlacementActivationMarkerSnapshot {
+  profileText: string; shardsText: string; profileStamp: [string,string,string,string,string]; shardsStamp: [string,string,string,string,string];
+}
+/** Source facts only: no writer attestation, quiescence claim or effect authority. */
+export interface PlacementSourcePreview {
+  home: string; base: Omit<SyncPlacementActivationContext, "writers" | "legacySyncQuiesced">;
+  activeHead?: string; markerHash: string; markers: PlacementActivationMarkerSnapshot; directories: string[]; prefixes: PlacementPublicationSource[];
+  rows: Map<string, PlacementSourceRow>; specialRows: Map<string, PlacementSpecialSourceRow>;
+  sourceRowsByRealm: Map<string, readonly PruneSourceRow[]>; assertSourcesUnchanged(): void;
+}
 function fail(code: "changed" | "invalid" | "bound" = "changed"): never { throw new SyncPlacementJournalError(code); }
 const digest = (bytes: Uint8Array | string) => createHash("sha256").update(bytes).digest("hex");
 const stamp = (s: BigIntStats) => [s.dev, s.ino, s.size, s.mtimeNs, s.ctimeNs].map(String);
@@ -50,7 +66,7 @@ function ownedDirectory(dir: string): BigIntStats {
 }
 /** ponytail: capture is capped at 256 metadata objects and 8 MiB/20000 source rows across all realms.
  * Larger homes need a reviewed chunked activation proof; no input is silently omitted at this ceiling. */
-function capture(homeInput: string, port: PlacementCapturePort, selected?: readonly PlacementRealm[], pending: readonly PlacementPendingSource[] = []): Omit<PlacementCapture, "assertCurrent"> {
+function sourcePreview(homeInput: string, selected?: readonly PlacementRealm[], pending: readonly PlacementPendingSource[] = [], policyVersion?: string, ownerProof?: PlacementActivationCaptureProof, sourceOwner?:PlacementActivationOwner): PlacementSourcePreview {
   let selection: PlacementRealm[] | undefined;
   if (selected !== undefined) {
     if (!Array.isArray(selected) || types.isProxy(selected) || selected.length > 256) fail("bound");
@@ -58,11 +74,8 @@ function capture(homeInput: string, port: PlacementCapturePort, selected?: reado
     selection = copied.map(realm => validatePlacementKey({ realm, id: "0".repeat(32), rowHash: "0".repeat(64) }).realm);
     if (!selection.length || new Set(selection.map(realm => canonicalJSON(realm))).size !== selection.length) fail();
   }
-  // All host callouts precede filesystem capture: a callback cannot alter input after its final proof.
-  const attestation = memoryPolicySnapshot(port.attest()), policyVersion = port.policyVersion?.();
-  if (!attestation) fail();
-  if (port.policyVersion && typeof policyVersion !== "string") fail();
   const home = realPath(homeInput), root = ownedDirectory(home);
+  if(sourceOwner)assertPlacementActivationOwner(sourceOwner,home);
   let metadataObjects = 0, metadataBytes = 0;
   const facts: unknown[] = [], sourceChecks: (() => void)[] = [];
   const pendingByPath = new Map(pending.map(item => [canonicalJSON(item.realm)+":"+item.pathHash,item]));
@@ -90,7 +103,17 @@ function capture(homeInput: string, port: PlacementCapturePort, selected?: reado
     const input = bytes(file, optional); if (!input) return undefined;
     return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input));
   };
-  const rawProfile = json(join(home, "profile.json")), rawShards = json(join(home, "shards.json"));
+  const markerStart = facts.length;
+  const profileBytes = bytes(join(home, "profile.json"))!, shardsBytes = bytes(join(home, "shards.json"))!;
+  const actualMarkers: PlacementActivationMarkerSnapshot = { profileText: profileBytes.toString("utf8"), shardsText: shardsBytes.toString("utf8"),
+    profileStamp: [...(facts[markerStart] as [string,PlacementActivationMarkerSnapshot["profileStamp"],string])[1]], shardsStamp: [...(facts[markerStart+1] as [string,PlacementActivationMarkerSnapshot["shardsStamp"],string])[1]] };
+  const markers = ownerProof ? activationSourceMarkers(ownerProof,home,actualMarkers) : actualMarkers;
+  if (ownerProof) {
+    facts[markerStart] = [join(home,"profile.json"),markers.profileStamp,digest(Buffer.from(markers.profileText))];
+    facts[markerStart+1] = [join(home,"shards.json"),markers.shardsStamp,digest(Buffer.from(markers.shardsText))];
+  }
+  const decodeMarker = (text: string): unknown => JSON.parse(new TextDecoder("utf-8",{fatal:true}).decode(Buffer.from(text)));
+  const rawProfile = decodeMarker(markers.profileText) as { schema?: string }, rawShards = decodeMarker(markers.shardsText);
   let activeHead: string | undefined;
   let base: ReturnType<typeof validatePlacementBaseV2>;
   if (rawProfile?.schema === PLACEMENT_PROFILE_SCHEMA) {
@@ -109,7 +132,11 @@ function capture(homeInput: string, port: PlacementCapturePort, selected?: reado
   const machine = json(join(home, "machine.json"));
   if (machine?.id !== base.shards.machine.id) fail();
   // An in-flight migration/prune is never accepted as a stable placement source.
-  for (const name of ["profile.lock", PUBLIC_PRUNE_INTENT]) if (lstatSync(join(home, name), { throwIfNoEntry: false })) fail();
+  for (const name of ["profile.lock", PUBLIC_PRUNE_INTENT]) {
+    if (name === "profile.lock" && ownerProof) continue; // The module-private proof validated this exact live owner and sealed intent.
+    if(name==="profile.lock"&&sourceOwner){assertPlacementActivationOwner(sourceOwner,home);continue;}
+    if (lstatSync(join(home,name),{throwIfNoEntry:false})) fail();
+  }
   const reader = new SegmentReader(16 * 1024 * 1024, { maxSourceBytes: 8 * 1024 * 1024, maxRows: 20000 });
   const rows = new Map<string, PlacementSourceRow>(), specialRows = new Map<string, PlacementSpecialSourceRow>(), sourceRowsByRealm = new Map<string, readonly PruneSourceRow[]>();
   const directories = [home], prefixes: PlacementPublicationSource[] = [];
@@ -242,29 +269,68 @@ function capture(homeInput: string, port: PlacementCapturePort, selected?: reado
   if (selection && realms.length !== selection.length) fail();
   const defaults = memoryPolicySnapshot({ names: DENY_NAMES, segments: DENY_SEGMENTS }); if (!defaults) fail();
   const configuration = loadAmemConfig(home).config;
-  const context: SyncPlacementActivationContext = { ...base, homeHash: hashJSON([home, String(root.dev), String(root.ino), String(root.uid)]), sourceHash: hashJSON(facts),
-    aliasesHash: digest(aliases ?? Buffer.alloc(0)), policyHash: hashJSON({ config: configuration, defaults, policyVersion }), realms,
-    writers: attestation.writers, legacySyncQuiesced: attestation.legacySyncQuiesced };
-  // Reuse the closed stage-1 context validator, including writer/version/realm bounds.
+  const contextBase: PlacementSourcePreview["base"] = { ...base,
+    homeHash: hashJSON([home, String(root.dev), String(root.ino), String(root.uid)]), sourceHash: hashJSON(facts),
+    aliasesHash: digest(aliases ?? Buffer.alloc(0)), policyHash: hashJSON({ config: configuration, defaults, policyVersion }), realms };
+  // ponytail: passive checks rely on native inode/size/ctime identity for the hashed prefixes.
+  // Immutable descriptor-bound source blocks are the upgrade path for hostile same-user raw writers.
+  const assertSourcesUnchanged = () => {
+    try {
+      const currentDefaults = memoryPolicySnapshot({ names: DENY_NAMES, segments: DENY_SEGMENTS });
+      if (!currentDefaults || hashJSON({ config: configuration, defaults: currentDefaults, policyVersion }) !== contextBase.policyHash) fail();
+      const now = ownedDirectory(home); if (now.dev !== root.dev || now.ino !== root.ino) fail();
+      for (const check of sourceChecks) check();
+      if (ownerProof) activationSourceMarkers(ownerProof,home,actualMarkers);
+      if(sourceOwner)assertPlacementActivationOwner(sourceOwner,home);
+    } catch { fail(); }
+  };
+  return { home, base: contextBase, assertSourcesUnchanged, ...(activeHead ? { activeHead } : {}), markerHash, markers,
+    directories: directories.sort(), prefixes, rows, specialRows, sourceRowsByRealm };
+}
+/** Read-only preview shares the source collector, without fabricating a quiescence attestation. */
+export function previewSyncPlacementSources(home: string): PlacementSourcePreview {
+  return previewSources(home);
+}
+/** Internal renewal inventory under the exact live home/profile/mutation owner; no marker virtualization. */
+export function previewOwnedSyncPlacementSources(home:string,owner:PlacementActivationOwner):PlacementSourcePreview {
+  assertPlacementActivationOwner(owner,home);return previewSources(home,owner);
+}
+function previewSources(home:string,owner?:PlacementActivationOwner):PlacementSourcePreview {
+  try { assertPlacementRuntime(home); const preview = sourcePreview(home,undefined,[],undefined,undefined,owner); preview.assertSourcesUnchanged(); return preview; }
+  catch (error) {
+    if (error && typeof error === "object" && !types.isProxy(error)) {
+      if (error instanceof SyncPlacementJournalError) throw error;
+      if (error instanceof SegmentReadBudgetError) return fail("bound");
+    }
+    return fail();
+  }
+}
+function capture(home: string, port: PlacementCapturePort, selected?: readonly PlacementRealm[], pending: readonly PlacementPendingSource[] = [], ownerProof?: PlacementActivationCaptureProof): Omit<PlacementCapture, "assertCurrent"> {
+  // All host callouts precede filesystem capture, including the final passive proof.
+  const attestation = memoryPolicySnapshot(port.attest()), policyVersion = port.policyVersion?.();
+  if (!attestation || port.policyVersion && typeof policyVersion !== "string") fail();
+  const source = sourcePreview(home, selected, pending, policyVersion, ownerProof);
+  const context: SyncPlacementActivationContext = { ...source.base, writers: attestation.writers, legacySyncQuiesced: attestation.legacySyncQuiesced };
   const validated = planSyncPlacementActivation(context, "0".repeat(64));
   context.writers = validated.writers; context.realms = validated.realms;
-  // ponytail: fast rechecks rely on held mutation fences plus native inode/size/ctime identity for the already-hashed prefixes.
-  // A hostile same-user raw writer is outside that contract; descriptor-bound immutable source blocks are the upgrade path.
+  const writerInventory=source.activeHead&&writerInventoryEvidence(source.home,source.activeHead)?readEffectiveSyncPlacementWriters(source.home):undefined;
+  if(writerInventory&&canonicalJSON(context.writers)!==canonicalJSON(writerInventory.writers))fail();
   const assertUnchanged = () => {
     try {
-    // Host callbacks run first; the final filesystem proof never invokes caller code afterwards.
-    const currentAttestation=memoryPolicySnapshot(port.attest()), currentVersion=port.policyVersion?.();
-    if(!currentAttestation) fail();
-    const checked=planSyncPlacementActivation({...context,writers:currentAttestation.writers,legacySyncQuiesced:currentAttestation.legacySyncQuiesced},"0".repeat(64));
-    const currentDefaults=memoryPolicySnapshot({names:DENY_NAMES,segments:DENY_SEGMENTS});
-    if(!currentDefaults)fail();
-    if(canonicalJSON(checked.writers)!==canonicalJSON(context.writers)||hashJSON({config:configuration,defaults:currentDefaults,policyVersion:currentVersion})!==context.policyHash) fail();
-    const now=ownedDirectory(home); if(now.dev!==root.dev||now.ino!==root.ino) fail();
-    for(const check of sourceChecks)check();
+      const currentAttestation = memoryPolicySnapshot(port.attest()), currentVersion = port.policyVersion?.();
+      if (!currentAttestation) fail();
+      const checked = planSyncPlacementActivation({ ...context, writers: currentAttestation.writers, legacySyncQuiesced: currentAttestation.legacySyncQuiesced }, "0".repeat(64));
+      if (canonicalJSON(checked.writers) !== canonicalJSON(context.writers) || currentVersion !== policyVersion) fail();
+      writerInventory?.assertCurrent();
+      if(source.activeHead&&!writerInventory&&writerInventoryEvidence(source.home,source.activeHead))fail();
+      source.assertSourcesUnchanged();
     } catch { fail(); }
   };
-  return { home, context, assertUnchanged, ...(activeHead ? { activeHead } : {}), markerHash, fingerprint: hashJSON({ context, markerHash }), directories: directories.sort(), prefixes, rows, specialRows, sourceRowsByRealm };
+  return { home: source.home, context, assertUnchanged, ...(source.activeHead ? { activeHead: source.activeHead } : {}),
+    ...(writerInventory?{writerInventory}:{}),markerHash: source.markerHash, fingerprint: hashJSON({ context, markerHash: source.markerHash,...(writerInventory?.revisionSequence?{writerRevisionHash:writerInventory.revisionHash}:{}) }), directories: source.directories,
+    prefixes: source.prefixes, rows: source.rows, specialRows: source.specialRows, sourceRowsByRealm: source.sourceRowsByRealm };
 }
+
 export function captureSyncPlacementContext(home: string, port: PlacementCapturePort, selected?: readonly PlacementRealm[], pendingInput: readonly PlacementPendingSource[] = []): PlacementCapture {
   try {
     const selection = selected === undefined ? undefined : memoryPolicySnapshot(selected);
@@ -282,6 +348,21 @@ export function captureSyncPlacementContext(home: string, port: PlacementCapture
     });
     const before = capture(home, port, selection, pending);
     return { ...before, assertCurrent: () => { try { if (capture(home, port, selection, pending).fingerprint !== before.fingerprint) fail(); } catch { fail(); } } };
+  } catch (error) {
+    if (error && typeof error === "object" && !types.isProxy(error)) {
+      if(error instanceof SharedWriterRevisionError){const code=Object.getOwnPropertyDescriptor(error,"code")?.value;if(code==="staging"||code==="pending")throw new SharedWriterRevisionError(code);}
+      if (error instanceof SyncPlacementJournalError) throw error;
+      if (error instanceof SegmentReadBudgetError) return fail("bound");
+    }
+    return fail();
+  }
+}
+
+/** Internal initial-activation capture only. Tokens require the actual profile owner, live home mutation and exact durable intent. */
+export function captureSyncPlacementActivationContext(home: string, port: PlacementCapturePort, proof: PlacementActivationCaptureProof): PlacementCapture {
+  try {
+    const before = capture(home,port,undefined,[],proof);
+    return { ...before, assertCurrent: () => { if (capture(home,port,undefined,[],proof).fingerprint !== before.fingerprint) fail(); } };
   } catch (error) {
     if (error && typeof error === "object" && !types.isProxy(error)) {
       if (error instanceof SyncPlacementJournalError) throw error;