@staix/agent-mem 0.20.3 → 0.22.0

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

@@ -0,0 +1,238 @@
+/** Complete selected-realm immutable history audit; Git acquisition and binding checks belong to the caller. */
+import { createHash } from "node:crypto";
+import { types } from "node:util";
+import { canonicalJSON, validGeneration } from "./generation.ts";
+import { validatePruneRow, type PruneRow } from "./prune.ts";
+import { verifyPublicPruneWitness } from "./public-prune-witness.ts";
+import { parsePublicPruneGitTree } from "./shard-sync-graph.ts";
+import { decodeShardDescriptor, decodePlacementTransportDescriptor, decodeShardPack, decodeShardManifest, isShardManifestPath,
+  shardSyncRef, SHARD_PACK_MAX_BYTES, type ShardSyncRealm, type ShardSyncRow } from "./shard-sync-format.ts";
+
+export interface ShardHistoryOrigin { ref: string; commit: string; pack: string; blob: string }
+export interface ShardHistoryManifest { path: string; bytes: Buffer; value: unknown; row: PruneRow; eligible: boolean; commit: string; blob: string }
+export interface ShardHistory {
+  rows: Map<string, ShardSyncRow>; files: Map<string, Buffer>; origins: Map<string, ShardHistoryOrigin>;
+  version: "v1" | "v2" | "v3"; manifests: Map<string, ShardHistoryManifest>;
+}
+export interface ShardHistoryAuditorOptions {
+  realm: ShardSyncRealm; generation: string; placement: boolean; publicPrune?: boolean;
+  /** Complete successful Git output only. The port rechecks receiving bindings around every await. */
+  git(args: string[]): Promise<string>;
+  /** Caller acquisition bounds and validates objects. Audit also retains identity/newline/bound checks. */
+  blob(oid: string, path: string): Promise<Buffer>;
+  /** Required by placement publication. Omitting this retains only the legacy trusted-Git abstraction.
+   * Body bytes, without the Git object header; the auditor verifies each requested identity itself. */
+  object?(oid: string, type: "commit" | "tree"): Promise<Buffer>;
+}
+export type ShardHistoryCause = "unavailable" | "blob" | "forbidden-entry" | "public-prune-floor";
+const refusals: Record<ShardHistoryCause, string> = {
+  unavailable: "Shard history is unavailable, inconsistent or unsupported; retain and inspect the complete selected history before continuing.",
+  blob: "Shard history blob is unavailable or its identity, bound or complete newline is invalid; retain and inspect the selected history before continuing.",
+  "forbidden-entry": "Shard history contains a forbidden historical tree entry; retain and inspect the selected history before continuing.",
+  "public-prune-floor": "Shard history requires the v2 public prune floor; activate compatible public-prune support before continuing.",
+};
+export class ShardHistoryError extends Error {
+  readonly code: ShardHistoryCause;
+  constructor(code: ShardHistoryCause = "unavailable") {
+    const safe = typeof code === "string" && Object.hasOwn(refusals, code) ? code : "unavailable";
+    super(refusals[safe]); this.code = safe; this.name = "ShardHistoryError";
+  }
+}
+function cause(error: unknown): ShardHistoryCause {
+  try {
+    if (!error || typeof error !== "object" || types.isProxy(error) || !(error instanceof ShardHistoryError)) return "unavailable";
+    const descriptor = Object.getOwnPropertyDescriptor(error, "code");
+    return descriptor && "value" in descriptor && typeof descriptor.value === "string" && Object.hasOwn(refusals, descriptor.value)
+      ? descriptor.value as ShardHistoryCause : "unavailable";
+  } catch { return "unavailable"; }
+}
+/** Never reads an external message/getter; only this module's closed own data-code selects safe static text. */
+export function shardHistoryRefusal(error: unknown): string { return refusals[cause(error)]; }
+function fail(code: ShardHistoryCause = "unavailable"): never { throw new ShardHistoryError(code); }
+const oid = (v: unknown): v is string => typeof v === "string" && v.length === 40 && /^[a-f0-9]+$/.test(v);
+const packPath = (v: string) => /^rows\/[a-f0-9]{64}\/[a-f0-9]{64}\.jsonl$/.exec(v)?.[0] === v;
+const digest = (bytes: Uint8Array | string) => createHash("sha256").update(bytes).digest("hex");
+const rank = { v1: 1, v2: 2, v3: 3 };
+function detached(value: ShardHistory): ShardHistory {
+  return { version: value.version, rows: new Map([...value.rows].map(([id, row]) => [id, structuredClone(row)])),
+    files: new Map([...value.files].map(([path, bytes]) => [path, Buffer.from(bytes)])),
+    origins: new Map([...value.origins].map(([id, origin]) => [id, { ...origin }])),
+    manifests: new Map([...value.manifests].map(([path, manifest]) => [path, { ...manifest, bytes: Buffer.from(manifest.bytes), value: structuredClone(manifest.value), row: structuredClone(manifest.row) }])) };
+}
+export class ShardHistoryAuditor {
+  readonly #options: ShardHistoryAuditorOptions;
+  readonly #ref: string;
+  readonly #histories = new Map<string, ShardHistory>();
+  readonly #audited = new Set<string>();
+  readonly #blobs = new Map<string, Buffer>();
+  readonly #decoded = new Map<string, ShardSyncRow[]>();
+  readonly #origins = new Map<string, ShardHistoryOrigin>();
+  readonly #manifestOrigins = new Map<string, { commit: string; blob: string }>();
+  readonly #parents = new Map<string, string[]>();
+  #running = false;
+  constructor(options: ShardHistoryAuditorOptions) {
+    this.#ref = shardSyncRef(options.realm);
+    if (!validGeneration(options.generation) || typeof options.placement !== "boolean" || options.publicPrune !== undefined && typeof options.publicPrune !== "boolean") fail();
+    this.#options = { ...options, realm: structuredClone(options.realm), publicPrune: options.publicPrune ?? options.placement };
+  }
+  async #blob(object: string, path: string): Promise<Buffer> {
+    try {
+      const maximum = path === "shard.json" || isShardManifestPath(path) ? 64 * 1024 : SHARD_PACK_MAX_BYTES;
+      let bytes = this.#blobs.get(object);
+      if (!bytes) {
+        const result = await this.#options.blob(object, path);
+        if (!(result instanceof Uint8Array)) fail("blob"); bytes = Buffer.from(result);
+        if (bytes.length < 1 || bytes.length > maximum || bytes.at(-1) !== 10
+          || createHash("sha1").update(`blob ${bytes.length}\0`).update(bytes).digest("hex") !== object) fail("blob");
+        this.#blobs.set(object, bytes);
+      }
+      if (bytes.length > maximum) fail("blob"); return bytes;
+    } catch { return fail("blob"); }
+  }
+  async #object(object: string, type: "commit" | "tree"): Promise<Buffer> {
+    if (!this.#options.object || !oid(object)) return fail();
+    const body = await this.#options.object(object, type);
+    if (!(body instanceof Uint8Array) || body.length > (type === "commit" ? 65536 : SHARD_PACK_MAX_BYTES)) return fail();
+    const bytes = Buffer.from(body);
+    if (createHash("sha1").update(`${type} ${bytes.length}\0`).update(bytes).digest("hex") !== object) return fail();
+    return bytes;
+  }
+  async #commit(commit: string, expected?: readonly string[]): Promise<string> {
+    const bytes = await this.#object(commit, "commit"), end = bytes.indexOf(10), headerEnd = bytes.indexOf(Buffer.from("\n\n"));
+    if (end !== 45 || headerEnd < end || !bytes.subarray(0, 5).equals(Buffer.from("tree "))) return fail();
+    const rootBytes = bytes.subarray(5, end), tree = rootBytes.toString("ascii");
+    if (!oid(tree) || !rootBytes.equals(Buffer.from(tree))) return fail();
+    const parents: string[] = [];
+    let at = end + 1;
+    while (at < headerEnd) {
+      const next = bytes.indexOf(10, at); if (next < at || next > headerEnd) return fail();
+      const line = bytes.subarray(at, next); at = next + 1;
+      if (line.subarray(0, 7).equals(Buffer.from("parent "))) {
+        const parentBytes = line.subarray(7), parent = parentBytes.toString("ascii");
+        if (!oid(parent) || !parentBytes.equals(Buffer.from(parent))) return fail(); parents.push(parent);
+      } else if (line.subarray(0, 5).equals(Buffer.from("tree "))) return fail();
+    }
+    const known = expected ?? this.#parents.get(commit);
+    if (known && canonicalJSON(parents) !== canonicalJSON(known)) return fail();
+    if (expected) this.#parents.set(commit, parents);
+    return tree;
+  }
+  async #treeEntries(root: string): Promise<string[]> {
+    // Raw trees are scoped to this one snapshot; retaining a full tree map for every historical commit is quadratic.
+    const parsed = new Map<string, ReturnType<typeof parsePublicPruneGitTree>>(), entries: string[] = [];
+    const walk = async (object: string, prefix: string): Promise<void> => {
+      let tree = parsed.get(object);
+      if (!tree) {
+        const bytes = await this.#object(object, "tree");
+        try { tree = parsePublicPruneGitTree(bytes); } catch { return fail("forbidden-entry"); }
+        parsed.set(object, tree);
+      }
+      for (const [name, entry] of tree) {
+        const path = prefix ? `${prefix}/${name}` : name;
+        if (entry.mode === "40000") {
+          const allowed = !prefix ? name === "rows" || name === "prune-witnesses"
+            : prefix === "rows" && name.length === 64 && /^[a-f0-9]+$/.test(name);
+          if (!allowed) return fail("forbidden-entry"); await walk(entry.oid, path);
+        } else {
+          if (path !== "shard.json" && !packPath(path) && !isShardManifestPath(path)) return fail("forbidden-entry");
+          entries.push(`100644 blob ${entry.oid}\t${path}`);
+        }
+      }
+    };
+    await walk(root, ""); return entries;
+  }
+  async #tree(commit: string, verifiedRoot?: string): Promise<ShardHistory> {
+    const entries = this.#options.object ? await this.#treeEntries(verifiedRoot ?? await this.#commit(commit))
+      : (await this.#options.git(["ls-tree", "-r", "-z", commit])).split("\0").filter(Boolean);
+    const rows = new Map<string, ShardSyncRow>(), files = new Map<string, Buffer>(), origins = new Map<string, ShardHistoryOrigin>();
+    const objects = new Map<string, string>(), manifests = new Map<string, ShardHistoryManifest>();
+    for (const entry of entries) {
+      const match = /^100644 blob ([a-f0-9]{40})\t(.+)$/.exec(entry);
+      if (!match || match[0] !== entry) fail("forbidden-entry");
+      const path = match[2]!, object = match[1]!;
+      if (files.has(path) || path !== "shard.json" && !packPath(path) && !isShardManifestPath(path)) fail("forbidden-entry");
+      files.set(path, await this.#blob(object, path)); objects.set(path, object);
+    }
+    const descriptor = files.get("shard.json"); if (!descriptor) return fail();
+    const version = this.#options.placement ? decodePlacementTransportDescriptor(descriptor, this.#options.realm) : decodeShardDescriptor(descriptor, this.#options.realm);
+    if (version !== "v1" && !this.#options.publicPrune) fail("public-prune-floor");
+    for (const [path, bytes] of files) if (packPath(path)) {
+      const object = objects.get(path)!; let pack = this.#decoded.get(object);
+      if (!pack) { pack = decodeShardPack(path, bytes, this.#options.realm, this.#options.generation); this.#decoded.set(object, pack); }
+      else if (!path.endsWith(`/${digest(bytes)}.jsonl`) || pack.some(row => path !== `rows/${digest(row.machine)}/${digest(bytes)}.jsonl`)) fail();
+      for (const row of pack) {
+        const old = rows.get(row.id); if (old && canonicalJSON(old) !== canonicalJSON(row)) fail(); rows.set(row.id, row);
+        if (!origins.has(row.id)) origins.set(row.id, this.#origins.get(row.id) ?? { ref: this.#ref, commit, pack: path, blob: object });
+      }
+    }
+    for (const [path, bytes] of files) if (isShardManifestPath(path)) {
+      if (version === "v1") fail();
+      const value = decodeShardManifest(path, bytes), candidate = value as { prune?: unknown; pruneOccurrence?: { pack: string; blob: string }; witnesses?: { pack: string; blob: string }[] };
+      const row = validatePruneRow(candidate.prune, undefined, "synced");
+      if (canonicalJSON(rows.get(row.id)) !== canonicalJSON(row) || !candidate.pruneOccurrence || !Array.isArray(candidate.witnesses)) fail();
+      const selected = new Map<string, { pack: string; blob: string; bytes: Buffer }>();
+      for (const ref of [candidate.pruneOccurrence, ...candidate.witnesses]) {
+        if (!ref || typeof ref.pack !== "string" || objects.get(ref.pack) !== ref.blob || !files.has(ref.pack)) fail();
+        selected.set(ref.pack, { pack: ref.pack, blob: ref.blob, bytes: files.get(ref.pack)! });
+      }
+      const proof = verifyPublicPruneWitness(value, { realm: this.#options.realm, packs: [...selected.values()] });
+      if (proof.status === "invalid") fail();
+      const origin = this.#manifestOrigins.get(path) ?? { commit, blob: objects.get(path)! };
+      manifests.set(path, { path, bytes, value, row, eligible: proof.status === "verified", ...origin });
+    }
+    return { rows, files, origins, version, manifests };
+  }
+  #accept(current: ShardHistory): void {
+    // Commit origins only after the complete tree and every parent retention rule passed.
+    for (const [id, origin] of current.origins) { if (!this.#origins.has(id)) this.#origins.set(id, origin); current.origins.set(id, this.#origins.get(id)!); }
+    for (const [path, manifest] of current.manifests) {
+      const first = this.#manifestOrigins.get(path) ?? { commit: manifest.commit, blob: manifest.blob };
+      this.#manifestOrigins.set(path, first); current.manifests.set(path, { ...manifest, ...first });
+    }
+  }
+  /** Ancestry of the immutable hash-verified commit graph, never a second Git interpretation of mutable cache bytes.
+   * The caller still proves this tip is the selected actual remote head. Legacy trusted-Git ports are insufficient. */
+  async verifiedAncestor(ancestor: string, tip: string): Promise<boolean> {
+    if (!this.#options.object || !oid(ancestor) || !oid(tip)) return fail();
+    await this.history(tip);
+    const pending = [tip], seen = new Set<string>();
+    while (pending.length) {
+      const commit = pending.pop()!; if (seen.has(commit)) continue; seen.add(commit);
+      const parents = this.#parents.get(commit);
+      if (!this.#audited.has(commit) || !parents) return fail();
+      if (commit === ancestor) return true;
+      for (const parent of parents) pending.push(parent);
+    }
+    return false;
+  }
+  /** Only requested tips retain full row maps. Parent trees are reconstructed with decoded immutable blobs. */
+  async history(tip: string): Promise<ShardHistory> {
+    if (!oid(tip) || this.#running) return fail(); this.#running = true;
+    try {
+      const cached = this.#histories.get(tip); if (cached) return detached(cached);
+      const lines = (await this.#options.git(["rev-list", "--topo-order", "--reverse", "--parents", tip])).split("\n").filter(Boolean);
+      let latest: ShardHistory | undefined; const seen = new Set<string>();
+      // ponytail: complete selected history still costs time and immutable selected-blob memory per invocation.
+      // Upgrade with a validated immutable commit/blob digest cache, never an arbitrary history lifetime cliff.
+      for (const line of lines) {
+        const [commit, ...parents] = line.split(" ");
+        if (!oid(commit) || parents.some(parent => !oid(parent)) || seen.has(commit)) return fail(); seen.add(commit);
+        const verifiedRoot = this.#options.object ? await this.#commit(commit, parents) : undefined;
+        if (this.#audited.has(commit)) { if (commit === tip) latest = await this.#tree(commit, verifiedRoot); continue; }
+        const current = await this.#tree(commit, verifiedRoot);
+        for (const parent of parents) {
+          if (!this.#audited.has(parent) || !seen.has(parent)) return fail();
+          const previous = this.#histories.get(parent) ?? await this.#tree(parent);
+          if (rank[current.version] < rank[previous.version]) fail();
+          if (previous.version !== "v1") for (const [path, bytes] of previous.files)
+            if (path !== "shard.json" && !current.files.get(path)?.equals(bytes)) fail();
+          for (const row of previous.rows.values()) if (canonicalJSON(current.rows.get(row.id)) !== canonicalJSON(row)) fail();
+        }
+        this.#accept(current); this.#audited.add(commit); if (commit === tip) latest = current;
+      }
+      if (!latest || lines.at(-1)?.split(" ")[0] !== tip) return fail();
+      this.#histories.set(tip, latest); return detached(latest);
+    } catch (error) { return fail(cause(error)); }
+    finally { this.#running = false; }
+  }
+}

package/src/memory/shard-sync.ts

@@ -1,3 +1,7 @@
+import { ShardSyncApplications, ShardSyncApplicationError } from "./shard-sync-applications.ts";
+import { ShardHistoryAuditor, ShardHistoryError, shardHistoryRefusal } from "./shard-sync-history.ts";
+import { validatePlacementProfile, type PlacementProfile } from "./sync-placement-format.ts";
+import { placementRuntimeRefusal } from "./sync-placement-guard.ts";
 import { assertPublisherBoundary, ensurePublisherBoundary, publisherPruneLineages } from "./prune-publisher-lineage.ts";
 import { verifyPublicPruneWitness, type PublicPruneWitnessV1 } from "./public-prune-witness.ts";
 import { readPublicPruneView, type PublicPruneViewV1 } from "./public-prune-view.ts";
@@ -7,7 +11,7 @@ import { PublicPruneInputError, PUBLIC_PRUNE_REPLAY_MAX_BYTES, PUBLIC_PRUNE_MAX_
 import { randomBytes, createHash } from "node:crypto";
 import { constants, closeSync, existsSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, readSync, renameSync, rmSync, unlinkSync, writeSync } from "node:fs";
 import { join } from "node:path";
-import { canonicalJSON, fsyncDirectory, hashJSON, readProfileJSON, readSelector, rebindPublicPruneProfile } from "./generation.ts";
+import { canonicalJSON, fsyncDirectory, hashJSON, readProfileJSON, readSelector, rebindPublicPruneProfile, legacyProfileMarkerShape, type ProfileSelector } from "./generation.ts";
 import { generationSyncLock } from "./generation-sync.ts";
 import { acquireMutation, assertMutationHandle, type MutationHandle } from "./mutation.ts";
 import { realPath } from "./platform.ts";
@@ -73,13 +77,30 @@ function selectorEvidence(folder: string, file: string, prefix?: Buffer | true):
     if(canonicalJSON(value)+"\n"!==text)refuse("prior selector unavailable");return{value,bytes:data,check};
   } finally {closeSync(fd);}
 }
+/** Closed prior selectors never authorize profile activation or change a pending prune payload. */
+function retainedSelector(store: MemoryStore, value: unknown, revision: string): { pruneInputSetHash: string } {
+  const candidate=value as {schema?:unknown}|undefined;
+  let prior: PlacementProfile | Extract<ProfileSelector, {schema:"agent-mem.profile/v2"}>;
+  if(candidate?.schema==="agent-mem.profile/v3") {
+    prior=validatePlacementProfile(value);
+    if(!store.profile.publicationFormat||prior.publicationFormat!==store.profile.publicationFormat||prior.placementHead!==store.profile.placementHead)
+      refuse("pending selector activation binding unavailable");
+  } else {
+    if(!legacyProfileMarkerShape(value)||value?.schema!=="agent-mem.profile/v2")refuse("pending selector binding unavailable");
+    prior=value;
+  }
+  if(prior.generation!==store.profile.generation||prior.foreignPruneFormat!==store.profile.foreignPruneFormat||hashJSON(prior)!==revision)
+    refuse("pending selector binding unavailable");
+  return prior;
+}
 function pendingSelector(store:MemoryStore,plan:PrunePlan,required=false):(()=>void)|undefined {
   if(!required&&plan.selectorRevision===store.profile.selectorRevision)return undefined;
   if(!store.profile.foreignPruneFormat)refuse("pending selector unavailable");
   const history=join(store.dir,"prune-plans","selector-history"),file=join(history,plan.seal+".json"),evidence=selectorEvidence(history,file),prior=evidence.value as Record<string,unknown>|undefined;
-  if(!prior||Object.keys(prior).length!==5||prior.schema!=="agent-mem.profile/v2"||prior.kind!=="generation"||prior.generation!==store.profile.generation
-    ||prior.foreignPruneFormat!==store.profile.foreignPruneFormat||typeof prior.pruneInputSetHash!=="string"||!/^[a-f0-9]{64}$/.test(prior.pruneInputSetHash)||hashJSON(prior)!==plan.selectorRevision)refuse("pending selector binding unavailable");
-  const bound={...store.profile,selectorRevision:plan.selectorRevision,pruneInputSetHash:prior.pruneInputSetHash};
+  const checked=retainedSelector(store,prior,plan.selectorRevision);
+  // A historical v2 selector remains evidence only. Retain the current v3 activation binding while proving
+  // its public-prune view can advance monotonically to the current selector, never enabling a v2 writer.
+  const bound={...store.profile,selectorRevision:plan.selectorRevision,pruneInputSetHash:checked.pruneInputSetHash};
   const check=()=>{evidence.check();const probe={...bound};rebindPublicPruneProfile(probe);if(probe.selectorRevision!==store.profile.selectorRevision)refuse("pending selector ancestry unavailable");};check();return check;
 }
 /** Recognize only the exact persisted transport shape; this reads metadata and never resumes an append. */
@@ -144,10 +165,8 @@ function selectorRetention(target: Target, advancing: boolean, install = false,
   const validate=(plan:PrunePlan,value:unknown)=>{
     const row=plan.rows[0]?.payload,prior=value as Record<string,unknown>|undefined;
     if(plan.rows.length!==1||!row||plan.generation!==target.generation||row.generation!==target.generation
-      ||canonicalJSON(plan)!==canonicalJSON(importPrunePlan(target.store,target.realm,row,plan.selectorRevision))
-      ||!prior||Object.keys(prior).length!==5||prior.schema!=="agent-mem.profile/v2"||prior.kind!=="generation"
-      ||prior.generation!==target.generation||prior.foreignPruneFormat!==target.store.profile.foreignPruneFormat
-      ||typeof prior.pruneInputSetHash!=="string"||!/^[a-f0-9]{64}$/.test(prior.pruneInputSetHash)||hashJSON(prior)!==plan.selectorRevision)refuse("selector recovery plan binding unavailable");
+      ||canonicalJSON(plan)!==canonicalJSON(importPrunePlan(target.store,target.realm,row,plan.selectorRevision)))refuse("selector recovery plan binding unavailable");
+    retainedSelector(target.store,prior,plan.selectorRevision);
   };
   for(const [seal,record] of records){
     const active=pending.get(seal),plan=active?.plan??validatePrunePlan(readProfileJSON(join(plans,seal+".json")));
@@ -423,23 +442,16 @@ async function prepareHolds(targets: readonly Target[], root: string, url: strin
     }
   }
 }
-function mergePackOrigins(into: Map<string, HoldSource>, byRealm: Map<string, Map<string, HoldSource>>, rows: readonly ShardSyncRow[], source: HoldSource): void {
-  const first = byRealm.get(source.ref) ?? new Map<string, HoldSource>(); byRealm.set(source.ref, first);
-  // Oldest-first history keeps a receipt's source stable across tip advancement and partial-write retry.
-  for (const row of rows) {
-    if (!first.has(row.id)) first.set(row.id, source);
-    if (!into.has(row.id)) into.set(row.id, first.get(row.id)!);
-  }
-}
-
-/** Sync only borrowed canonical project/user targets. Internal error/phase observers are test-only, never CLI/SyncOptions ports. */
 export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions = {}, testOnlyUnexpectedError?: (error: unknown) => void, testOnlyPhase?: (phase: SyncPhase) => void): Promise<SyncResult> {
+  const placementRefusal = placementRuntimeRefusal(store.profile.home, store.profile);
+  if (placementRefusal) return { ok: false, pushed: false, entries: 0, error: placementRefusal };
+  if (store.profile.publicationFormat === "agent-mem.sync-placement/v1") return (await import("./sync-placement-transport.ts")).syncPlacementMemory(store, opts);
   let pushed = false, releaseTransport: (() => void) | undefined, releaseSync: (() => void) | undefined;
   const releases: (() => void)[] = [], transient: string[] = [], temporary: string[] = [];
   const v2 = store.profile.foreignPruneFormat === "agent-mem.public-prune-witness/v1";
   let expectedRevision = store.profile.selectorRevision;
   let expectedBinding: string | undefined, expectedSources: string | undefined, expectedPolicy: string | undefined;
-  const application: NonNullable<SyncResult["pruneApplication"]> = { transport:"unconfirmed", proofComplete:0, projectionActive:null, nativeApplied:null, held:0, phase:"preflight" };
+  let application: NonNullable<SyncResult["pruneApplication"]> = { transport:"unconfirmed", proofComplete:0, projectionActive:null, nativeApplied:null, held:0, phase:"preflight" };
   const fail = (error: string): SyncResult => ({ ok: false, pushed, entries: 0, error, ...(v2 ? {pruneApplication:{...application,transport:pushed?"durable":"unconfirmed"}} : {}) });
   let root = "", cache = "", targets: Target[] = [], homeMutation:MutationHandle|undefined;
   let boundView:PublicPruneViewV1|undefined;
@@ -529,7 +541,7 @@ export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions =
       const release = acquireMutation(target.store.dir); if (!release) refuse(`${shardSyncLabel(target.realm)}: another source mutation is running`); releases.push(release); target.mutation=release;
       if (v2) ensurePublisherBoundary(target.store.profile,release);
     }
-    const blobCache = new Map<string, Buffer>(), decoded = new Map<string, ShardSyncRow[]>();
+    const blobCache = new Map<string, Buffer>();
     const blob = async (object: string, path: string): Promise<Buffer> => {
       const maximum = path === "shard.json" || isShardManifestPath(path) ? 64 * 1024 : SHARD_PACK_MAX_BYTES, prior = blobCache.get(object);
       if (prior) { if (prior.length > maximum) refuse("shard sync blob exceeds its bound"); return prior; }
@@ -542,69 +554,16 @@ export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions =
       if (identity !== object) refuse("shard sync public blob identity mismatch");
       blobCache.set(object, bytes); return bytes;
     };
-    type History = { rows: Map<string, ShardSyncRow>; files: Map<string, Buffer>; origins: Map<string, HoldSource>; version:"v1"|"v2"; manifests:Map<string,SyncManifest> };
-    // Keep only requested tips. Per-commit full row maps would make append-only history quadratic in memory.
-    const histories = new Map<string, History>(), audited = new Set<string>();
-    const firstOrigins = new Map<string, Map<string, HoldSource>>();
-    const manifestOrigins = new Map<string,{commit:string;blob:string}>();
-    const treeState = async (commit: string, target: Target): Promise<History> => {
-      const entries=(await required(["ls-tree","-r","-z",commit],"shard sync tree unavailable")).split("\0").filter(Boolean);
-      const rows=new Map<string,ShardSyncRow>(),files=new Map<string,Buffer>(),origins=new Map<string,HoldSource>(),objects=new Map<string,string>(),manifests=new Map<string,SyncManifest>();
-      for(const entry of entries){
-        const match=/^100644 blob ([a-f0-9]{40})\t(.+)$/.exec(entry);
-        if(!match||match[0]!==entry||match[2]!=="shard.json"&&!PACK.test(match[2]!)&&!isShardManifestPath(match[2]!))refuse(`${shardSyncLabel(target.realm)}: forbidden historical tree entry`);
-        const path=match[2]!,oid=match[1]!,bytes=await blob(oid,path);files.set(path,bytes);objects.set(path,oid);
-      }
-      const descriptor=files.get("shard.json");if(!descriptor)refuse(`${shardSyncLabel(target.realm)}: historical descriptor missing`);
-      const version=decodeShardDescriptor(descriptor,target.realm);
-      if(version==="v2"&&!v2)refuse("remote shard requires the explicitly activated public prune view");
-      for(const [path,bytes] of files)if(PACK.test(path)){
-        const oid=objects.get(path)!,key=`${shardSyncRef(target.realm)}:${oid}`;let pack=decoded.get(key);
-        if(!pack){pack=decodeShardPack(path,bytes,target.realm,target.generation);decoded.set(key,pack);}
-        else if(!path.endsWith(`/${digest(bytes)}.jsonl`)||pack.some(row=>path!==`rows/${digest(row.machine)}/${digest(bytes)}.jsonl`))refuse("immutable pack path changed");
-        mergeRows(rows,pack,target.realm);mergePackOrigins(origins,firstOrigins,pack,{ref:shardSyncRef(target.realm),commit,pack:path,blob:oid});
-      }
-      for(const [path,bytes] of files)if(isShardManifestPath(path)){
-        if(version!=="v2")refuse("a v1 tree cannot contain prune manifests");
-        const value=decodeShardManifest(path,bytes),candidate=value as {prune?:unknown;pruneOccurrence?:{pack:string;blob:string};witnesses?:{pack:string;blob:string}[]};
-        const row=validatePruneRow(candidate.prune,undefined,"synced");
-        if(canonicalJSON(rows.get(row.id))!==canonicalJSON(row))refuse("manifest original prune is missing or conflicts");
-        if(!candidate.pruneOccurrence||!Array.isArray(candidate.witnesses))refuse("manifest references unavailable");
-        const selected=new Map<string,{pack:string;blob:string;bytes:Buffer}>();
-        for(const ref of [candidate.pruneOccurrence,...candidate.witnesses]){
-          if(!ref||typeof ref.pack!=="string"||objects.get(ref.pack)!==ref.blob||!files.has(ref.pack))refuse("manifest complete pack is unavailable");
-          selected.set(ref.pack,{pack:ref.pack,blob:ref.blob,bytes:files.get(ref.pack)!});
-        }
-        const proof=verifyPublicPruneWitness(value,{realm:target.realm,packs:[...selected.values()]});
-        if(proof.status==="invalid")refuse("manifest lacks complete original public proof");
-        const identity=`${shardSyncRef(target.realm)}:${path}`,origin=manifestOrigins.get(identity)??{commit,blob:objects.get(path)!};manifestOrigins.set(identity,origin);
-        manifests.set(path,{path,bytes,value,row,eligible:proof.status==="verified",...origin});
-      }
-      return{rows,files,origins,version,manifests};
-    };
-    const history = async (tip: string, target: Target): Promise<History> => {
-      const key = `${shardSyncRef(target.realm)}:${tip}`, cached = histories.get(key); if (cached) return cached;
-      const commits = (await required(["rev-list", "--topo-order", "--reverse", "--parents", tip], "shard sync history unavailable")).split("\n").filter(Boolean);
-      let latest: History | undefined;
-      // ponytail: complete selected history still costs time and selected pack memory per invocation.
-      // Upgrade: a validated immutable commit/blob digest cache, never an arbitrary lifetime refusal cliff.
-      for (const line of commits) {
-        const [commit, ...parents] = line.split(" ");
-        if (!commit || !OID.test(commit) || parents.some(parent => !OID.test(parent))) refuse("shard sync history identity invalid");
-        const identity = `${shardSyncRef(target.realm)}:${commit}`;
-        if (audited.has(identity)) { if (commit === tip) latest = await treeState(commit, target); continue; }
-        const current = await treeState(commit, target);
-        for (const parent of parents) {
-          if (!audited.has(`${shardSyncRef(target.realm)}:${parent}`)) refuse(`${shardSyncLabel(target.realm)}: historical parent unavailable`);
-          const previous = histories.get(`${shardSyncRef(target.realm)}:${parent}`) ?? await treeState(parent, target);
-          if(previous.version==="v2"&&current.version!=="v2")refuse("shard history cannot downgrade from v2");
-          if(previous.version==="v2")for(const [path,bytes] of previous.files)if(path!=="shard.json"&&!current.files.get(path)?.equals(bytes))refuse("immutable v2 history artifact removed or changed");
-          for (const row of previous.rows.values()) if (canonicalJSON(current.rows.get(row.id)) !== canonicalJSON(row)) refuse(`${shardSyncLabel(target.realm)}: historical original row removed or replaced`);
-        }
-        audited.add(identity); if (commit === tip) latest = current;
+    const auditors = new Map<string, ShardHistoryAuditor>();
+    const history = (tip: string, target: Target) => {
+      const ref = shardSyncRef(target.realm);
+      let auditor = auditors.get(ref);
+      if (!auditor) {
+        auditor = new ShardHistoryAuditor({ realm: target.realm, generation: target.generation, placement: false, publicPrune: v2,
+          git: args => required(args, "shard sync history unavailable"), blob });
+        auditors.set(ref, auditor);
       }
-      if (!latest) refuse("shard sync history unavailable");
-      histories.set(key, latest); return latest;
+      return auditor.history(tip);
     };
     const fetchTargets = async (): Promise<void> => {
       for (const target of targets) {
@@ -691,23 +650,6 @@ export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions =
         || !decodeShardPack(value.source.pack, bytes, target.realm, target.generation).some(item => canonicalJSON(item) === canonicalJSON(value.row))
         || value.source.ref !== shardSyncRef(target.realm)) refuse(`${shardSyncLabel(target.realm)}: prune hold source mismatch`);
     };
-    const loadExistingApplications = async () => {
-      if(!v2)return;
-      const selected=readSelector(store.profile.home).selector;if(selected?.schema!=="agent-mem.profile/v2")refuse("selected v2 profile unavailable");
-      boundView=readPublicPruneView(store.profile.home,selected.pruneInputSetHash,store.profile.generation!);
-      for(const target of targets){
-        target.registered=[];const key=target.realm.scope==="user"?"user":`project:${target.realm.key}`,set=boundView.realms[key];if(!set)continue;
-        const projection=reducePublicPruneInputs({dir:target.store.dir,realm:target.realm,receivingGeneration:target.generation,inputSetHash:set});
-        for(const hash of projection.inputs){
-          const descriptor=readPublicPruneInputDescriptor({dir:target.store.dir,hash});
-          if(!target.remote||descriptor.source.remoteHash!==digest(url))refuse("registered prune source history disappeared or its remote binding changed");
-          await required(["merge-base","--is-ancestor",descriptor.source.commit,target.remote],"registered prune source is missing from replacement history");
-          const original=await 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);
-        }
-      }
-    };
     const objectCache=new Map<string,{type:"commit"|"tree"|"blob";body:Uint8Array}>(), graphObjects=new Map<string,Uint8Array>();
     // ponytail: one sync retains at most the 256 MiB replay budget across selected realms; segmented acquisition is the upgrade.
     let objectBytes=0;
@@ -724,57 +666,20 @@ export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions =
       if(result.code!==0||result.out.length!==size)refuse("Git object bytes unavailable");
       const value:{type:"commit"|"tree"|"blob";body:Uint8Array}={type:type as "commit"|"tree"|"blob",body:result.out};objectBytes+=encodedSize;objectCache.set(oid,value);return value;
     };
-    const prepareApplications = async () => {
-      if(!v2)return;application.proofComplete=0;application.held=0;
-      for(const target of targets){
-        const current=await history(target.commit!,target);target.manifests=new Map(current.manifests);
-        target.eligible=new Set([...current.manifests.values()].filter(item=>item.eligible).map(item=>item.row.id));
-        application.proofComplete+=target.eligible.size;
-        const key=target.realm.scope==="user"?"user":`project:${target.realm.key}`,initial=boundView!.realms[key]??null;
-        const inputs=[];
-        for(const record of [...current.manifests.values()].sort((a,b)=>a.path<b.path?-1:1)){
-          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(inputs.length>=PUBLIC_PRUNE_MAX_SETS)throw new PublicPruneInputError("resource");
-          const acquired=await collectPublicPruneGitGraph({commit:record.commit,manifestPath:record.path,manifestBlob:record.blob,realm:target.realm,readObject});
-          // Share exact raw objects before accumulating inputs; repeated manifests cannot multiply graph memory.
-          const objects=acquired.map(item=>{
-            const prior=graphObjects.get(item.oid);if(prior&&!Buffer.from(prior).equals(item.bytes))refuse("conflicting Git graph bytes");
-            const bytes=prior??item.bytes;graphObjects.set(item.oid,bytes);
-            const cached=objectCache.get(item.oid)!;objectCache.set(item.oid,{type:cached.type,body:bytes.subarray(bytes.indexOf(0)+1)});return{oid:item.oid,bytes};
-          });
-          inputs.push({witnessHash,source:{remoteHash:digest(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:expectedRevision,inputSetHash:initial};
-          target.batch=preparePublicPruneInputBatch({dir:target.store.dir,binding,current:()=>{check();return{...binding,selectorRevision:expectedRevision};},inputs},target.mutation!);
-        }
-      }
-      await prepareHolds(targets,root,url,proveHoldSource);application.held=targets.reduce((n,item)=>n+item.holds.length,0);application.phase="prepared";
-    };
-    const installApplications = async () => {
-      if(!v2)return;
-      const realms={...boundView!.realms};
-      for(const target of targets)if(target.batch){
-        const installed=persistPublicPruneInputBatch(target.batch,{mutation:target.mutation!,observe:()=>check()});
-        realms[target.realm.scope==="user"?"user":`project:${target.realm.key}`]=installed.inputSetHash;testOnlyPhase?.("inputs-installed");
-      }
-      const view:PublicPruneViewV1={...boundView!,realms};
-      const changed=canonicalJSON(view)!==canonicalJSON(boundView);
-      if(changed){
-        for(const target of targets)selectorRetention(target,true,true);
-        const result=await advancePublicPruneView({memoryDir:store.profile.home,view,expectedRevision,mutations:[homeMutation!,...targets.map(item=>item.mutation!)]});
-        expectedRevision=result.revision;boundView=view;
-        // The same open handles validate/rebind; no close/reopen or authority flag is used.
-        for(const target of targets)target.store.refresh();
-        if(shardSyncSourceBinding(store)!==expectedSources||opts.policyVersion?.()!==expectedPolicy)refuse("source binding or policy changed during view commit");
-        expectedBinding=shardSyncBinding(store);
-        testOnlyPhase?.("view-committed");
-      }
-      application.projectionActive=targets.reduce((n,target)=>n+[...target.eligible].filter(id=>(target.rows.get(id) as PruneRow).generation!==target.generation).length,0);application.phase="active";check();
-    };
+    const applications = v2 ? new ShardSyncApplications({ home: store.profile.home, root, url, targets, homeMutation: homeMutation!,
+      getRevision: () => expectedRevision, setRevision: revision => { expectedRevision = revision; }, check, history,
+      candidateHistory: target => history(target.commit!, target), readObject,
+      retainGraphObject: (oid, bytes) => { const cached = objectCache.get(oid)!; objectCache.set(oid, {type:cached.type,body:bytes.subarray(bytes.indexOf(0)+1)}); },
+      assertAncestor: (ancestor, descendant) => required(["merge-base","--is-ancestor",ancestor,descendant], "registered prune source is missing from selected history").then(() => {}),
+      afterAdvance: () => {
+        if (shardSyncSourceBinding(store) !== expectedSources || opts.policyVersion?.() !== expectedPolicy) refuse("source binding or policy changed during view commit");
+        expectedBinding = shardSyncBinding(store);
+      }, phase: testOnlyPhase,
+    }) : undefined;
+    if (applications) application = applications.application;
+    const loadExistingApplications = async () => { await applications?.loadExisting(); };
+    const prepareApplications = async () => { await applications?.prepare(); };
+    const installApplications = async () => { await applications?.install(); };
     localTargets(); await fetchTargets(); localTargets(); provePrunes(targets); await loadExistingApplications(); await prepareHolds(targets, root, url, proveHoldSource); check();
     // Every selected realm, including its complete remote history/prunes, is preflighted before the first append or publication.
     for (let attempt = 0; attempt < 2; attempt++) {
@@ -814,7 +719,8 @@ export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions =
     }
     return fail("shard sync selected-ref push failed");
   } catch (error) {
-    if (error instanceof PublicPruneInputError || error instanceof ShardSyncFormatError || error instanceof SyncRefusal) return fail(error.message);
+    if (error instanceof ShardHistoryError) return fail(shardHistoryRefusal(error));
+    if (error instanceof PublicPruneInputError || error instanceof ShardSyncFormatError || error instanceof ShardSyncApplicationError || error instanceof SyncRefusal) return fail(error.message);
     try { testOnlyUnexpectedError?.(error); } catch { /* A test observer cannot change the neutral result. */ }
     return fail("shard sync unavailable");
   } finally {
@@ -825,3 +731,12 @@ export async function syncShardedMemory(store: MemoryStore, opts: SyncOptions =
     try { releaseTransport?.(); } catch { /* private lock cleanup */ }
   }
 }
+
+
+// Internal application seams shared by the independently admitted placement coordinator.
+// These are deliberately absent from the package barrel: validation and complete fetched-proof preflight stay mandatory.
+export type { Target as ShardSyncApplicationTarget, PendingPrune as ShardSyncPendingPrune, HoldSource as ShardSyncHoldSource,
+  HoldReceipt as ShardSyncHoldReceipt, Hold as ShardSyncHold, SyncPhase as ShardSyncApplicationPhase,
+  SyncManifest as ShardSyncApplicationManifest, ProveHoldSource as ShardSyncProveHoldSource };
+export { sourceRows as shardSourceRows, provePrunes as shardProvePrunes, importRows as shardImportRows,
+  selectorRetention as shardSelectorRetention, prepareHolds as shardPrepareHolds, installHold as shardInstallHold, holdWarning as shardHoldWarning };