@staix/agent-mem 0.20.3 → 0.22.0

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

package/src/memory/sync-placement-writer-revision-format.ts

@@ -0,0 +1,122 @@
+/** Pure same-epoch writer metadata codecs. Valid data and seals are neither person authority nor fresh install proof. */
+import { createHash } from "node:crypto";
+import { isAbsolute, resolve } from "node:path";
+import { types } from "node:util";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { syncPlacementWriterId, type MeasuredSyncPlacementWriterRoot } from "./sync-placement-writers.ts";
+import { PLACEMENT_FORMAT } from "./sync-placement-format.ts";
+import type { SyncPlacementWriterAttestation } from "./sync-placement-plan.ts";
+
+export const WRITER_REVISION_MAX_BYTES=512*1024;
+export const WRITER_COMMIT_MAX_BYTES=64*1024;
+export const WRITER_RENEWAL_INTENT_MAX_BYTES=1024*1024;
+export const WRITER_REVISION_LIMIT=64;
+export const WRITER_COMMIT_LOG="writer-revisions.jsonl";
+export const WRITER_RENEWAL_INTENT_FILE="sync-placement-writer-renewal.json";
+export const WRITER_REVISION_SCHEMA="agent-mem.sync-placement-writer-revision/v1";
+export const WRITER_COMMIT_SCHEMA="agent-mem.sync-placement-writer-commit/v1";
+export const WRITER_RENEWAL_INTENT_SCHEMA="agent-mem.sync-placement-writer-renewal/v1";
+
+export type SharedWriterRevisionErrorCode="invalid"|"bound"|"changed"|"pending"|"staging"|"cap";
+const messages:Record<SharedWriterRevisionErrorCode,string>={
+  invalid:"Writer renewal metadata is invalid or unsupported; have the person inspect the retained same-epoch inventory and rerun amem migrate --sync-placement --dry-run.",
+  bound:"Writer renewal metadata exceeds its supported bound; retain the existing inventory and request a separately reviewed archival/checkpoint before retrying.",
+  changed:"Writer renewal bindings changed; retain the existing inventory, inspect the same-epoch evidence and review a fresh dry-run before applying.",
+  pending:"Writer renewal is pending; preserve its exact intent and have the person run amem migrate --sync-placement --resume.",
+  staging:"Writer renewal has orphan staging without a registered final intent; have the person inspect it and run amem migrate --sync-placement --abandon, then amem migrate --sync-placement --dry-run before another apply.",
+  cap:"Writer revision capacity is exhausted (remaining 0); retain this epoch and request a separately reviewed archival/checkpoint before another renewal.",
+};
+// ponytail: at most64 immutable writer revisions; only a separately reviewed archival/checkpoint can extend this history.
+export class SharedWriterRevisionError extends Error {
+  readonly remaining?:number;
+  constructor(readonly code:SharedWriterRevisionErrorCode){
+    const safe=typeof code==="string"&&Object.hasOwn(messages,code)?code:"invalid";
+    super(messages[safe]);this.name="SharedWriterRevisionError";this.code=safe;if(safe==="cap")this.remaining=0;
+  }
+}
+function fail(code:SharedWriterRevisionErrorCode="invalid"):never {throw new SharedWriterRevisionError(code);}
+function safe<T>(run:()=>T):T {try{return run();}catch(error){
+  if(error&&typeof error==="object"&&!types.isProxy(error)&&error instanceof SharedWriterRevisionError){
+    const code=Object.getOwnPropertyDescriptor(error,"code");if(code&&"value"in code&&typeof code.value==="string"&&Object.hasOwn(messages,code.value))fail(code.value as SharedWriterRevisionErrorCode);
+  }return fail();
+}}
+function object(input:unknown,keys:readonly string[]):Record<string,unknown>{
+  if(!input||typeof input!=="object"||types.isProxy(input)||Array.isArray(input)||![Object.prototype,null].includes(Object.getPrototypeOf(input))||Object.getOwnPropertySymbols(input).length)fail();
+  if(Object.getOwnPropertyNames(input).length!==keys.length)fail();const out:Record<string,unknown>=Object.create(null);
+  for(const key of keys){const field=Object.getOwnPropertyDescriptor(input,key);if(!field||!("value"in field)||!field.enumerable)fail();out[key]=field.value;}return out;
+}
+function array(input:unknown,maximum:number):unknown[]{
+  if(!input||typeof input!=="object"||types.isProxy(input)||!Array.isArray(input)||Object.getPrototypeOf(input)!==Array.prototype||Object.getOwnPropertySymbols(input).length)fail();
+  const length=Object.getOwnPropertyDescriptor(input,"length")?.value;
+  if(!Number.isSafeInteger(length)||length<1||length>maximum)fail("bound");
+  if(Object.getOwnPropertyNames(input).length!==length+1)fail();const out:unknown[]=[];
+  for(let i=0;i<length;i++){const field=Object.getOwnPropertyDescriptor(input,String(i));if(!field||!("value"in field)||!field.enumerable)fail();out.push(field.value);}return out;
+}
+function hex(input:unknown,width=64):string {if(typeof input!=="string"||input.length!==width||!/^[a-f0-9]+$/.test(input))fail();return input;}
+function integer(input:unknown,minimum:number,maximum:number):number {if(typeof input!=="number"||!Number.isSafeInteger(input)||input<minimum||input>maximum)fail();return input;}
+function sequence(input:unknown):number {if(typeof input==="number"&&Number.isSafeInteger(input)&&input>WRITER_REVISION_LIMIT)fail("cap");return integer(input,1,WRITER_REVISION_LIMIT);}
+function path(input:unknown):string {if(typeof input!=="string"||!isAbsolute(input)||resolve(input)!==input||input.includes("\0"))fail();if(Buffer.byteLength(input)>4096)fail("bound");return input;}
+function version(input:unknown):string {
+  if(typeof input!=="string"||input.length>64)fail();const match=/^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.exec(input);
+  if(!match||match[0]!==input)fail();const parts=match.slice(1).map(Number);
+  if(!parts.every(Number.isSafeInteger)||parts[0]===0&&parts[1]!<22)fail();return input;
+}
+function bounded(value:unknown,maximum:number):void {if(Buffer.byteLength(canonicalJSON(value)+"\n")>maximum)fail("bound");}
+function roots(input:unknown):MeasuredSyncPlacementWriterRoot[]{
+  const out:MeasuredSyncPlacementWriterRoot[]=[],ids=new Set<string>();let previous="";
+  for(const entry of array(input,256)){
+    const value=object(entry,["root","writerId","version","pin"]),root=path(value.root),writerId=hex(value.writerId);
+    if(root<=previous||ids.has(writerId)||writerId!==syncPlacementWriterId(root))fail();
+    out.push({root,writerId,version:version(value.version),pin:hex(value.pin)});ids.add(writerId);previous=root;
+  }return out;
+}
+export function writerRevisionFile(value:number):string {return `writer-revision-${String(sequence(value)).padStart(5,"0")}.json`;}
+export function writerHistoryFileLimit(name:string):number|undefined {
+  if(name===WRITER_COMMIT_LOG)return WRITER_COMMIT_MAX_BYTES;
+  if(typeof name!=="string")return;const match=/^writer-revision-([0-9]{5})\.json$/.exec(name);
+  if(!match||match[0]!==name)return;const n=Number(match[1]);return n>=1&&n<=WRITER_REVISION_LIMIT?WRITER_REVISION_MAX_BYTES:undefined;
+}
+export function writerInventoryGenesis(epochHash:string,activationHash:string):string {
+  return hashJSON(["agent-mem.sync-placement-writer-genesis/v1",hex(epochHash),hex(activationHash)]);
+}
+export interface WriterRevisionBody {
+  schema:typeof WRITER_REVISION_SCHEMA;epochHash:string;generation:string;homeHash:string;activationHash:string;initialLocatorHash:string;
+  sequence:number;previousHash:string;journal:{sequence:number;headHash:string};roots:MeasuredSyncPlacementWriterRoot[];requestId:string;
+}
+export interface WriterRevision extends WriterRevisionBody {seal:string}
+export interface WriterCommitBody {schema:typeof WRITER_COMMIT_SCHEMA;epochHash:string;sequence:number;previousHash:string;revisionHash:string}
+export interface WriterCommit extends WriterCommitBody {seal:string}
+export interface WriterRenewalIntentBody {schema:typeof WRITER_RENEWAL_INTENT_SCHEMA;home:string;revision:WriterRevision;commit:WriterCommit;previousLogBytes:number;previousLogHash:string}
+export interface WriterRenewalIntent extends WriterRenewalIntentBody {seal:string}
+function revision(input:unknown,sealed:boolean):WriterRevision {
+  const v=object(input,["schema","epochHash","generation","homeHash","activationHash","initialLocatorHash","sequence","previousHash","journal","roots","requestId",...(sealed?["seal"]:[])]);
+  if(v.schema!==WRITER_REVISION_SCHEMA)fail();const journal=object(v.journal,["sequence","headHash"]);
+  const body:WriterRevisionBody={schema:WRITER_REVISION_SCHEMA,epochHash:hex(v.epochHash),generation:hex(v.generation,32),homeHash:hex(v.homeHash),activationHash:hex(v.activationHash),
+    initialLocatorHash:hex(v.initialLocatorHash),sequence:sequence(v.sequence),previousHash:hex(v.previousHash),journal:{sequence:integer(journal.sequence,0,20000),headHash:hex(journal.headHash)},roots:roots(v.roots),requestId:hex(v.requestId)};
+  if(body.sequence===1&&body.previousHash!==writerInventoryGenesis(body.epochHash,body.activationHash))fail();
+  const value={...body,seal:hashJSON(body)};if(sealed&&hex(v.seal)!==value.seal)fail();bounded(value,WRITER_REVISION_MAX_BYTES);return value;
+}
+export function createWriterRevision(body:WriterRevisionBody):WriterRevision {return safe(()=>revision(body,false));}
+export function validateWriterRevision(value:unknown):WriterRevision {return safe(()=>revision(value,true));}
+export function writerRevisionWriters(input:WriterRevision):SyncPlacementWriterAttestation[]{
+  return validateWriterRevision(input).roots.map<SyncPlacementWriterAttestation>(({writerId,version,pin})=>({writerId,version,pin,publicationFormat:PLACEMENT_FORMAT,compatible:true as const})).sort((a,b)=>a.writerId.localeCompare(b.writerId));
+}
+function commit(input:unknown,sealed:boolean):WriterCommit {
+  const v=object(input,["schema","epochHash","sequence","previousHash","revisionHash",...(sealed?["seal"]:[])]);if(v.schema!==WRITER_COMMIT_SCHEMA)fail();
+  const body:WriterCommitBody={schema:WRITER_COMMIT_SCHEMA,epochHash:hex(v.epochHash),sequence:sequence(v.sequence),previousHash:hex(v.previousHash),revisionHash:hex(v.revisionHash)};
+  const value={...body,seal:hashJSON(body)};if(sealed&&hex(v.seal)!==value.seal)fail();bounded(value,WRITER_COMMIT_MAX_BYTES);return value;
+}
+export function createWriterCommit(input:WriterRevision):WriterCommit {
+  const rev=validateWriterRevision(input);return safe(()=>commit({schema:WRITER_COMMIT_SCHEMA,epochHash:rev.epochHash,sequence:rev.sequence,previousHash:rev.previousHash,revisionHash:rev.seal},false));
+}
+export function validateWriterCommit(value:unknown):WriterCommit {return safe(()=>commit(value,true));}
+function intent(input:unknown,sealed:boolean):WriterRenewalIntent {
+  const v=object(input,["schema","home","revision","commit","previousLogBytes","previousLogHash",...(sealed?["seal"]:[])]);if(v.schema!==WRITER_RENEWAL_INTENT_SCHEMA)fail();
+  const rev=validateWriterRevision(v.revision),ack=validateWriterCommit(v.commit),previousLogBytes=integer(v.previousLogBytes,0,WRITER_COMMIT_MAX_BYTES),previousLogHash=hex(v.previousLogHash);
+  if(ack.epochHash!==rev.epochHash||ack.sequence!==rev.sequence||ack.previousHash!==rev.previousHash||ack.revisionHash!==rev.seal)fail();
+  if(rev.sequence===1&&(previousLogBytes!==0||previousLogHash!==createHash("sha256").update("").digest("hex")))fail();
+  const body:WriterRenewalIntentBody={schema:WRITER_RENEWAL_INTENT_SCHEMA,home:path(v.home),revision:rev,commit:ack,previousLogBytes,previousLogHash};
+  const value={...body,seal:hashJSON(body)};if(sealed&&hex(v.seal)!==value.seal)fail();bounded(value,WRITER_RENEWAL_INTENT_MAX_BYTES);return value;
+}
+export function createWriterRenewalIntent(body:WriterRenewalIntentBody):WriterRenewalIntent {return safe(()=>intent(body,false));}
+export function validateWriterRenewalIntent(value:unknown):WriterRenewalIntent {return safe(()=>intent(value,true));}