@staix/agent-mem 0.20.3 → 0.22.0

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-policy-inspection.ts

@@ -0,0 +1,126 @@
+import { createHash } from "node:crypto";
+import { lstatSync } from "node:fs";
+import { types } from "node:util";
+import { join } from "node:path";
+import { SegmentReadBudgetError } from "./bridge.ts";
+import { DENY_NAMES, DENY_SEGMENTS } from "./platform.ts";
+import { memoryPolicySnapshot } from "./policy.ts";
+import { loadAmemConfig } from "./config.ts";
+import { canonicalJSON, readProfileJSON, selectorRevision } from "./generation.ts";
+import { assertFormatFloor } from "./formats.ts";
+import type { MemoryStore } from "./store.ts";
+import { shardSyncBinding } from "./sync-binding.ts";
+import { outboundPolicyEvaluator, visitOwnSegment, SYNC_SCREEN_MAX_BYTES, SYNC_SCREEN_MAX_ROWS, type RowScreen, type SyncPolicyCategory } from "./sync-screen.ts";
+
+export type { SyncPolicyCategory } from "./sync-screen.ts";
+export interface SyncPolicyInspectionOptions {
+  /** Narrows the machine policy, over the same canonical content projection as SyncOptions.screen. */
+  screen?: RowScreen;
+  /** Optional host epoch, as in SyncOptions.policyVersion. A change makes the inspection incomplete. */
+  policyVersion?: () => string;
+}
+export interface SyncPolicyDeclinedRow { id: string; categories: SyncPolicyCategory[] }
+export type SyncPolicyInspection = {
+  complete: true;
+  declined: SyncPolicyDeclinedRow[];
+  counts: { scanned: number; declined: number; byCategory: Record<SyncPolicyCategory, number> };
+  /** SHA-256 over the sorted complete declined IDs/categories, never over private content or policy patterns. */
+  fingerprint: string;
+} | { complete: false; reason: "input-unavailable" | "input-bound" | "input-changed" | "binding-changed" | "policy-unavailable" };
+
+const hash = (value: unknown) => createHash("sha256").update(canonicalJSON(value)).digest("hex");
+
+/** Bounded, read-only inspection of exactly the opened sync targets. No refresh, rebind, publication or transport. */
+export function inspectSyncPolicy(store: MemoryStore, options: SyncPolicyInspectionOptions = {}): SyncPolicyInspection {
+  let failure: Extract<SyncPolicyInspection, {complete: false}>["reason"] = "input-unavailable";
+  try {
+    assertFormatFloor(store.profile.home, "sync");
+    const targets = [...store.openedSyncTargets()];
+    const metadata = [...new Set([join(store.profile.home, "profile.json"), join(store.profile.home, "shards.json"), join(store.profile.home, "aliases.jsonl"), join(store.profile.home, "amem.config.json"), join(store.profile.home, "machine.json"), ...targets.flatMap(target => [join(target.dir, "machine.json"), join(target.dir, "project.json"), ...(target.profile.kind === "generation" ? [join(target.dir, "generation.json"), join(target.dir, "generation-seal.json"), join(target.dir, "migration-sources.json")] : [])])])];
+    const stamps = () => metadata.map(file => {
+      const stat = lstatSync(file, { bigint: true, throwIfNoEntry: false });
+      if (!stat) return "absent";
+      if (!stat.isFile() || stat.isSymbolicLink() || stat.size > BigInt(SYNC_SCREEN_MAX_BYTES)) throw new Error("metadata unavailable");
+      return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].map(String);
+    });
+    const binding = () => hash({
+      stamps: stamps(),
+      root: store.profile,
+      selector: selectorRevision(store.profile.home),
+      ...(store.profile.sharded ? { shards: shardSyncBinding(store) } : {}),
+      targets: targets.map(target => ({ profile: target.profile, machine: target.machine,
+        selector: selectorRevision(target.profile.home),
+        machineFile: readProfileJSON(join(target.dir, "machine.json"), 4096),
+        ...(target.profile.kind === "generation" ? {
+          generation: readProfileJSON(join(target.dir, "generation.json"), 4096),
+          seal: readProfileJSON(join(target.dir, "generation-seal.json")),
+        } : {}),
+      })),
+    });
+    // Stale handles are not silently rebound, including a monotone selector change supported by sync itself.
+    if (targets.some(target => selectorRevision(target.profile.home) !== target.profile.selectorRevision)) return { complete: false, reason: "binding-changed" };
+    if (targets.some(target => (readProfileJSON(join(target.dir, "machine.json"), 4096) as {id?: unknown} | undefined)?.id !== target.machine.id)) return { complete: false, reason: "binding-changed" };
+    const epoch = binding();
+    failure = "policy-unavailable";
+    const policyVersion = options.policyVersion?.();
+    if (options.policyVersion !== undefined && typeof policyVersion !== "string") throw new Error("host policy unavailable");
+    const defaults = () => {
+      const value = memoryPolicySnapshot({ names: DENY_NAMES, segments: DENY_SEGMENTS });
+      if (!value) throw new Error("policy unavailable");
+      return hash(value);
+    };
+    const defaultEpoch = defaults();
+    const policy = () => hash({ config: loadAmemConfig(store.profile.home).config, defaults: defaults() });
+    failure = "policy-unavailable";
+    const policyEpoch = policy(), evaluate = outboundPolicyEvaluator(store.profile.home, options.screen);
+    const assertCurrent = () => {
+      failure = "binding-changed";
+      if (binding() !== epoch || canonicalJSON(store.openedSyncTargets().map(target => [target.dir, target.machine.id])) !== canonicalJSON(targets.map(target => [target.dir, target.machine.id]))) throw new Error("binding changed");
+      failure = "policy-unavailable";
+      if (policy() !== policyEpoch || options.policyVersion?.() !== policyVersion) throw new Error("policy changed");
+    };
+    const ids = new Map<string, { hash: string; categories: Set<SyncPolicyCategory> }>();
+    let scanned = 0;
+    const visit = (row: Record<string, unknown>) => {
+      failure = "input-bound";
+      if (++scanned > SYNC_SCREEN_MAX_ROWS) throw new Error("row bound");
+      failure = "input-unavailable";
+      if (typeof row.id !== "string" || !/^[a-f0-9]{32}$/.test(row.id)) throw new Error("row id unavailable");
+      const rowHash = hash(row), prior = ids.get(row.id);
+      if (prior && prior.hash !== rowHash) throw new Error("row identity changed");
+      failure = "policy-unavailable";
+      if (defaults() !== defaultEpoch) throw new Error("default policy changed");
+      const verdict = evaluate(row);
+      if (defaults() !== defaultEpoch) throw new Error("default policy changed");
+      const item = prior ?? { hash: rowHash, categories: new Set<SyncPolicyCategory>() };
+      if (!verdict.ok) item.categories.add(verdict.category);
+      ids.set(row.id, item);
+      if (options.policyVersion?.() !== policyVersion) { failure = "policy-unavailable"; throw new Error("host policy changed"); }
+    };
+    const checks: (() => void)[] = [];
+    for (const target of targets) {
+      assertCurrent(); failure = "input-unavailable";
+      if (target.profile.kind === "generation") checks.push(target.inspectOutboundRows(visit, { maxBytes: SYNC_SCREEN_MAX_BYTES, maxRows: SYNC_SCREEN_MAX_ROWS }));
+      else checks.push(visitOwnSegment(target.dir, target.machine.id, visit));
+      assertCurrent();
+    }
+    for (const check of checks) { failure = "input-changed"; check(); }
+    assertCurrent();
+    const declined = [...ids].filter(([, item]) => item.categories.size > 0).sort(([a], [b]) => a.localeCompare(b))
+      .map(([id, item]) => ({ id, categories: [...item.categories].sort() }));
+    const byCategory: Record<SyncPolicyCategory, number> = { secret: 0, "personal-data": 0, "deny-path": 0, "private-or-invalid": 0, host: 0 };
+    for (const row of declined) for (const category of row.categories) byCategory[category]++;
+    return { complete: true, declined, counts: { scanned, declined: declined.length, byCategory }, fingerprint: hash(declined) };
+  } catch (error) {
+    let reason: Extract<SyncPolicyInspection, { complete: false }>["reason"] = failure;
+    // Caller errors are not trusted diagnostics: never read message, getters or proxy properties.
+    try {
+      if (error && typeof error === "object" && !types.isProxy(error)) {
+        const code = Object.getOwnPropertyDescriptor(error, "code")?.value;
+        if (["input-unavailable", "input-bound", "input-changed"].includes(code)) reason = code;
+        else if (error instanceof SegmentReadBudgetError) reason = "input-bound";
+      }
+    } catch { /* An exotic caller exception cannot escape as a data-bearing error. */ }
+    return { complete: false, reason };
+  }
+}