@staix/agent-mem 0.21.0 → 0.22.0

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

@@ -0,0 +1,84 @@
+/** Expected inventory metadata only. Callers must still obtain fresh install attestations. */
+import { lstatSync, opendirSync } from "node:fs";
+import { join } from "node:path";
+import { hashJSON } from "./generation.ts";
+import { readPlacementRuntimeMarkers } from "./sync-placement-guard.ts";
+import { readActivePlacementBinding, type ActivePlacementBinding } from "./sync-placement-active.ts";
+import { readPlacementWriterJournalAnchors, placementWriterJournalToken } from "./sync-placement-journal-storage.ts";
+import { readWriterHistory, isWriterRenewalIntentTempName } from "./sync-placement-writer-history.ts";
+import { SharedWriterRevisionError, writerRevisionWriters, WRITER_RENEWAL_INTENT_FILE } from "./sync-placement-writer-revision-format.ts";
+import { readInitialSyncPlacementWriterLocator, SYNC_PLACEMENT_WRITER_ROOTS_FILE } from "./sync-placement-writer-roots.ts";
+import { requireWriterRenewalHomeFloor } from "./sync-placement-prerequisites.ts";
+import type { SyncPlacementWriterAttestation } from "./sync-placement-plan.ts";
+
+export interface EffectiveSyncPlacementWriters {
+  epochHash:string;activationHash:string;revisionSequence:number;revisionHash:string;roots?:readonly string[];
+  writers:readonly SyncPlacementWriterAttestation[];initialLocatorHash?:string;
+  assertCurrent():void;
+}
+function fail():never{throw new SharedWriterRevisionError("changed");}
+function active(home:string):ActivePlacementBinding {
+  const markers=readPlacementRuntimeMarkers(home),value=readActivePlacementBinding(home,markers.profile,markers.shards);if(!value)fail();return value;
+}
+const key=(value:ActivePlacementBinding)=>hashJSON({epoch:value.epoch,activation:value.activation,head:value.profile.placementHead,generation:value.profile.generation});
+const fileStamp=(home:string)=>{
+  const s=lstatSync(join(home,SYNC_PLACEMENT_WRITER_ROOTS_FILE),{bigint:true,throwIfNoEntry:false});
+  return s?[s.dev,s.ino,s.mode,s.uid,s.nlink,s.size,s.mtimeNs,s.ctimeNs].map(String).join(":"):undefined;
+};
+/** A source-only capture can bootstrap its initial fence; do not impose renewal admission on that old path. */
+export function writerInventoryEvidence(home:string,epochHash:string):boolean{
+  const scan=(dir:string,maximum:number,match:(name:string)=>boolean)=>{
+    const reader=opendirSync(dir);let count=0,found=false;try{for(;;){const e=reader.readSync();if(!e)break;if(++count>maximum)throw new SharedWriterRevisionError("bound");if(match(e.name))found=true;}}finally{reader.closeSync();}return found;
+  };
+  const outside=scan(home,20000,name=>{
+    if(name.startsWith(WRITER_RENEWAL_INTENT_FILE+".pending-")&&!isWriterRenewalIntentTempName(name))throw new SharedWriterRevisionError("invalid");
+    return name===WRITER_RENEWAL_INTENT_FILE||isWriterRenewalIntentTempName(name);
+  });
+  let dir=home;
+  for(const part of ["sync-placement","epochs",epochHash]){
+    dir=join(dir,part);const s=lstatSync(dir,{throwIfNoEntry:false});if(!s)return outside;
+    if(!s.isDirectory()||s.isSymbolicLink()||s.uid!==process.getuid?.()||(s.mode&0o077)!==0)throw new SharedWriterRevisionError("invalid");
+  }
+  return scan(dir,255,name=>name.startsWith("writer-"))||outside;
+}
+export function readEffectiveSyncPlacementWriters(home:string):EffectiveSyncPlacementWriters {
+  const binding=active(home),bindingKey=key(binding),epochHash=binding.profile.placementHead;
+  writerInventoryEvidence(home,epochHash);
+  const history=readWriterHistory(home,{epochHash,activationHash:binding.activation.seal,homeHash:binding.epoch.homeHash,generation:binding.epoch.generation});
+  const initialStamp=fileStamp(home),initial=initialStamp===undefined?undefined:readInitialSyncPlacementWriterLocator(home);
+  if(history.sequence){
+    requireWriterRenewalHomeFloor(home);
+    if(!initial||history.current?.initialLocatorHash!==initial.seal)fail();
+  }
+  let anchorToken:string|undefined;
+  // ponytail: native inode/size/ctime identity permits prefix reuse; hostile same-user rewrites need immutable snapshot blocks.
+  const anchors=()=>{
+    if(!history.sequence)return;
+    const token=placementWriterJournalToken(home,epochHash);if(token===anchorToken)return;
+    const journal=readPlacementWriterJournalAnchors(home,epochHash);
+    if(journal.epoch.homeHash!==binding.epoch.homeHash||journal.activation.seal!==binding.activation.seal)fail();
+    for(const anchor of history.anchors){
+      if(anchor.sequence>journal.sequence||(anchor.sequence===0?epochHash:journal.records[anchor.sequence-1]?.seal)!==anchor.headHash)fail();
+    }
+    if(placementWriterJournalToken(home,epochHash)!==token)fail();anchorToken=token;
+  };
+  const assertCurrent=()=>{
+    history.assertCurrent();if(key(active(home))!==bindingKey||fileStamp(home)!==initialStamp)fail();
+    if(initial&&readInitialSyncPlacementWriterLocator(home).seal!==initial.seal)fail();
+    if(history.sequence)requireWriterRenewalHomeFloor(home);
+    anchors();history.assertCurrent();
+  };
+  anchors();assertCurrent();
+  const roots=history.current?.roots.map(root=>root.root)??initial?.roots.map(root=>root.root);
+  return{epochHash,activationHash:binding.activation.seal,revisionSequence:history.sequence,revisionHash:history.headHash,
+    writers:history.current?writerRevisionWriters(history.current):binding.activation.writers,
+    ...(roots?{roots}:{}),...(initial?{initialLocatorHash:initial.seal}:{}),assertCurrent};
+}
+/** Locators only; these paths and expected pins never replace a fresh callback. */
+export function readEffectiveSyncPlacementWriterRoots(home:string):string[]{
+  const value=readEffectiveSyncPlacementWriters(home);if(!value.roots)throw new SharedWriterRevisionError("invalid");value.assertCurrent();return[...value.roots];
+}
+/** Keep existing no-revision artifacts byte-identical while binding renewed attempts to their committed head. */
+export function writerBoundPlacementContextHash(context:unknown,inventory?:Pick<EffectiveSyncPlacementWriters,"revisionSequence"|"revisionHash">):string {
+  return inventory?.revisionSequence?hashJSON(["agent-mem.sync-placement-writer-bound-context/v1",context,inventory.revisionHash]):hashJSON(context);
+}

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

@@ -6,9 +6,11 @@ import { join } from "node:path";
 import { LOCAL_METADATA_MAX_BYTES, legacyProfileMarkerShape, type BoundProfile } from "./generation.ts";
 import { legacyShardMarkerShape } from "./shard.ts";
 import { PLACEMENT_PROFILE_SCHEMA, PLACEMENT_SHARDS_SCHEMA, validatePlacementProfile, validatePlacementShards } from "./sync-placement-format.ts";
+import { PLACEMENT_ACTIVATION_INTENT } from "./sync-placement-activation-path.ts";
 
 export const PLACEMENT_STAGE1_REFUSAL = "sync placement v3 requires matching durable activation metadata; keep the current compatible profile active until person-authorized activation is complete";
 export const PLACEMENT_MARKER_REFUSAL = "sync placement metadata is invalid or unsupported; person inspection and a compatible reader are required before continuing";
+export const PLACEMENT_ACTIVATION_PENDING = "sync placement activation is pending or incomplete; have the person inspect retained evidence and run amem migrate --sync-placement --resume, or --abandon only while both markers retain their original v2 bytes";
 export class SyncPlacementRuntimeError extends Error {
   readonly code: "sync_placement_not_enabled" | "sync_placement_unavailable";
   constructor(reason: string) { super(reason); this.name = "SyncPlacementRuntimeError"; this.code = reason === PLACEMENT_STAGE1_REFUSAL ? "sync_placement_not_enabled" : "sync_placement_unavailable"; }
@@ -65,13 +67,17 @@ export function placementMarkerRefusal(profile: unknown, shards: unknown): strin
 export function placementSelectorRefusal(home: string): string | undefined {
   // A durable placement fence forbids falling back to raw legacy sync after marker rollback.
   const fenced = placementFencePresent(home);
+  const pending = placementActivationPending(home);
   let profile: unknown, shards: unknown;
   try { profile = readMarker(join(home, "profile.json")); } catch { /* The original selector reader reports this legacy failure. */ }
   try { shards = readMarker(join(home, "shards.json")); } catch { /* Ordinary migration still owns malformed split-state recovery. */ }
-  if (schema(profile) !== PLACEMENT_PROFILE_SCHEMA && schema(shards) !== PLACEMENT_SHARDS_SCHEMA) return fenced ? PLACEMENT_MARKER_REFUSAL : undefined;
+  if (schema(profile) !== PLACEMENT_PROFILE_SCHEMA && schema(shards) !== PLACEMENT_SHARDS_SCHEMA) return pending ? PLACEMENT_ACTIVATION_PENDING : fenced ? PLACEMENT_MARKER_REFUSAL : undefined;
   const refusal = placementMarkerRefusal(profile, shards);
-  if (refusal !== PLACEMENT_STAGE1_REFUSAL) return refusal;
-  try { return readActivePlacementBinding(home, profile, shards) ? undefined : refusal; } catch { return PLACEMENT_MARKER_REFUSAL; }
+  if (refusal !== PLACEMENT_STAGE1_REFUSAL) return pending ? PLACEMENT_ACTIVATION_PENDING : refusal;
+  try { return readActivePlacementBinding(home, profile, shards) ? undefined : pending ? PLACEMENT_ACTIVATION_PENDING : refusal; } catch { return PLACEMENT_MARKER_REFUSAL; }
+}
+function placementActivationPending(home: string): boolean {
+  return lstatSync(join(home,PLACEMENT_ACTIVATION_INTENT),{throwIfNoEntry:false}) !== undefined;
 }
 function placementFencePresent(home: string): boolean {
   const root = lstatSync(join(home, "sync-placement"), { throwIfNoEntry: false });
@@ -82,15 +88,15 @@ function placementFencePresent(home: string): boolean {
 /** Bounded activation/view metadata only; no data/index open, cache mutation, lock or child/network call.
  * The v3 publication coordinator separately proves the complete journal, selected sources and policy. */
 export function placementRuntimeRefusal(home: string, bound?: Pick<BoundProfile,"kind"|"sharded"|"generation"|"publicationFormat"|"placementHead">): string | undefined {
-  try { const fenced = placementFencePresent(home), markers = readPlacementRuntimeMarkers(home);
+  try { const fenced = placementFencePresent(home), pending = placementActivationPending(home), markers = readPlacementRuntimeMarkers(home);
     const refusal = placementMarkerRefusal(markers.profile, markers.shards);
     if (refusal === PLACEMENT_STAGE1_REFUSAL) {
       const active=readActivePlacementBinding(home,markers.profile,markers.shards);
-      if(!active)return refusal;
+      if(!active)return pending ? PLACEMENT_ACTIVATION_PENDING : refusal;
       if(bound && (bound.kind!=="generation"||bound.sharded!==true||bound.generation!==active.profile.generation||bound.publicationFormat!==active.profile.publicationFormat||bound.placementHead!==active.profile.placementHead)) return PLACEMENT_MARKER_REFUSAL;
       return undefined;
     }
-    return refusal ?? (fenced ? PLACEMENT_MARKER_REFUSAL : undefined); }
+    return refusal ?? (pending ? PLACEMENT_ACTIVATION_PENDING : fenced ? PLACEMENT_MARKER_REFUSAL : undefined); }
   catch { return PLACEMENT_MARKER_REFUSAL; }
 }
 export function assertPlacementRuntime(home: string): void {

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

@@ -25,6 +25,7 @@ import type { PlacementPublicationDecisionReason } from "./sync-placement-public
 import type { ShardSyncRealm, ShardSyncRow } from "./shard-sync-format.ts";
 import type { MemoryStore } from "./store.ts";
 import { captureInspectionPendingPrunes } from "./sync-placement-inspection-pending.ts";
+import { SharedWriterRevisionError } from "./sync-placement-writer-revision-format.ts";
 
 export interface SyncPlacementInspectionOptions {
   screen?: RowScreen;
@@ -119,7 +120,7 @@ export async function inspectSyncPlacement(store: MemoryStore, input: SyncPlacem
     const port: PlacementCapturePort = { attest: options.placementAttestation, ...(options.policyVersion ? { policyVersion: options.policyVersion } : {}) };
     const capture = captureSyncPlacementContext(home, port, targets.map(target => physical(target.realm)));
     captured = true;
-    if (capture.activeHead !== active.profile.placementHead || canonicalJSON(capture.context.writers) !== canonicalJSON(active.activation.writers)) fail("attestation-unavailable");
+    if (capture.activeHead !== active.profile.placementHead || canonicalJSON(capture.context.writers) !== canonicalJSON(capture.writerInventory?.writers??active.activation.writers)) fail("attestation-unavailable");
     phase = "journal-unavailable"; const retained = captureInspectionJournal(home, active.profile.placementHead);
     const check = () => {
       if (binding() !== beforeBinding) fail("binding-changed"); retained.assertCurrent(); capture.assertUnchanged();
@@ -219,6 +220,9 @@ export async function inspectSyncPlacement(store: MemoryStore, input: SyncPlacem
   } catch (error) {
     let reason: SyncPlacementInspectionIncompleteReason = phase;
     if (error && typeof error === "object" && !types.isProxy(error)) {
+      if(error instanceof SharedWriterRevisionError){const code=Object.getOwnPropertyDescriptor(error,"code")?.value;
+        if(code==="staging"||code==="pending")return{complete:false,reason:"journal-unavailable",nextStep:new SharedWriterRevisionError(code).message};
+      }
       if (error instanceof Incomplete) reason = error.reason;
       else if (error instanceof FormatFloorError) {
         if (error.code === "format_floor") reason = "reader-upgrade-required";

package/src/memory/sync-placement-journal-storage.ts

@@ -14,6 +14,8 @@ import { PLACEMENT_ACTIVE_FENCE_SCHEMA, PLACEMENT_JOURNAL_MAX_RECORDS, PLACEMENT
 import { validatePlacementPublicationRoot, validatePlacementPublicationBundle, validatePlacementPublicationFact, publicationFileNames,
   PLACEMENT_PUBLICATION_RECORD_MAX_BYTES, type PlacementPublicationRoot, type PlacementPublicationBundle, type PlacementPublicationFact } from "./sync-placement-publication-plan.ts";
 import { PlacementProjection } from "./sync-placement-projection.ts";
+import { WRITER_RENEWAL_INTENT_FILE, WRITER_RENEWAL_INTENT_MAX_BYTES, WRITER_COMMIT_LOG, writerHistoryFileLimit, writerRevisionFile } from "./sync-placement-writer-revision-format.ts";
+import { isWriterRenewalIntentTempName } from "./sync-placement-writer-history.ts";
 
 export type PlacementStoragePhase = "epoch-written" | "epoch-fsync" | "activation-written" | "activation-fsync" | "fence-written" | "fence-fsync"
   | "intent-written" | "intent-fsync" | "chunk-written" | "chunk-fsync" | "intent-cleared"
@@ -53,7 +55,18 @@ function names(dir: string, maximum: number): string[] {
   finally { reader.closeSync(); }
   return result.sort();
 }
-function inventory(p: Paths): { files: Map<string, BigIntStats>; token: string } {
+function renewalIntentObjects(home:string):{count:number;token:unknown[]} {
+  const token:unknown[]=[];
+  for(const name of names(home,20000)){
+    if(name!==WRITER_RENEWAL_INTENT_FILE&&!isWriterRenewalIntentTempName(name))continue;
+    const s=lstatSync(join(home,name),{bigint:true});
+    if(!s.isFile()||s.isSymbolicLink()||s.uid!==BigInt(process.getuid?.()??-1)||(s.mode&0o777n)!==0o600n||![1n,2n].includes(s.nlink))fail();
+    if(s.size>BigInt(WRITER_RENEWAL_INTENT_MAX_BYTES))fail("bound");
+    token.push([name,String(s.dev),String(s.ino),String(s.size),String(s.nlink),String(s.mtimeNs),String(s.ctimeNs)]);
+  }
+  return{count:token.length,token};
+}
+function inventory(p: Paths): { files: Map<string, BigIntStats>; token: string; renewalObjects:number } {
   const parents: unknown[] = [];
   for (const dir of [p.home, p.root, p.epochs, p.dir]) { const stat = state(dir, true); parents.push([dir, stat ? [String(stat.dev), String(stat.ino)] : null]); }
   if (state(p.root, true)) for (const name of names(p.root, 2)) {
@@ -63,15 +76,17 @@ function inventory(p: Paths): { files: Map<string, BigIntStats>; token: string }
   const files = new Map<string, BigIntStats>();
   if (state(p.dir, true)) for (const name of names(p.dir, PLACEMENT_JOURNAL_MAX_OBJECTS - 1)) {
     const chunk = /^records-\d{5}\.jsonl$/.test(name);
-    if (!chunk && !publicationName(name) && !["epoch.json", "activation.json", "append-intent.json"].includes(name)) fail();
+    const writerLimit=writerHistoryFileLimit(name);
+    if (!chunk && !publicationName(name) && writerLimit===undefined && !["epoch.json", "activation.json", "append-intent.json"].includes(name)) fail();
     const stat = state(join(p.dir, name))!;
-    if (stat.size > BigInt(chunk || /-chunk-\d{5}\.json$/.test(name) ? PLACEMENT_JOURNAL_CHUNK_MAX_BYTES : PLACEMENT_JOURNAL_ROOT_MAX_BYTES)) fail("bound");
+    if (stat.size > BigInt(writerLimit??(chunk || /-chunk-\d{5}\.json$/.test(name) ? PLACEMENT_JOURNAL_CHUNK_MAX_BYTES : PLACEMENT_JOURNAL_ROOT_MAX_BYTES))) fail("bound");
     files.set(name, stat);
   }
   // One global active.json slot is always reserved, whether that fence exists yet or not.
-  if (files.size + 1 > PLACEMENT_JOURNAL_MAX_OBJECTS) fail("bound");
+  const renewal=renewalIntentObjects(p.home);
+  if (files.size + 1 + renewal.count > PLACEMENT_JOURNAL_MAX_OBJECTS) fail("bound");
   const fence = state(join(p.root, "active.json"));
-  return { files, token: canonicalJSON({ parents, files: [...files].map(([name, stat]) => [name, String(stat.dev), String(stat.ino), String(stat.size), String(stat.mtimeNs), String(stat.ctimeNs)]),
+  return { files, renewalObjects:renewal.count, token: canonicalJSON({ parents, renewal:renewal.token, files: [...files].map(([name, stat]) => [name, String(stat.dev), String(stat.ino), String(stat.size), String(stat.mtimeNs), String(stat.ctimeNs)]),
     fence: fence ? [String(fence.dev), String(fence.ino), String(fence.size), String(fence.mtimeNs), String(fence.ctimeNs)] : null }) };
 }
 function readOwned(file: string, maximum: number): Buffer | undefined {
@@ -152,7 +167,7 @@ function snapshot(p: Paths): Snapshot {
   if ((records.length > 0 || pendingBytes !== undefined) && (!activeFence || fencePending || activeFence.epochHash !== p.hash
     || activeFence.homeHash !== epoch.homeHash || activeFence.generation !== epoch.generation)) fail();
   if (inventory(p).token !== before.token) fail("changed");
-  return { epoch, activation: plan, records, projection, headHash: projection.headHash, sequence: projection.sequence, objects: before.files.size + 1, pending: !!pending || intentPending || fencePending, chunks, intentPending, fencePending, ...(pending ? { pendingRecordSequence: pending.record.sequence, pendingRecord: validatePlacementRecord(pending.record) } : {}), ...(pending ? { intent: pending } : {}) };
+  return { epoch, activation: plan, records, projection, headHash: projection.headHash, sequence: projection.sequence, objects: before.files.size + 1 + before.renewalObjects, pending: !!pending || intentPending || fencePending, chunks, intentPending, fencePending, ...(pending ? { pendingRecordSequence: pending.record.sequence, pendingRecord: validatePlacementRecord(pending.record) } : {}), ...(pending ? { intent: pending } : {}) };
 }
 export function readPlacementJournal(home: string, epochHash: string): PlacementJournalRead {
   return protectedIO(() => {
@@ -168,12 +183,41 @@ export function readPlacementJournal(home: string, epochHash: string): Placement
     if (inventory(p).token !== before) fail("changed"); return result;
   });
 }
+/** Writer history only needs the authoritative row prefix, including during owned publication-root writes.
+ * Full transport/recovery still uses readPlacementJournal and its reservation proof. */
+export function placementWriterJournalToken(home:string,epochHash:string):string {
+  return protectedIO(()=>{
+    const p=paths(home,epochHash),dir=state(p.dir,true);if(!dir)fail("changed");
+    const rows:unknown[]=[["directory",String(dir.dev),String(dir.ino),String(dir.mode),String(dir.uid)]];
+    for(const name of names(p.dir,PLACEMENT_JOURNAL_MAX_OBJECTS-1))if(name.startsWith("records-")||name==="append-intent.json"){
+      const s=state(join(p.dir,name));if(!s)fail("changed");
+      rows.push([name,String(s.dev),String(s.ino),String(s.mode),String(s.uid),String(s.nlink),String(s.size),String(s.mtimeNs),String(s.ctimeNs)]);
+    }
+    return canonicalJSON(rows);
+  });
+}
+export function readPlacementWriterJournalAnchors(home:string,epochHash:string):Pick<PlacementJournalRead,"epoch"|"activation"|"records"|"sequence"|"headHash"> {
+  return protectedIO(()=>{
+    const read=snapshot(paths(home,epochHash));
+    return{epoch:read.epoch,activation:read.activation,records:read.records,sequence:read.sequence,headHash:read.headHash};
+  });
+}
 function current(p: Paths, opts: PlacementStorageOptions, required: readonly string[] = []): void {
   try { assertMutationHandle(opts.mutation, p.home); } catch { return fail("busy"); }
   try { opts.assertCurrent(); } catch (error) { if (knownError(error)) throw error; return fail("changed"); }
   try { assertMutationHandle(opts.mutation, p.home); } catch { return fail("busy"); }
   const found = inventory(p), names = new Set([...found.files.keys(), ...required, ...reservedPublicationJournalNames(p)]);
-  if (names.size + 1 > PLACEMENT_JOURNAL_MAX_OBJECTS) fail("bound");
+  if(found.renewalObjects)fail("pending");
+  if (names.size + 1 + found.renewalObjects > PLACEMENT_JOURNAL_MAX_OBJECTS) fail("bound");
+}
+/** One shared budget includes the outside intent and its transient immutable-publication companion. */
+export function writerRenewalCapacity(home:string,epochHash:string,sequence:number):{objects:number;remainingObjects:number} {
+  return protectedIO(()=>{
+    const p=paths(home,epochHash),found=inventory(p),next=new Set([...found.files.keys(),...reservedPublicationJournalNames(p),WRITER_COMMIT_LOG,writerRevisionFile(sequence)]);
+    const objects=next.size+1+Math.max(2,found.renewalObjects);
+    if(objects>PLACEMENT_JOURNAL_MAX_OBJECTS)fail("bound");
+    return{objects,remainingObjects:PLACEMENT_JOURNAL_MAX_OBJECTS-objects};
+  });
 }
 function writer<T>(home: string, epochHash: string, opts: PlacementStorageOptions, work: (p: Paths) => T, incompleteAttempt?: string, preflight?: readonly string[] | ((p: Paths) => readonly string[])): T {
   return protectedIO(() => {

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

@@ -10,11 +10,12 @@ import { outboundPolicyEvaluator, type RowScreen } from "./sync-screen.ts";
 import { assertPlacementRuntime } from "./sync-placement-guard.ts";
 import { PLACEMENT_FORMAT } from "./sync-placement-format.ts";
 import { planSyncPlacementActivation, validatePlacementPlan, validateSyncPlacementActivation, type SyncPlacementActivationPlan } from "./sync-placement-plan.ts";
-import { captureSyncPlacementContext, type PlacementCapturePort, type PlacementCapture } from "./sync-placement-capture.ts";
+import { captureSyncPlacementContext, placementCaptureContextHash, type PlacementCapturePort, type PlacementCapture } from "./sync-placement-capture.ts";
 import { PLACEMENT_EPOCH_SCHEMA, placementEpochHash, placementKeyId, validatePlacementEpoch, validatePlacementKey, validatePlacementEvent,
   SyncPlacementJournalError, type PlacementEpoch, type PlacementKey, type PlacementCommittedOutcome, type PlacementAmbiguousOutcome } from "./sync-placement-journal-format.ts";
 import { rebuildPlacementProjection } from "./sync-placement-projection.ts";
 import { preparePlacementEpoch, readPlacementJournal, appendPlacementEvent } from "./sync-placement-journal-storage.ts";
+import { SharedWriterRevisionError } from "./sync-placement-writer-revision-format.ts";
 
 export interface PlacementJournalPreview { epoch: PlacementEpoch; plan: SyncPlacementActivationPlan }
 export interface PlacementAuthorizationBinding {
@@ -28,7 +29,13 @@ export interface PlacementJournalPort extends PlacementCapturePort {
 }
 function fail(code: "invalid" | "changed" | "authorization" | "policy" | "local" | "conflict" | "pending" | "busy" = "invalid"): never { throw new SyncPlacementJournalError(code); }
 function protectedCall<T>(work: () => T): T {
-  try { return work(); } catch (error) { if (error && typeof error === "object" && !types.isProxy(error) && error instanceof SyncPlacementJournalError) throw error; return fail("changed"); }
+  try { return work(); } catch (error) {
+    if(error&&typeof error==="object"&&!types.isProxy(error)){
+      if(error instanceof SyncPlacementJournalError)throw error;
+      if(error instanceof SharedWriterRevisionError){const code=Object.getOwnPropertyDescriptor(error,"code")?.value;if(code==="staging"||code==="pending")throw new SharedWriterRevisionError(code);}
+    }
+    return fail("changed");
+  }
 }
 function person(port: PlacementJournalPort, action: "prepare" | "hold" | "release", seal: string, details: Omit<PlacementAuthorizationBinding, "action" | "seal"> = {}): void {
   let authorized = false;
@@ -86,7 +93,7 @@ function active(home: string, input: PlacementEffectRequest, port: PlacementCapt
   if (capture.activeHead !== input.epochHash || journal.epoch.homeHash !== capture.context.homeHash
     || journal.epoch.generation !== (capture.context.profile as { generation: string }).generation
     || journal.activation.targetProfile.placementHead !== input.epochHash
-    || canonicalJSON(capture.context.writers) !== canonicalJSON(journal.activation.writers)
+    || canonicalJSON(capture.context.writers) !== canonicalJSON(capture.writerInventory?.writers??journal.activation.writers)
     || canonicalJSON(capture.context.realms.map(({ bindingHash: _hash, ...identity }) => identity))
       !== canonicalJSON(journal.activation.realms.map(({ bindingHash: _hash, ...identity }) => identity))) fail("changed");
   const markers = readPlacementRuntimeMarkers(capture.home), profile = validatePlacementProfile(markers.profile);
@@ -116,7 +123,7 @@ function effect(home: string, raw: PlacementEffectRequest, port: PlacementJourna
       if (!outboundPolicyEvaluator(capture.home, port.screen)(source.row as unknown as Record<string, unknown>).ok) fail("policy");
       partial = { ...fields, kind: "release" };
     } else partial = { ...fields, kind: decision.kind, outcome: decision.outcome };
-    const effectHash = hashJSON({ event: partial, expectedHead: input.expectedHead, markerHash: capture.markerHash, contextHash: hashJSON(capture.context) });
+    const effectHash = hashJSON({ event: partial, expectedHead: input.expectedHead, markerHash: capture.markerHash, contextHash: placementCaptureContextHash(capture) });
     const event = validatePlacementEvent({ ...partial, effectHash });
     if (decision.kind === "release" || decision.kind === "hold" && decision.mode === "person") person(port, decision.kind, effectHash, { epochHash: input.epochHash, key: Object.freeze({ ...input.key, realm: Object.freeze({ ...input.key.realm }) }),
       expectedHead: input.expectedHead, policyHash: capture.context.policyHash });

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

@@ -0,0 +1,50 @@
+/** Activation preflight only. Never migrates, opens an index, raises a floor or creates a home. */
+import { lstatSync } from "node:fs";
+import { realPath } from "./platform.ts";
+import { hashJSON } from "./generation.ts";
+import { assertFormatFloor, readFormatFloors } from "./formats.ts";
+import { readPlacementRuntimeMarkers } from "./sync-placement-guard.ts";
+import { readActivePlacementBinding, type ActivePlacementBinding } from "./sync-placement-active.ts";
+import { PLACEMENT_PROFILE_SCHEMA, validatePlacementBaseV2, type PlacementBaseV2 } from "./sync-placement-format.ts";
+
+export const PLACEMENT_ACTIVATION_MIN_READER = "0.21.0";
+const preview = "amem migrate --sync-placement --dry-run";
+function requireHomeFloor(home: string,minReader:string): string {
+  assertFormatFloor(home, "curated"); assertFormatFloor(home, "sync");
+  const floors = readFormatFloors(home), minimum = minReader.split(".").map(Number);
+  const adequate = floors?.some(row => {
+    if (row.surface !== "home" || !/^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.test(row.minReader)) return false;
+    const parts = row.minReader.split(".").map(Number);
+    for (let i = 0; i < 3; i++) if (parts[i] !== minimum[i]) return parts[i]! > minimum[i]!;
+    return true;
+  });
+  if (!adequate) throw Error(`Sync placement requires a person-authored home floor of ${minReader} or later in formats.json; have the person append that record, then rerun ${preview}.`);
+  return hashJSON(floors);
+}
+export function requirePlacementHomeFloor(home:string):string{return requireHomeFloor(home,PLACEMENT_ACTIVATION_MIN_READER);}
+export function requireWriterRenewalHomeFloor(home:string):string{return requireHomeFloor(home,"0.22.0");}
+export interface PlacementActivationPrerequisites { home: string; floorHash: string; base?: PlacementBaseV2; active?: ActivePlacementBinding }
+export function requirePlacementActivationPrerequisites(input: string): PlacementActivationPrerequisites {
+  let home: string;
+  try { home = realPath(input); const stat = lstatSync(home); if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0) throw Error(); }
+  catch { throw Error("Sync placement memory home is unavailable or unsafe; select an existing private memory home and rerun amem migrate --sync-placement --dry-run."); }
+  assertFormatFloor(home, "curated"); assertFormatFloor(home, "sync");
+  const markers = readPlacementRuntimeMarkers(home);
+  const shards = markers.shards as { schema?: string; phase?: string } | undefined;
+  const profile = markers.profile as { schema?: string } | undefined;
+  if (!shards || shards.schema === "agent-mem.shards/v1" && shards.phase !== "active") {
+    throw Error("Sync placement requires an active shard home; run amem migrate --shards --dry-run and complete that person-reviewed migration first.");
+  }
+  if (shards.schema === "agent-mem.shards/v1") {
+    throw Error("Sync placement requires the v2 public-prune view; run amem migrate --public-prune-view --dry-run and complete that person-reviewed migration first.");
+  }
+  if (profile?.schema === PLACEMENT_PROFILE_SCHEMA) {
+    const active = readActivePlacementBinding(home, markers.profile, markers.shards);
+    if (!active) throw Error("Sync placement activation is incomplete; inspect retained evidence and run amem migrate --sync-placement --resume.");
+    return { home, floorHash: requirePlacementHomeFloor(home), active };
+  }
+  let base: PlacementBaseV2;
+  try { base = validatePlacementBaseV2(markers.profile, markers.shards); }
+  catch { throw Error("Sync placement base metadata is invalid or unsupported; inspect the active shard/public-prune metadata before rerunning amem migrate --sync-placement --dry-run."); }
+  return { home, floorHash: requirePlacementHomeFloor(home), base };
+}

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

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