@staix/agent-mem 0.21.0 → 0.22.1

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

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

@@ -0,0 +1,167 @@
+/** Immutable initial install locator only. Returned paths are never fresh compatibility or quiescence evidence. */
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, type BigIntStats } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { types } from "node:util";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { memoryPolicySnapshot } from "./policy.ts";
+import { realPath } from "./platform.ts";
+import { assertMutationHandle, type MutationHandle } from "./mutation.ts";
+import { readPlacementRuntimeMarkers } from "./sync-placement-guard.ts";
+import { readActivePlacementBinding } from "./sync-placement-active.ts";
+import { readPlacementJournal } from "./sync-placement-journal-storage.ts";
+import { writeImmutableActivationMetadata } from "./public-prune-activation.ts";
+import { measureSyncPlacementWriters, SyncPlacementWriterError, 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 SYNC_PLACEMENT_WRITER_ROOTS_FILE="sync-placement-writer-roots.json";
+export const SYNC_PLACEMENT_WRITER_ROOTS_SCHEMA="agent-mem.sync-placement-writer-roots/v1";
+interface LocatorBody {
+  schema:typeof SYNC_PLACEMENT_WRITER_ROOTS_SCHEMA;homeHash:string;epochHash:string;activationHash:string;
+  roots:{root:string;writerId:string}[];
+}
+export interface InitialSyncPlacementWriterLocator extends LocatorBody {seal:string}
+type Locator=InitialSyncPlacementWriterLocator;
+const MAX_BYTES=256*1024,MAX_ROOTS=256,MAX_PATH=4096;
+const hash=(text:string)=>createHash("sha256").update(text).digest("hex");
+const hex=(value:unknown):value is string=>typeof value==="string"&&value.length===64&&/^[a-f0-9]+$/.test(value);
+const stamp=(s:BigIntStats)=>[s.dev,s.ino,s.mode,s.uid,s.nlink,s.size,s.mtimeNs,s.ctimeNs].map(String).join(":");
+function fail():never {throw new SyncPlacementWriterError("unavailable");}
+function protectedCall<T>(work:()=>T):T {try{return work();}catch(error){
+  if(error&&typeof error==="object"&&!types.isProxy(error)&&error instanceof SyncPlacementWriterError){const code=Object.getOwnPropertyDescriptor(error,"code");if(code&&"value"in code&&code.value==="bound")throw new SyncPlacementWriterError("bound");}
+  return fail();
+}}
+function directory(home:string):BigIntStats {
+  const s=lstatSync(home,{bigint:true});
+  if(!s.isDirectory()||s.isSymbolicLink()||s.uid!==BigInt(process.getuid?.()??-1)||(s.mode&0o777n)!==0o700n)fail();return s;
+}
+function fileState(file:string):BigIntStats {
+  const s=lstatSync(file,{bigint:true});
+  if(!s.isFile()||s.isSymbolicLink()||s.uid!==BigInt(process.getuid?.()??-1)||(s.mode&0o777n)!==0o600n
+    ||s.nlink!==1n&&s.nlink!==2n||s.size<1n||s.size>BigInt(MAX_BYTES))fail();return s;
+}
+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();
+  const fields=Object.getOwnPropertyDescriptors(input);if(Object.keys(fields).sort().join()!==[...keys].sort().join())fail();
+  const out:Record<string,unknown>=Object.create(null);
+  for(const key of keys){const field=fields[key];if(!field||!("value"in field)||!field.enumerable)fail();out[key]=field.value;}return out;
+}
+function array(input:unknown):unknown[] {
+  if(!input||typeof input!=="object"||types.isProxy(input)||!Array.isArray(input)||Object.getPrototypeOf(input)!==Array.prototype||Object.getOwnPropertySymbols(input).length)fail();
+  const fields=Object.getOwnPropertyDescriptors(input),length=Object.getOwnPropertyDescriptor(input,"length")?.value;
+  if(!Number.isSafeInteger(length)||length<1||length>MAX_ROOTS||Object.keys(fields).length!==length+1)fail();
+  const out:unknown[]=[];for(let i=0;i<length;i++){const field=fields[String(i)];if(!field||!("value"in field)||!field.enumerable)fail();out.push(field.value);}return out;
+}
+function validate(input:unknown):Locator {
+  const value=object(input,["schema","homeHash","epochHash","activationHash","roots","seal"]);
+  if(value.schema!==SYNC_PLACEMENT_WRITER_ROOTS_SCHEMA||!hex(value.homeHash)||!hex(value.epochHash)||!hex(value.activationHash)||!hex(value.seal)
+    )fail();
+  const roots:{root:string;writerId:string}[]=[],ids=new Set<string>();let prior="";
+  for(const entry of array(value.roots)){
+    const item=object(entry,["root","writerId"]);
+    if(typeof item.root!=="string"||!isAbsolute(item.root)||resolve(item.root)!==item.root||Buffer.byteLength(item.root)>MAX_PATH||item.root.includes("\0")
+      ||item.root<=prior||!hex(item.writerId)||ids.has(item.writerId))fail();
+    roots.push({root:item.root,writerId:item.writerId});prior=item.root;ids.add(item.writerId);
+  }
+  const body:LocatorBody={schema:SYNC_PLACEMENT_WRITER_ROOTS_SCHEMA,homeHash:value.homeHash,epochHash:value.epochHash,activationHash:value.activationHash,roots};
+  if(hashJSON(body)!==value.seal)fail();
+  if(Buffer.byteLength(canonicalJSON(value)+"\n")>MAX_BYTES)throw new SyncPlacementWriterError("bound");
+  return{...body,seal:value.seal};
+}
+function idSet(writers:readonly SyncPlacementWriterAttestation[]):string[] {
+  const copy=memoryPolicySnapshot(writers);if(!Array.isArray(copy)||copy.length<1||copy.length>MAX_ROOTS)fail();
+  const ids=copy.map(writer=>{if(!writer||typeof writer!=="object"||!hex(writer.writerId))fail();return writer.writerId;}).sort();
+  if(new Set(ids).size!==ids.length)fail();return ids;
+}
+function bind(value:Locator,expected:{homeHash:string;epochHash:string;activationHash:string},writers:readonly SyncPlacementWriterAttestation[]):void {
+  if(value.homeHash!==expected.homeHash||value.epochHash!==expected.epochHash||value.activationHash!==expected.activationHash
+    ||canonicalJSON(value.roots.map(root=>root.writerId).sort())!==canonicalJSON(idSet(writers)))fail();
+}
+function readOwned(file:string):{text:string;check():void} {
+  const before=fileState(file),fd=openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
+  try{
+    if(stamp(fstatSync(fd,{bigint:true}))!==stamp(before))fail();
+    const data=Buffer.alloc(Number(before.size)+1);let at=0;
+    while(at<data.length){const count=readSync(fd,data,at,data.length-at,at);if(!count)break;at+=count;}
+    if(at!==Number(before.size)||stamp(fstatSync(fd,{bigint:true}))!==stamp(before)||stamp(fileState(file))!==stamp(before))fail();
+    const text=new TextDecoder("utf-8",{fatal:true}).decode(data.subarray(0,at)),companion=`${file}.pending-${hash(text)}`;
+    const paired=lstatSync(companion,{bigint:true,throwIfNoEntry:false});
+    if(before.nlink===2n){const peer=fileState(companion);if(peer.dev!==before.dev||peer.ino!==before.ino||stamp(peer)!==stamp(before))fail();}
+    else if(paired)fail();
+    return{text,check(){if(stamp(fileState(file))!==stamp(before))fail();
+      const now=lstatSync(companion,{bigint:true,throwIfNoEntry:false});
+      if(paired? !now||stamp(fileState(companion))!==stamp(paired):!!now)fail();}};
+  }finally{closeSync(fd);}
+}
+export interface SyncPlacementWriterRootsInput {epochHash:string;homeHash:string;activationHash:string;roots:readonly MeasuredSyncPlacementWriterRoot[]}
+export interface SyncPlacementWriterRootsBinding {homeHash:string;epochHash:string;activationHash:string;writers:readonly SyncPlacementWriterAttestation[]}
+function copiedInput(input:SyncPlacementWriterRootsInput) {
+  const copied=object(input,["epochHash","homeHash","activationHash","roots"]);
+  if(!hex(copied.epochHash)||!hex(copied.homeHash)||!hex(copied.activationHash))fail();
+  const roots=array(copied.roots).map(value=>{
+    const root=object(value,["root","writerId","version","pin"]);
+    if(typeof root.root!=="string"||typeof root.version!=="string"||!hex(root.writerId)||!hex(root.pin))fail();
+    return{root:root.root,writerId:root.writerId,version:root.version,pin:root.pin};
+  }).sort((a,b)=>a.root<b.root?-1:a.root>b.root?1:0);
+  return{homeHash:copied.homeHash,epochHash:copied.epochHash,activationHash:copied.activationHash,roots};
+}
+/** Pure initial-locator data plan. It proves framing/binding/bounds only, never fresh install bytes or permission. */
+export function planSyncPlacementWriterRoots(input:SyncPlacementWriterRootsInput,binding:SyncPlacementWriterRootsBinding):Locator {
+  return protectedCall(()=>{
+    const copied=copiedInput(input),expected=object(binding,["homeHash","epochHash","activationHash","writers"]);
+    if(!hex(expected.homeHash)||!hex(expected.epochHash)||!hex(expected.activationHash))fail();
+    const writers=memoryPolicySnapshot(expected.writers) as readonly SyncPlacementWriterAttestation[]|undefined;if(!writers)fail();idSet(writers);
+    const proposed=copied.roots.map(({writerId,version,pin})=>({writerId,version,pin,publicationFormat:PLACEMENT_FORMAT,compatible:true})).sort((a,b)=>a.writerId.localeCompare(b.writerId));
+    if(canonicalJSON(proposed)!==canonicalJSON([...writers].sort((a,b)=>a.writerId.localeCompare(b.writerId))))fail();
+    const body:LocatorBody={schema:SYNC_PLACEMENT_WRITER_ROOTS_SCHEMA,homeHash:copied.homeHash,epochHash:copied.epochHash,activationHash:copied.activationHash,
+      roots:copied.roots.map(({root,writerId})=>({root,writerId}))};
+    const value=validate({...body,seal:hashJSON(body)});
+    bind(value,{homeHash:expected.homeHash,epochHash:expected.epochHash,activationHash:expected.activationHash},writers);return value;
+  });
+}
+export interface SyncPlacementWriterRootsWriteOptions {mutation:MutationHandle;assertCurrent():void}
+/** Called only under activation's live fences. Initial bytes are immutable; renewal belongs to its own reviewed protocol. */
+export function writeSyncPlacementWriterRoots(homeInput:string,input:SyncPlacementWriterRootsInput,expectedWriters:readonly SyncPlacementWriterAttestation[],options:SyncPlacementWriterRootsWriteOptions):void {
+  protectedCall(()=>{
+    const home=realPath(homeInput),before=directory(home);assertMutationHandle(options.mutation,home);options.assertCurrent();
+    const copied=copiedInput(input),roots=copied.roots;
+    const measured=measureSyncPlacementWriters(roots.map(root=>root.root));
+    if(canonicalJSON(measured.roots)!==canonicalJSON(roots.sort((a,b)=>a.root<b.root?-1:a.root>b.root?1:0)))fail();
+    const journal=readPlacementJournal(home,copied.epochHash),expected=memoryPolicySnapshot(expectedWriters);
+    if(!expected||!Array.isArray(expected))fail();idSet(expected);
+    const sorted=(writers:readonly SyncPlacementWriterAttestation[])=>[...writers].sort((a,b)=>a.writerId.localeCompare(b.writerId));
+    if(canonicalJSON(sorted(measured.writers))!==canonicalJSON(sorted(expected))||canonicalJSON(sorted(measured.writers))!==canonicalJSON(sorted(journal.activation.writers)))fail();
+    const value=planSyncPlacementWriterRoots({...copied,roots:measured.roots},{homeHash:journal.epoch.homeHash,epochHash:hashJSON(journal.epoch),activationHash:journal.activation.seal,writers:journal.activation.writers});
+    if(canonicalJSON(idSet(expected))!==canonicalJSON(idSet(journal.activation.writers)))fail();
+    assertMutationHandle(options.mutation,home);options.assertCurrent();
+    const file=join(home,SYNC_PLACEMENT_WRITER_ROOTS_FILE),text=canonicalJSON(value)+"\n";
+    const existing=lstatSync(file,{throwIfNoEntry:false});if(existing){const read=readOwned(file);if(read.text!==text)fail();read.check();}
+    // The shared writer reads a crash-left orphan before its own content check. Bound that read here,
+    // after the final caller proof; only its exact deterministic staging name can be resumed.
+    const staging=lstatSync(`${file}.pending-${hash(text)}`,{bigint:true,throwIfNoEntry:false});
+    if(staging){
+      if(!staging.isFile()||staging.isSymbolicLink()||staging.uid!==BigInt(process.getuid?.()??-1)||(staging.mode&0o777n)!==0o600n||staging.size>BigInt(MAX_BYTES))fail();
+      if(existing){const final=fileState(file);if(final.nlink!==2n||staging.nlink!==2n||stamp(staging)!==stamp(final))fail();}
+      else if(staging.nlink!==1n)fail();
+    }
+    writeImmutableActivationMetadata(file,text);
+    assertMutationHandle(options.mutation,home);options.assertCurrent();
+    const after=directory(home);if(after.dev!==before.dev||after.ino!==before.ino)fail();
+    const read=readOwned(file);if(read.text!==text)fail();read.check();
+  });
+}
+/** Returns only initial locator paths; the caller must independently remeasure their actual bytes at each attestation. */
+export function readInitialSyncPlacementWriterLocator(homeInput:string):InitialSyncPlacementWriterLocator {
+  return protectedCall(()=>{
+    const home=realPath(homeInput),before=directory(home);
+    const active=()=>{const markers=readPlacementRuntimeMarkers(home),value=readActivePlacementBinding(home,markers.profile,markers.shards);if(!value)fail();return value;};
+    const initial=active(),read=readOwned(join(home,SYNC_PLACEMENT_WRITER_ROOTS_FILE)),value=validate(JSON.parse(read.text));
+    if(canonicalJSON(value)+"\n"!==read.text)fail();
+    bind(value,{homeHash:initial.epoch.homeHash,epochHash:initial.profile.placementHead,activationHash:initial.activation.seal},initial.activation.writers);
+    const final=active();if(canonicalJSON(final)!==canonicalJSON(initial))fail();
+    const after=directory(home);if(after.dev!==before.dev||after.ino!==before.ino)fail();read.check();
+    return value;
+  });
+}
+export function readSyncPlacementWriterRoots(homeInput:string):string[]{return readInitialSyncPlacementWriterLocator(homeInput).roots.map(root=>root.root);}

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

@@ -0,0 +1,135 @@
+/** Read-only install measurement. Pins are exact-byte facts, not person authority or host quiescence. */
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, opendirSync, readSync, type BigIntStats } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { types } from "node:util";
+import { hashJSON } from "./generation.ts";
+import { realPath } from "./platform.ts";
+import { PLACEMENT_FORMAT } from "./sync-placement-format.ts";
+import type { SyncPlacementWriterAttestation } from "./sync-placement-plan.ts";
+
+export interface MeasuredSyncPlacementWriterRoot { root: string; writerId: string; version: string; pin: string }
+export interface SyncPlacementWriterMeasurement { roots: MeasuredSyncPlacementWriterRoot[]; writers: SyncPlacementWriterAttestation[] }
+export type SyncPlacementWriterErrorCode = "invalid" | "unavailable" | "unsupported" | "bound" | "changed";
+const causes: Record<SyncPlacementWriterErrorCode,string> = {
+  invalid:"invalid or duplicate writer-root inventory",unavailable:"unreadable or unsafe writer-root runtime files",
+  unsupported:"unsupported writer-root package identity or release",bound:"writer-root inventory exceeds its supported bound",changed:"writer-root changed during measurement",
+};
+export type SyncPlacementWriterFailureDetail = "below-minimum" | "wrong-package" | "writable-runtime" | "unreadable" | "invalid-version" | "invalid-inventory" | "unsafe-runtime" | "missing-runtime" | "bound" | "changed";
+const details:Record<SyncPlacementWriterFailureDetail,string>={
+  "below-minimum":"release is below 0.21.0", "wrong-package":"package is not @staix/agent-mem", "writable-runtime":"runtime code is group- or world-writable",
+  unreadable:"runtime files are unreadable or missing", "invalid-version":"package version is not a supported plain release", "invalid-inventory":"root inventory is invalid or duplicated",
+  "unsafe-runtime":"runtime files have unsafe types or symlinks", "missing-runtime":"required bin/amem.js or src/index.ts is missing",bound:"inventory exceeds a supported bound",changed:"install changed during measurement",
+};
+export class SyncPlacementWriterError extends Error {
+  constructor(readonly code: SyncPlacementWriterErrorCode, readonly rootIndex?: number, readonly detail:SyncPlacementWriterFailureDetail=code==="unsupported"?"invalid-version":code==="invalid"?"invalid-inventory":code==="bound"?"bound":code==="changed"?"changed":"unreadable") {
+    super(`Sync placement ${causes[code]} (${details[detail]}); upgrade or repair the amem install and its host exact pin, then rerun amem migrate --sync-placement --dry-run. For a managed writer, rerun amem setup <target> --apply after upgrading.`);
+    this.name="SyncPlacementWriterError";
+  }
+}
+/** Closed own data only: external error messages, accessors and proxies are never diagnostic authority. */
+export function extractSyncPlacementWriterFailure(error:unknown):{code:SyncPlacementWriterErrorCode;detail:SyncPlacementWriterFailureDetail;rootIndex?:number}|undefined {
+  try{
+    if(!error||typeof error!=="object"||types.isProxy(error)||!(error instanceof SyncPlacementWriterError))return;
+    const fields=Object.getOwnPropertyDescriptors(error),code=fields.code?.value,detail=fields.detail?.value,index=fields.rootIndex;
+    if(typeof code!=="string"||!Object.hasOwn(causes,code)||typeof detail!=="string"||!Object.hasOwn(details,detail)
+      ||index&&!("value"in index))return;
+    const rootIndex=index?.value;if(rootIndex!==undefined&&(!Number.isSafeInteger(rootIndex)||rootIndex<0||rootIndex>=256))return;
+    return{code:code as SyncPlacementWriterErrorCode,detail:detail as SyncPlacementWriterFailureDetail,...(rootIndex===undefined?{}:{rootIndex})};
+  }catch{return;}
+}
+const MAX_ROOTS=256,MAX_FILES=4096,MAX_BYTES=64*1024*1024,MAX_PACKAGE=64*1024,MAX_PATH=4096,MAX_NODES=8192;
+// ponytail: namespace traversal also caps 8192 entries and depth64; larger installs need a reviewed chunked inventory.
+const RUNTIME=["src","bin","hooks",".claude-plugin"] as const;
+const stamp=(s:BigIntStats)=>[s.dev,s.ino,s.mode,s.uid,s.gid,s.nlink,s.size,s.mtimeNs,s.ctimeNs].map(String).join(":");
+const digest=(bytes:Uint8Array)=>createHash("sha256").update(bytes).digest("hex");
+
+/** Internal frozen-locator identity; callers validate canonical paths before treating it as a writer key. */
+export function syncPlacementWriterId(root:string):string {return hashJSON(["agent-mem.sync-placement-writer/v1",root]);}
+
+export function measureSyncPlacementWriters(input:readonly string[]):SyncPlacementWriterMeasurement {
+  let index:number|undefined;
+  function fail(code:SyncPlacementWriterErrorCode,detail?:SyncPlacementWriterFailureDetail):never {throw new SyncPlacementWriterError(code,index,detail);}
+  if(!input||typeof input!=="object"||types.isProxy(input)||!Array.isArray(input)||Object.getPrototypeOf(input)!==Array.prototype
+    ||input.length<1||Object.getOwnPropertySymbols(input).length)fail("invalid");
+  if(input.length>MAX_ROOTS)fail("bound");
+  const fields=Object.getOwnPropertyDescriptors(input);
+  if(Object.keys(fields).length!==input.length+1)fail("invalid");
+  const requested:string[]=[],seen=new Set<string>(),checks:(()=>void)[]=[],namespaces:(()=>void)[]=[],measured:MeasuredSyncPlacementWriterRoot[]=[];
+  let files=0,bytes=0,nodes=0;
+  const rememberCheck=(check:()=>void)=>{const rootIndex=index;checks.push(()=>{index=rootIndex;check();});};
+  try {
+    const node=(file:string,directory:boolean):BigIntStats=>{
+      const s=lstatSync(file,{bigint:true});
+      // Public installs may be readable by everyone and share Bun's hardlinked cache. Writeable code is unsafe.
+      if(s.isSymbolicLink()||(directory?!s.isDirectory():!s.isFile()))fail("unavailable","unsafe-runtime");
+      if((s.mode&0o022n)!==0n)fail("unavailable","writable-runtime");
+      return s;
+    };
+    for(index=0;index<input.length;index++){
+      const field=fields[String(index)];if(!field||!("value"in field)||!field.enumerable)fail("invalid");
+      const value:unknown=field.value;
+      if(typeof value!=="string"||!isAbsolute(value)||Buffer.byteLength(value)>MAX_PATH||value.includes("\0"))fail("invalid");
+      requested.push(value);
+    }
+    for(index=0;index<requested.length;index++){
+      const requestedRoot=requested[index]!,root=realPath(requestedRoot);
+      if(Buffer.byteLength(root)>MAX_PATH||seen.has(root))fail("invalid");seen.add(root);
+      const rootStat=node(root,true),inventory:[string,string][]=[];
+      rememberCheck(()=>{if(realPath(requestedRoot)!==root||stamp(node(root,true))!==stamp(rootStat))fail("changed");});
+      const remember=(file:string,before:BigIntStats,directory:boolean)=>rememberCheck(()=>{if(stamp(node(file,directory))!==stamp(before))fail("changed");});
+      const path=(relative:string)=>{if(Buffer.byteLength(relative)>MAX_PATH||Buffer.byteLength(join(root,relative))>MAX_PATH)fail("bound");return join(root,relative);};
+      const read=(relative:string,maximum:number):Buffer=>{
+        const file=path(relative),before=node(file,false);
+        if(++files>MAX_FILES||before.size>BigInt(maximum)||before.size>BigInt(MAX_BYTES-bytes))fail("bound");
+        const fd=openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
+        try{
+          if(stamp(fstatSync(fd,{bigint:true}))!==stamp(before))fail("changed");
+          const data=Buffer.alloc(Number(before.size));let at=0;
+          while(at<data.length){const count=readSync(fd,data,at,data.length-at,at);if(count<=0)fail("changed");at+=count;}
+          if(stamp(fstatSync(fd,{bigint:true}))!==stamp(before)||stamp(node(file,false))!==stamp(before))fail("changed");
+          bytes+=data.length;inventory.push([relative,digest(data)]);remember(file,before,false);return data;
+        }finally{closeSync(fd);}
+      };
+      const visit=(relative:string,depth=0)=>{
+        if(depth>64)fail("bound");
+        const file=path(relative),before=node(file,true),names:string[]=[];remember(file,before,true);
+        const dir=opendirSync(file);
+        try{for(;;){const entry=dir.readSync();if(!entry)break;if(++nodes>MAX_NODES)fail("bound");names.push(entry.name);}}finally{dir.closeSync();}
+        if(stamp(node(file,true))!==stamp(before))fail("changed");
+        const rootIndex=index;
+        namespaces.push(()=>{
+          index=rootIndex;const current:string[]=[],reader=opendirSync(file);
+          try{for(;;){const entry=reader.readSync();if(!entry)break;if(current.length>=names.length)fail("changed");current.push(entry.name);}}finally{reader.closeSync();}
+          if(JSON.stringify(current.sort())!==JSON.stringify(names))fail("changed");
+        });
+        for(const name of names.sort()){
+          const child=`${relative}/${name}`,s=lstatSync(path(child),{bigint:true});
+          if(s.isSymbolicLink())fail("unavailable","unsafe-runtime");
+          if(s.isDirectory())visit(child,depth+1);else read(child,MAX_BYTES);
+        }
+      };
+      const packageBytes=read("package.json",MAX_PACKAGE);let pkg:unknown;
+      try{pkg=JSON.parse(new TextDecoder("utf-8",{fatal:true}).decode(packageBytes));}catch(error){if(error&&typeof error==="object"&&!types.isProxy(error)&&error instanceof SyncPlacementWriterError)throw error;fail("unsupported");}
+      const version=pkg&&typeof pkg==="object"&&!Array.isArray(pkg)?Object.getOwnPropertyDescriptor(pkg,"version")?.value:undefined;
+      const name=pkg&&typeof pkg==="object"?Object.getOwnPropertyDescriptor(pkg,"name")?.value:undefined;
+      const match=typeof version==="string"&&version.length<=64?/^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.exec(version):null;
+      if(name!=="@staix/agent-mem")fail("unsupported","wrong-package");
+      if(!match||match[0]!==version)fail("unsupported","invalid-version");
+      const parts=match.slice(1).map(Number);if(!parts.every(Number.isSafeInteger))fail("unsupported","invalid-version");
+      if(parts[0]===0&&parts[1]!<21)fail("unsupported","below-minimum");
+      for(const relative of RUNTIME){
+        const file=path(relative),s=lstatSync(file,{bigint:true,throwIfNoEntry:false});
+        if(s)visit(relative);else rememberCheck(()=>{if(lstatSync(file,{throwIfNoEntry:false}))fail("changed");});
+      }
+      if(!inventory.some(([file])=>file==="bin/amem.js")||!inventory.some(([file])=>file==="src/index.ts"))fail("unsupported","missing-runtime");
+      inventory.sort(([a],[b])=>a<b?-1:a>b?1:0);
+      measured.push({root,writerId:syncPlacementWriterId(root),version:version as string,pin:hashJSON(inventory)});
+    }
+    for(const check of checks)check();
+    for(const check of namespaces)check();
+    measured.sort((a,b)=>a.root<b.root?-1:a.root>b.root?1:0);
+    const writers=measured.map<SyncPlacementWriterAttestation>(({writerId,version,pin})=>({writerId,version,pin,publicationFormat:PLACEMENT_FORMAT,compatible:true})).sort((a,b)=>a.writerId.localeCompare(b.writerId));
+    return{roots:measured,writers};
+  }catch(error){if(error&&typeof error==="object"&&!types.isProxy(error)&&error instanceof SyncPlacementWriterError)throw error;return fail("unavailable");}
+}

package/src/memory/sync.ts

@@ -1,4 +1,3 @@
-import { syncPlacementMemory } from "./sync-placement-transport.ts";
 import type { PlacementCapturePort } from "./sync-placement-capture.ts";
 import { placementRuntimeRefusal } from "./sync-placement-guard.ts";
 import { assertFormatFloor } from "./formats.ts";
@@ -238,7 +237,7 @@ export async function syncMemory(store: MemoryStore, opts: SyncOptions = {}): Pr
   assertFormatFloor(store.profile.home, "sync");
   const placementRefusal = placementRuntimeRefusal(store.profile.home, store.profile);
   if (placementRefusal) return { ok: false, pushed: false, entries: 0, error: placementRefusal };
-  if (store.profile.publicationFormat === "agent-mem.sync-placement/v1") return syncPlacementMemory(store, opts);
+  if (store.profile.publicationFormat === "agent-mem.sync-placement/v1") return (await import("./sync-placement-transport.ts")).syncPlacementMemory(store, opts);
   if (store.profile.sharded) {
     try {
       // Refresh only through the existing proved monotone profile rebind before pinning this attempt.

package/src/setup-toml.ts

@@ -37,7 +37,7 @@ function inline(value: unknown): string {
   // Bun emits scalars and many arrays as one assignment. Reuse that literal when it is safe in this scope.
   // Objects/AOTs may become headers; those need the inline form below to avoid changing subsequent table scope.
   let rendered = "";
-  try { rendered = Bun.TOML.stringify({ setup_value: value }); } catch { /* The validated inline encoder covers values the built-in writer cannot emit. */ }
+  try { rendered = Bun.TOML.stringify({ setup_value: value }) ?? ""; } catch { /* The validated inline encoder covers values the built-in writer cannot emit. */ }
   const literal = /^setup_value\s*=\s*([^\r\n]*)\r?\n?$/.exec(rendered)?.[1];
   if (literal !== undefined && isDeepStrictEqual(shape(parse(rendered).setup_value), shape(value))) return literal;
   const encode = (part: unknown): string => {
@@ -255,7 +255,8 @@ function arrayEdit(before: readonly unknown[], after: readonly unknown[]): { kee
 function appendedTables(path: readonly string[], values: readonly unknown[], eol: string): string {
   if (!values.every(plain)) return error();
   const document: Record<string, unknown> = {}; edit(document, path, [...values]);
-  let source: string; try { source = Bun.TOML.stringify(document); } catch { return error(); }
+  let source: string | undefined; try { source = Bun.TOML.stringify(document); } catch { return error(); }
+  if (source === undefined) return error();
   const sourceUnits = statements(source), rows = sourceUnits.filter(unit => prefix(path, unit.path));
   if (rows.filter(unit => unit.header && unit.array && unit.path.length === path.length).length !== values.length) return error();
   return rows.map(unit => source.slice(unit.start, unit.end)).join("").replace(/\r?\n/g, eol);