@staix/agent-mem 0.21.0 → 0.22.1

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

@@ -11,7 +11,10 @@ import { memoryPolicySnapshot } from "./policy.ts";
 import { outboundPolicyEvaluator } from "./sync-screen.ts";
 import { readActivePlacementBinding } from "./sync-placement-active.ts";
 import { readPlacementRuntimeMarkers } from "./sync-placement-guard.ts";
-import { captureSyncPlacementContext, type PlacementCapture, type PlacementPendingSource } from "./sync-placement-capture.ts";
+import { captureSyncPlacementContext, placementCaptureContextHash, type PlacementCapture, type PlacementPendingSource } from "./sync-placement-capture.ts";
+import { readEffectiveSyncPlacementWriters, type EffectiveSyncPlacementWriters } from "./sync-placement-effective-writers.ts";
+import { SharedWriterRevisionError } from "./sync-placement-writer-revision-format.ts";
+import { types } from "node:util";
 import type { PlannedGitObject } from "./sync-placement-git.ts";
 import { PLACEMENT_FORMAT } from "./sync-placement-format.ts";
 import { createPlacementRecord, placementKeyId, type PlacementEvent, type PlacementRealm, type PlacementHoldReason, type PlacementRecord } from "./sync-placement-journal-format.ts";
@@ -50,15 +53,18 @@ class PlacementTransport {
   targets: Target[] = []; homeMutation?: MutationHandle; rootMutation?: MutationHandle; cacheIdentity?: {dev:number;ino:number}; cacheConfigIdentity?: string; epochHash = ""; journal!: PlacementJournalRead; capture?: PlacementCapture;
   machineId = ""; url = ""; revision = ""; accepted = false; factual = false; attempted = false; lastPolicyCheckUnixMs?: number; lastPolicyHash?: string; policyCheckSource?: "live"|"durable-intent"; attemptHash?: string;
   evaluator?: ReturnType<typeof outboundPolicyEvaluator>; applications?: ShardSyncApplications; current?: Materialized; recovered = false;
+  writerInventory?:EffectiveSyncPlacementWriters;
   constructor(store: MemoryStore, opts: SyncOptions, phase?: Phase, testOnlyError?: (error:unknown)=>void) { this.testOnlyError=testOnlyError; this.store = store; this.opts = opts; this.phase = phase; this.home = store.profile.home; this.root = join(this.home, "shard-sync-placement"); this.cache = join(this.root, "objects.git"); }
   attest(): void {
     if (!this.opts.placementAttestation || this.opts.screen && !this.opts.policyVersion) refuse();
     const value = memoryPolicySnapshot(this.opts.placementAttestation());
     if (!value || value.legacySyncQuiesced !== true || !Array.isArray(value.writers)) refuse();
     const writers = [...value.writers].sort((a,b) => a.writerId.localeCompare(b.writerId));
-    if (canonicalJSON(writers) !== canonicalJSON(this.journal.activation.writers)) refuse();
+    if(!this.writerInventory||canonicalJSON(writers)!==canonicalJSON(this.writerInventory.writers))refuse();
+    this.writerInventory.assertCurrent();
   }
   metadata(): void {
+    this.writerInventory?.assertCurrent();
     if(this.rootMutation)assertMutationHandle(this.rootMutation,this.root);
     if(this.cacheIdentity){const stat=lstatSync(this.cache);if(stat.isSymbolicLink()||!stat.isDirectory()||stat.dev!==this.cacheIdentity.dev||stat.ino!==this.cacheIdentity.ino)refuse();}
     if(this.cacheIdentity){
@@ -105,7 +111,7 @@ class PlacementTransport {
   async initialize(): Promise<void> {
     const markers = readPlacementRuntimeMarkers(this.home), active = readActivePlacementBinding(this.home, markers.profile, markers.shards);
     if (!active || this.store.profile.publicationFormat !== PLACEMENT_FORMAT || this.store.profile.placementHead !== active.profile.placementHead) refuse();
-    this.epochHash = active.profile.placementHead; this.machineId = active.shards.machine.id; this.revision = readSelector(this.home).revision; this.journal = readPlacementJournal(this.home, this.epochHash); this.attest();
+    this.epochHash = active.profile.placementHead; this.machineId = active.shards.machine.id; this.revision = readSelector(this.home).revision; this.journal = readPlacementJournal(this.home, this.epochHash); this.writerInventory=readEffectiveSyncPlacementWriters(this.home);this.attest();
     const opened = this.store.openedSyncTargets();
     if (!opened.length || opened.length > 2 || !opened.includes(this.store) || opened.some(item => item.profile.home !== this.home || !item.profile.sharded || !item.profile.generation
       || !item.profile.shardUser && item.profile.shardKey !== this.store.profile.shardKey)) refuse();
@@ -186,7 +192,8 @@ class PlacementTransport {
       pathHash: digest(`log/${item.row.machine}.jsonl`), offset: item.offset, prefixHash: item.prefixHash, line: item.line })));
     this.capture = captureSyncPlacementContext(this.home, { attest: this.opts.placementAttestation!, ...(this.opts.policyVersion ? { policyVersion: this.opts.policyVersion } : {}) }, this.targets.map(physical), pending);
     if (this.capture.activeHead !== this.epochHash || this.capture.context.homeHash !== this.journal.epoch.homeHash
-      || canonicalJSON(this.capture.context.writers) !== canonicalJSON(this.journal.activation.writers)) refuse();
+      || canonicalJSON(this.capture.context.writers) !== canonicalJSON(this.writerInventory?.writers)
+      || !!this.writerInventory?.revisionSequence&&this.capture.writerInventory?.revisionHash!==this.writerInventory.revisionHash) refuse();
     this.check();
   }
   async applicationCoordinator(): Promise<ShardSyncApplications> {
@@ -232,7 +239,7 @@ class PlacementTransport {
       publisherLineages:(index,rows)=>{const target=this.targets[index]!;assertPublisherBoundary(target.store.profile,target.mutation!);return publisherPruneLineages(target.store.profile,target.mutation!,rows);}});
     for(const [index,target]of this.targets.entries())Object.assign(target,materialized.targets[index]!);
     const {decisions,plannedTargets:targets,objects}=materialized;
-    const body={epochHash:this.epochHash,generation:this.journal.epoch.generation,homeHash:capture.context.homeHash,contextHash:hashJSON(capture.context),markerHash:capture.markerHash,
+    const body={epochHash:this.epochHash,generation:this.journal.epoch.generation,homeHash:capture.context.homeHash,contextHash:placementCaptureContextHash(capture),markerHash:capture.markerHash,
       sourceHash:capture.context.sourceHash,aliasesHash:capture.context.aliasesHash,policyHash:capture.context.policyHash,remoteHash:digest(this.url),
       journal:frozen?.root.journal??{sequence:frontier.sequence,headHash:frontier.headHash},createdUnixSeconds,policySnapshotUnixMs:frozen?.root.policySnapshotUnixMs??this.lastPolicyCheckUnixMs??Date.now(),targets,reservedRecords:0,reservedRecordBytes:[] as number[]};
     let bundle=planPlacementPublication(body,{sources:capture.prefixes,decisions,objects});
@@ -446,7 +453,7 @@ class PlacementTransport {
       catch { if(retained)return await this.terminalUnknown(retained);throw new Error("placement source preflight unavailable"); }
       if(retained){
         const root=retained.bundle.root;
-        const stable=root.contextHash===hashJSON(this.capture!.context)&&root.markerHash===this.capture!.markerHash&&root.sourceHash===this.capture!.context.sourceHash
+        const stable=root.contextHash===placementCaptureContextHash(this.capture!)&&root.markerHash===this.capture!.markerHash&&root.sourceHash===this.capture!.context.sourceHash
           &&root.policyHash===this.capture!.context.policyHash&&root.targets.every((target,index)=>target.expectedRemoteHead===(this.targets[index]?.remote??null));
         if(!stable)return await this.terminalUnknown(retained);
       }
@@ -476,6 +483,10 @@ class PlacementTransport {
       this.factual=true;return await this.finish(material);
     }catch(error){
       try { this.testOnlyError?.(error); } catch { /* Test observers never alter production results. */ }
+      if(error&&typeof error==="object"&&!types.isProxy(error)&&error instanceof SharedWriterRevisionError){
+        const code=Object.getOwnPropertyDescriptor(error,"code")?.value;
+        if(code==="staging"||code==="pending")return this.result(false,this.attemptHash?"unknown":"not-needed",new SharedWriterRevisionError(code).message);
+      }
       return this.result(false,this.attemptHash?"unknown":"not-needed",this.attemptHash?"Placement sync stopped with a retained attempt that may have published; recheck its exact receipts before another publication.":"Placement sync is unavailable; verify the active epoch, selected sources, policy, private remote and writer pins before retrying.");
     }finally{
       let ownedCache=true;try{this.metadata();}catch{ownedCache=false;}

package/src/memory/sync-placement-writer-history.ts

@@ -0,0 +1,278 @@
+/** Private append-only writer inventory history. It never measures installs or grants activation authority. */
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, openSync, opendirSync, readSync, unlinkSync, writeSync, type BigIntStats } from "node:fs";
+import { dirname, join } 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 {
+  WRITER_REVISION_MAX_BYTES, WRITER_COMMIT_MAX_BYTES, WRITER_RENEWAL_INTENT_MAX_BYTES, WRITER_REVISION_LIMIT,
+  WRITER_COMMIT_LOG, WRITER_RENEWAL_INTENT_FILE, writerRevisionFile, writerInventoryGenesis,
+  validateWriterRevision, validateWriterCommit, validateWriterRenewalIntent, createWriterCommit,
+  SharedWriterRevisionError, type WriterRevision, type WriterCommit, type WriterRenewalIntent,
+} from "./sync-placement-writer-revision-format.ts";
+
+export interface WriterHistoryBinding { epochHash: string; activationHash: string; homeHash: string; generation: string; initialLocatorHash?: string }
+export type WriterHistoryPhase = "intent-started" | "intent-written" | "intent-fsync" | "intent-published" | "revision-written" | "revision-fsync" | "commit-started" | "commit-written" | "commit-fsync" | "intent-cleared";
+export interface WriterHistoryOptions { mutation: MutationHandle; assertCurrent(): void; phase?(phase: WriterHistoryPhase): void }
+export interface WriterHistoryRead {
+  current?: WriterRevision; commits: WriterCommit[]; anchors: { sequence: number; headHash: string }[];
+  sequence: number; headHash: string; logBytes: number; logHash: string; pending?: WriterRenewalIntent; appendStarted: boolean; assertCurrent(): void;
+}
+const encode = (value: unknown) => Buffer.from(canonicalJSON(value) + "\n");
+const sha = (value: Uint8Array) => createHash("sha256").update(value).digest("hex");
+const stamp = (s: BigIntStats) => [s.dev,s.ino,s.uid,s.mode,s.nlink,s.size,s.mtimeNs,s.ctimeNs].map(String).join(":");
+const identity = (s: BigIntStats) => [s.dev,s.ino,s.uid,s.mode].map(String).join(":");
+function fail(code: "invalid" | "bound" | "changed" | "pending" | "staging" = "invalid"): never { throw new SharedWriterRevisionError(code); }
+function safe<T>(work: () => T): T {
+  try { return work(); } catch (error) {
+    if (error && typeof error === "object" && !types.isProxy(error) && error instanceof SharedWriterRevisionError) {
+      const code=Object.getOwnPropertyDescriptor(error,"code");
+      if(code&&"value"in code&&["invalid","bound","changed","pending","staging","cap"].includes(code.value))throw new SharedWriterRevisionError(code.value);
+    }
+    return fail();
+  }
+}
+function owned(s: BigIntStats, dir = false, links: readonly bigint[] = [1n]): void {
+  if (s.isSymbolicLink() || s.uid !== BigInt(process.getuid?.() ?? -1)
+    || (dir ? !s.isDirectory() || (s.mode & 0o077n) !== 0n : !s.isFile() || !links.includes(s.nlink) || (s.mode & 0o777n) !== 0o600n)) fail();
+}
+function checkedDir(file: string): BigIntStats { const s = lstatSync(file,{bigint:true}); owned(s,true); return s; }
+interface FileRead { bytes: Buffer; stat: BigIntStats }
+function read(file: string, max: number, checks: (() => void)[] = [], links: readonly bigint[] = [1n]): FileRead | undefined {
+  const before = lstatSync(file,{bigint:true,throwIfNoEntry:false});
+  if (!before) { checks.push(() => { if (lstatSync(file,{throwIfNoEntry:false})) fail("changed"); }); return undefined; }
+  owned(before,false,links); if (before.size > BigInt(max)) fail("bound");
+  const fd = openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
+  try {
+    const opened = fstatSync(fd,{bigint:true}); owned(opened,false,links); if (stamp(opened)!==stamp(before)) fail("changed");
+    const buffer = Buffer.alloc(Number(opened.size)+1); let at=0;
+    while (at<buffer.length) { const n=readSync(fd,buffer,at,buffer.length-at,at); if (!n) break; at+=n; }
+    if (at!==Number(opened.size) || stamp(fstatSync(fd,{bigint:true}))!==stamp(opened) || stamp(lstatSync(file,{bigint:true}))!==stamp(opened)) fail("changed");
+    checks.push(() => { const now=lstatSync(file,{bigint:true}); owned(now,false,links); if(stamp(now)!==stamp(opened))fail("changed"); });
+    return {bytes:buffer.subarray(0,at),stat:opened};
+  } finally { closeSync(fd); }
+}
+function decode<T>(bytes: Buffer, validate: (value: unknown) => T): T {
+  const text = new TextDecoder("utf-8",{fatal:true}).decode(bytes), result=validate(JSON.parse(text));
+  if (!bytes.equals(encode(result))) fail(); return result;
+}
+function binding(value: WriterHistoryBinding): WriterHistoryBinding {
+  if (!value || typeof value!=="object" || types.isProxy(value) || Object.getOwnPropertySymbols(value).length) fail();
+  const descriptors=Object.getOwnPropertyDescriptors(value), keys=["epochHash","activationHash","homeHash","generation"];
+  if(Object.keys(descriptors).some(key=>![...keys,"initialLocatorHash"].includes(key)))fail();
+  const result: Record<string,string>={};
+  for(const key of keys){const d=descriptors[key];if(!d||!("value"in d)||!d.enumerable||typeof d.value!=="string"||d.value.length!==(key==="generation"?32:64)||!/^[a-f0-9]+$/.test(d.value))fail();result[key]=d.value;}
+  const locator=descriptors.initialLocatorHash;if(locator){if(!("value"in locator)||!locator.enumerable||typeof locator.value!=="string"||locator.value.length!==64||!/^[a-f0-9]+$/.test(locator.value))fail();result.initialLocatorHash=locator.value;}
+  return result as unknown as WriterHistoryBinding;
+}
+interface Paths { home: string; epoch: string; intent: string; log: string; dirs: [string,BigIntStats][] }
+function paths(homeInput: string, input: WriterHistoryBinding): Paths {
+  const home=realPath(homeInput), original=checkedDir(homeInput), root=checkedDir(home);
+  if(identity(original)!==identity(root)||hashJSON([home,String(root.dev),String(root.ino),String(root.uid)])!==input.homeHash)fail("changed");
+  const dirs:[string,BigIntStats][]=[[home,root]];
+  let current=home;for(const part of ["sync-placement","epochs",input.epochHash]){current=join(current,part);dirs.push([current,checkedDir(current)]);}
+  return {home,epoch:current,intent:join(home,WRITER_RENEWAL_INTENT_FILE),log:join(current,WRITER_COMMIT_LOG),dirs};
+}
+function manifest(p: Paths): string[] {
+  const iterator=opendirSync(p.epoch), names:string[]=[]; let count=0;
+  try {for(;;){const entry=iterator.readSync();if(!entry)break;if(++count>255)fail("bound");
+    if(entry.name.startsWith("writer-")){if(entry.name!==WRITER_COMMIT_LOG&&!/^writer-revision-\d{5}\.json$/.test(entry.name))fail();names.push(entry.name);}
+  }} finally {iterator.closeSync();} return names.sort();
+}
+function boundRevision(revision: WriterRevision,b:WriterHistoryBinding):void {
+  if(revision.epochHash!==b.epochHash||revision.activationHash!==b.activationHash||revision.homeHash!==b.homeHash||revision.generation!==b.generation||b.initialLocatorHash!==undefined&&revision.initialLocatorHash!==b.initialLocatorHash)fail();
+}
+function intentBinding(intent:WriterRenewalIntent):WriterHistoryBinding {const r=intent.revision;return {epochHash:r.epochHash,activationHash:r.activationHash,homeHash:r.homeHash,generation:r.generation};}
+/** Exact basename reserved alongside the final outside intent during atomic publication. */
+export function writerRenewalIntentTempName(value:WriterRenewalIntent):string {return WRITER_RENEWAL_INTENT_FILE+".pending-"+sha(encode(validateWriterRenewalIntent(value)));}
+export function isWriterRenewalIntentTempName(name:string):boolean {const match=new RegExp("^"+WRITER_RENEWAL_INTENT_FILE.replaceAll(".","\\.")+"\\.pending-[a-f0-9]{64}$").exec(name);return !!match&&match[0]===name;}
+function intentTemps(p:Paths):string[]{
+  const iterator=opendirSync(p.home),out:string[]=[];let count=0,bytes=0;
+  try{for(;;){const item=iterator.readSync();if(!item)break;if(++count>20000||(bytes+=Buffer.byteLength(item.name))>8*1024*1024)fail("bound");
+    if(item.name.startsWith(WRITER_RENEWAL_INTENT_FILE+".pending-")){if(!isWriterRenewalIntentTempName(item.name))fail();if(out.length>=256)fail("bound");out.push(item.name);}
+  }}finally{iterator.closeSync();}return out.sort();
+}
+function readIntent(p:Paths,checks:(()=>void)[],expected?:WriterRenewalIntent,ignoreUnpublishedStaging=false):{file?:FileRead;intent?:WriterRenewalIntent;temp?:string}{
+  const names=intentTemps(p);if(!ignoreUnpublishedStaging)checks.push(()=>{if(canonicalJSON(intentTemps(p))!==canonicalJSON(names))fail("changed");});
+  const final=read(p.intent,WRITER_RENEWAL_INTENT_MAX_BYTES,checks,[1n,2n]);
+  if(!final&&names.length){if(ignoreUnpublishedStaging)return{};fail("staging");}
+  if(names.length>1)fail();const temp=names[0]?join(p.home,names[0]):undefined;
+  const staging=temp?read(temp,WRITER_RENEWAL_INTENT_MAX_BYTES,checks,[1n,2n]):undefined;
+  if(!final&&!staging)return{};
+  const file=final??staging!;
+  let intent:WriterRenewalIntent;
+  if(expected){const full=encode(expected);if(file.bytes.length>full.length||!file.bytes.equals(full.subarray(0,file.bytes.length)))fail();intent=expected;}
+  else {try{intent=decode(file.bytes,validateWriterRenewalIntent);}catch{fail("pending");}}
+  const full=encode(intent),known=join(p.home,writerRenewalIntentTempName(intent));if(temp&&temp!==known)fail();
+  if(final){if(!final.bytes.equals(full))fail();if(staging){if(final.stat.nlink!==2n||staging.stat.nlink!==2n||stamp(final.stat)!==stamp(staging.stat)||!staging.bytes.equals(full))fail();}else if(final.stat.nlink!==1n)fail();}
+  else if(staging!.stat.nlink!==1n)fail();
+  return{file,intent,temp};
+}
+function publishIntent(p:Paths,intent:WriterRenewalIntent,opts:WriterHistoryOptions):void{
+  const before=readIntent(p,[],intent),full=encode(intent),temp=join(p.home,writerRenewalIntentTempName(intent));
+  if(!before.file||!lstatSync(p.intent,{throwIfNoEntry:false})){
+    complete(p,temp,full,WRITER_RENEWAL_INTENT_MAX_BYTES,opts,"intent-written","intent-fsync",{at:0,phase:"intent-started"});proof(p,opts);
+    const staged=readFileExpected(temp,full,WRITER_RENEWAL_INTENT_MAX_BYTES);proof(p,opts);
+    if(stamp(lstatSync(temp,{bigint:true}))!==stamp(staged.stat))fail("changed");linkSync(temp,p.intent);syncDir(p,p.home,opts);
+  }
+  const current=readIntent(p,[],intent);if(!current.file||!current.file.bytes.equals(full))fail();
+  if(current.temp){proof(p,opts);const pair=readIntent(p,[],intent);if(pair.temp!==temp||!pair.file||stamp(pair.file.stat)!==stamp(current.file.stat))fail("changed");unlinkSync(temp);syncDir(p,p.home,opts);}
+  const final=readFileExpected(p.intent,full,WRITER_RENEWAL_INTENT_MAX_BYTES),fd=openSync(p.intent,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
+  try{if(stamp(fstatSync(fd,{bigint:true}))!==stamp(final.stat))fail("changed");proof(p,opts);fsyncSync(fd);if(stamp(lstatSync(p.intent,{bigint:true}))!==stamp(final.stat))fail("changed");}finally{closeSync(fd);}syncDir(p,p.home,opts);
+  if(stamp(lstatSync(p.intent,{bigint:true}))!==stamp(final.stat))fail("changed");
+}
+interface Snapshot { result:WriterHistoryRead; paths:Paths; log:Buffer; intentBytes?:Buffer }
+function snapshot(home:string,b:WriterHistoryBinding,allowPending:boolean,expected?:WriterRenewalIntent,ignoreUnpublishedStaging=false):Snapshot {
+  const p=paths(home,b), checks:(()=>void)[]=[], names=manifest(p);
+  for(const [dir,stat]of p.dirs)checks.push(()=>{if(identity(checkedDir(dir))!==identity(stat))fail("changed");});
+  checks.push(()=>{if(canonicalJSON(manifest(p))!==canonicalJSON(names))fail("changed");});
+  const intentRead=readIntent(p,checks,expected,ignoreUnpublishedStaging),intentFile=intentRead.file;let pending=intentRead.intent;
+  if(pending){if(!allowPending)fail("pending");if(pending.home!==p.home)fail();boundRevision(pending.revision,b);}
+  else if(expected)fail("pending");
+  const logFile=read(p.log,WRITER_COMMIT_MAX_BYTES,checks), log=logFile?.bytes??Buffer.alloc(0);
+  const commits:WriterCommit[]=[],anchors:{sequence:number;headHash:string}[]=[];let current:WriterRevision|undefined;
+  let head=writerInventoryGenesis(b.epochHash,b.activationHash),previous=0,completeBytes=log.length;
+  const lastLF=log.lastIndexOf(10);if(lastLF!==log.length-1){if(!pending)fail("pending");completeBytes=lastLF+1;}
+  let at=0;
+  while(at<completeBytes){const end=log.indexOf(10,at);if(end<at)fail();const commit=decode(log.subarray(at,end+1),validateWriterCommit);at=end+1;
+    if(commits.length>=WRITER_REVISION_LIMIT)fail("bound");if(commit.epochHash!==b.epochHash||commit.sequence!==commits.length+1||commit.previousHash!==head)fail();
+    const file=join(p.epoch,writerRevisionFile(commit.sequence)),raw=read(file,WRITER_REVISION_MAX_BYTES,checks);if(!raw)fail();
+    const revision=decode(raw.bytes,validateWriterRevision);boundRevision(revision,b);
+    if(revision.sequence!==commit.sequence||revision.previousHash!==head||canonicalJSON(createWriterCommit(revision))!==canonicalJSON(commit))fail();
+    if(current&&revision.initialLocatorHash!==current.initialLocatorHash)fail();
+    if(revision.journal.sequence<previous||revision.journal.sequence===previous&&anchors.length&&revision.journal.headHash!==anchors.at(-1)!.headHash)fail();
+    anchors.push({...revision.journal});previous=revision.journal.sequence;commits.push(commit);current=revision;head=commit.seal;
+  }
+  const expectedNames=new Set(commits.map(commit=>writerRevisionFile(commit.sequence)));if(logFile)expectedNames.add(WRITER_COMMIT_LOG);
+  if(pending){
+    const start=pending.previousLogBytes, next=pending.revision.sequence;
+    if(start>log.length||sha(log.subarray(0,start))!==pending.previousLogHash||start>0&&log[start-1]!==10)fail();
+    const beforeCount=commits.filter(commit=>commit.sequence<next).length;
+    if(beforeCount!==next-1||commits.length<next-1||commits.length>next)fail();
+    const beforeHead=next===1?writerInventoryGenesis(b.epochHash,b.activationHash):commits[next-2]!.seal;
+    if(pending.revision.previousHash!==beforeHead||start!==committedPrefixLength(log,next-1))fail();
+    const tail=log.subarray(start),line=encode(pending.commit);if(tail.length>line.length||!tail.equals(line.subarray(0,tail.length)))fail();
+    const candidateFile=join(p.epoch,writerRevisionFile(next)),candidate=read(candidateFile,WRITER_REVISION_MAX_BYTES,checks),full=encode(pending.revision);
+    if(candidate){if(candidate.bytes.length>full.length||!candidate.bytes.equals(full.subarray(0,candidate.bytes.length)))fail();expectedNames.add(writerRevisionFile(next));}
+    if(tail.length&&(!candidate||!candidate.bytes.equals(full)))fail();
+    if(current&&current.initialLocatorHash!==pending.revision.initialLocatorHash)fail();
+    if(next>1){const anchor=anchors[next-2]!;if(pending.revision.journal.sequence<anchor.sequence||pending.revision.journal.sequence===anchor.sequence&&pending.revision.journal.headHash!==anchor.headHash)fail();}
+  }else if(completeBytes!==log.length||logFile&&commits.length===0)fail("pending");
+  if(canonicalJSON([...expectedNames].sort())!==canonicalJSON(names))fail();
+  const assertCurrent=()=>safe(()=>{for(const check of checks)check();});assertCurrent();
+  return{paths:p,log,intentBytes:intentFile?.bytes,result:{current,commits,anchors,sequence:commits.length,headHash:head,logBytes:log.length,logHash:sha(log),pending,appendStarted:!!pending&&log.length>pending.previousLogBytes,assertCurrent}};
+}
+function committedPrefixLength(log:Buffer,count:number):number {let at=0;for(let n=0;n<count;n++){const lf=log.indexOf(10,at);if(lf<0)fail();at=lf+1;}return at;}
+export function readWriterHistory(home:string,input:WriterHistoryBinding,options:{allowPending?:boolean}={}):WriterHistoryRead {
+  return safe(()=>snapshot(home,binding(input),options.allowPending===true).result);
+}
+function proof(p:Paths,opts:WriterHistoryOptions):void {
+  assertMutationHandle(opts.mutation,p.home);opts.assertCurrent();assertMutationHandle(opts.mutation,p.home);
+  for(const [dir,stat]of p.dirs)if(identity(checkedDir(dir))!==identity(stat))fail("changed");
+}
+function syncDir(p:Paths,dir:string,opts:WriterHistoryOptions):void {
+  proof(p,opts);const stat=checkedDir(dir),fd=openSync(dir,constants.O_RDONLY|constants.O_DIRECTORY|constants.O_NOFOLLOW);
+  try{if(identity(fstatSync(fd,{bigint:true}))!==identity(stat))fail("changed");proof(p,opts);fsyncSync(fd);}finally{closeSync(fd);}proof(p,opts);
+}
+function complete(p:Paths,file:string,full:Buffer,max:number,opts:WriterHistoryOptions,written:WriterHistoryPhase,synced:WriterHistoryPhase,start?:{at:number;phase:WriterHistoryPhase}):void {
+  if(full.length>max)fail("bound");proof(p,opts);const prior=read(file,max);if(prior&&(prior.bytes.length>full.length||!prior.bytes.equals(full.subarray(0,prior.bytes.length))))fail();
+  let installed:BigIntStats;
+  const fd=openSync(file,constants.O_WRONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK|(prior?0:constants.O_CREAT|constants.O_EXCL),0o600);
+  try{
+    const opened=fstatSync(fd,{bigint:true});owned(opened);if(prior?stamp(opened)!==stamp(prior.stat):opened.size!==0n)fail("changed");
+    let observed=opened;proof(p,opts);let at=prior?.bytes.length??0;
+    while(at<full.length){proof(p,opts);if(stamp(fstatSync(fd,{bigint:true}))!==stamp(observed)||stamp(lstatSync(file,{bigint:true}))!==stamp(observed))fail("changed");const firstByte=start!==undefined&&at===start.at;const n=writeSync(fd,full,at,firstByte?1:full.length-at,at);if(n<=0)fail();at+=n;observed=fstatSync(fd,{bigint:true});if(firstByte)opts.phase?.(start!.phase);}
+    opts.phase?.(written);proof(p,opts);const after=fstatSync(fd,{bigint:true});if(stamp(after)!==stamp(observed)||after.size!==BigInt(full.length)||stamp(lstatSync(file,{bigint:true}))!==stamp(after))fail("changed");fsyncSync(fd);installed=fstatSync(fd,{bigint:true});opts.phase?.(synced);
+    if(stamp(lstatSync(file,{bigint:true}))!==stamp(installed))fail("changed");
+  }finally{closeSync(fd);}syncDir(p,dirname(file),opts);proof(p,opts);if(stamp(lstatSync(file,{bigint:true}))!==stamp(installed!))fail("changed");
+}
+function checkedIntent(home:string,value:WriterRenewalIntent,opts:WriterHistoryOptions):{intent:WriterRenewalIntent;snapshot:Snapshot}{
+  const intent=validateWriterRenewalIntent(value),b=intentBinding(intent),p=paths(home,b);proof(p,opts);
+  const read=snapshot(home,b,true,intent);if(!read.intentBytes)fail("pending");return{intent,snapshot:read};
+}
+export function writeWriterRenewalIntent(home:string,value:WriterRenewalIntent,opts:WriterHistoryOptions):void {
+  safe(()=>{
+    const intent=validateWriterRenewalIntent(value),b=intentBinding(intent),p=paths(home,b);if(intent.home!==p.home)fail();
+    if(intent.previousLogBytes+encode(intent.commit).length>WRITER_COMMIT_MAX_BYTES)fail("bound");proof(p,opts);
+    const prior=readIntent(p,[],intent).file;
+    const old=prior?snapshot(home,b,true,intent):snapshot(home,b,false);
+    if(!prior&&(intent.revision.sequence!==old.result.sequence+1||intent.revision.previousHash!==old.result.headHash||intent.previousLogBytes!==old.result.logBytes||intent.previousLogHash!==old.result.logHash))fail("changed");
+    old.result.assertCurrent();publishIntent(p,intent,opts);snapshot(home,b,true).result.assertCurrent();opts.phase?.("intent-published");
+  });
+}
+export function writeWriterRevision(home:string,value:WriterRenewalIntent,opts:WriterHistoryOptions):void {
+  safe(()=>{const {intent,snapshot:read}=checkedIntent(home,value,opts);read.result.assertCurrent();
+    publishIntent(read.paths,intent,opts);
+    complete(read.paths,join(read.paths.epoch,writerRevisionFile(intent.revision.sequence)),encode(intent.revision),WRITER_REVISION_MAX_BYTES,opts,"revision-written","revision-fsync");
+    snapshot(home,intentBinding(intent),true).result.assertCurrent();});
+}
+export function appendWriterCommit(home:string,value:WriterRenewalIntent,opts:WriterHistoryOptions):void {
+  safe(()=>{const {intent,snapshot:read}=checkedIntent(home,value,opts);read.result.assertCurrent();
+    publishIntent(read.paths,intent,opts);
+    complete(read.paths,join(read.paths.epoch,writerRevisionFile(intent.revision.sequence)),encode(intent.revision),WRITER_REVISION_MAX_BYTES,opts,"revision-written","revision-fsync");
+    const prefix=read.log.subarray(0,intent.previousLogBytes),full=Buffer.concat([prefix,encode(intent.commit)]);
+    complete(read.paths,read.paths.log,full,WRITER_COMMIT_MAX_BYTES,opts,"commit-written","commit-fsync",{at:intent.previousLogBytes,phase:"commit-started"});snapshot(home,intentBinding(intent),true).result.assertCurrent();});
+}
+export function clearWriterRenewalIntent(home:string,value:WriterRenewalIntent,opts:WriterHistoryOptions):void {
+  safe(()=>{const intent=validateWriterRenewalIntent(value),p=paths(home,intentBinding(intent));proof(p,opts);
+    const prior=readIntent(p,[],intent).file;
+    if(prior){const read=snapshot(home,intentBinding(intent),true,intent);if(!prior.bytes.equals(encode(intent))||read.result.headHash!==intent.commit.seal||read.log.length!==intent.previousLogBytes+encode(intent.commit).length)fail("pending");
+      appendWriterCommit(home,intent,opts);proof(p,opts);const now=readFileExpected(p.intent,encode(intent),WRITER_RENEWAL_INTENT_MAX_BYTES);proof(p,opts);if(stamp(lstatSync(p.intent,{bigint:true}))!==stamp(now.stat))fail("changed");unlinkSync(p.intent);opts.phase?.("intent-cleared");}
+    else {const read=snapshot(home,intentBinding(intent),false);if(read.result.headHash!==intent.commit.seal)fail("changed");}
+    syncDir(p,p.epoch,opts);syncDir(p,p.home,opts);proof(p,opts);snapshot(home,intentBinding(intent),false).result.assertCurrent();});
+}
+function readFileExpected(file:string,full:Buffer,max:number):FileRead {const value=read(file,max);if(!value||!value.bytes.equals(full))fail();return value;}
+export function abandonWriterRenewal(home:string,value:WriterRenewalIntent,opts:WriterHistoryOptions):void {
+  safe(()=>{const intent=validateWriterRenewalIntent(value),p=paths(home,intentBinding(intent));proof(p,opts);
+    if(!readIntent(p,[],intent).file){
+      const cleared=snapshot(home,intentBinding(intent),false);
+      if(cleared.result.sequence!==intent.revision.sequence-1||cleared.result.headHash!==intent.revision.previousHash||cleared.result.logBytes!==intent.previousLogBytes||cleared.result.logHash!==intent.previousLogHash)fail("changed");
+      cleared.result.assertCurrent();syncDir(p,p.epoch,opts);syncDir(p,p.home,opts);proof(p,opts);return;
+    }
+    const before=snapshot(home,intentBinding(intent),true,intent);
+    if(before.result.appendStarted)fail("pending");
+    const check=()=>{proof(p,opts);const current=snapshot(home,intentBinding(intent),true,intent);if(current.result.appendStarted||current.log.length!==intent.previousLogBytes||sha(current.log)!==intent.previousLogHash)fail("pending");};
+    check();const candidate=join(p.epoch,writerRevisionFile(intent.revision.sequence)),prior=read(candidate,WRITER_REVISION_MAX_BYTES);
+    if(prior){check();if(stamp(lstatSync(candidate,{bigint:true}))!==stamp(prior.stat))fail("changed");unlinkSync(candidate);syncDir(p,p.epoch,opts);}
+    const log=read(p.log,WRITER_COMMIT_MAX_BYTES);if(intent.revision.sequence===1&&log){if(log.bytes.length)fail("pending");check();if(stamp(lstatSync(p.log,{bigint:true}))!==stamp(log.stat))fail("changed");unlinkSync(p.log);syncDir(p,p.epoch,opts);}
+    // Reassert parent durability even when the prior owner removed a member before its fsync.
+    syncDir(p,p.epoch,opts);check();const intentRead=readIntent(p,[],intent);if(!intentRead.file)fail("changed");
+    if(intentRead.temp){check();unlinkSync(intentRead.temp);syncDir(p,p.home,opts);}
+    const pending=read(p.intent,WRITER_RENEWAL_INTENT_MAX_BYTES);
+    if(pending){proof(p,opts);if(!pending.bytes.equals(encode(intent))||stamp(lstatSync(p.intent,{bigint:true}))!==stamp(pending.stat))fail("changed");unlinkSync(p.intent);opts.phase?.("intent-cleared");}
+    syncDir(p,p.home,opts);proof(p,opts);snapshot(home,intentBinding(intent),false).result.assertCurrent();
+  });
+}
+
+
+/** Person coordinator only: discard unpublished atomic-intent staging, never a registered or committed renewal.
+ * This purpose-specific reader exception is deliberately unavailable to ordinary history/resolver callers. */
+export function abandonUnpublishedWriterStaging(home:string,input:WriterHistoryBinding,opts:WriterHistoryOptions&{assertCommittedHistory?(history:WriterHistoryRead):void}):{removed:number}{
+  return safe(()=>{
+    const b=binding(input),p=paths(home,b);proof(p,opts);
+    if(lstatSync(p.intent,{throwIfNoEntry:false}))fail("pending");
+    const before=snapshot(home,b,false,undefined,true);before.result.assertCurrent();
+    const guarded:WriterHistoryOptions={...opts,assertCurrent(){opts.assertCurrent();opts.assertCommittedHistory?.(before.result);}};
+    proof(p,guarded);
+    const members=new Map<string,{stat:BigIntStats;hash:string}>();
+    for(const name of intentTemps(p)){
+      proof(p,guarded);const file=join(p.home,name),value=read(file,WRITER_RENEWAL_INTENT_MAX_BYTES);if(!value)fail("changed");
+      members.set(name,{stat:value.stat,hash:sha(value.bytes)});
+    }
+    const check=()=>{
+      proof(p,guarded);before.result.assertCurrent();
+      if(lstatSync(p.intent,{throwIfNoEntry:false})||canonicalJSON(intentTemps(p))!==canonicalJSON([...members.keys()].sort()))fail("changed");
+    };
+    check();let removed=0;
+    for(const [name,expected]of members){
+      check();const file=join(p.home,name),value=read(file,WRITER_RENEWAL_INTENT_MAX_BYTES);
+      if(!value||stamp(value.stat)!==stamp(expected.stat)||sha(value.bytes)!==expected.hash)fail("changed");
+      check();if(stamp(lstatSync(file,{bigint:true}))!==stamp(expected.stat))fail("changed");
+      unlinkSync(file);members.delete(name);removed++;syncDir(p,p.home,guarded);check();
+    }
+    // A previous owner may have unlinked the last stage before the directory fsync/acknowledgement.
+    syncDir(p,p.epoch,guarded);syncDir(p,p.home,guarded);check();return{removed};
+  });
+}

package/src/memory/sync-placement-writer-renewal.ts

@@ -0,0 +1,179 @@
+/** Person-only same-epoch writer renewal. No source/journal recovery, publication or floor writer. */
+import { randomBytes, createHash } from "node:crypto";
+import { lstatSync, opendirSync } from "node:fs";
+import { join, basename } from "node:path";
+import { types } from "node:util";
+import { canonicalJSON, readProfileJSON, hashJSON, legacyProfileMarkerShape } from "./generation.ts";
+import { validatePlacementProfile } from "./sync-placement-format.ts";
+import { realPath } from "./platform.ts";
+import { readPlacementRuntimeMarkers } from "./sync-placement-guard.ts";
+import { readActivePlacementBinding, type ActivePlacementBinding } from "./sync-placement-active.ts";
+import { readInitialSyncPlacementWriterLocator } from "./sync-placement-writer-roots.ts";
+import { readEffectiveSyncPlacementWriters } from "./sync-placement-effective-writers.ts";
+import { readPlacementJournal, readPlacementWriterJournalAnchors, writerRenewalCapacity } from "./sync-placement-journal-storage.ts";
+import { readWriterHistory, writeWriterRenewalIntent, writeWriterRevision, appendWriterCommit, clearWriterRenewalIntent, abandonWriterRenewal, abandonUnpublishedWriterStaging, type WriterHistoryPhase, type WriterHistoryRead } from "./sync-placement-writer-history.ts";
+import { createWriterRevision, createWriterCommit, createWriterRenewalIntent, writerRevisionWriters, WRITER_REVISION_SCHEMA, WRITER_RENEWAL_INTENT_SCHEMA, WRITER_REVISION_LIMIT, WRITER_COMMIT_LOG, SharedWriterRevisionError, type WriterRenewalIntent } from "./sync-placement-writer-revision-format.ts";
+import { requireWriterRenewalHomeFloor } from "./sync-placement-prerequisites.ts";
+import { withPlacementActivationFences } from "./sync-placement-activation-locks.ts";
+import { assertPlacementActivationOwner, type PlacementActivationOwner } from "./sync-placement-activation-proof.ts";
+import { previewSyncPlacementSources, previewOwnedSyncPlacementSources } from "./sync-placement-capture.ts";
+import { captureInspectionPendingPrunes } from "./sync-placement-inspection-pending.ts";
+import { validatePrunePlan } from "./prune.ts";
+import { initialPlacementWriterContext, previewActivePlacementWriters } from "../sync-placement-writer-context.ts";
+import type { PlacementActivationOptions } from "./sync-placement-activation.ts";
+
+export class WriterRenewalError extends Error{
+  constructor(readonly causeClass:"pending"|"candidate"|"changed"|"capacity"|"authorization",details=""){
+    super(causeClass==="pending"
+      ? "Writer renewal refuses an outstanding append, publication, reservation or source-recovery intent; if a precommit renewal is retained, run amem migrate --sync-placement --abandon first. Then restore the inventoried install (for example dot ai rollback amem or the host's previous pin), run amem sync to finish the exact attempt, then preview and apply renewal."
+      :causeClass==="candidate"
+        ? "Writer renewal requires an explicit complete --writer-root inventory of 0.22.0-or-later installs; upgrade the CLI/host pins, refresh managed setup receipts and run amem migrate --sync-placement --dry-run before applying."
+        :causeClass==="capacity"
+          ? `Writer renewal metadata capacity is exhausted ${details}; retain this epoch and request a separately reviewed archival/checkpoint protocol before another renewal.`
+          :causeClass==="authorization"
+            ? "Writer renewal requires explicit person authorization of this exact inventory; have the person preview it with amem migrate --sync-placement --dry-run and then apply."
+            : "Writer renewal frozen inventory or binding changed; restore it and run amem migrate --sync-placement --resume, or use --abandon before commit append starts and review a new dry-run.");
+    this.name="WriterRenewalError";
+  }
+}
+function active(home:string):ActivePlacementBinding{
+  const markers=readPlacementRuntimeMarkers(home),value=readActivePlacementBinding(home,markers.profile,markers.shards);if(!value)throw new WriterRenewalError("changed");return value;
+}
+const binding=(a:ActivePlacementBinding)=>({epochHash:a.profile.placementHead,activationHash:a.activation.seal,homeHash:a.epoch.homeHash,generation:a.epoch.generation});
+function list(dir:string,maximum:number):string[]{
+  const out:string[]=[],reader=opendirSync(dir);try{for(;;){const e=reader.readSync();if(!e)break;if(out.length>=maximum)throw new SharedWriterRevisionError("bound");out.push(e.name);}}finally{reader.closeSync();}return out.sort();
+}
+function directories(home:string,a:ActivePlacementBinding):string[]{
+  const out=[home];for(const r of a.activation.realms)out.push(r.scope==="user"?join(home,"user"):join(home,"projects",r.keyHash.slice(0,16)));
+  const checked=(dir:string)=>{const s=lstatSync(dir);if(!s.isDirectory()||s.isSymbolicLink()||s.uid!==process.getuid?.()||(s.mode&0o022)!==0)throw new WriterRenewalError("changed");};
+  const projects=join(home,"projects");if(lstatSync(projects,{throwIfNoEntry:false})){
+    checked(projects);for(const name of list(projects,256))if(/^[a-f0-9]{16}$/.test(name)){
+      const dir=join(projects,name);checked(dir);if(lstatSync(join(dir,"generation.json"),{throwIfNoEntry:false}))out.push(dir);
+    }
+  }
+  for(const dir of out)checked(dir);
+  return[...new Set(out)].sort();
+}
+function pendingSources(home:string,owner?:PlacementActivationOwner):()=>void{
+  try{
+    const source=owner?previewOwnedSyncPlacementSources(home,owner):previewSyncPlacementSources(home),checks=source.directories.map(captureInspectionPendingPrunes);
+    for(const dir of source.directories){
+      const history=join(dir,"prune-plans","selector-history");if(!lstatSync(history,{throwIfNoEntry:false}))continue;
+      const seen=new Set<string>();
+      for(const name of list(history,128)){
+        const m=/^([a-f0-9]{64})\.json(\.pending)?$/.exec(name);if(!m||m[2])throw new WriterRenewalError("pending");seen.add(m[1]!);
+        if(seen.size>64)throw new SharedWriterRevisionError("bound");
+        const stat=lstatSync(join(history,name));if(!stat.isFile()||stat.isSymbolicLink()||stat.nlink!==1||stat.uid!==process.getuid?.()||(stat.mode&0o077)!==0||stat.size>262144)throw new WriterRenewalError("pending");
+        const plan=validatePrunePlan(readProfileJSON(join(dir,"prune-plans",m[1]+".json")));
+        if(plan.seal!==m[1]||plan.rows.length!==1)throw new WriterRenewalError("pending");
+        const prior=readProfileJSON(join(history,name));if(!prior||typeof prior!=="object"||hashJSON(prior)!==plan.selectorRevision)throw new WriterRenewalError("pending");
+        if((prior as {schema?:unknown}).schema==="agent-mem.profile/v3")validatePlacementProfile(prior);else if(!legacyProfileMarkerShape(prior))throw new WriterRenewalError("pending");
+        const row=plan.rows[0]!.payload;
+        if(![...source.specialRows.values()].some(item=>item.row.id===row.id&&hashJSON(item.row)===hashJSON(row)
+          &&(dir===home||basename(dir)==="user"&&item.key.realm.scope==="user"||item.key.realm.scope==="project"&&item.key.realm.keyHash.slice(0,16)===basename(dir))))throw new WriterRenewalError("pending");
+      }
+    }
+    return()=>{source.assertSourcesUnchanged();for(const check of checks)check();};
+  }catch(error){if(error instanceof SharedWriterRevisionError&&error.code==="bound")throw error;throw new WriterRenewalError("pending");}
+}
+function journalClear(home:string,epochHash:string):void{
+  try{const j=readPlacementJournal(home,epochHash);if(j.pending||j.publicationReservation)throw Error();}catch{throw new WriterRenewalError("pending");}
+}
+function supported(version:string):boolean{const p=version.split(".").map(Number);return p[0]!>0||p[0]===0&&p[1]!>=22;}
+function person(options:PlacementActivationOptions,intent:WriterRenewalIntent):void{
+  let okay=false;try{okay=options.authorize(Object.freeze({seal:intent.revision.seal,generation:intent.revision.generation,homeHash:intent.revision.homeHash}))===true;}catch{}
+  if(!okay)throw new WriterRenewalError("authorization");
+}
+export async function renewSyncPlacementWriters(options:PlacementActivationOptions):Promise<Record<string,unknown>|undefined>{
+  const home=realPath(options.memoryDir),initial=active(home),b=binding(initial);
+  let history:WriterHistoryRead;
+  try{history=readWriterHistory(home,b,{allowPending:true});}catch(error){
+    if(options.mode!=="abandon"||!error||typeof error!=="object"||types.isProxy(error)||!(error instanceof SharedWriterRevisionError)||Object.getOwnPropertyDescriptor(error,"code")?.value!=="staging")throw error;
+    requireWriterRenewalHomeFloor(home);
+    return withPlacementActivationFences(home,directories(home,initial),async(mutation,owner)=>{
+      const locator=readInitialSyncPlacementWriterLocator(home),seal=hashJSON({action:"abandon-unpublished-writer-staging",...b,initialLocatorHash:locator.seal});
+      let authorized=false;try{authorized=options.authorize(Object.freeze({seal,generation:b.generation,homeHash:b.homeHash}))===true;}catch{}
+      if(!authorized)throw new WriterRenewalError("authorization");
+      const assertCurrent=()=>{assertPlacementActivationOwner(owner);requireWriterRenewalHomeFloor(home);if(canonicalJSON(binding(active(home)))!==canonicalJSON(b)||readInitialSyncPlacementWriterLocator(home).seal!==locator.seal)throw new WriterRenewalError("changed");};
+      const assertCommittedHistory=(history:WriterHistoryRead)=>{
+        assertCurrent();const journal=readPlacementWriterJournalAnchors(home,b.epochHash);
+        for(const anchor of history.anchors)if(anchor.sequence>journal.sequence||(anchor.sequence===0?b.epochHash:journal.records[anchor.sequence-1]?.seal)!==anchor.headHash)throw new WriterRenewalError("changed");
+      };
+      const cleared=abandonUnpublishedWriterStaging(home,{...b,initialLocatorHash:locator.seal},{mutation,assertCurrent,assertCommittedHistory});
+      return{mode:options.mode,active:true,abandoned:true,unpublishedStagingRemoved:cleared.removed,nextStep:"amem migrate --sync-placement --dry-run"};
+    });
+  }
+  if(!history.pending&&(options.mode==="resume"||options.mode==="abandon")&&history.sequence===0)return undefined;
+  if(options.mode==="dry-run"){
+    if(history.pending)return{mode:options.mode,active:true,renewalSupported:true,pending:true,commitStarted:history.appendStarted,abandonable:!history.appendStarted,sequence:history.sequence,remainingRevisions:WRITER_REVISION_LIMIT-history.sequence};
+    const expected=readEffectiveSyncPlacementWriters(home);let floorReady=true;try{requireWriterRenewalHomeFloor(home);}catch{floorReady=false;}
+    let recoveryReady=true,objectSlotsRemaining:number|undefined;
+    try{journalClear(home,b.epochHash);pendingSources(home);objectSlotsRemaining=256-readPlacementJournal(home,b.epochHash).objects;}catch{recoveryReady=false;}
+    const writers=previewActivePlacementWriters(home,options.ownRoot,options.writerRoots),remaining=WRITER_REVISION_LIMIT-history.sequence;
+    return{mode:options.mode,active:true,renewalSupported:true,forwardOnly:true,sequence:history.sequence,revisionHash:history.headHash,remainingRevisions:WRITER_REVISION_LIMIT-history.sequence,
+      quiescence:"deferred-to-apply",floorReady,requiredHomeFloor:"0.22.0",recoveryReady,...(recoveryReady?{}:{nextStep:new WriterRenewalError("pending").message}),
+      ...(objectSlotsRemaining===undefined?{}:{objectSlotsRemaining}),...(remaining<=4?{capacityNotice:`${remaining} renewals remain before the 64-revision ceiling; the shared object budget may refuse earlier. Archival/checkpointing requires a separate reviewed protocol.`}:{}),
+      writers,candidateMinimumVersion:"0.22.0",candidatesSupported:writers.complete&&writers.roots.every(r=>supported(r.version)),expectedWriterCount:expected.writers.length};
+  }
+  requireWriterRenewalHomeFloor(home);
+  if(history.pending&&options.mode==="apply")throw new SharedWriterRevisionError("pending");
+  if(!history.pending&&options.mode==="abandon")throw new WriterRenewalError("changed");
+  if(!history.pending&&options.mode==="apply"&&!options.writerRoots.length)throw new WriterRenewalError("candidate");
+  // No new intent is written before every pre-existing recovery obligation has been rejected.
+  // An unlocked refusal stays entirely passive; crashed owners must first be reclaimed by the real fences below.
+  const passivePreflight=options.mode==="apply"||options.mode==="resume"&&history.pending&&!history.appendStarted&&!lstatSync(join(home,"profile.lock"),{throwIfNoEntry:false});
+  let sourceCheck=passivePreflight?(journalClear(home,b.epochHash),pendingSources(home)):undefined;
+  return withPlacementActivationFences(home,directories(home,initial),async(mutation,owner)=>{
+    if(options.mode==="resume"&&history.pending&&!history.appendStarted){journalClear(home,b.epochHash);sourceCheck=pendingSources(home,owner);}
+    let intent=history.pending;
+    const cleanupOnly=!intent&&options.mode==="resume"&&!!history.current;
+    if(cleanupOnly){
+      const prefix=Buffer.from(history.commits.slice(0,-1).map(row=>canonicalJSON(row)+"\n").join(""));
+      intent=createWriterRenewalIntent({schema:WRITER_RENEWAL_INTENT_SCHEMA,home,revision:history.current!,commit:history.commits.at(-1)!,previousLogBytes:prefix.length,previousLogHash:createHash("sha256").update(prefix).digest("hex")});
+    }
+    const locator=readInitialSyncPlacementWriterLocator(home);
+    const metadata=()=>{
+      assertPlacementActivationOwner(owner);requireWriterRenewalHomeFloor(home);
+      const now=active(home);if(canonicalJSON(binding(now))!==canonicalJSON(b)||readInitialSyncPlacementWriterLocator(home).seal!==locator.seal)throw new WriterRenewalError("changed");
+      if(intent){const journal=readPlacementWriterJournalAnchors(home,b.epochHash),anchor=intent.revision.journal;
+        if(anchor.sequence>journal.sequence||(anchor.sequence===0?b.epochHash:journal.records[anchor.sequence-1]?.seal)!==anchor.headHash)throw new WriterRenewalError("changed");}
+    };
+    metadata();
+    if(cleanupOnly){
+      person(options,intent!);clearWriterRenewalIntent(home,intent!,{mutation,assertCurrent:metadata});
+      return{mode:options.mode,active:true,renewed:false,alreadyCommitted:true,sequence:history.sequence,remainingRevisions:WRITER_REVISION_LIMIT-history.sequence};
+    }
+    if(!intent){
+      journalClear(home,b.epochHash);sourceCheck?.();
+      const current=readWriterHistory(home,{...b,initialLocatorHash:locator.seal});
+      if(current.sequence>=WRITER_REVISION_LIMIT)throw new SharedWriterRevisionError("cap");
+      const candidate=initialPlacementWriterContext(home,options.writerRoots,options.ownRoot);if(candidate.measurement.roots.some(r=>!supported(r.version)))throw new WriterRenewalError("candidate");
+      candidate.attest();const previous=current.current?writerRevisionWriters(current.current):initial.activation.writers;
+      if(canonicalJSON(previous)===canonicalJSON(candidate.measurement.writers))return{mode:options.mode,active:true,renewed:false,sequence:current.sequence,remainingRevisions:WRITER_REVISION_LIMIT-current.sequence};
+      const journal=readPlacementJournal(home,b.epochHash),revision=createWriterRevision({schema:WRITER_REVISION_SCHEMA,...b,initialLocatorHash:locator.seal,sequence:current.sequence+1,previousHash:current.headHash,
+        journal:{sequence:journal.sequence,headHash:journal.headHash},roots:candidate.measurement.roots,requestId:randomBytes(32).toString("hex")});
+      intent=createWriterRenewalIntent({schema:WRITER_RENEWAL_INTENT_SCHEMA,home,revision,commit:createWriterCommit(revision),previousLogBytes:current.logBytes,previousLogHash:current.logHash});
+    }
+    const fixed=intent;person(options,fixed);
+    const log=join(home,"sync-placement","epochs",b.epochHash,WRITER_COMMIT_LOG);
+    const started=()=>{const s=lstatSync(log,{throwIfNoEntry:false});return!!s&&s.isFile()&&!s.isSymbolicLink()&&s.size>fixed.previousLogBytes;};
+    const check=()=>{
+      metadata();
+      try{writerRenewalCapacity(home,b.epochHash,fixed.revision.sequence);}catch{throw new WriterRenewalError("capacity",`(remaining ${WRITER_REVISION_LIMIT-history.sequence} revision slots before the independent 64-revision ceiling)`);}
+      if(!started()&&options.mode!=="abandon"){
+        journalClear(home,b.epochHash);sourceCheck?.();
+        const candidate=initialPlacementWriterContext(home,fixed.revision.roots.map(r=>r.root),options.ownRoot);candidate.attest();
+        if(canonicalJSON(candidate.measurement.roots)!==canonicalJSON(fixed.revision.roots))throw new WriterRenewalError("changed");
+        const j=readPlacementJournal(home,b.epochHash);if(j.sequence!==fixed.revision.journal.sequence||j.headHash!==fixed.revision.journal.headHash)throw new WriterRenewalError("changed");
+      }
+    };
+    const storage={mutation,assertCurrent:check,phase:(phase:WriterHistoryPhase)=>options.renewalCheckpoint?.(phase)};
+    if(options.mode==="abandon"){
+      abandonWriterRenewal(home,fixed,{...storage,assertCurrent:metadata});
+      return{mode:options.mode,active:true,abandoned:true,sequence:history.sequence,remainingRevisions:WRITER_REVISION_LIMIT-history.sequence};
+    }
+    check();writeWriterRenewalIntent(home,fixed,storage);writeWriterRevision(home,fixed,storage);appendWriterCommit(home,fixed,storage);
+    clearWriterRenewalIntent(home,fixed,{...storage,assertCurrent:metadata});
+    return{mode:options.mode,active:true,renewed:true,epochHash:b.epochHash,sequence:fixed.revision.sequence,revisionHash:fixed.commit.seal,remainingRevisions:WRITER_REVISION_LIMIT-fixed.revision.sequence};
+  });
+}