@staix/agent-mem 0.20.3 → 0.22.0

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

@@ -0,0 +1,257 @@
+/** Read-only retained placement evidence. Neither a planned object nor a cached ref is a publication receipt. */
+import { capturePlacementPublicationMetadata, type PlacementJournalRead, type PlacementPublicationStored } from "./sync-placement-journal-storage.ts";
+import { rebuildPlacementProjection, type PlacementProjection } from "./sync-placement-projection.ts";
+import { SyncPlacementJournalError } from "./sync-placement-journal-format.ts";
+import { createHash } from "node:crypto";
+import { lstatSync, opendirSync } from "node:fs";
+import { join } from "node:path";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { memoryGitEnv, memoryGitSync } from "./platform.ts";
+import { placementCacheConfigStamp, placementCacheRootStamp, validatePlacementCacheConfig } from "./sync-placement-cache.ts";
+import { SYNC_SCREEN_MAX_BYTES, SYNC_SCREEN_MAX_ROWS } from "./sync-screen.ts";
+import { PUBLIC_PRUNE_REPLAY_MAX_BYTES } from "./public-prune-input-chain.ts";
+import { PUBLIC_PRUNE_GRAPH_MAX_BYTES } from "./public-prune-inputs.ts";
+import { ShardHistoryAuditor } from "./shard-sync-history.ts";
+import { SHARD_PACK_MAX_BYTES, shardSyncRef, type ShardSyncRealm } from "./shard-sync-format.ts";
+import type { PlacementRealm } from "./sync-placement-journal-format.ts";
+import { placementKeyId } from "./sync-placement-journal-format.ts";
+import type { ShardHistory } from "./shard-sync-history.ts";
+import type { PlacementPublicationDecision, PlacementPublicationObject } from "./sync-placement-publication-plan.ts";
+
+export interface InspectionJournal {
+  journal: PlacementJournalRead;
+  projection: PlacementProjection;
+  publications: ReadonlyMap<string, PlacementPublicationStored>;
+  assertCurrent(): void;
+}
+
+export function captureInspectionJournal(home: string, epochHash: string): InspectionJournal {
+  const captured = capturePlacementPublicationMetadata(home, epochHash, io => {
+    const journal = io.journal();
+    if (journal.pending) throw new SyncPlacementJournalError("pending");
+    const attempts = new Set<string>();
+    for (const name of io.names()) {
+      const match = /^publication-([a-f0-9]{64})-/.exec(name);
+      if (match) attempts.add(match[1]!);
+    }
+    const publications = new Map<string, PlacementPublicationStored>();
+    for (const attempt of [...attempts].sort()) {
+      const publication = io.publication(attempt);
+      if (publication.pending) throw new SyncPlacementJournalError("pending");
+      const frontier = (sequence: number) => sequence === 0 ? publication.bundle.root.epochHash : journal.records[sequence - 1]?.seal;
+      if (frontier(publication.bundle.root.journal.sequence) !== publication.bundle.root.journal.headHash) throw new SyncPlacementJournalError("corrupt");
+      const receipt = publication.facts.find(fact => fact.phase === "completed");
+      if (receipt?.phase === "completed" && frontier(receipt.journal.sequence) !== receipt.journal.headHash) throw new SyncPlacementJournalError("corrupt");
+      const root = publication.bundle.root, artifact = publication.facts.find(fact => fact.phase === "artifact-built");
+      if (artifact?.phase === "artifact-built" && artifact.exportHash !== hashJSON(root.targets.map(target => target.exportSetHash))) throw new SyncPlacementJournalError("corrupt");
+      if (receipt?.phase === "completed" && receipt.outcomeHash !== (receipt.outcome === "committed"
+        ? hashJSON({ attempt: root.seal, commits: root.targets.map(target => target.commit) }) : hashJSON({ attempt: root.seal, outcome: "unknown" }))) throw new SyncPlacementJournalError("corrupt");
+      publications.set(attempt, publication);
+    }
+    return { journal, projection: rebuildPlacementProjection(journal.epoch, journal.records), publications };
+  });
+  return { ...captured.value, assertCurrent: captured.assertCurrent };
+}
+
+export interface InspectionExposureProof { remoteHash: string; refHash: string; commit: string }
+export interface InspectionTarget { realm: ShardSyncRealm; generation: string }
+export interface RetainedInspectionHistories {
+  old: (ShardHistory | undefined)[];
+  tips: (string | undefined)[];
+  published: Map<string, InspectionExposureProof[]>;
+}
+const physicalRealm = (realm: ShardSyncRealm): PlacementRealm => realm.scope === "user" ? { scope: "user" } : { scope: "project", keyHash: hash(realm.key) };
+
+/** Historical core acknowledgement plus exact immutable membership, never a current remote-head observation. */
+export async function inspectRetainedPublicationHistories(snapshot: InspectionJournal, targets: readonly InspectionTarget[], objects?: PlacementInspectionObjects): Promise<RetainedInspectionHistories> {
+  const result: RetainedInspectionHistories = { old: targets.map(() => undefined), tips: targets.map(() => undefined), published: new Map() };
+  const selected = new Map(targets.map((target, index) => [canonicalJSON(physicalRealm(target.realm)), index]));
+  const publications = [...snapshot.publications.values()].sort((a, b) => a.bundle.root.journal.sequence - b.bundle.root.journal.sequence || a.bundle.root.seal.localeCompare(b.bundle.root.seal));
+  for (const publication of publications) {
+    const root = publication.bundle.root, decisions = publication.bundle.chunks.filter(chunk => chunk.kind === "decisions").flatMap(chunk => chunk.items as PlacementPublicationDecision[]);
+    const decisionByKey = new Map(decisions.map(decision => [placementKeyId(decision.key), decision]));
+    const receipt = publication.facts.find(fact => fact.phase === "completed"), artifact = publication.facts.find(fact => fact.phase === "artifact-built");
+    if (!objects || publication.phase !== "completed" || receipt?.phase !== "completed" || receipt.outcome !== "committed") continue;
+    if (artifact?.phase !== "artifact-built") unavailable();
+    for (const [targetIndex, planned] of root.targets.entries()) {
+      const index = selected.get(canonicalJSON(planned.realm)); if (index === undefined) continue;
+      const target = targets[index]!, tip = planned.commit ?? planned.expectedRemoteHead;
+      if (!tip) continue;
+      if (planned.refHash !== hash(shardSyncRef(target.realm))) unavailable();
+      const auditor = objects.auditor(target.realm, target.generation), history = await auditor.history(tip);
+      if (history.rows.size > SYNC_SCREEN_MAX_ROWS) bound();
+      const membership = [...history.rows.values()].map(row => ({ id: row.id, rowHash: hashJSON(row) })).sort((a, b) => a.id.localeCompare(b.id));
+      if (hashJSON(membership) !== planned.exportSetHash || hash(history.files.get("shard.json") ?? Buffer.alloc(0)) !== planned.descriptorHash
+        || planned.tree !== objects.tree(tip)) unavailable();
+      const retained = publication.bundle.chunks.filter(chunk => chunk.kind === "objects").flatMap(chunk => chunk.items as PlacementPublicationObject[]);
+      for (const object of retained) if (object.targetIndex === targetIndex) {
+        const body = objects.object(object.oid, object.type, object.type === "commit" ? 65536 : SHARD_PACK_MAX_BYTES);
+        if (body.length !== object.size || hash(body) !== object.sha256) unavailable();
+      }
+      const acknowledgedHistories = new Map<string, ShardHistory>([[tip, history]]);
+      for (const record of snapshot.journal.records) {
+        if (record.kind !== "publication-committed" || record.outcome.attemptHash !== root.seal
+          || record.sequence <= root.journal.sequence || record.sequence > root.journal.sequence + root.reservedRecords
+          || canonicalJSON(record.key.realm) !== canonicalJSON(planned.realm)) continue;
+        const id = placementKeyId(record.key), decision = decisionByKey.get(id), commit = record.outcome.commit;
+        if (!decision || record.sourcePlacement !== decision.sourcePlacement || record.outcome.remoteHash !== root.remoteHash || record.outcome.refHash !== planned.refHash
+          || !(commit === planned.expectedRemoteHead || decision.eligible && planned.publish && commit === planned.commit)
+          || record.requestId !== hashJSON({ attempt: root.seal, key: record.key, kind: record.kind, commit })
+          || record.effectHash !== hashJSON({ attempt: root.seal, context: root.contextHash, key: record.key, kind: record.kind, commit })
+          || record.outcome.proofHash !== hashJSON({ attempt: root.seal, key: record.key, commit, remote: root.remoteHash, ref: planned.refHash })) unavailable();
+        let atCommit = acknowledgedHistories.get(commit);
+        if (!atCommit) {
+          if (!await auditor.verifiedAncestor(commit, tip)) unavailable();
+          atCommit = await auditor.history(commit); acknowledgedHistories.set(commit, atCommit);
+        }
+        const row = atCommit.rows.get(record.key.id);
+        if (!row || hashJSON(row) !== record.key.rowHash) unavailable();
+        const proof = { remoteHash: root.remoteHash, refHash: planned.refHash, commit };
+        const prior = result.published.get(id) ?? [];
+        const previous = prior.findIndex(value => value.remoteHash === proof.remoteHash && value.refHash === proof.refHash);
+        if (previous < 0) prior.push(proof); else prior[previous] = proof;
+        result.published.set(id, prior);
+      }
+      // Only the retained selected origin supplies publication dependencies. A receipt from another remote
+      // is historical exposure, never a reason to hydrate its bodies into the current publication target.
+      if (root.remoteHash === objects.remoteHash) { result.old[index] = history; result.tips[index] = tip; }
+    }
+  }
+  for (const proofs of result.published.values()) proofs.sort((a, b) => canonicalJSON(a).localeCompare(canonicalJSON(b)));
+  objects?.assertCurrent(); snapshot.assertCurrent(); return result;
+}
+
+function unavailable(): never { throw new SyncPlacementJournalError("corrupt"); }
+function bound(): never { throw new SyncPlacementJournalError("bound"); }
+const hash = (bytes: string | Uint8Array) => createHash("sha256").update(bytes).digest("hex");
+const oid = (value: string) => /^[a-f0-9]{40}$/.test(value);
+const forbidden = ["commondir", "shallow", "info/grafts", "objects/info/alternates", "objects/info/http-alternates", "config.worktree"];
+function readCommand(args: readonly string[]): boolean {
+  const ref = (value: string | undefined) => !!value && /^refs\/heads\/amem\/(?:u|p\/[a-f0-9]{16})$/.test(value);
+  if (args[0] === "config") return args.join("\0") === "config\0--local\0--no-includes\0--null\0--list";
+  if (args[0] === "cat-file") return args.length === 3 && ["-t", "-s", "blob", "commit", "tree"].includes(args[1] ?? "") && oid(args[2] ?? "");
+  if (args[0] === "rev-list") return args.length === 5 && args.slice(0, 4).join("\0") === "rev-list\0--topo-order\0--reverse\0--parents" && oid(args[4] ?? "");
+  if (args[0] === "symbolic-ref") return args.length === 3 && args[1] === "--quiet" && ref(args[2]);
+  return args[0] === "rev-parse" && (args.length === 2 && ["--is-bare-repository", "--show-object-format"].includes(args[1] ?? "")
+    || args.length === 4 && args[1] === "--verify" && args[2] === "--quiet" && ref(args[3]));
+}
+
+/** Bind the complete private cache inventory, not a mutable ref as evidence of a remote acknowledgement.
+ * ponytail: diagnostic cache metadata shares the 20000-entry/8MiB ceiling and the existing 256MiB replay-disk
+ * ceiling. Larger inventories need a reviewed immutable object inventory; no entry is silently skipped. */
+function cacheInventory(cache: string): string {
+  const pending = [cache], rows: unknown[] = []; let metadataBytes = 0, diskBytes = 0;
+  const record = (file: string) => {
+    if (rows.length >= SYNC_SCREEN_MAX_ROWS) return bound();
+    const stat = lstatSync(file, { bigint: true });
+    if (stat.isSymbolicLink() || stat.uid !== BigInt(process.getuid?.() ?? -1) || (stat.mode & 0o077n) !== 0n
+      || !stat.isDirectory() && (!stat.isFile() || stat.nlink !== 1n) || file.endsWith(".promisor")) unavailable();
+    if (stat.isFile()) { diskBytes += Number(stat.size); if (diskBytes > PUBLIC_PRUNE_REPLAY_MAX_BYTES) bound(); }
+    const row = [file, stat.isDirectory() ? "directory" : "file", ...[stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeNs, stat.ctimeNs].map(String)];
+    metadataBytes += Buffer.byteLength(canonicalJSON(row)); if (metadataBytes > SYNC_SCREEN_MAX_BYTES) bound(); rows.push(row);
+    return stat.isDirectory();
+  };
+  record(cache);
+  while (pending.length) {
+    const reader = opendirSync(pending.pop()!);
+    try { for (;;) { const entry = reader.readSync(); if (!entry) break; const file = join(reader.path, entry.name); if (record(file)) pending.push(file); } }
+    finally { reader.closeSync(); }
+  }
+  return hash(canonicalJSON(rows.sort((a, b) => canonicalJSON(a).localeCompare(canonicalJSON(b)))));
+}
+
+/** Fixed local Git reads only. No initialization, fetch, remote probing, write command, credential or lazy fetch. */
+export class PlacementInspectionObjects {
+  readonly cache: string;
+  readonly remoteHash: string;
+  private readonly home: string;
+  private readonly stamp: string;
+  private readonly rootStamp: string;
+  private readonly inventory: string;
+  private readonly check: () => void;
+  private bytes = 0;
+  private sourceRows = 0;
+  private sourceBytes = 0;
+  private readonly sourcePacks = new Set<string>();
+  private readonly objects = new Map<string, { type: string; bytes: Buffer }>();
+  constructor(home: string, check: () => void) {
+    this.home = home; this.cache = join(home, "shard-sync-placement", "objects.git"); this.check = check;
+    this.rootStamp = placementCacheRootStamp(home);
+    this.inventory = cacheInventory(this.cache); this.stamp = placementCacheConfigStamp(this.cache);
+    this.quick();
+    const config = validatePlacementCacheConfig(this.text(["config", "--local", "--no-includes", "--null", "--list"]));
+    const origin = config.get("remote.origin.url");
+    if (!origin || origin.length > 4096 || origin.startsWith("-") || /[\r\n\0]/.test(origin) || config.has("remote.origin.pushurl") && config.get("remote.origin.pushurl") !== origin) unavailable();
+    this.remoteHash = hash(origin);
+    if (this.text(["rev-parse", "--is-bare-repository"]) !== "true" || this.text(["rev-parse", "--show-object-format"]) !== "sha1") unavailable();
+    this.assertCurrent();
+  }
+  private quick(): void {
+    this.check(); this.cacheCheck();
+  }
+  private cacheCheck(): void {
+    if (placementCacheRootStamp(this.home) !== this.rootStamp) throw new SyncPlacementJournalError("changed");
+    if (placementCacheConfigStamp(this.cache) !== this.stamp) throw new SyncPlacementJournalError("changed");
+    for (const file of forbidden) if (lstatSync(join(this.cache, file), { throwIfNoEntry: false })) unavailable();
+  }
+  private run(args: string[], maximum: number): { code: number; bytes: Buffer } {
+    this.quick();
+    if (!readCommand(args)) unavailable();
+    const env = memoryGitEnv(process.env, { repositoryIsolation: true, readOnlyDiagnostic: true });
+    const result = memoryGitSync(["--no-replace-objects", "--git-dir", this.cache, "-c", "protocol.allow=never", "-c", "maintenance.auto=false", "-c", "gc.auto=0", "-c", "core.commitGraph=false", ...args],
+      { encoding: "buffer", cwd: this.home, env, timeout: 10000, killSignal: "SIGKILL", maxBuffer: maximum });
+    this.quick();
+    if (result.error) { if ((result.error as NodeJS.ErrnoException).code === "ENOBUFS") bound(); unavailable(); }
+    return { code: result.status ?? -1, bytes: result.stdout };
+  }
+  private text(args: string[]): string {
+    const result = this.run(args, SYNC_SCREEN_MAX_BYTES); if (result.code !== 0) unavailable();
+    return new TextDecoder("utf-8", { fatal: true }).decode(result.bytes).trim();
+  }
+  ref(realm: ShardSyncRealm): string | undefined {
+    const ref = shardSyncRef(realm), symbolic = this.run(["symbolic-ref", "--quiet", ref], 65536);
+    if (symbolic.code !== 1) unavailable();
+    const result = this.run(["rev-parse", "--verify", "--quiet", ref], 65536), value = result.bytes.toString("utf8").trim();
+    if (result.code === 1) return undefined;
+    if (result.code !== 0 || !oid(value)) unavailable(); return value;
+  }
+  object(object: string, type: "commit" | "tree" | "blob", maximum: number): Buffer {
+    // ponytail: a diagnostic retains at most 20000 object identities within the existing 80MiB graph bound.
+    // Larger retained histories need a reviewed immutable digest inventory; physical row-pack limits stay separate.
+    if (!oid(object)) unavailable();
+    const prior = this.objects.get(object); if (prior) { if (prior.type !== type || prior.bytes.length > maximum) unavailable(); return Buffer.from(prior.bytes); }
+    if (this.objects.size >= SYNC_SCREEN_MAX_ROWS) bound();
+    if (this.text(["cat-file", "-t", object]) !== type) unavailable();
+    const size = Number(this.text(["cat-file", "-s", object]));
+    if (!Number.isSafeInteger(size) || size < 0 || size > maximum || this.bytes + size > PUBLIC_PRUNE_GRAPH_MAX_BYTES) bound();
+    const result = this.run(["cat-file", type, object], Math.max(1, maximum));
+    if (result.code !== 0 || result.bytes.length !== size || createHash("sha1").update(`${type} ${size}\0`).update(result.bytes).digest("hex") !== object) unavailable();
+    this.bytes += size; this.objects.set(object, { type, bytes: result.bytes }); return Buffer.from(result.bytes);
+  }
+  auditor(realm: ShardSyncRealm, generation: string): ShardHistoryAuditor {
+    // The byte cache is shared and bounded. Do not retain a full decoded body map for every historical receipt.
+    return new ShardHistoryAuditor({ realm, generation, placement: true, publicPrune: true, git: async args => this.text(args),
+        object: async (id, type) => this.object(id, type, type === "commit" ? 65536 : SHARD_PACK_MAX_BYTES),
+        blob: async (id, path) => {
+          const bytes = this.object(id, "blob", path === "shard.json" || path.startsWith("prune-witnesses/") ? 65536 : SHARD_PACK_MAX_BYTES);
+          const physical = canonicalJSON([realm, id]);
+          if (path.startsWith("rows/") && !this.sourcePacks.has(physical)) {
+            let lines = 0; for (const byte of bytes) if (byte === 10) lines++;
+            if (this.sourceRows + lines > SYNC_SCREEN_MAX_ROWS || this.sourceBytes + bytes.length > SYNC_SCREEN_MAX_BYTES) bound();
+            this.sourceRows += lines; this.sourceBytes += bytes.length; this.sourcePacks.add(physical);
+          }
+          return bytes;
+        } });
+  }
+  tree(commit: string): string {
+    const body = this.object(commit, "commit", 65536), first = body.subarray(0, body.indexOf(10)).toString("ascii");
+    if (!/^tree [a-f0-9]{40}$/.test(first)) unavailable(); return first.slice(5);
+  }
+  assertCurrent(): void {
+    this.check(); this.assertRetained();
+  }
+  /** Passive final proof: never invokes an attestation/policy callback after another input's final check. */
+  assertRetained(): void {
+    this.cacheCheck(); if (cacheInventory(this.cache) !== this.inventory) throw new SyncPlacementJournalError("changed");
+  }
+}

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

@@ -0,0 +1,66 @@
+/** Passive pending-prune namespace capture. It grants no recovery, writer or publication authority. */
+import { lstatSync, opendirSync, type BigIntStats } from "node:fs";
+import { join } from "node:path";
+import { types } from "node:util";
+import { canonicalJSON, hashJSON } from "./generation.ts";
+import { realPath } from "./platform.ts";
+import { SYNC_SCREEN_MAX_BYTES, SYNC_SCREEN_MAX_ROWS } from "./sync-screen.ts";
+import { SyncPlacementJournalError, type SyncPlacementJournalErrorCode } from "./sync-placement-journal-format.ts";
+
+function fail(code: SyncPlacementJournalErrorCode = "corrupt"): never { throw new SyncPlacementJournalError(code); }
+function owned(stat: BigIntStats, directory: boolean): void {
+  if (stat.isSymbolicLink() || stat.uid !== BigInt(process.getuid?.() ?? -1) || (stat.mode & 0o077n) !== 0n
+    || (directory ? !stat.isDirectory() : !stat.isFile() || stat.nlink !== 1n)) fail();
+}
+const stamp = (stat: BigIntStats) => [stat.dev, stat.ino, stat.uid, stat.mode, stat.size, stat.mtimeNs, stat.ctimeNs].map(String);
+function parentIdentity(target: string): string {
+  const stat = lstatSync(target, { bigint: true }); owned(stat, true);
+  // Derived indexes may change the target directory; its identity/ownership, rather than unrelated contents, is binding.
+  return canonicalJSON([stat.dev, stat.ino, stat.uid, stat.mode].map(String));
+}
+function snapshot(target: string): string {
+  const dir = join(target, "prune-plans"), before = lstatSync(dir, { bigint: true, throwIfNoEntry: false });
+  if (!before) return "absent";
+  owned(before, true);
+  const rows: string[][] = []; let count = 0, metadataBytes = Buffer.byteLength(canonicalJSON({ directory: stamp(before), entries: [] }));
+  const iterator = opendirSync(dir);
+  try {
+    for (;;) {
+      const entry = iterator.readSync(); if (!entry) break;
+      if (++count > SYNC_SCREEN_MAX_ROWS) fail("bound");
+      // Refuse incomplete/malformed claim names too. No content is read, decoded, completed or removed.
+      if (entry.name.startsWith("pending-local-") || entry.name.startsWith("pending-log-")) fail("pending");
+      const stat = lstatSync(join(dir, entry.name), { bigint: true }); owned(stat, stat.isDirectory());
+      const row = [entry.name, stat.isDirectory() ? "directory" : "file", ...stamp(stat)];
+      metadataBytes += Buffer.byteLength(canonicalJSON(row)) + (rows.length ? 1 : 0); if (metadataBytes > SYNC_SCREEN_MAX_BYTES) fail("bound");
+      rows.push(row);
+    }
+  } finally { iterator.closeSync(); }
+  const after = lstatSync(dir, { bigint: true }); owned(after, true);
+  if (canonicalJSON(stamp(before)) !== canonicalJSON(stamp(after))) fail("changed");
+  rows.sort((a, b) => a[0]! < b[0]! ? -1 : a[0]! > b[0]! ? 1 : 0);
+  return hashJSON({ directory: stamp(before), entries: rows });
+}
+function safeError(error: unknown, final: boolean): never {
+  if (error && typeof error === "object" && !types.isProxy(error) && error instanceof SyncPlacementJournalError) {
+    const code = Object.getOwnPropertyDescriptor(error, "code");
+    if (code && "value" in code && ["bound", "pending", "changed", "corrupt"].includes(code.value))
+      return fail(final && code.value !== "bound" ? "changed" : code.value);
+  }
+  return fail(final ? "changed" : "corrupt");
+}
+/** Captures the selected target's namespace and returns a no-effect final recheck.
+ * ponytail: at most20000 direct metadata entries/8MiB of canonical name/stat metadata may be captured. Saved plan
+ * bodies are never read; a reviewed streaming namespace proof is required before this inventory ceiling can grow. */
+export function captureInspectionPendingPrunes(targetDir: string): () => void {
+  try {
+    const original = parentIdentity(targetDir), target = realPath(targetDir);
+    if (parentIdentity(target) !== original) fail("changed");
+    const before = snapshot(target);
+    if (parentIdentity(target) !== original) fail("changed");
+    return () => {
+      try { if (parentIdentity(target) !== original || snapshot(target) !== before || parentIdentity(target) !== original) fail("changed"); }
+      catch (error) { safeError(error, true); }
+    };
+  } catch (error) { return safeError(error, false); }
+}

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

@@ -0,0 +1,240 @@
+/** IDs-only current placement decisions and separately verified historical exposure. No effects or network. */
+import { createHash } from "node:crypto";
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { types } from "node:util";
+import { SegmentReadBudgetError } from "./bridge.ts";
+import { canonicalJSON, hashJSON, selectorRevision } from "./generation.ts";
+import { assertFormatFloor, FormatFloorError } from "./formats.ts";
+import { readPlacementRuntimeMarkers, SyncPlacementRuntimeError } from "./sync-placement-guard.ts";
+import { readActivePlacementBinding } from "./sync-placement-active.ts";
+import { PLACEMENT_FORMAT } from "./sync-placement-format.ts";
+import { captureSyncPlacementContext, type PlacementCapturePort } from "./sync-placement-capture.ts";
+import { placementKeyId, SyncPlacementJournalError, type PlacementKey, type PlacementHoldReason } from "./sync-placement-journal-format.ts";
+import { materializePlacementRows, verifiedPlacementPrunes } from "./sync-placement-materialize.ts";
+import { placementCacheRootStamp } from "./sync-placement-cache.ts";
+import { captureInspectionJournal, inspectRetainedPublicationHistories, PlacementInspectionObjects, type InspectionExposureProof } from "./sync-placement-inspection-evidence.ts";
+import { outboundPolicyEvaluator, type RowScreen, type SyncPolicyCategory } from "./sync-screen.ts";
+import { explicitExpirySnapshot } from "./generation-index.ts";
+import { reducePruneRows, type PruneRow } from "./prune.ts";
+import { readPublicPruneViewForActivation } from "./public-prune-view.ts";
+import { reducePublicPruneInputs } from "./public-prune-inputs.ts";
+import { inspectPublisherPruneLineages } from "./prune-publisher-lineage.ts";
+import type { PublicPruneLineage } from "./public-prune-witness.ts";
+import type { PlacementPublicationDecisionReason } from "./sync-placement-publication-plan.ts";
+import type { ShardSyncRealm, ShardSyncRow } from "./shard-sync-format.ts";
+import type { MemoryStore } from "./store.ts";
+import { captureInspectionPendingPrunes } from "./sync-placement-inspection-pending.ts";
+import { SharedWriterRevisionError } from "./sync-placement-writer-revision-format.ts";
+
+export interface SyncPlacementInspectionOptions {
+  screen?: RowScreen;
+  policyVersion?: () => string;
+  /** Same fresh writer-pin binding as v3 sync; this read-only port grants no effect or activation authority. */
+  placementAttestation?: PlacementCapturePort["attest"];
+}
+export type SyncPlacementDisposition = "eligible" | "policy-local" | "person-local" | "held";
+export type SyncPlacementExposureEvidence = InspectionExposureProof;
+export type SyncPlacementExposure = { certainty: "verified-published"; evidence: SyncPlacementExposureEvidence[] }
+  | { certainty: "not-observed" | "unknown" };
+export interface SyncPlacementInspectionRow extends PlacementKey {
+  sourcePlacement: "local" | "synced";
+  disposition: SyncPlacementDisposition;
+  reason: PlacementPublicationDecisionReason;
+  categories: SyncPolicyCategory[];
+  holdReasons: PlacementHoldReason[];
+  exposure: SyncPlacementExposure;
+}
+export interface SyncPlacementIntrinsicLocalRow extends PlacementKey {
+  sourcePlacement: "local";
+  reason: "intrinsic-local";
+  categories: SyncPolicyCategory[];
+  holdReasons: PlacementHoldReason[];
+  exposure: SyncPlacementExposure;
+}
+export type SyncPlacementInspectionIncompleteReason = "placement-not-active" | "binding-changed" | "input-unavailable" | "input-bound" | "input-changed"
+  | "journal-unavailable" | "policy-unavailable" | "attestation-unavailable" | "evidence-unavailable" | "reader-upgrade-required";
+export type SyncPlacementInspection = {
+  complete: true; rows: SyncPlacementInspectionRow[]; intrinsicLocal: SyncPlacementIntrinsicLocalRow[]; fingerprint: string;
+  counts: { selected: number; rows: number; intrinsicLocal: number; eligible: number; policyLocal: number; personLocal: number; held: number; verifiedPublished: number; notObserved: number; unknown: number };
+} | { complete: false; reason: SyncPlacementInspectionIncompleteReason; nextStep: string };
+
+const categories: readonly SyncPolicyCategory[] = ["secret", "personal-data", "deny-path", "private-or-invalid", "host"];
+const remedies: Record<SyncPlacementInspectionIncompleteReason, string> = {
+  "placement-not-active": "Placement is not active; complete the person-reviewed shard/public-prune migrations and separately authorized placement activation before inspecting placement.",
+  "binding-changed": "Selected placement bindings changed; inspect the retained activation to restore matching markers when required, then reopen the selected project/user handles and inspect again.",
+  "input-unavailable": "Selected source or placement-context inputs are unreadable, incomplete or unsupported; inspect retained source metadata and any recorded partial request, verify compatible writer pins, then inspect again.",
+  "input-bound": "Placement inspection exceeds its supported 8 MiB/20000-row or retained-evidence bounds; request a person-reviewed bounded epoch transition before inspecting again.",
+  "input-changed": "The selected placement inspection context changed; wait for stable source, journal and policy bindings, then inspect again.",
+  "journal-unavailable": "The retained placement journal is incomplete or inconsistent; preserve it and resume its exact recorded request with a compatible runtime before inspecting again.",
+  "policy-unavailable": "The policy callback/version or configured/default-deny epoch is unavailable or changed; restore a stable policy and policyVersion before inspecting again.",
+  "attestation-unavailable": "Fresh placement writer-pin/quiescence attestation is missing or invalid; supply the matching placementAttestation callback and inspect again.",
+  "evidence-unavailable": "Retained publication evidence is unreadable or inconsistent; check the private cache's ownership, permissions, links and exact objects, restore compatible retained evidence, then use a separately authorized sync to reverify before inspecting again.",
+  "reader-upgrade-required": "The configured sync format floor refuses the loaded reader; install a compatible newer runtime, reopen the selected handles and inspect again.",
+};
+class Incomplete extends Error {
+  constructor(readonly reason: SyncPlacementInspectionIncompleteReason) { super(remedies[reason]); }
+}
+function fail(reason: SyncPlacementInspectionIncompleteReason): never { throw new Incomplete(reason); }
+const digest = (value: string) => createHash("sha256").update(value).digest("hex");
+function physical(realm: ShardSyncRealm): PlacementKey["realm"] { return realm.scope === "user" ? { scope: "user" } : { scope: "project", keyHash: digest(realm.key) }; }
+function keyId(key: PlacementKey): string { return placementKeyId({ realm: key.realm, id: key.id, rowHash: key.rowHash }); }
+function callbacks(input: SyncPlacementInspectionOptions): SyncPlacementInspectionOptions {
+  if (!input || typeof input !== "object" || types.isProxy(input) || ![Object.prototype, null].includes(Object.getPrototypeOf(input))) fail("policy-unavailable");
+  const fields = Object.getOwnPropertyDescriptors(input);
+  const read = <K extends keyof SyncPlacementInspectionOptions>(key: K): SyncPlacementInspectionOptions[K] => {
+    const field = fields[key]; if (!field) return undefined;
+    if (!("value" in field) || !field.enumerable || field.value !== undefined && typeof field.value !== "function") fail("policy-unavailable");
+    return field.value as SyncPlacementInspectionOptions[K];
+  };
+  const result = { screen: read("screen"), policyVersion: read("policyVersion"), placementAttestation: read("placementAttestation") };
+  if (result.screen && !result.policyVersion) fail("policy-unavailable"); return result;
+}
+function inactive(store: MemoryStore): Extract<SyncPlacementInspection, { complete: false }> {
+  const steps: string[] = [];
+  if (!store.profile.sharded) steps.push("Have the person run amem migrate --shards --dry-run, review the plan, then amem migrate --shards --apply.");
+  if (!store.profile.foreignPruneFormat) steps.push("Have the person run amem migrate --public-prune-view --dry-run, review the plan, then amem migrate --public-prune-view --apply.");
+  steps.push("Complete separately person-authorized placement activation with compatible exact writer pins; this stage provides no placement activation command or marker writer.");
+  return { complete: false, reason: "placement-not-active", nextStep: "Placement is not active. " + steps.join(" ") };
+}
+
+export async function inspectSyncPlacement(store: MemoryStore, input: SyncPlacementInspectionOptions = {}): Promise<SyncPlacementInspection> {
+  let phase: SyncPlacementInspectionIncompleteReason = "input-unavailable";
+  let captured = false;
+  try {
+    const options = callbacks(input), home = store.profile.home;
+    assertFormatFloor(home, "sync");
+    const opened = [...store.openedSyncTargets()];
+    const binding = () => hashJSON(store.openedSyncTargets().map(target => ({ profile: target.profile, machine: target.machine,
+      selector: selectorRevision(target.profile.home) })));
+    if (opened.some(target => selectorRevision(target.profile.home) !== target.profile.selectorRevision)) fail("binding-changed");
+    const beforeBinding = binding();
+    if (store.profile.publicationFormat !== PLACEMENT_FORMAT) return inactive(store);
+    if (!options.placementAttestation) fail("attestation-unavailable");
+    if (!opened.length || opened.length > 2 || !opened.includes(store) || opened.some(target => target.profile.home !== home || !target.profile.sharded
+      || !target.profile.generation || !target.profile.shardUser && target.profile.shardKey !== store.profile.shardKey)) fail("binding-changed");
+    const markers = readPlacementRuntimeMarkers(home), active = readActivePlacementBinding(home, markers.profile, markers.shards);
+    if (!active || active.profile.placementHead !== store.profile.placementHead) fail("binding-changed");
+    const targets = opened.map(target => ({ store: target, realm: target.profile.shardUser ? { scope: "user" as const } : { scope: "project" as const, key: target.profile.shardKey! }, generation: target.profile.generation! }));
+    const pendingChecks = targets.map(target => captureInspectionPendingPrunes(target.store.dir));
+    const port: PlacementCapturePort = { attest: options.placementAttestation, ...(options.policyVersion ? { policyVersion: options.policyVersion } : {}) };
+    const capture = captureSyncPlacementContext(home, port, targets.map(target => physical(target.realm)));
+    captured = true;
+    if (capture.activeHead !== active.profile.placementHead || canonicalJSON(capture.context.writers) !== canonicalJSON(capture.writerInventory?.writers??active.activation.writers)) fail("attestation-unavailable");
+    phase = "journal-unavailable"; const retained = captureInspectionJournal(home, active.profile.placementHead);
+    const check = () => {
+      if (binding() !== beforeBinding) fail("binding-changed"); retained.assertCurrent(); capture.assertUnchanged();
+      if (binding() !== beforeBinding) fail("binding-changed");
+    };
+    phase = "evidence-unavailable";
+    const cacheRoot = join(home, "shard-sync-placement"), rootStamp = lstatSync(cacheRoot, { throwIfNoEntry: false }) ? placementCacheRootStamp(home) : undefined;
+    const cache = join(cacheRoot, "objects.git"), cacheAbsent = !lstatSync(cache, { throwIfNoEntry: false });
+    const objects = cacheAbsent ? undefined : new PlacementInspectionObjects(home, check);
+    const histories = await inspectRetainedPublicationHistories(retained, targets, objects);
+    const cached = targets.map(target => objects?.ref(target.realm));
+    const view = readPublicPruneViewForActivation(home, active.profile.pruneInputSetHash, active.profile.generation);
+    const foreignChecks: (() => void)[] = [];
+    phase = "input-unavailable";
+    const plannedTargets = targets.map((target, index) => {
+      const realm = physical(target.realm), id = canonicalJSON(realm), sources = capture.sourceRowsByRealm.get(id);
+      if (!sources) fail("binding-changed");
+      const prunes = [...capture.specialRows.values()].filter(source => canonicalJSON(source.key.realm) === id && source.row.op === "prune");
+      const reduced = reducePruneRows(prunes.map(source => ({ row: source.row, placement: source.sourcePlacement })), { rows: sources, expiries: explicitExpirySnapshot(sources) }, target.generation);
+      if (reduced.invalid || reduced.pending.length) fail("input-unavailable");
+      const inputSetHash = view.realms[target.realm.scope === "user" ? "user" : `project:${target.realm.key}`];
+      let pruned = reduced.targets;
+      if (inputSetHash) {
+        const replay = () => reducePublicPruneInputs({ dir: target.store.dir, realm: target.realm, receivingGeneration: target.generation, inputSetHash,
+          publicationFormat: PLACEMENT_FORMAT, nativeTargets: [...reduced.targets], ordinary: sources.map(source => source.row) });
+        const before = replay(); pruned = before.targets;
+        const identity = (value: ReturnType<typeof replay>) => hashJSON({ targets: [...value.targets].sort(), rows: [...value.rowHashes].sort(), inputs: value.inputs, commitments: value.commitments });
+        const fingerprint = identity(before); foreignChecks.push(() => { if (identity(replay()) !== fingerprint) fail("input-changed"); });
+      }
+      const localPrunes = new Map(prunes.filter(source => source.sourcePlacement === "synced").map(source => [source.key.id, source.row as PruneRow]));
+      return { realm: target.realm, generation: target.generation, remote: histories.tips[index], local: cached[index], fetched: new Set(histories.old[index]?.rows.keys()), localPrunes, pruned };
+    });
+    const lineages = targets.map((target, index) => {
+      const rows = new Map<string, ShardSyncRow>(histories.old[index]?.rows);
+      for (const source of [...capture.rows.values(), ...capture.specialRows.values()]) if (canonicalJSON(source.key.realm) === canonicalJSON(physical(target.realm)) && source.row.op !== "vault_link") {
+        const prior = rows.get(source.key.id); if (prior && hashJSON(prior) !== source.key.rowHash) fail("input-unavailable"); rows.set(source.key.id, source.row);
+      }
+      const candidates = [...rows.values()].filter((row): row is PruneRow => row.op === "prune" && row.generation === target.generation);
+      const boundary = join(target.store.dir, "local", `publisher-boundary-${target.store.machine.id}.json`);
+      const proof = lstatSync(boundary, { throwIfNoEntry: false }) ? inspectPublisherPruneLineages(target.store.profile, candidates) : new Map<string, PublicPruneLineage>();
+      return { rows, proof };
+    });
+    const verified = verifiedPlacementPrunes(targets.map((target, index) => ({ realm: target.realm, generation: target.generation, rows: lineages[index]!.rows,
+      fetched: plannedTargets[index]!.fetched, lineageIds: new Set<string>(lineages[index]!.proof.keys()) })));
+    const rowCategories = new Map<string, Set<SyncPolicyCategory>>();
+    phase = "policy-unavailable"; const evaluate = outboundPolicyEvaluator(home, options.screen);
+    phase = "input-unavailable";
+    const guardedEvaluate = (value: unknown): ReturnType<typeof evaluate> => {
+      check(); let verdict: ReturnType<typeof evaluate>;
+      try { verdict = evaluate(structuredClone(value) as Record<string, unknown>); } catch { return fail("policy-unavailable"); }
+      check();
+      if (!verdict.ok && value && typeof value === "object" && "id" in value && typeof value.id === "string") {
+        let known = rowCategories.get(value.id); if (!known) rowCategories.set(value.id, known = new Set()); known.add(verdict.category);
+      }
+      return verdict;
+    };
+    const materialized = await materializePlacementRows({ capture, projection: retained.projection, generation: active.profile.generation, targets: plannedTargets,
+      old: histories.old, verifiedPrunes: verified, createdUnixSeconds: Math.floor(Date.now() / 1000), evaluate: guardedEvaluate,
+      readTree: async (_index, head) => { if (!objects) fail("evidence-unavailable"); return objects.tree(head); },
+      publisherLineages: (index, rows) => inspectPublisherPruneLineages(targets[index]!.store.profile, rows) });
+    const exposureFor = (key: PlacementKey): SyncPlacementExposure => {
+      const known = histories.published.get(placementKeyId(key)), attempts = retained.projection.get(key)?.attempts;
+      return known?.length ? { certainty: "verified-published", evidence: known } : { certainty: attempts?.length ? "unknown" : "not-observed" };
+    };
+    const rows: SyncPlacementInspectionRow[] = materialized.decisions.map(decision => {
+      const state = retained.projection.get(decision.key), holdReasons = state?.reasons ?? [], own = new Set<SyncPolicyCategory>(rowCategories.get(decision.key.id));
+      for (const value of [decision.reason, ...holdReasons]) if (categories.includes(value as SyncPolicyCategory)) own.add(value as SyncPolicyCategory);
+      const disposition: SyncPlacementDisposition = decision.eligible ? "eligible" : holdReasons.includes("person-local") ? "person-local"
+        : decision.reason !== "source-local" && own.size ? "policy-local" : "held";
+      return { ...decision.key, sourcePlacement: decision.sourcePlacement, disposition, reason: decision.reason,
+        categories: [...own].sort(), holdReasons: [...holdReasons].sort(), exposure: exposureFor(decision.key) };
+    });
+    const outboundKeys = new Set(rows.map(keyId));
+    const intrinsicLocal: SyncPlacementIntrinsicLocalRow[] = [];
+    for (const source of capture.specialRows.values()) if (!outboundKeys.has(placementKeyId(source.key))) {
+      if (source.sourcePlacement !== "local") fail("input-unavailable");
+      guardedEvaluate(source.row);
+      const holdReasons = retained.projection.get(source.key)?.reasons ?? [], own = new Set<SyncPolicyCategory>(rowCategories.get(source.key.id));
+      for (const reason of holdReasons) if (categories.includes(reason as SyncPolicyCategory)) own.add(reason as SyncPolicyCategory);
+      intrinsicLocal.push({ ...source.key, sourcePlacement: "local", reason: "intrinsic-local", categories: [...own].sort(), holdReasons: [...holdReasons].sort(), exposure: exposureFor(source.key) });
+    }
+    intrinsicLocal.sort((a, b) => keyId(a).localeCompare(keyId(b)));
+    // The final recapture invokes host callbacks first; every remaining proof is passive filesystem/data validation.
+    phase = "input-changed"; capture.assertCurrent(); retained.assertCurrent(); for (const checkPending of pendingChecks) checkPending(); for (const checkForeign of foreignChecks) checkForeign(); objects?.assertRetained();
+    if (cacheAbsent && lstatSync(cache, { throwIfNoEntry: false })) fail("input-changed");
+    if (rootStamp !== undefined ? placementCacheRootStamp(home) !== rootStamp : lstatSync(cacheRoot, { throwIfNoEntry: false }) !== undefined) fail("input-changed");
+    if (binding() !== beforeBinding) fail("binding-changed");
+    assertFormatFloor(home, "sync");
+    const counts = { selected: rows.length + intrinsicLocal.length, rows: rows.length, intrinsicLocal: intrinsicLocal.length, eligible: 0, policyLocal: 0, personLocal: 0, held: 0, verifiedPublished: 0, notObserved: 0, unknown: 0 };
+    for (const row of rows) {
+      counts[row.disposition === "policy-local" ? "policyLocal" : row.disposition === "person-local" ? "personLocal" : row.disposition]++;
+    }
+    for (const row of [...rows, ...intrinsicLocal]) {
+      counts[row.exposure.certainty === "verified-published" ? "verifiedPublished" : row.exposure.certainty === "not-observed" ? "notObserved" : "unknown"]++;
+    }
+    return { complete: true, rows, intrinsicLocal, counts, fingerprint: hashJSON({ rows, intrinsicLocal }) };
+  } catch (error) {
+    let reason: SyncPlacementInspectionIncompleteReason = phase;
+    if (error && typeof error === "object" && !types.isProxy(error)) {
+      if(error instanceof SharedWriterRevisionError){const code=Object.getOwnPropertyDescriptor(error,"code")?.value;
+        if(code==="staging"||code==="pending")return{complete:false,reason:"journal-unavailable",nextStep:new SharedWriterRevisionError(code).message};
+      }
+      if (error instanceof Incomplete) reason = error.reason;
+      else if (error instanceof FormatFloorError) {
+        if (error.code === "format_floor") reason = "reader-upgrade-required";
+        else return { complete: false, reason: "input-unavailable", nextStep: "The sync reader-floor declaration is unreadable or unsupported; inspect and restore the person-approved declaration with a compatible runtime, then inspect again." };
+      }
+      else if (error instanceof SyncPlacementRuntimeError) reason = "binding-changed";
+      else if (error instanceof SegmentReadBudgetError) reason = "input-bound";
+      else if (error instanceof SyncPlacementJournalError) {
+        if (error.code === "bound") reason = "input-bound";
+        else if (error.code === "changed") reason = captured ? "input-changed" : "input-unavailable";
+      }
+    }
+    return { complete: false, reason, nextStep: remedies[reason] };
+  }
+}