@staix/agent-mem 0.20.3 → 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-format.ts

@@ -0,0 +1,182 @@
+import { types } from "node:util";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { SHARDED_V2_FIELDS } from "./shard.ts";
+import type { SourcePrefix } from "./migrate.ts";
+import type { ShardSyncRealm } from "./shard-sync-format.ts";
+
+export const PLACEMENT_FORMAT = "agent-mem.sync-placement/v1";
+export const PLACEMENT_PROFILE_SCHEMA = "agent-mem.profile/v3";
+export const PLACEMENT_SHARDS_SCHEMA = "agent-mem.shards/v3";
+export const PLACEMENT_DESCRIPTOR_SCHEMA = "agent-mem.shard-sync/v3";
+const FOREIGN_FORMAT = "agent-mem.public-prune-witness/v1", METADATA_MAX = 256 * 1024, WIRE_MAX = 64 * 1024, SOURCES_MAX = 20_000;
+
+export class SyncPlacementFormatError extends Error {
+  readonly code = "sync_placement_format";
+  constructor() {
+    super("Sync placement metadata is invalid, unsupported or exceeds its bound. Inspect the saved activation plan and use compatible writers before retrying.");
+    this.name = "SyncPlacementFormatError";
+  }
+}
+export interface PlacementProfile {
+  schema: typeof PLACEMENT_PROFILE_SCHEMA; kind: "generation"; generation: string;
+  foreignPruneFormat: typeof FOREIGN_FORMAT; pruneInputSetHash: string;
+  publicationFormat: typeof PLACEMENT_FORMAT; placementHead: string;
+}
+export interface PlacementShardsFields {
+  generation: string; phase: "active"; selectorRevision: string;
+  sourceGeneration?: string; sources: SourcePrefix[]; machine: { id: string; label: string };
+  legacyCommit?: string; deadLeasesRemoved?: { lease: string; at: string }[];
+}
+export interface PlacementShards extends PlacementShardsFields {
+  schema: typeof PLACEMENT_SHARDS_SCHEMA; publicationFormat: typeof PLACEMENT_FORMAT; placementHead: string;
+}
+export interface PlacementBaseV2 {
+  profile: { schema: "agent-mem.profile/v2"; kind: "generation"; generation: string; foreignPruneFormat: typeof FOREIGN_FORMAT; pruneInputSetHash: string };
+  shards: PlacementShardsFields & { schema: "agent-mem.shards/v2" };
+}
+export type PlacementDescriptor = { schema: typeof PLACEMENT_DESCRIPTOR_SCHEMA; publicationFormat: typeof PLACEMENT_FORMAT }
+  & ({ scope: "user" } | { scope: "project"; key: string });
+export interface PlacementMarkers { profile: PlacementProfile; shards: PlacementShards }
+const fail = (): never => { throw new SyncPlacementFormatError(); };
+const hex = (value: unknown, width: number): value is string => typeof value === "string" && value.length === width && new RegExp(`^[a-f0-9]{${width}}$`).test(value);
+const has = (value: Record<string, unknown>, key: string): boolean => Object.hasOwn(value, key);
+function record(value: unknown, required: readonly string[], optional: readonly string[] = []): Record<string, unknown> {
+  if (!value || typeof value !== "object" || types.isProxy(value) || Array.isArray(value)) return fail();
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null || Object.getOwnPropertySymbols(value).length) return fail();
+  const keys = Object.getOwnPropertyNames(value), allowed = new Set([...required, ...optional]);
+  if (keys.length < required.length || keys.length > allowed.size || required.some(key => !Object.hasOwn(value, key))) return fail();
+  const copy: Record<string, unknown> = Object.create(null);
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!allowed.has(key) || !descriptor || !("value" in descriptor) || !descriptor.enumerable) return fail();
+    copy[key] = descriptor.value;
+  }
+  return copy;
+}
+function text(value: unknown, maximum = METADATA_MAX): string {
+  if (typeof value !== "string" || Buffer.byteLength(value) > maximum) return fail();
+  return value;
+}
+function integer(value: unknown): number { if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) return fail(); return value; }
+function bounded<T>(value: T, maximum = METADATA_MAX): T { if (Buffer.byteLength(canonicalJSON(value) + "\n") > maximum) return fail(); return value; }
+function list(value: unknown, maximum: number): unknown[] {
+  if (types.isProxy(value) || !Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype || Object.getOwnPropertySymbols(value).length) return fail();
+  const length = Object.getOwnPropertyDescriptor(value, "length")?.value;
+  if (!Number.isSafeInteger(length) || length < 0 || length > maximum || Object.getOwnPropertyNames(value).length !== length + 1) return fail();
+  const result: unknown[] = [];
+  for (let index = 0; index < length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) return fail();
+    result.push(descriptor.value);
+  }
+  return result;
+}
+function sourcePrefixes(value: unknown): SourcePrefix[] {
+  const result: SourcePrefix[] = [], seen = new Set<string>(); let bytes = 2;
+  for (const input of list(value, SOURCES_MAX)) {
+    const row = record(input, ["source", "path", "offset", "hash", "tailBytes"], ["commit", "stamp"]);
+    if (typeof row.source !== "string" || !["legacy-local", "legacy-main", "generation"].includes(row.source)) return fail();
+    const path = text(row.path);
+    if (/^(log|local)\/[A-Za-z0-9][A-Za-z0-9._-]*\.jsonl$/.exec(path)?.[0] !== path || row.source === "legacy-main" && !path.startsWith("log/")) return fail();
+    if (!hex(row.hash, 64) || (row.source === "legacy-main" ? !hex(row.commit, 40) : has(row, "commit"))) return fail();
+    const source: SourcePrefix = { source: row.source, path, offset: integer(row.offset), hash: row.hash as string, tailBytes: integer(row.tailBytes) };
+    if (has(row, "commit")) source.commit = row.commit as string;
+    if (has(row, "stamp")) { source.stamp = text(row.stamp); if (source.stamp.length > 1024) return fail(); }
+    const key = `${source.source}:${source.path}`; if (seen.has(key)) return fail(); seen.add(key);
+    bytes += Buffer.byteLength(canonicalJSON(source)) + 1; if (bytes > METADATA_MAX) return fail(); result.push(source);
+  }
+  return result;
+}
+function shardFields(value: Record<string, unknown>, profile: { generation: string }): PlacementShardsFields {
+  if (value.phase !== "active" || value.generation !== profile.generation || !hex(value.selectorRevision, 64)) return fail();
+  const machine = record(value.machine, ["id", "label"]); if (!hex(machine.id, 16)) return fail();
+  const result: PlacementShardsFields = { generation: profile.generation, phase: "active", selectorRevision: value.selectorRevision,
+    sources: sourcePrefixes(value.sources), machine: { id: machine.id, label: text(machine.label) } };
+  if (has(value, "sourceGeneration")) { if (value.sourceGeneration !== profile.generation) return fail(); result.sourceGeneration = profile.generation; }
+  if (has(value, "legacyCommit")) { if (!hex(value.legacyCommit, 40)) return fail(); result.legacyCommit = value.legacyCommit; }
+  if (has(value, "deadLeasesRemoved")) {
+    const audits: { lease: string; at: string }[] = []; let bytes = 2;
+    for (const input of list(value.deadLeasesRemoved, 128)) {
+      const audit = record(input, ["lease", "at"]), lease = text(audit.lease), at = text(audit.at);
+      if (/^[1-9][0-9]*-[a-f0-9]{64}\.json$/.exec(lease)?.[0] !== lease || !Number.isFinite(Date.parse(at)) || new Date(at).toISOString() !== at) return fail();
+      const row = { lease, at }; bytes += Buffer.byteLength(canonicalJSON(row)) + 1; if (bytes > METADATA_MAX) return fail(); audits.push(row);
+    }
+    result.deadLeasesRemoved = audits;
+  }
+  return result;
+}
+function checked<T>(work: () => T): T { try { return work(); } catch { return fail(); } }
+export function validatePlacementProfile(value: unknown): PlacementProfile {
+  return checked<PlacementProfile>(() => {
+    const row = record(value, ["schema", "kind", "generation", "foreignPruneFormat", "pruneInputSetHash", "publicationFormat", "placementHead"]);
+    if (row.schema !== PLACEMENT_PROFILE_SCHEMA || row.kind !== "generation" || !hex(row.generation, 32) || row.foreignPruneFormat !== FOREIGN_FORMAT || !hex(row.pruneInputSetHash, 64) || row.publicationFormat !== PLACEMENT_FORMAT || !hex(row.placementHead, 64)) return fail();
+    return bounded({ schema: PLACEMENT_PROFILE_SCHEMA, kind: "generation", generation: row.generation, foreignPruneFormat: FOREIGN_FORMAT,
+      pruneInputSetHash: row.pruneInputSetHash, publicationFormat: PLACEMENT_FORMAT, placementHead: row.placementHead });
+  });
+}
+export function validatePlacementShards(value: unknown, profile: PlacementProfile): PlacementShards {
+  return checked<PlacementShards>(() => {
+    const bound = validatePlacementProfile(profile), row = record(value, ["schema", "generation", "phase", "selectorRevision", "sources", "machine", "publicationFormat", "placementHead"], ["sourceGeneration", "legacyCommit", "deadLeasesRemoved"]);
+    if (row.schema !== PLACEMENT_SHARDS_SCHEMA || row.publicationFormat !== PLACEMENT_FORMAT || row.placementHead !== bound.placementHead || row.selectorRevision !== hashJSON(bound)) return fail();
+    return bounded({ ...shardFields(row, bound), schema: PLACEMENT_SHARDS_SCHEMA, publicationFormat: PLACEMENT_FORMAT, placementHead: bound.placementHead });
+  });
+}
+export function validatePlacementDescriptor(value: unknown, expectedRealm?: ShardSyncRealm): PlacementDescriptor {
+  return checked<PlacementDescriptor>(() => {
+    const row = record(value, ["schema", "scope", "publicationFormat"], ["key"]);
+    if (row.schema !== PLACEMENT_DESCRIPTOR_SCHEMA || row.publicationFormat !== PLACEMENT_FORMAT) return fail();
+    let result: PlacementDescriptor;
+    if (row.scope === "user" && !has(row, "key")) result = { schema: PLACEMENT_DESCRIPTOR_SCHEMA, scope: "user", publicationFormat: PLACEMENT_FORMAT };
+    else if (row.scope === "project" && typeof row.key === "string" && row.key.length) result = { schema: PLACEMENT_DESCRIPTOR_SCHEMA, scope: "project", key: text(row.key, WIRE_MAX), publicationFormat: PLACEMENT_FORMAT };
+    else return fail();
+    if (expectedRealm !== undefined) {
+      const expected = record(expectedRealm, ["scope"], ["key"]);
+      if (expected.scope !== result.scope || result.scope === "user" && has(expected, "key") || result.scope === "project" && expected.key !== result.key) return fail();
+    }
+    return bounded(result, WIRE_MAX);
+  });
+}
+export function validatePlacementBaseV2(profile: unknown, shards: unknown): PlacementBaseV2 {
+  return checked<PlacementBaseV2>(() => {
+    const p = record(profile, ["schema", "kind", "generation", "foreignPruneFormat", "pruneInputSetHash"]);
+    if (p.schema !== "agent-mem.profile/v2" || p.kind !== "generation" || !hex(p.generation, 32) || p.foreignPruneFormat !== FOREIGN_FORMAT || !hex(p.pruneInputSetHash, 64)) return fail();
+    const normalized: PlacementBaseV2["profile"] = { schema: "agent-mem.profile/v2", kind: "generation", generation: p.generation, foreignPruneFormat: FOREIGN_FORMAT, pruneInputSetHash: p.pruneInputSetHash };
+    // Read imported constants inside the function: generation/shard guard imports may form a module cycle.
+    const s = record(shards, ["schema", "generation", "phase", "selectorRevision", "sources", "machine"], SHARDED_V2_FIELDS.filter(key => !["schema", "generation", "phase", "selectorRevision", "sources", "machine"].includes(key)));
+    if (s.schema !== "agent-mem.shards/v2" || s.selectorRevision !== hashJSON(normalized)) return fail();
+    return { profile: bounded(normalized), shards: bounded({ ...shardFields(s, normalized), schema: "agent-mem.shards/v2" }) };
+  });
+}
+/** Placement upgrade only. Shape/authority checks remain the responsibility of the exact marker-pair validator. */
+export function validatePlacementVersionTransition(fromSchema: unknown, toSchema: unknown): void {
+  const families = ["agent-mem.profile", "agent-mem.shards", "agent-mem.shard-sync"];
+  for (const family of families) if (toSchema === `${family}/v3` && [1, 2, 3].some(version => fromSchema === `${family}/v${version}`)) return;
+  fail();
+}
+export function validatePlacementMarkerTransition(oldProfile: unknown, oldShards: unknown, newProfile: unknown, newShards: unknown): PlacementMarkers {
+  return checked<PlacementMarkers>(() => {
+    const base = validatePlacementBaseV2(oldProfile, oldShards), profile = validatePlacementProfile(newProfile), shards = validatePlacementShards(newShards, profile);
+    const { schema: _p, publicationFormat: _pf, placementHead: _ph, ...profileRest } = profile;
+    const { schema: _bp, ...baseProfileRest } = base.profile;
+    const { schema: _s, selectorRevision: _sr, publicationFormat: _sf, placementHead: _sh, ...shardsRest } = shards;
+    const { schema: _bs, selectorRevision: _bsr, ...baseShardsRest } = base.shards;
+    if (canonicalJSON(profileRest) !== canonicalJSON(baseProfileRest) || canonicalJSON(shardsRest) !== canonicalJSON(baseShardsRest)) return fail();
+    return { profile, shards };
+  });
+}
+function decode<T>(bytes: Uint8Array, maximum: number, validate: (value: unknown) => T): T {
+  return checked(() => {
+    if (types.isProxy(bytes) || !types.isUint8Array(bytes)) return fail();
+    const prototype = Object.getPrototypeOf(Uint8Array.prototype);
+    const intrinsic = (key: string) => Object.getOwnPropertyDescriptor(prototype, key)!.get!.call(bytes);
+    const size = intrinsic("byteLength") as number;
+    if (!size || size > maximum) return fail();
+    const view = new Uint8Array(intrinsic("buffer") as ArrayBuffer, intrinsic("byteOffset") as number, size);
+    const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(view), result = validate(JSON.parse(text));
+    if (canonicalJSON(result) + "\n" !== text) return fail(); return result;
+  });
+}
+export const decodePlacementProfile = (bytes: Uint8Array): PlacementProfile => decode(bytes, METADATA_MAX, validatePlacementProfile);
+export const decodePlacementShards = (bytes: Uint8Array, profile: PlacementProfile): PlacementShards => decode(bytes, METADATA_MAX, value => validatePlacementShards(value, profile));
+export const decodePlacementDescriptor = (bytes: Uint8Array, expectedRealm?: ShardSyncRealm): PlacementDescriptor => decode(bytes, WIRE_MAX, value => validatePlacementDescriptor(value, expectedRealm));

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

@@ -0,0 +1,95 @@
+/** Pure Git object planning. Bytes are unchanged object bodies; no object is installed or published here. */
+import { createHash } from "node:crypto";
+import { types } from "node:util";
+import { PUBLIC_PRUNE_REPLAY_MAX_BYTES } from "./public-prune-input-chain.ts";
+import { decodePlacementTransportDescriptor, decodeShardManifest, isShardManifestPath, SHARD_PACK_MAX_BYTES, type ShardSyncRealm } from "./shard-sync-format.ts";
+
+export interface PlannedGitObject { type: "blob" | "tree" | "commit"; oid: string; bytes: Buffer; path: string | null }
+export interface PlacementGitObjects { objects: PlannedGitObject[]; tree: string; commit: string }
+export class PlacementGitObjectError extends Error {
+  constructor() { super("Sync placement Git objects are invalid or exceed supported bounds; rebuild the exact verified publication plan."); this.name = "PlacementGitObjectError"; }
+}
+function fail(): never { throw new PlacementGitObjectError(); }
+const oid = (v: unknown): v is string => typeof v === "string" && v.length === 40 && /^[a-f0-9]+$/.test(v);
+const PACK = /^rows\/([a-f0-9]{64})\/([a-f0-9]{64})\.jsonl$/;
+const hash = (v: Uint8Array) => createHash("sha256").update(v).digest("hex");
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const getBuffer = Object.getOwnPropertyDescriptor(typedArrayPrototype, "buffer")!.get!;
+const getOffset = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteOffset")!.get!;
+const getLength = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteLength")!.get!;
+const mapSize = Object.getOwnPropertyDescriptor(Map.prototype, "size")!.get!;
+interface TreeNode { directories: Map<string, TreeNode>; blobs: Map<string, string> }
+function node(): TreeNode { return { directories: new Map(), blobs: new Map() }; }
+function object(type: PlannedGitObject["type"], bytes: Buffer, path: string | null): PlannedGitObject {
+  return { type, oid: createHash("sha1").update(`${type} ${bytes.length}\0`).update(bytes).digest("hex"), bytes, path };
+}
+/** Exact Git object bodies and identities, with frozen commit metadata and no-op tree reuse.
+ * Retained public bytes share the existing replay bound; new source's separate 8MiB allowance is the caller's proof. */
+export function compilePlacementGitObjects(files: ReadonlyMap<string, Uint8Array>, parent: string | null, createdUnixSeconds: number,
+  previous?: { tree: string; commit: string }): PlacementGitObjects {
+  try { return compile(files, parent, createdUnixSeconds, previous); } catch { return fail(); }
+}
+function compile(files: ReadonlyMap<string, Uint8Array>, parent: string | null, createdUnixSeconds: number,
+  previous?: { tree: string; commit: string }): PlacementGitObjects {
+  if (!files || typeof files !== "object" || types.isProxy(files) || Object.getPrototypeOf(files) !== Map.prototype
+    || !Number.isSafeInteger(createdUnixSeconds) || createdUnixSeconds < 0 || parent !== null && !oid(parent)) return fail();
+  const count = mapSize.call(files);
+  if (!Number.isSafeInteger(count) || count < 1 || count > 20000) return fail();
+  if (previous !== undefined) {
+    if (!previous || typeof previous !== "object" || types.isProxy(previous) || Object.getOwnPropertySymbols(previous).length) return fail();
+    const fields = Object.getOwnPropertyDescriptors(previous);
+    if (Object.keys(fields).sort().join() !== "commit,tree" || !fields.tree || !fields.commit || !("value" in fields.tree) || !("value" in fields.commit)
+      || !oid(fields.tree.value) || !oid(fields.commit.value)) return fail();
+    previous = { tree: fields.tree.value, commit: fields.commit.value };
+  }
+  const entries: { path: string; bytes: Buffer }[] = []; let total = 0;
+  for (const [path, value] of Map.prototype.entries.call(files) as Iterable<[unknown, unknown]>) {
+    if (typeof path !== "string" || types.isProxy(value) || !(value instanceof Uint8Array)) return fail();
+    const pack = PACK.exec(path), validPack = pack?.[0] === path;
+    if (path !== "shard.json" && !validPack && !isShardManifestPath(path)) return fail();
+    const length = getLength.call(value) as number, maximum = validPack ? SHARD_PACK_MAX_BYTES : 64 * 1024;
+    if (length < 1 || length > maximum || (total += length) > PUBLIC_PRUNE_REPLAY_MAX_BYTES) return fail();
+    const bytes = Buffer.from(Buffer.from(getBuffer.call(value) as ArrayBuffer, getOffset.call(value) as number, length));
+    if (bytes.at(-1) !== 10 || validPack && hash(bytes) !== pack![2]) return fail();
+    if (isShardManifestPath(path)) decodeShardManifest(path, bytes);
+    if (path === "shard.json") {
+      const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)) as Record<string, unknown>;
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return fail();
+      const realm: ShardSyncRealm = parsed.scope === "user" ? { scope: "user" }
+        : parsed.scope === "project" && typeof parsed.key === "string" ? { scope: "project", key: parsed.key } : fail();
+      decodePlacementTransportDescriptor(bytes, realm);
+    }
+    entries.push({ path, bytes });
+  }
+  if (entries.length !== count || !entries.some(entry => entry.path === "shard.json")) return fail();
+  entries.sort((a,b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  const objects: PlannedGitObject[] = [], trees: PlannedGitObject[] = [], root = node();
+  for (const entry of entries) {
+    const blob = object("blob", entry.bytes, entry.path); objects.push(blob);
+    const parts = entry.path.split("/"); let target = root;
+    for (const name of parts.slice(0, -1)) { if (target.blobs.has(name)) return fail(); let next = target.directories.get(name); if (!next) target.directories.set(name, next = node()); target = next; }
+    const name = parts.at(-1)!; if (target.directories.has(name) || target.blobs.has(name)) return fail(); target.blobs.set(name, blob.oid);
+  }
+  const buildTree = (tree: TreeNode, path: string): string => {
+    const children: { name: string; oid: string; directory: boolean }[] = [...tree.blobs].map(([name, id]) => ({ name, oid: id, directory: false }));
+    for (const [name, directory] of [...tree.directories].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0))
+      children.push({ name, oid: buildTree(directory, path ? `${path}/${name}` : name), directory: true });
+    children.sort((a,b) => Buffer.compare(Buffer.from(a.name + (a.directory ? "/" : "")), Buffer.from(b.name + (b.directory ? "/" : ""))));
+    let length = 0; const chunks: Buffer[] = [];
+    for (const child of children) {
+      const prefix = Buffer.from(`${child.directory ? "40000" : "100644"} ${child.name}\0`);
+      length += prefix.length + 20; if (length > SHARD_PACK_MAX_BYTES) return fail(); chunks.push(prefix, Buffer.from(child.oid, "hex"));
+    }
+    const result = object("tree", Buffer.concat(chunks, length), path); trees.push(result); return result.oid;
+  };
+  const tree = buildTree(root, "");
+  trees.sort((a,b) => (b.path ? b.path.split("/").length : 0) - (a.path ? a.path.split("/").length : 0)
+    || (a.path! < b.path! ? -1 : a.path! > b.path! ? 1 : 0));
+  objects.push(...trees);
+  if (previous?.tree === tree) return { objects, tree, commit: previous.commit };
+  const identity = `agent-mem <agent-mem@sync.invalid> ${createdUnixSeconds} +0000`;
+  const body = Buffer.from(`tree ${tree}\n${parent === null ? "" : `parent ${parent}\n`}author ${identity}\ncommitter ${identity}\n\nmemory: placement shard append\n`);
+  if (body.length > 64 * 1024) return fail();
+  const commit = object("commit", body, null); objects.push(commit);
+  return { objects, tree, commit: commit.oid };
+}

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

@@ -0,0 +1,104 @@
+import { readActivePlacementBinding } from "./sync-placement-active.ts";
+import { types } from "node:util";
+/** Closed activation metadata admits v3 readers; publication still requires full journal/source/policy proof. */
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, type BigIntStats } from "node:fs";
+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"; }
+}
+class MarkerChanged extends Error {}
+const same = (left: BigIntStats, right: BigIntStats) => left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+function readMarker(file: string): unknown | undefined {
+  for (let attempt = 0; attempt < 6; attempt++) {
+    let fd: number | undefined;
+    try {
+      const before = lstatSync(file, { bigint: true, throwIfNoEntry: false });
+      if (!before) return undefined;
+      if (!before.isFile() || before.isSymbolicLink() || before.size > BigInt(LOCAL_METADATA_MAX_BYTES)) throw new SyncPlacementRuntimeError(PLACEMENT_MARKER_REFUSAL);
+      fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+      const opened = fstatSync(fd, { bigint: true });
+      if (!same(before, opened)) throw new MarkerChanged();
+      const bytes = Buffer.alloc(Number(opened.size) + 1); let count = 0;
+      while (count < bytes.length) { const read = readSync(fd, bytes, count, bytes.length - count, count); if (!read) break; count += read; }
+      const after = fstatSync(fd, { bigint: true }), named = lstatSync(file, { bigint: true, throwIfNoEntry: false });
+      if (count !== Number(opened.size) || !same(opened, after) || !named || named.isSymbolicLink() || !same(opened, named)) throw new MarkerChanged();
+      return JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes.subarray(0, count)));
+    } catch (error) { if (error instanceof MarkerChanged && attempt < 5) continue; throw new SyncPlacementRuntimeError(PLACEMENT_MARKER_REFUSAL); }
+    finally { if (fd !== undefined) closeSync(fd); }
+  }
+  throw new SyncPlacementRuntimeError(PLACEMENT_MARKER_REFUSAL);
+}
+export function readPlacementRuntimeMarkers(home: string): { profile: unknown | undefined; shards: unknown | undefined } {
+  return { profile: readMarker(join(home, "profile.json")), shards: readMarker(join(home, "shards.json")) };
+}
+function schema(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  return Object.getOwnPropertyDescriptor(value, "schema")?.value;
+}
+function plainMarker(value: unknown): boolean {
+  if (value === undefined) return true;
+  if (!value || typeof value !== "object" || Array.isArray(value) || types.isProxy(value) || Object.getOwnPropertySymbols(value).length) return false;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return false;
+  return Object.values(Object.getOwnPropertyDescriptors(value)).every(field => "value" in field && field.enumerable);
+}
+/** Pure dispatch, so generation's active selector reader need not recursively call readSelector. */
+export function placementMarkerRefusal(profile: unknown, shards: unknown): string | undefined {
+  if (!plainMarker(profile) || !plainMarker(shards)) return PLACEMENT_MARKER_REFUSAL;
+  if (schema(profile) === PLACEMENT_PROFILE_SCHEMA || schema(shards) === PLACEMENT_SHARDS_SCHEMA) {
+    try { validatePlacementShards(shards, validatePlacementProfile(profile)); }
+    catch { return PLACEMENT_MARKER_REFUSAL; }
+    return PLACEMENT_STAGE1_REFUSAL;
+  }
+  if (!legacyProfileMarkerShape(profile) || !legacyShardMarkerShape(shards)) return PLACEMENT_MARKER_REFUSAL;
+  return undefined;
+}
+/** Selector preflight only recognizes v3. Legacy malformed/split metadata must retain its existing reader/recovery path. */
+// This narrow probe is not a data/transport gate; effects must still use the full runtime guard.
+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 pending ? PLACEMENT_ACTIVATION_PENDING : fenced ? PLACEMENT_MARKER_REFUSAL : undefined;
+  const refusal = placementMarkerRefusal(profile, shards);
+  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 });
+  if (!root) return false;
+  if (root.isSymbolicLink() || !root.isDirectory() || root.uid !== process.getuid?.() || (root.mode & 0o077) !== 0) return true;
+  return lstatSync(join(home, "sync-placement", "active.json"), { throwIfNoEntry: false }) !== undefined;
+}
+/** 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), 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 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 ?? (pending ? PLACEMENT_ACTIVATION_PENDING : fenced ? PLACEMENT_MARKER_REFUSAL : undefined); }
+  catch { return PLACEMENT_MARKER_REFUSAL; }
+}
+export function assertPlacementRuntime(home: string): void {
+  const refusal = placementRuntimeRefusal(home); if (refusal) throw new SyncPlacementRuntimeError(refusal);
+}