@staix/agent-mem 0.20.2 → 0.21.0

package/src/memory/public-prune-advance.ts

@@ -1,3 +1,4 @@
+import { validatePlacementProfile, validatePlacementShards } from "./sync-placement-format.ts";
 /** Already-v2 monotone commit. Native rows stay unchanged; readers apply the proved growing mask on rebind. */
 import { createHash } from "node:crypto";
 import { constants, closeSync, fsyncSync, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
@@ -73,10 +74,15 @@ function checked(value: unknown, home: string): AdvanceIntent {
   guard(value.schema === "agent-mem.public-prune-advance/v1" && value.home === home && hex(value.generation,32) && hex(value.expectedRevision,64));
   for(const key of ["previousProfile","previousShards","finalProfile","finalShards"])guard(typeof value[key] === "string");
   const previous=JSON.parse(value.previousProfile as string), oldShards=JSON.parse(value.previousShards as string), final=JSON.parse(value.finalProfile as string), shards=JSON.parse(value.finalShards as string), view=validatePublicPruneView(value.view);
-  guard(object(previous) && exact(previous,["schema","kind","generation","foreignPruneFormat","pruneInputSetHash"]) && previous.kind === "generation" && hex(previous.pruneInputSetHash,64) && previous.schema === "agent-mem.profile/v2" && previous.generation === value.generation && previous.foreignPruneFormat === "agent-mem.public-prune-witness/v1" && hashJSON(previous) === value.expectedRevision);
-  guard(object(final) && exact(final,["schema","kind","generation","foreignPruneFormat","pruneInputSetHash"]) && final.schema === previous.schema && final.kind === "generation" && final.generation === value.generation && final.foreignPruneFormat === previous.foreignPruneFormat && final.pruneInputSetHash === publicPruneViewHash(view));
+  const placed = previous?.schema === "agent-mem.profile/v3";
+  const profileFields = ["schema","kind","generation","foreignPruneFormat","pruneInputSetHash", ...(placed ? ["publicationFormat","placementHead"] : [])];
+  const shardFields: readonly string[] = [...SHARDED_V2_FIELDS, ...(placed ? ["publicationFormat","placementHead"] : [])];
+  if (placed) { validatePlacementShards(oldShards, validatePlacementProfile(previous)); validatePlacementShards(shards, validatePlacementProfile(final)); }
+  guard(object(previous) && exact(previous,profileFields) && previous.kind === "generation" && hex(previous.pruneInputSetHash,64) && previous.schema === (placed ? "agent-mem.profile/v3" : "agent-mem.profile/v2") && previous.generation === value.generation && previous.foreignPruneFormat === "agent-mem.public-prune-witness/v1" && hashJSON(previous) === value.expectedRevision);
+  guard(object(final) && exact(final,profileFields) && final.schema === previous.schema && final.kind === "generation" && final.generation === value.generation && final.foreignPruneFormat === previous.foreignPruneFormat && final.pruneInputSetHash === publicPruneViewHash(view));
+  if (placed) guard(final.publicationFormat === previous.publicationFormat && final.placementHead === previous.placementHead);
   guard(view.receivingGeneration === value.generation && canonicalJSON(final)+"\n" === value.finalProfile && hashJSON(final) === value.finalProfileHash && hashJSON(shards) === value.finalShardsHash && canonicalJSON(shards)+"\n" === value.finalShards);
-  guard(object(oldShards) && object(shards) && Object.keys(oldShards).every(key=>(SHARDED_V2_FIELDS as readonly string[]).includes(key)) && Object.keys(shards).every(key=>(SHARDED_V2_FIELDS as readonly string[]).includes(key)) && oldShards.phase === "active" && oldShards.generation === value.generation && oldShards.schema === "agent-mem.shards/v2" && oldShards.selectorRevision === value.expectedRevision && shards.selectorRevision === value.finalProfileHash);
+  guard(object(oldShards) && object(shards) && Object.keys(oldShards).every(key=>shardFields.includes(key)) && Object.keys(shards).every(key=>shardFields.includes(key)) && oldShards.phase === "active" && oldShards.generation === value.generation && oldShards.schema === (placed ? "agent-mem.shards/v3" : "agent-mem.shards/v2") && oldShards.selectorRevision === value.expectedRevision && shards.selectorRevision === value.finalProfileHash);
   const {selectorRevision:_old,...a}=oldShards,{selectorRevision:_new,...b}=shards;guard(canonicalJSON(a)===canonicalJSON(b));
   guard(Array.isArray(value.bindings) && value.bindings.length <= 1024 && object(value.root) && exact(value.root,["dev","ino","aliasesHash","machineHash"]) && hex(value.root.aliasesHash,64) && hex(value.root.machineHash,64));
   let prior="";for(const item of value.bindings){guard(object(item)&&exact(item,["key","dir","dev","ino","metadata"])&&typeof item.key==="string"&&item.key>prior&&item.dir===realmDir(home,item.key)&&hex(item.metadata,64));prior=item.key;}
@@ -91,7 +97,7 @@ function proofs(intent: AdvanceIntent): (()=>void)[] {
   for(const [key,set] of Object.entries(intent.view.realms)){
     if(old.realms[key]===set)continue;
     const binding=intent.bindings.find(item=>item.key===key);guard(binding);
-    const load=createPublicPruneReplayCache({dir:binding.dir,realm:key==="user"?{scope:"user"}:{scope:"project",key:key.slice(8)},receivingGeneration:intent.generation,inputSetHash:set});
+    const load=createPublicPruneReplayCache({dir:binding.dir,realm:key==="user"?{scope:"user"}:{scope:"project",key:key.slice(8)},receivingGeneration:intent.generation,inputSetHash:set,...(previous.schema==="agent-mem.profile/v3"?{publicationFormat:"agent-mem.sync-placement/v1" as const}:{})});
     const check=()=>{const proof:PublicPruneProjection=load();guard(old.realms[key]===undefined||proof.commitments.includes(old.realms[key]!));};check();checks.push(check);
   }
   return checks;
@@ -128,7 +134,7 @@ function run(intent: AdvanceIntent, provided: readonly MutationHandle[]|undefine
 }
 export async function advancePublicPruneView(options: PublicPruneAdvanceOptions):Promise<PublicPruneAdvanceResult>{
   const home=realPath(options.memoryDir),root=owned(home,true),selection=readSelector(home),profile=selection.selector;
-  guard(profile?.schema==="agent-mem.profile/v2"&&selection.revision===options.expectedRevision);
+  guard((profile?.schema==="agent-mem.profile/v2"||profile?.schema==="agent-mem.profile/v3")&&selection.revision===options.expectedRevision);
   const view=validatePublicPruneView(options.view);guard(view.receivingGeneration===profile.generation);
   const previousProfile=raw(join(home,"profile.json")),previousShards=raw(join(home,"shards.json")),old=readPublicPruneViewForActivation(home,profile.pruneInputSetHash,profile.generation);
   const bindings:Binding[]=[];

package/src/memory/public-prune-inputs.ts

@@ -7,7 +7,7 @@ import { acquireMutation, assertMutationHandle, type MutationHandle } from "./mu
 import { realPath } from "./platform.ts";
 import { entryId, type Entry } from "./store.ts";
 import { prunePayloadHash } from "./prune.ts";
-import { shardSyncRef, type ShardSyncRealm } from "./shard-sync-format.ts";
+import { decodePlacementTransportDescriptor, shardSyncRef, type ShardSyncRealm } from "./shard-sync-format.ts";
 import { verifyPublicPruneWitness, type VerifiedPublicPruneWitness } from "./public-prune-witness.ts";
 
 import { PUBLIC_PRUNE_INPUT_MAX_BYTES, PUBLIC_PRUNE_REPLAY_MAX_BYTES, PUBLIC_PRUNE_MAX_SETS, PublicPruneInputError, validatePublicPruneInputSet, type PublicPruneInputSetV1 } from "./public-prune-input-chain.ts";
@@ -20,7 +20,7 @@ export interface PublicPruneInputV1 {
   schema: "agent-mem.public-prune-input/v1"; realm: ShardSyncRealm; receivingGeneration: string;
   selectorRevision: string; witnessHash: string; source: Source;
 }
-export interface PublicPruneBinding { realm: ShardSyncRealm; receivingGeneration: string; selectorRevision: string; inputSetHash: string | null }
+export interface PublicPruneBinding { publicationFormat?: "agent-mem.sync-placement/v1"; realm: ShardSyncRealm; receivingGeneration: string; selectorRevision: string; inputSetHash: string | null }
 /** Complete Git object bytes, including the uncompressed '<type> <size>\0' header. */
 export interface PublicPruneObject { oid: string; bytes: Uint8Array }
 export interface PublicPruneInputOptions {
@@ -32,7 +32,7 @@ declare const planBrand: unique symbol;
 export interface PublicPruneInputPlan { readonly [planBrand]: true }
 export interface PublicPruneInputRegistration { inputHash?: string; inputSetHash: string; previous: string | null }
 export interface PublicPruneReplayInput {
-  dir: string; realm: ShardSyncRealm; receivingGeneration: string; inputSetHash: string;
+  dir: string; realm: ShardSyncRealm; receivingGeneration: string; inputSetHash: string; publicationFormat?: "agent-mem.sync-placement/v1";
   nativeTargets?: readonly string[]; ordinary?: readonly Entry[];
 }
 export interface PublicPruneProjection {
@@ -68,9 +68,10 @@ export function validatePublicPruneInput(v: unknown): PublicPruneInputV1 {
   });
 }
 function binding(v: PublicPruneBinding): PublicPruneBinding {
-  guard(object(v) && exact(v, ["realm", "receivingGeneration", "selectorRevision", "inputSetHash"]));
+  guard(object(v) && exact(v, ["realm", "receivingGeneration", "selectorRevision", "inputSetHash", ...(v.publicationFormat === undefined ? [] : ["publicationFormat"])]));
+  guard(v.publicationFormat === undefined || v.publicationFormat === "agent-mem.sync-placement/v1");
   guard(hex(v.receivingGeneration, 32) && (hex(v.selectorRevision, 64) || v.selectorRevision === "absent") && (v.inputSetHash === null || hex(v.inputSetHash, 64)));
-  return { realm: selectedRealm(v.realm), receivingGeneration: v.receivingGeneration, selectorRevision: v.selectorRevision, inputSetHash: v.inputSetHash };
+  return { realm: selectedRealm(v.realm), receivingGeneration: v.receivingGeneration, selectorRevision: v.selectorRevision, inputSetHash: v.inputSetHash, ...(v.publicationFormat ? {publicationFormat:v.publicationFormat} : {}) };
 }
 function json(bytes: Buffer): unknown {
   guard(bytes.length > 0 && bytes.length <= PUBLIC_PRUNE_INPUT_MAX_BYTES, "resource");
@@ -99,7 +100,7 @@ function treeEntries(body: Buffer): Map<string, { mode: string; oid: string }> {
   return entries;
 }
 /** Exact path closure only. Sibling object bodies are neither requested nor retained. */
-function graph(input: PublicPruneInputV1, load: (oid: string) => Buffer): { proof: VerifiedPublicPruneWitness; used: Set<string> } {
+function graph(input: PublicPruneInputV1, load: (oid: string) => Buffer, publicationFormat?: "agent-mem.sync-placement/v1"): { proof: VerifiedPublicPruneWitness; used: Set<string> } {
   const used = new Set<string>(), cache = new Map<string, GitObject>(), trees = new Map<string, ReturnType<typeof treeEntries>>(); let total = 0;
   const get = (oid: string, type: GitObject["type"]): GitObject => {
     let item = cache.get(oid);
@@ -121,8 +122,8 @@ function graph(input: PublicPruneInputV1, load: (oid: string) => Buffer): { proo
     }
     return { oid, body: get(oid, "blob").body };
   };
-  const expected = { schema: "agent-mem.shard-sync/v2", ...input.realm };
-  guard(canonicalJSON(json(path("shard.json").body)) === canonicalJSON(expected));
+  const version = decodePlacementTransportDescriptor(path("shard.json").body, input.realm);
+  guard(version === "v2" || version === "v3" && publicationFormat === "agent-mem.sync-placement/v1");
   const manifest = path(input.source.manifestPath); guard(manifest.oid === input.source.manifestBlob);
   const raw = json(manifest.body); guard(object(raw) && Array.isArray(raw.witnesses) && raw.witnesses.length <= 64 && object(raw.pruneOccurrence));
   const refs = [raw.pruneOccurrence, ...raw.witnesses], packs = new Map<string, { pack: string; blob: string; bytes: Buffer }>();
@@ -151,7 +152,7 @@ export function preparePublicPruneInput(options: PublicPruneInputOptions): Publi
       }
       input = validatePublicPruneInput({ schema: "agent-mem.public-prune-input/v1", realm: expected.realm, receivingGeneration: expected.receivingGeneration,
         selectorRevision: expected.selectorRevision, witnessHash: value.witnessHash, source: value.source });
-      const checked = graph(input, oid => { const bytes = objects.get(oid); guard(bytes); return bytes; });
+      const checked = graph(input, oid => { const bytes = objects.get(oid); guard(bytes); return bytes; }, expected.publicationFormat);
       guard(checked.used.size === objects.size); // never retain whole sibling subtrees or unrelated private bodies
     }
     guard(canonicalJSON(binding(options.current())) === canonicalJSON(expected), "binding");
@@ -202,7 +203,7 @@ function replay(input: Omit<PublicPruneReplayInput, "dir">, load: Loader): Publi
   for (const member of members) {
     const descriptor = validatePublicPruneInput(json(data("input", member)));
     guard(hashJSON(descriptor) === member && descriptor.receivingGeneration === input.receivingGeneration && canonicalJSON(descriptor.realm) === canonicalJSON(selected));
-    const { proof } = graph(descriptor, oid => data("object", oid)), prune = proof.manifest.prune, hash = prunePayloadHash(prune), key = `${canonicalJSON(selected)}:${prune.id}`;
+    const { proof } = graph(descriptor, oid => data("object", oid), input.publicationFormat), prune = proof.manifest.prune, hash = prunePayloadHash(prune), key = `${canonicalJSON(selected)}:${prune.id}`;
     guard(!identities.has(key) || identities.get(key) === hash); identities.set(key, hash);
     for (const ref of proof.manifest.witnesses) { guard(!rowHashes.has(ref.id) || rowHashes.get(ref.id) === ref.rowHash); rowHashes.set(ref.id, ref.rowHash); }
     for (const target of prune.targets) targets.add(target.id);
@@ -312,7 +313,7 @@ export function persistPublicPruneInput(plan: PublicPruneInputPlan, options: { o
     for (const suffix of ["", "-wal", "-shm", "-journal"]) { const stat = lstatSync(join(dir, "mutation-lock.db" + suffix), { throwIfNoEntry: false }); if (stat) privateStat(stat); }
     const release = options.mutation ?? acquireMutation(dir); guard(release); assertMutationHandle(release, dir); try {
       current(); assertMutationHandle(release, dir); recoverLinkedTemps(dir, release); current(); const previous = expected.inputSetHash;
-      const members = previous ? replay({ realm: expected.realm, receivingGeneration: expected.receivingGeneration, inputSetHash: previous }, (kind, id) => read(dir, kind, id)).inputs : [];
+      const members = previous ? replay({ realm: expected.realm, receivingGeneration: expected.receivingGeneration, ...(expected.publicationFormat ? {publicationFormat:expected.publicationFormat} : {}), inputSetHash: previous }, (kind, id) => read(dir, kind, id)).inputs : [];
       const inputHash = prepared.input && hashJSON(prepared.input), includes = inputHash !== undefined && members.includes(inputHash);
       const set: PublicPruneInputSetV1 = { schema: "agent-mem.public-prune-input-set/v1", receivingGeneration: expected.receivingGeneration,
         previous, inputs: [...new Set([...members, ...(inputHash ? [inputHash] : [])])].sort() };
@@ -323,7 +324,7 @@ export function persistPublicPruneInput(plan: PublicPruneInputPlan, options: { o
       if (prepared.input && inputHash) writes.set(`input:${inputHash}`, { kind: "input", id: inputHash, bytes: Buffer.from(canonicalJSON(prepared.input) + "\n") });
       if (inputSetHash !== previous) writes.set(`set:${inputSetHash}`, { kind: "set", id: inputSetHash, bytes: Buffer.from(canonicalJSON(set) + "\n") });
       // Preflight the complete future committed view and byte budget before the first archive write.
-      replay({ realm: expected.realm, receivingGeneration: expected.receivingGeneration, inputSetHash }, (kind, id) => writes.get(`${kind}:${id}`)?.bytes ?? read(dir, kind, id));
+      replay({ realm: expected.realm, receivingGeneration: expected.receivingGeneration, ...(expected.publicationFormat ? {publicationFormat:expected.publicationFormat} : {}), inputSetHash }, (kind, id) => writes.get(`${kind}:${id}`)?.bytes ?? read(dir, kind, id));
       capacity(dir, writes); current();
       for (const value of writes.values()) { assertMutationHandle(release, dir); write(dir, value.kind, value.id, value.bytes, options.observe); current(); assertMutationHandle(release, dir); }
       return { ...(inputHash ? { inputHash } : {}), inputSetHash, previous };
@@ -386,12 +387,12 @@ function batchOverlay(batch: PreparedBatch): { writes: Map<string, ArchiveWrite>
   };
   const load: Loader = (kind, id) => writes.get(`${kind}:${id}`)?.bytes ?? read(batch.dir, kind, id);
   let previous = expected.inputSetHash, lastInputHash: string | undefined;
-  let members = previous ? replay({ realm: expected.realm, receivingGeneration: expected.receivingGeneration, inputSetHash: previous }, load).inputs : [];
+  let members = previous ? replay({ realm: expected.realm, receivingGeneration: expected.receivingGeneration, ...(expected.publicationFormat ? {publicationFormat:expected.publicationFormat} : {}), inputSetHash: previous }, load).inputs : [];
   for (const prepared of batch.inputs) {
     guard(prepared.input); const input = prepared.input, inputHash = hashJSON(input); lastInputHash = inputHash;
     // Every descriptor stays bound to the actual initial selector revision, never a simulated callback.
     guard(canonicalJSON(prepared.binding) === canonicalJSON(expected));
-    const checked = graph(input, oid => { const bytes = prepared.objects.get(oid); guard(bytes); return bytes; });
+    const checked = graph(input, oid => { const bytes = prepared.objects.get(oid); guard(bytes); return bytes; }, expected.publicationFormat);
     guard(checked.used.size === prepared.objects.size);
     for (const [oid, bytes] of prepared.objects) add("object", oid, bytes);
     add("input", inputHash, Buffer.from(canonicalJSON(input) + "\n"));
@@ -405,7 +406,7 @@ function batchOverlay(batch: PreparedBatch): { writes: Map<string, ArchiveWrite>
     const set: PublicPruneInputSetV1 = { schema: "agent-mem.public-prune-input-set/v1", receivingGeneration: expected.receivingGeneration, previous: null, inputs: [] };
     previous = hashJSON(set); add("set", previous, Buffer.from(canonicalJSON(set) + "\n"));
   }
-  replay({ realm: expected.realm, receivingGeneration: expected.receivingGeneration, inputSetHash: previous }, load);
+  replay({ realm: expected.realm, receivingGeneration: expected.receivingGeneration, ...(expected.publicationFormat ? {publicationFormat:expected.publicationFormat} : {}), inputSetHash: previous }, load);
   // capacity removes already-complete candidates only from its private working copy.
   capacity(batch.dir, writes);
   return { writes, result: { inputSetHash: previous, previous: expected.inputSetHash, ...(lastInputHash ? { inputHash: lastInputHash } : {}) } };
@@ -449,7 +450,7 @@ export function persistPublicPruneInputBatch(batch: PublicPruneInputBatch, optio
       batchCurrent(prepared, mutation); write(prepared.dir, item.kind, item.id, item.bytes, options?.observe); batchCurrent(prepared, mutation);
     }
     // Validate installed bytes too, including exact retries and interrupted prior attempts.
-    replay({ realm: prepared.binding.realm, receivingGeneration: prepared.binding.receivingGeneration, inputSetHash: result.inputSetHash }, (kind, id) => read(prepared.dir, kind, id));
+    replay({ realm: prepared.binding.realm, receivingGeneration: prepared.binding.receivingGeneration, ...(prepared.binding.publicationFormat ? {publicationFormat:prepared.binding.publicationFormat} : {}), inputSetHash: result.inputSetHash }, (kind, id) => read(prepared.dir, kind, id));
     batchCurrent(prepared, mutation); return result;
   });
 }

package/src/memory/shard-sync-applications.ts

@@ -0,0 +1,153 @@
+/** Shared v2/v3 public-prune application preflight and durable view installation. No row import or transport publication. */
+import { createHash } from "node:crypto";
+import { canonicalJSON, readSelector } from "./generation.ts";
+import { advancePublicPruneView } from "./public-prune-advance.ts";
+import { readPublicPruneView, type PublicPruneViewV1 } from "./public-prune-view.ts";
+import { collectPublicPruneGitGraph } from "./shard-sync-graph.ts";
+import { PublicPruneInputError, PUBLIC_PRUNE_REPLAY_MAX_BYTES, PUBLIC_PRUNE_MAX_SETS, preparePublicPruneInputBatch,
+  persistPublicPruneInputBatch, readPublicPruneInputDescriptor, readPublicPruneInputSetChain, reducePublicPruneInputs,
+  type PublicPruneInputOptions } from "./public-prune-inputs.ts";
+import { decodeShardPack, shardSyncRef, SHARD_PACK_MAX_BYTES } from "./shard-sync-format.ts";
+import { shardPrepareHolds, shardSelectorRetention, type ShardSyncApplicationTarget, type ShardSyncApplicationPhase,
+  type ShardSyncHoldReceipt } from "./shard-sync.ts";
+import type { ShardHistory } from "./shard-sync-history.ts";
+import type { MutationHandle } from "./mutation.ts";
+import type { SyncResult } from "./sync.ts";
+import type { PruneRow } from "./prune.ts";
+
+type Target = ShardSyncApplicationTarget;
+export interface ShardApplicationGitObject { type: "commit" | "tree" | "blob"; body: Uint8Array }
+export interface ShardSyncApplicationsOptions {
+  home: string; root: string; url: string; targets: Target[]; homeMutation: MutationHandle;
+  getRevision(): string; setRevision(revision: string): void; check(): void;
+  history(tip: string, target: Target): Promise<ShardHistory>;
+  /** Placement supplies an already audited in-memory candidate before installing Git objects. */
+  candidateHistory(target: Target): Promise<ShardHistory>;
+  assertAncestor(ancestor: string, descendant: string, target: Target): Promise<void>;
+  readObject(oid: string): Promise<ShardApplicationGitObject>;
+  /** Rebind the caller's acquisition cache to these same immutable raw bytes, avoiding a second retained body. */
+  retainGraphObject?(oid: string, rawBytes: Uint8Array): void | Promise<void>;
+  /** Re-prove source/policy stability and update the caller's metadata binding after a legitimate view commit. */
+  afterAdvance(): void | Promise<void>;
+  phase?(phase: ShardSyncApplicationPhase): void | Promise<void>;
+}
+export class ShardSyncApplicationError extends Error {
+  constructor(message: string) { super(message); this.name = "ShardSyncApplicationError"; }
+}
+function refuse(message: string): never { throw new ShardSyncApplicationError(message); }
+const digest = (value: Uint8Array | string) => createHash("sha256").update(value).digest("hex");
+const oid = (value: unknown): value is string => typeof value === "string" && value.length === 40 && /^[a-f0-9]+$/.test(value);
+const realmKey = (target: Target) => target.realm.scope === "user" ? "user" : `project:${target.realm.key}`;
+export class ShardSyncApplications {
+  readonly #options: ShardSyncApplicationsOptions;
+  #boundView?: PublicPruneViewV1;
+  readonly #objects = new Map<string, ShardApplicationGitObject>();
+  readonly #graphs = new Map<string, Uint8Array>();
+  readonly #sets = new Set<string>();
+  #objectBytes = 0;
+  readonly application: NonNullable<SyncResult["pruneApplication"]> = { transport: "unconfirmed", proofComplete: 0, projectionActive: null, nativeApplied: null, held: 0, phase: "preflight" };
+  constructor(options: ShardSyncApplicationsOptions) { this.#options = options; }
+  get boundView(): Readonly<PublicPruneViewV1> | undefined { return this.#boundView && structuredClone(this.#boundView); }
+  async #checked<T>(work: () => T | Promise<T>): Promise<T> { this.#options.check(); const value = await work(); this.#options.check(); return value; }
+  async #proveHoldSource(target: Target, receipt: ShardSyncHoldReceipt): Promise<void> {
+    if (!target.remote) refuse("foreign prune has no selected public source");
+    await this.#checked(() => this.#options.assertAncestor(receipt.source.commit, target.remote!, target));
+    const original = await this.#checked(() => this.#options.history(receipt.source.commit, target)), bytes = original.files.get(receipt.source.pack);
+    if (!bytes || createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex") !== receipt.source.blob
+      || !decodeShardPack(receipt.source.pack, bytes, target.realm, target.generation).some(row => canonicalJSON(row) === canonicalJSON(receipt.row))
+      || receipt.source.ref !== shardSyncRef(target.realm)) refuse("shard sync prune hold source mismatch");
+  }
+  async loadExisting(): Promise<void> {
+    const o = this.#options; o.check();
+    const selected = readSelector(o.home).selector;
+    if ((selected?.schema !== "agent-mem.profile/v2" && selected?.schema !== "agent-mem.profile/v3")
+      || o.targets.some(target => target.generation !== selected.generation)) refuse("selected public-prune profile unavailable");
+    this.#boundView = readPublicPruneView(o.home, selected.pruneInputSetHash, selected.generation);
+    for (const target of o.targets) {
+      target.registered = []; const set = this.#boundView.realms[realmKey(target)]; if (!set) continue;
+      // Shared across selected realms and retries; neither reopening an overlay nor repeating preflight resets the allowance.
+      const chain = readPublicPruneInputSetChain({ dir: target.store.dir, receivingGeneration: target.generation, inputSetHash: set, ...(target.store.profile.publicationFormat ? {publicationFormat:target.store.profile.publicationFormat} : {}) });
+      for (const commitment of chain.commitments) this.#sets.add(`${target.store.dir}:${commitment}`);
+      if (this.#sets.size > PUBLIC_PRUNE_MAX_SETS) throw new PublicPruneInputError("resource");
+      const projection = reducePublicPruneInputs({ dir: target.store.dir, realm: target.realm, receivingGeneration: target.generation, inputSetHash: set, ...(target.store.profile.publicationFormat ? {publicationFormat:target.store.profile.publicationFormat} : {}) });
+      for (const hash of projection.inputs) {
+        const descriptor = readPublicPruneInputDescriptor({ dir: target.store.dir, hash });
+        if (!target.remote || descriptor.source.remoteHash !== digest(o.url)) refuse("registered prune source history disappeared or its remote binding changed");
+        await this.#checked(() => o.assertAncestor(descriptor.source.commit, target.remote!, target));
+        const original = await this.#checked(() => o.history(descriptor.source.commit, target)), manifest = original.manifests.get(descriptor.source.manifestPath);
+        if (!manifest || !manifest.eligible || manifest.blob !== descriptor.source.manifestBlob || descriptor.source.ref !== shardSyncRef(target.realm)
+          || digest(canonicalJSON(manifest.value)) !== descriptor.witnessHash) refuse("registered prune anchor no longer has exact audited evidence");
+        target.registered.push(descriptor);
+      }
+    }
+    o.check();
+  }
+  async #readObject(object: string): Promise<ShardApplicationGitObject> {
+    if (!oid(object)) refuse("Git object identity invalid");
+    const cached = this.#objects.get(object); if (cached) return cached;
+    const value = await this.#checked(() => this.#options.readObject(object));
+    if (!value || !["commit", "tree", "blob"].includes(value.type) || !(value.body instanceof Uint8Array)) refuse("Git object type refused");
+    const limit = value.type === "commit" ? 65536 : SHARD_PACK_MAX_BYTES;
+    if (value.body.length > limit) refuse("Git object exceeds complete evidence bound");
+    const header = Buffer.from(`${value.type} ${value.body.length}\0`), encodedSize = header.length + value.body.length;
+    if (this.#objectBytes + encodedSize > PUBLIC_PRUNE_REPLAY_MAX_BYTES) throw new PublicPruneInputError("resource");
+    if (createHash("sha1").update(header).update(value.body).digest("hex") !== object) refuse("Git object identity mismatch");
+    this.#objectBytes += encodedSize; this.#objects.set(object, value); return value;
+  }
+  async prepare(): Promise<void> {
+    const o = this.#options; o.check(); if (!this.#boundView) refuse("public-prune application preflight is missing");
+    this.application.proofComplete = 0; this.application.held = 0; let plannedSets = this.#sets.size;
+    for (const target of o.targets) {
+      const current = await this.#checked(() => o.candidateHistory(target)); target.manifests = new Map(current.manifests);
+      target.eligible = new Set([...current.manifests.values()].filter(item => item.eligible).map(item => item.row.id)); this.application.proofComplete += target.eligible.size;
+      const initial = this.#boundView.realms[realmKey(target)] ?? null, inputs: NonNullable<PublicPruneInputOptions["input"]>[] = [];
+      for (const record of [...current.manifests.values()].sort((a,b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0)) {
+        if (!record.eligible || record.row.generation === target.generation) continue;
+        const witnessHash = digest(canonicalJSON(record.value)); if (target.registered.some(item => item.witnessHash === witnessHash)) continue;
+        if (++plannedSets > PUBLIC_PRUNE_MAX_SETS) throw new PublicPruneInputError("resource");
+        // A pure candidate is not publication evidence. Foreign anchors must still be in actual selected remote history.
+        if (!target.remote) refuse("foreign prune has no selected public source");
+        await this.#checked(() => o.assertAncestor(record.commit, target.remote!, target));
+        const original = await this.#checked(() => o.history(record.commit, target)), anchor = original.manifests.get(record.path);
+        if (!anchor || !anchor.eligible || anchor.blob !== record.blob || canonicalJSON(anchor.value) !== canonicalJSON(record.value)) refuse("foreign prune anchor lacks exact audited public evidence");
+        const acquired = await this.#checked(() => collectPublicPruneGitGraph({ commit: record.commit, manifestPath: record.path, manifestBlob: record.blob, realm: target.realm, ...(target.store.profile.publicationFormat ? {publicationFormat:target.store.profile.publicationFormat} : {}), readObject: object => this.#readObject(object) }));
+        const objects: { oid: string; bytes: Uint8Array }[] = [];
+        for (const item of acquired) {
+          const prior = this.#graphs.get(item.oid); if (prior && !Buffer.from(prior).equals(item.bytes)) refuse("conflicting Git graph bytes");
+          const bytes = prior ?? item.bytes; this.#graphs.set(item.oid, bytes);
+          const cached = this.#objects.get(item.oid); if (!cached) refuse("Git graph acquisition receipt unavailable");
+          this.#objects.set(item.oid, { type: cached.type, body: bytes.subarray(bytes.indexOf(0) + 1) });
+          if (o.retainGraphObject) await this.#checked(() => o.retainGraphObject!(item.oid, bytes));
+          objects.push({ oid: item.oid, bytes });
+        }
+        inputs.push({ witnessHash, source: { remoteHash: digest(o.url), ref: shardSyncRef(target.realm), commit: record.commit, manifestPath: record.path, manifestBlob: record.blob }, objects });
+      }
+      target.batch = undefined;
+      if (inputs.length) {
+        const binding = { realm: target.realm, receivingGeneration: target.generation, selectorRevision: o.getRevision(), inputSetHash: initial, ...(target.store.profile.publicationFormat ? {publicationFormat:target.store.profile.publicationFormat} : {}) };
+        target.batch = preparePublicPruneInputBatch({ dir: target.store.dir, binding, current: () => { o.check(); return { ...binding, selectorRevision: o.getRevision() }; }, inputs }, target.mutation!);
+      }
+    }
+    await this.#checked(() => shardPrepareHolds(o.targets, o.root, o.url, (target, receipt) => this.#proveHoldSource(target, receipt)));
+    this.application.held = o.targets.reduce((sum, target) => sum + target.holds.length, 0); this.application.phase = "prepared";
+  }
+  async install(): Promise<void> {
+    const o = this.#options; o.check(); if (!this.#boundView) refuse("public-prune application preflight is missing");
+    const realms = { ...this.#boundView.realms };
+    for (const target of o.targets) if (target.batch) {
+      const installed = persistPublicPruneInputBatch(target.batch, { mutation: target.mutation!, observe: () => o.check() }); realms[realmKey(target)] = installed.inputSetHash;
+      if (o.phase) await this.#checked(() => o.phase!("inputs-installed"));
+    }
+    const view: PublicPruneViewV1 = { ...this.#boundView, realms };
+    if (canonicalJSON(view) !== canonicalJSON(this.#boundView)) {
+      for (const target of o.targets) shardSelectorRetention(target, true, true);
+      const result = await advancePublicPruneView({ memoryDir: o.home, view, expectedRevision: o.getRevision(), mutations: [o.homeMutation, ...o.targets.map(target => target.mutation!)] });
+      o.setRevision(result.revision); this.#boundView = view;
+      for (const target of o.targets) target.store.refresh();
+      await o.afterAdvance();
+      if (o.phase) await this.#checked(() => o.phase!("view-committed"));
+    }
+    this.application.projectionActive = o.targets.reduce((sum, target) => sum + [...target.eligible].filter(id => (target.rows.get(id) as PruneRow).generation !== target.generation).length, 0);
+    this.application.phase = "active"; o.check();
+  }
+}

package/src/memory/shard-sync-format.ts

@@ -1,3 +1,5 @@
+import { PLACEMENT_DESCRIPTOR_SCHEMA, validatePlacementDescriptor } from "./sync-placement-format.ts";
+import { PLACEMENT_STAGE1_REFUSAL } from "./sync-placement-guard.ts";
 import { createHash } from "node:crypto";
 import { legacyEntries } from "./bridge.ts";
 import { canonicalJSON, validGeneration } from "./generation.ts";
@@ -50,10 +52,23 @@ function decodeMetadata(bytes: Uint8Array, label: string): Record<string, unknow
 }
 export function decodeShardDescriptor(bytes: Uint8Array, realm: ShardSyncRealm): "v1" | "v2" {
   const label = shardSyncLabel(realm), value = decodeMetadata(bytes, label);
+  if (value.schema === PLACEMENT_DESCRIPTOR_SCHEMA) {
+    try { validatePlacementDescriptor(value, realm); } catch { throw new ShardSyncFormatError(label, "invalid placement descriptor"); }
+    throw new ShardSyncFormatError(label, PLACEMENT_STAGE1_REFUSAL);
+  }
   const version = value.schema === SHARD_SYNC_SCHEMA ? "v1" : value.schema === SHARD_SYNC_V2_SCHEMA ? "v2" : undefined;
   if (!version || canonicalJSON(value) + "\n" !== shardSyncDescriptor(realm, version)) throw new ShardSyncFormatError(label, "descriptor realm or schema mismatch");
   return version;
 }
+/** Known wire metadata for activated placement audit/proof only. Legacy transports retain their v3 refusal. */
+export function decodePlacementTransportDescriptor(bytes: Uint8Array, realm: ShardSyncRealm): "v1" | "v2" | "v3" {
+  const value = decodeMetadata(bytes, shardSyncLabel(realm));
+  if (value.schema === PLACEMENT_DESCRIPTOR_SCHEMA) {
+    try { validatePlacementDescriptor(value, realm); } catch { throw new ShardSyncFormatError(shardSyncLabel(realm), "invalid placement descriptor"); }
+    return "v3";
+  }
+  return decodeShardDescriptor(bytes, realm);
+}
 export function isShardManifestPath(path: string): boolean { return MANIFEST.exec(path)?.[0] === path; }
 /** Shape and lineage classification belong to Layer 1 after complete pack acquisition. */
 export function decodeShardManifest(path: string, bytes: Uint8Array): unknown {

package/src/memory/shard-sync-graph.ts

@@ -1,11 +1,12 @@
 /** Bounded selected-path acquisition only. Transport admission and receiving binding stay with the caller. */
 import { createHash } from "node:crypto";
 import { PUBLIC_PRUNE_GRAPH_MAX_BYTES, PUBLIC_PRUNE_GRAPH_MAX_OBJECTS, PUBLIC_PRUNE_INPUT_MAX_BYTES, PublicPruneInputError, type PublicPruneObject } from "./public-prune-inputs.ts";
-import { decodeShardDescriptor, decodeShardManifest, SHARD_PACK_MAX_BYTES, type ShardSyncRealm } from "./shard-sync-format.ts";
+import { decodePlacementTransportDescriptor, decodeShardManifest, SHARD_PACK_MAX_BYTES, type ShardSyncRealm } from "./shard-sync-format.ts";
 import { PUBLIC_PRUNE_MAX_PACKS, PUBLIC_PRUNE_MAX_WITNESSES, verifyPublicPruneWitness } from "./public-prune-witness.ts";
 
 type ObjectType = "commit" | "tree" | "blob";
 export interface PublicPruneGitGraphOptions {
+  publicationFormat?: "agent-mem.sync-placement/v1";
   commit: string; manifestPath: string; manifestBlob: string; realm: ShardSyncRealm;
   readObject: (oid: string) => Promise<{ type: ObjectType; body: Uint8Array }>;
 }
@@ -13,7 +14,7 @@ const hex = (v: unknown, n: number): v is string => typeof v === "string" && v.l
 const object = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
 function guard(ok: unknown, resource = false): asserts ok { if (!ok) throw new PublicPruneInputError(resource ? "resource" : "unavailable"); }
 interface TreeEntry { mode: "40000" | "100644"; oid: string }
-function parseTree(body: Buffer): Map<string, TreeEntry> {
+export function parsePublicPruneGitTree(body: Buffer): Map<string, TreeEntry> {
   const entries = new Map<string, TreeEntry>();
   for (let offset = 0; offset < body.length;) {
     const space = body.indexOf(32, offset); guard(space > offset);
@@ -59,12 +60,13 @@ export async function collectPublicPruneGitGraph(options: PublicPruneGitGraphOpt
       let oid = root;
       for (let i = 0; i < parts.length; i++) {
         let entries = trees.get(oid);
-        if (!entries) { entries = parseTree((await get(oid, "tree")).body); trees.set(oid, entries); }
+        if (!entries) { entries = parsePublicPruneGitTree((await get(oid, "tree")).body); trees.set(oid, entries); }
         const entry = entries.get(parts[i]!); guard(entry && entry.mode === (i === parts.length - 1 ? "100644" : "40000")); oid = entry.oid;
       }
       const value = await get(oid, "blob"); return { oid, body: value.body };
     };
-    guard(decodeShardDescriptor((await path("shard.json")).body, realm) === "v2");
+    const version = decodePlacementTransportDescriptor((await path("shard.json")).body, realm);
+    guard(version === "v2" || version === "v3" && options.publicationFormat === "agent-mem.sync-placement/v1");
     const manifest = await path(manifestPath); guard(manifest.oid === manifestBlob);
     const raw = decodeShardManifest(manifestPath, manifest.body);
     guard(object(raw) && object(raw.pruneOccurrence) && Array.isArray(raw.witnesses));