in2-agent-server 0.20260821.185429

package/dist/direct/orgRepo.js

@@ -0,0 +1,1531 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { runProcess } from "../core/spawn.js";
+import { ORGREPO_ROOT, WORKSPACE_ROOT } from "../core/paths.js";
+import { CHILD_COLLECTION_NAMES, sortKeysDeep } from "../projection/diff.js";
+import { expandComponent } from "./containers.js";
+import { incompleteFacetsOf } from "../orgread/layoutSnapshot.js";
+import { assessComparability, readerIdentityLabel } from "./snapshotComparability.js";
+import { recordGitSpawn } from "./orgRepoSpawnCount.js";
+// The per-org mirror (plan 2026-08-02-002 U2; origin R1–R6, R8).
+//
+// A git repository per org, holding the post-image of every component IN2 has ever TOUCHED there
+// plus the source XML it deployed. Touched, not read: a wave's projection is deliberately wider
+// than its work, and what separates the two is the wave's own request — see `isTouched`. It is a
+// CACHE, not an authority: everything in it is derivable from the evidence bundles, and `rebuild`
+// re-derives it. That is what makes it safe to throw away and what makes cross-machine convergence
+// possible — two consultants holding the same bundle set produce the same history, byte for byte,
+// without merging anything.
+//
+// Determinism is the whole design, so every input git would normally take from the environment is
+// pinned:
+//
+//   author/committer   fixed constants (the operator rides a TRAILER, where it cannot move a SHA)
+//   timestamps         the bundle's mutation window, never the wall clock
+//   ordering           a total sort key — (window start, session id, wave, attempt) — never arrival
+//                      order. ATTEMPT IS A TERM, not a detail: a retry is its own wave here (U2's
+//                      KTD — amending would rewrite history), so it both separates two states of
+//                      one wave in `waveIdentity` and orders them when their windows agree.
+//   config             repo-local, with the user's global and system config neutralized outright
+//   line endings       `* -text` plus core.autocrlf=false: no attribute may rewrite a byte
+//   object format      SHA-1, stated rather than inherited from whatever the local git defaults to
+//
+// The remaining nondeterminism is the SERIALIZATION itself, and it is versioned rather than
+// pretended away: every commit carries `Materializer:`, and a rebuild that meets a foreign trailer
+// from a different version rebuilds the whole history rather than appending a differently-shaped
+// commit onto it (U8 consumes this; the trailer is written here).
+// v4 (2026-08-03): a facet the reader COULD NOT READ is now recorded, where before it vanished.
+// `readLayoutSnapshot` drops `relatedLists` when its Tooling probe fails and declares
+// `INCOMPLETE_FACET relatedLists: ...` in `errors` — and `canonicalSnapshot` stripped `errors`, so
+// the mirror filed a layout that reads as simply having no related lists. `direct_history show`
+// and `diff` then presented a false record of org state: an absence that looks like a fact.
+// `incompleteFacets` now rides the committed snapshot, and an `Incomplete-Facet:` trailer rides the
+// commit, so the bound is visible without reading blobs.
+//
+// The FACET NAME is persisted, never the reason text — see `canonicalSnapshot` for why that line is
+// where it is.
+//
+// CHEAP ON EXISTING HISTORY, and measured rather than assumed: the key is emitted only when
+// non-empty, so a snapshot with nothing to declare is byte-identical to its v3 form. Across the
+// live corpus at the time of this change (org 00Dfn00000BFjbBEAT, 16 sessions, 1224 post-image
+// component snapshots, 55 of them Layouts) ZERO carry an `INCOMPLETE_FACET` marker — 51 layouts
+// predate the dedicated reader and 4 were read with the probe UP. Replaying all 68 bundles under v3
+// and under v4 yields the IDENTICAL `projection/` subtree (e079a329): no blob changes content, so
+// this bump rides along with v3's for free on any mirror not yet rebuilt. The one file that does
+// move is the mirror's own README, which v4 rewrites — it promised "as the org reported it" with no
+// caveat that the org sometimes does not report, and a doc that overstates a guarantee is a defect.
+//
+// v3 (2026-08-03): a disagreement between two snapshots read by DIFFERENT READERS is no longer
+// carded as drift — it is recorded as `Drift-Not-Comparable:` instead (see
+// `snapshotComparability.ts`). The TREE is untouched; what moves is the commit message, and on this
+// history that is the same thing: a differently-worded commit is a different SHA, so v2 and v3
+// replaying one bundle set diverge from the first affected wave onward. Stamped rather than slipped
+// in, for the reason the v1->v2 note gives.
+//
+// Unlike most bumps this one REPAIRS recorded history rather than only re-deriving it. A v2 mirror
+// holds false accusations: replaying the PV corpus (68 commits, org 00Dfn00000BFjbBEAT) under v3
+// drops `Drift: Layout:PV_Asset__c-PV Asset Layout` — which was reader shape, not an edit — and
+// leaves all six genuine `Drift: CustomObject:*` cards exactly where they were. Mirrors still on v2
+// keep the false card until they are replayed: `in2 rebuild-mirror <orgId>`.
+//
+// v2 (2026-08-02): the overlay covers what a wave TOUCHED rather than everything its projection
+// read — see `isTouched`. That changes the tree a given bundle materializes to, which is exactly
+// what this stamp is for: an install still on v1 and an install on v2 replaying the same bundles
+// produce different histories, and the trailer is what makes that visible rather than a mystery
+// about why two consultants' SHAs disagree. Mirrors written by v1 keep their contaminated content
+// until they are replayed — `in2 rebuild-mirror <orgId>`.
+export const MATERIALIZER_VERSION = "orgrepo-v4";
+// Fixed identity. Not a person — the person is `Operator:`. See the note above.
+const AUTHOR_NAME = "IN2 Mirror";
+const AUTHOR_EMAIL = "mirror@in2.local";
+// The root commit's date. Any value works as long as it is the SAME value everywhere; the wall
+// clock is the one value that is not.
+const EPOCH = "1970-01-01T00:00:00Z";
+const GIT_TIMEOUT_MS = 30_000;
+const LOCK_POLL_MS = 25;
+const LOCK_TIMEOUT_MS = 60_000;
+// A lock directory older than this belongs to a process that died holding it. Generous, because
+// taking a live lock away is far worse than waiting: an apply's whole commit runs inside it.
+const LOCK_STALE_MS = 5 * 60_000;
+/** Verdicts that changed the org, and therefore the only ones that materialize (origin R2). */
+const STATE_CHANGING = new Set(["DIFF_VERIFIED", "DELIVERED_WITH_DRIFT", "AMBIGUOUS_DELIVERY"]);
+export const isStateChanging = (verdict) => STATE_CHANGING.has(verdict);
+export class OrgRepoError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "OrgRepoError";
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// identity and path safety
+// ---------------------------------------------------------------------------------------------
+const ORG_ID_RE = /^[a-zA-Z0-9]{15}$|^[a-zA-Z0-9]{18}$/;
+function assertOrgId(orgId) {
+    if (!ORG_ID_RE.test(orgId)) {
+        throw new OrgRepoError("INVALID_ORG_ID", `${JSON.stringify(orgId)} is not a Salesforce org id (15 or 18 alphanumerics). The mirror is keyed by org id and the key becomes a directory name, so anything else is refused rather than normalized.`);
+    }
+    return orgId;
+}
+export function mirrorPath(orgId, root) {
+    return path.join(root ?? ORGREPO_ROOT, assertOrgId(orgId));
+}
+/** A repo-relative path that cannot escape the repo. Manifest paths are org-derived — check them. */
+function safeRelPath(rel) {
+    const normalized = path.normalize(rel).replace(/^[/\\]+/, "");
+    if (!normalized || normalized === "." || normalized.split(/[/\\]/).includes("..") || path.isAbsolute(normalized)) {
+        throw new OrgRepoError("UNSAFE_PATH", `refusing a mirror path that escapes the repository: ${JSON.stringify(rel)}`);
+    }
+    return normalized;
+}
+// A ref the caller may name. Not a git shell: anything option-shaped is refused outright rather
+// than passed to git, where `--upload-pack=` and friends turn a read tool into an exec surface.
+const REF_RE = /^[A-Za-z0-9][A-Za-z0-9._/^~-]{0,199}$/;
+function assertRef(ref) {
+    if (!REF_RE.test(ref) || ref.includes("..")) {
+        throw new OrgRepoError("INVALID_REF", `${JSON.stringify(ref)} is not a plain revision.`);
+    }
+    return ref;
+}
+// ---------------------------------------------------------------------------------------------
+// git plumbing
+// ---------------------------------------------------------------------------------------------
+// An always-empty config file, handed to git as its global and system config, so the user's
+// ~/.gitconfig cannot reach in — which matters because commit.gpgsign, core.autocrlf and user.name
+// are all things a developer's machine sets and all things that would make this machine's history
+// disagree with everyone else's.
+//
+// `/dev/null` rather than a nonexistent path under the temp directory, which is what this was
+// first: git treats a missing file as empty too, but on a shared machine `/tmp` is world-writable,
+// so a fixed filename there is a config file ANYONE can create — and git config has entries
+// (`core.fsmonitor`, `core.pager`, alias expansion) that name a program to run. `/dev/null` cannot
+// be hijacked and always exists.
+const NO_CONFIG = "/dev/null";
+function gitEnv(date) {
+    const stamp = date ?? EPOCH;
+    return {
+        ...process.env,
+        GIT_CONFIG_GLOBAL: NO_CONFIG,
+        GIT_CONFIG_SYSTEM: NO_CONFIG,
+        GIT_ATTR_NOSYSTEM: "1",
+        GIT_AUTHOR_NAME: AUTHOR_NAME,
+        GIT_AUTHOR_EMAIL: AUTHOR_EMAIL,
+        GIT_AUTHOR_DATE: stamp,
+        GIT_COMMITTER_NAME: AUTHOR_NAME,
+        GIT_COMMITTER_EMAIL: AUTHOR_EMAIL,
+        GIT_COMMITTER_DATE: stamp,
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_OPTIONAL_LOCKS: "0",
+        TZ: "UTC"
+    };
+}
+async function git(cwd, args, opts = {}) {
+    recordGitSpawn();
+    const run = await runProcess("git", args, {
+        cwd,
+        env: gitEnv(opts.date),
+        timeoutMs: GIT_TIMEOUT_MS,
+        ...(opts.input !== undefined ? { input: opts.input } : {})
+    });
+    if (run.spawnError) {
+        throw new OrgRepoError("GIT_FAILED", `git is not available on PATH (${run.spawnError}) — the org mirror needs it. History for this org is not being recorded.`);
+    }
+    return { ok: run.exitCode === 0 && !run.timedOut, stdout: run.stdout, stderr: run.stderr, exitCode: run.exitCode };
+}
+/**
+ * `git`, but keeping stdout's BYTES.
+ *
+ * Only `git cat-file --batch` needs this: its records are length-prefixed in bytes, so slicing a
+ * decoded string would drift the moment a snapshot carries a multi-byte character in a label — and
+ * drift there means returning one component's identity for another's, silently, in a report that
+ * names somebody's work.
+ */
+async function gitRaw(cwd, args, opts = {}) {
+    recordGitSpawn();
+    const run = await runProcess("git", args, {
+        cwd,
+        env: gitEnv(),
+        timeoutMs: GIT_TIMEOUT_MS,
+        binary: true,
+        ...(opts.input !== undefined ? { input: opts.input } : {})
+    });
+    if (run.spawnError) {
+        throw new OrgRepoError("GIT_FAILED", `git is not available on PATH (${run.spawnError}) — the org mirror needs it. History for this org is not being recorded.`);
+    }
+    return {
+        ok: run.exitCode === 0 && !run.timedOut,
+        stdout: run.stdout,
+        stderr: run.stderr,
+        exitCode: run.exitCode,
+        stdoutBuffer: run.stdoutBuffer ?? Buffer.alloc(0)
+    };
+}
+async function gitOrThrow(cwd, args, opts = {}) {
+    const run = await git(cwd, args, opts);
+    if (!run.ok) {
+        throw new OrgRepoError("GIT_FAILED", `git ${args[0]} failed (${run.exitCode}): ${(run.stderr || run.stdout).trim().slice(0, 400)}`);
+    }
+    return run.stdout;
+}
+// ---------------------------------------------------------------------------------------------
+// the per-org advisory lock
+// ---------------------------------------------------------------------------------------------
+/**
+ * Serialize same-org work on an advisory `mkdir` lock — the pattern proven in the scale run.
+ *
+ * QUEUE, never refuse: parallel arms against one org are a supported scenario (origin R2), and a
+ * refusal there would make the mirror's completeness depend on scheduling luck. `mkdir` is the
+ * primitive because it is atomic on every filesystem this runs on, needs no daemon, and leaves a
+ * directory whose mtime is enough to spot a holder that died.
+ */
+export async function withOrgLock(orgId, opts, fn) {
+    const root = opts.root ?? ORGREPO_ROOT;
+    await fs.mkdir(root, { recursive: true });
+    const lockDir = path.join(root, `${assertOrgId(orgId)}.lock`);
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            await fs.mkdir(lockDir);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const age = await fs
+                .stat(lockDir)
+                .then((s) => Date.now() - s.mtimeMs)
+                .catch(() => 0);
+            if (age > LOCK_STALE_MS) {
+                // The holder died. Removing a live lock would corrupt an index mid-commit, which is why
+                // the staleness bar is minutes rather than seconds.
+                await fs.rm(lockDir, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() > deadline) {
+                throw new OrgRepoError("LOCK_TIMEOUT", `another apply has held the ${orgId} mirror lock for over ${Math.round(LOCK_TIMEOUT_MS / 1000)}s (${lockDir}).`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
+        }
+    }
+    try {
+        await fs
+            .writeFile(path.join(lockDir, "holder.json"), `${JSON.stringify({ pid: process.pid })}\n`, "utf8")
+            .catch(() => undefined);
+        return await fn();
+    }
+    finally {
+        await fs.rm(lockDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// materialization
+// ---------------------------------------------------------------------------------------------
+/**
+ * The bytes a component contributes to the mirror.
+ *
+ * `observedAt` is dropped, and this is the load-bearing line of the whole module: the projection
+ * stamps every snapshot with the moment it was read, so carrying it through would make an
+ * unchanged component look changed on every single wave — a commit per apply forever, and "no
+ * commit when nothing changed" (R2) quietly false. `errors` goes for the same reason from the other
+ * direction: it describes the READ, not the org.
+ *
+ * WITH ONE EXCEPTION, and the distinction is the whole of v4. An `INCOMPLETE_FACET` entry is not a
+ * fact about the read, it is a fact about THIS DOCUMENT: "the facet named here is not in the state
+ * below". `readLayoutSnapshot` DELETES the key it could not verify, so without the marker the
+ * snapshot asserts a clean absence — a layout with no related lists, indistinguishable from one
+ * whose related lists were never read. That is a false record of org state, and it is the one thing
+ * this tree must never contain. Every other `errors` entry ("read failed: Entity 'null' not found",
+ * a timeout) describes an attempt and is dropped exactly as before.
+ *
+ * THE FACET NAME IS PERSISTED, NOT THE MESSAGE. Two degraded reads of one layout carry different
+ * causes — "connection reset", "socket hang up" — while declaring the identical durable fact. The
+ * prose is transient read-error noise; storing it would make two byte-different blobs out of one
+ * org state, and a byte difference in this tree IS a drift card. Worse, `differingKeys` walks
+ * `state.metadata` and would not see a top-level errors difference at all, so the resulting card
+ * would name no facet and `assessComparability` would pass it through as COMPARABLE. A drift
+ * accusation manufactured entirely out of error text is precisely the failure #26 exists to stop.
+ *
+ * Top level, beside `family` and `source`, and NOT inside `state.metadata`: `differingKeys` reads
+ * the top of `metadata` as the org's facets, so a marker filed there would read as one.
+ *
+ * Keys are sorted deep, because Salesforce returns the same metadata in different key orders on
+ * different reads (the projection diff has carried this normalization since the 6.5.1 run).
+ */
+function canonicalSnapshot(snapshot) {
+    const source = (snapshot ?? {});
+    const { observedAt: _observedAt, errors, ...rest } = source;
+    const incomplete = incompleteFacetsOf(Array.isArray(errors) ? errors : undefined);
+    // Only when non-empty. A snapshot with nothing to declare must serialize byte-for-byte as it did
+    // before this key existed, so the bump costs nothing on history that has no gap to record.
+    const declared = [...new Set(incomplete)].sort();
+    const withMarker = declared.length > 0 ? { ...rest, incompleteFacets: declared } : rest;
+    return `${JSON.stringify(sortKeysDeep(withMarker), null, 2)}\n`;
+}
+const componentKey = (c) => `${c.typeName}:${c.fullName}`;
+/**
+ * Trailer values are IDENTIFIERS, so the audit trail cannot ingest unsanitized org content.
+ *
+ * Component identities are org content — an admin names the layout — and they are recorded because
+ * identity is the entire point. What must not survive is the trailer GRAMMAR: a component named
+ * "x\nOrg-Id: 00Dhacked" would otherwise add a line that git parses as a trailer and rewrite the
+ * commit's own claim about which org it belongs to. Control characters go, whitespace collapses,
+ * and the value is capped — so an identity stays one value on one line.
+ */
+function trailerValue(raw) {
+    // eslint-disable-next-line no-control-regex
+    const flat = raw
+        .replace(/[\u0000-\u001f\u007f]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return flat.slice(0, 200);
+}
+/**
+ * The differing facets, and an HONEST COUNT when there are more than fit.
+ *
+ * `trailerValue` caps a value at 200 characters, which on a long list would silently drop the tail —
+ * and this particular list is the evidence that a difference the reader change cannot explain is
+ * present. A truncation that reads as a complete list is the one failure this whole module exists to
+ * avoid, so the overflow is counted out loud. The full list always survives on the wave result and
+ * in `verdict.json`; only the git trailer is bounded.
+ */
+function facetList(keys, max = 12) {
+    const shown = keys.slice(0, max);
+    const rest = keys.length - shown.length;
+    return `${trailerValue(shown.join(", "))}${rest > 0 ? ` (+${rest} more)` : ""}`;
+}
+/**
+ * The components this wave committed with a facet they could not read, as trailer values.
+ *
+ * Derived from the same `errors` arrays `canonicalSnapshot` reads, so the commit and the tree can
+ * never disagree about which facets went unread. It rides a trailer as well as the blob because
+ * every consumer that renders history — `direct_history log`/`show`, the batch report — reads
+ * trailers, and making them open blobs to find out would be a git call per file on a read path
+ * that currently makes none.
+ */
+function incompleteFacetTrailers(components) {
+    const out = [];
+    for (const component of components) {
+        const errors = component.snapshot?.errors;
+        const facets = [...new Set(incompleteFacetsOf(Array.isArray(errors) ? errors : undefined))].sort();
+        if (facets.length === 0)
+            continue;
+        out.push(`${trailerValue(componentKey(component))} <> ${facetList(facets)}`);
+    }
+    return out.sort();
+}
+function commitMessage(wave, changed, removed, drifted, attributed, incomparable) {
+    const subject = `${trailerValue(wave.wave)} attempt ${wave.attempt}: ${trailerValue(wave.verdict)} — ` +
+        `${changed} component(s)${removed ? `, ${removed} removed` : ""}`;
+    const trailers = [
+        `Org-Id: ${wave.orgId}`,
+        `Session-Id: ${trailerValue(wave.sessionId)}`,
+        `Wave: ${trailerValue(wave.wave)}`,
+        `Attempt: ${wave.attempt}`,
+        `Verdict: ${trailerValue(wave.verdict)}`,
+        `Window-Start: ${trailerValue(wave.windowStart)}`,
+        `Materializer: ${MATERIALIZER_VERSION}`
+    ];
+    if (wave.batchId)
+        trailers.push(`Batch-Id: ${trailerValue(wave.batchId)}`);
+    for (const id of wave.requirementIds ?? [])
+        trailers.push(`Requirement-Id: ${trailerValue(id)}`);
+    if (wave.operator)
+        trailers.push(`Operator: ${trailerValue(wave.operator)}`);
+    if (wave.revertOf) {
+        trailers.push(`Revert-Of: ${trailerValue(`${wave.revertOf.sessionId}/${wave.revertOf.wave}`)}`);
+    }
+    // An ambiguous wave's unobserved components are UNKNOWN in this commit, not unchanged — the flag
+    // is what lets a later drift comparison say so instead of guessing.
+    if (wave.ambiguous)
+        trailers.push("Ambiguous-Delivery: true");
+    // The change scan could not bracket the deploy, so this commit's position in history approximates
+    // nothing. Said here rather than inferred, because order looks equally confident either way.
+    if (wave.windowSuspect)
+        trailers.push("Ordering-Unreliable: true");
+    for (const key of drifted)
+        trailers.push(`Drift: ${trailerValue(key)}`);
+    // Recorded rather than silently dropped: a reader of this history is entitled to see that the
+    // mirror's copy of a component was stale AND why it was not treated as an outside edit. One
+    // trailer per (container, child) pair, so nothing has to be truncated to fit a line.
+    for (const entry of attributed) {
+        for (const child of entry.children) {
+            trailers.push(`Drift-Explained: ${trailerValue(entry.key)} <- ${trailerValue(child)}`);
+        }
+    }
+    // NOT a `Drift:` trailer, deliberately: this history must not record as an accusation something
+    // that is a fact about our own readers. Written all the same, because a comparison that could not
+    // be made is a gap in the record and a reader of this history is entitled to see where.
+    for (const entry of incomparable) {
+        const cause = entry.reason === "READER_CHANGED"
+            ? `${trailerValue(entry.recorded ?? "?")} -> ${trailerValue(entry.observed ?? "?")}`
+            : `facet unread: ${trailerValue((entry.facets ?? []).join(", "))}`;
+        trailers.push(`Drift-Not-Comparable: ${trailerValue(entry.key)} <> ${cause} <> differs: ${facetList(entry.differingKeys)}`);
+    }
+    // What this commit's post-image does NOT contain. A record of the org that silently omits a facet
+    // it could not read is a false record, and the absence is invisible in the tree by construction —
+    // the reader deletes the key rather than leaving an unreliable value. Said out loud here so a
+    // reader of history sees the bound instead of a clean-looking absence.
+    for (const entry of incompleteFacetTrailers(wave.components))
+        trailers.push(`Incomplete-Facet: ${entry}`);
+    return `${subject}\n\n${trailers.join("\n")}\n`;
+}
+async function writeRepoFile(repoDir, rel, content) {
+    const abs = path.join(repoDir, safeRelPath(rel));
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, content, "utf8");
+}
+/**
+ * The org's mirror directory, initialized if absent, with its configuration pinned.
+ *
+ * The pinning is repo-local AND environment-level (see `gitEnv`) on purpose: the repo config
+ * documents the intent where a human looking at the mirror can read it, and the environment is
+ * what actually makes it hermetic when a machine's global config disagrees.
+ */
+export async function ensureRepo(orgId, opts = {}) {
+    const dir = mirrorPath(orgId, opts.root);
+    const isRepo = await fs
+        .stat(path.join(dir, ".git"))
+        .then(() => true)
+        .catch(() => false);
+    if (isRepo) {
+        const recorded = (await git(dir, ["config", "--local", "in2.orgId"])).stdout.trim();
+        if (recorded && recorded.toLowerCase() !== orgId.toLowerCase()) {
+            throw new OrgRepoError("ORG_ID_MISMATCH", `the mirror at ${dir} records org ${recorded}, not ${orgId}. Refusing — one history per org is the invariant that makes this readable at all, and merging two orgs' components into one would be unrecoverable.`);
+        }
+        return dir;
+    }
+    await fs.mkdir(dir, { recursive: true });
+    await gitOrThrow(dir, ["init", "--quiet", "--initial-branch=main", "--object-format=sha1"]);
+    for (const [key, value] of [
+        ["user.name", AUTHOR_NAME],
+        ["user.email", AUTHOR_EMAIL],
+        // Byte fidelity. A mirror whose line endings depend on the machine that wrote it is not a
+        // mirror; it is a second history that happens to look similar.
+        ["core.autocrlf", "false"],
+        ["core.safecrlf", "false"],
+        ["core.fileMode", "false"],
+        ["core.symlinks", "false"],
+        // macOS precomposes NFD filenames on read and Linux does not, so a component whose name
+        // carries an accent would hash to two different trees on two machines. Stated rather than
+        // platform-defaulted, even though Salesforce API names are ASCII — layout NAMES are not.
+        ["core.precomposeunicode", "true"],
+        ["core.hooksPath", path.join(dir, ".git", "no-hooks")],
+        ["commit.gpgsign", "false"],
+        ["tag.gpgsign", "false"],
+        ["gc.auto", "0"],
+        ["in2.orgId", orgId]
+    ]) {
+        await gitOrThrow(dir, ["config", "--local", key, value]);
+    }
+    // `-text` over everything: no attribute may decide to normalize a byte on one machine and not
+    // another. `-diff` on the source tree keeps binary static-resource bytes out of a text diff.
+    await writeRepoFile(dir, ".gitattributes", "* -text\n");
+    await writeRepoFile(dir, "README.md", [
+        `# IN2 org mirror — ${orgId}`,
+        "",
+        "Every component IN2 has TOUCHED in this org, as the org reported it after each wave. A",
+        "component a wave merely READ is not here — the projection behind a wave is deliberately wider",
+        "than its work, and this history is a record of deliveries, not of reads.",
+        "",
+        "AS THE ORG REPORTED IT — AND SOMETIMES THE ORG DOES NOT REPORT. A read can fail to reach a",
+        "facet (SOAP `readMetadata` omits Layout related lists without saying so), and the reader then",
+        "DROPS that facet rather than storing a value it cannot trust. A snapshot missing a facet for",
+        "that reason says so in its own `incompleteFacets`, and the commit carries an",
+        "`Incomplete-Facet:` trailer. Where you see one, the facet was NEVER READ — it is not a claim",
+        "that it is empty, and authoring a full-file replacement from that snapshot would delete",
+        "whatever the org actually has there.",
+        "",
+        "- `projection/` — the post-image canonical JSON, one file per component. Exact about what it",
+        "  contains, and explicit about what it does not: a deleted component's file is removed, and a",
+        "  facet that could not be read is named in `incompleteFacets`.",
+        "- `source/` — the source-format XML that was deployed. A DEPLOY LOG, not a live tree: a",
+        "  deleted component's last deployed bytes stay here on purpose.",
+        "",
+        "This is a REBUILDABLE CACHE derived from the evidence bundles, not an authority: it can be",
+        "deleted and re-materialized, and every commit carries the materializer version that produced",
+        "it. Do not edit it by hand and do not persist its commit SHAs — a rebuild rewrites them by",
+        "design.",
+        ""
+    ].join("\n"));
+    await gitOrThrow(dir, ["add", "-A", "."]);
+    await gitOrThrow(dir, ["commit", "--quiet", "-F", "-"], {
+        date: EPOCH,
+        input: `mirror: ${orgId}\n\nOrg-Id: ${orgId}\nMaterializer: ${MATERIALIZER_VERSION}\n`
+    });
+    return dir;
+}
+/** A repo-relative path as git wants it, whatever separator this platform joined it with. */
+const gitPath = (...parts) => parts.flatMap((p) => p.split(/[/\\]/)).filter(Boolean).join("/");
+/** The identity a snapshot blob names, or null if it names none. The one parse, shared. */
+function keyFromSnapshotJson(text) {
+    try {
+        const snapshot = JSON.parse(text);
+        if (typeof snapshot.typeName === "string" && typeof snapshot.fullName === "string") {
+            return `${snapshot.typeName}:${snapshot.fullName}`;
+        }
+    }
+    catch {
+        // Not a snapshot, or not JSON at all. Unnamed, therefore unusable as evidence.
+    }
+    return null;
+}
+/**
+ * A committed projection file's component identity, read from the BLOB — never guessed from the
+ * path. The projection sanitizes names on the way to disk (`projection/project.ts` `safeName`), so
+ * inverting a path is a guess, and a guessed identity here would either forge an attribution or
+ * forge an accusation. Many blobs, ONE git process.
+ *
+ * `git show <rev>:<path>` is one process per blob, so resolving a history's component identities
+ * cost one child process PER COMPONENT — 25 launches for a 24-component wave, serially, at the
+ * batch close of every run. `git cat-file --batch` takes the revisions on stdin and streams every
+ * blob back, which is the same bytes read by the same plumbing in one launch.
+ *
+ * THE OUTPUT FORMAT, exactly, because parsing it wrong is how a batch silently returns the wrong
+ * component's identity. For each input line git emits either
+ *
+ *     <sha> <type> <size>\n<size bytes of content>\n      (found)
+ *     <the input line> missing\n                          (not found)
+ *
+ * The size prefix is what makes this safe: content is taken by BYTE COUNT, never by scanning for a
+ * delimiter, so a snapshot containing a newline — every one of them does — cannot desynchronize the
+ * stream. Reading is done over a Buffer rather than a string for the same reason: `size` counts
+ * bytes, and a multi-byte character in a label would make a character-indexed slice drift.
+ *
+ * Answers are returned POSITIONALLY, one per request, so a caller's mapping is by index and never
+ * by re-deriving identity from a path — which is the property this module refuses to rely on.
+ *
+ * A `missing` answer is a null, exactly as a failed `git show` was: a deleted file whose parent
+ * revision does not exist (the root commit) and a path that was never committed both legitimately
+ * resolve to nothing, and neither may be reported as a component.
+ */
+async function keysFromBlobs(dir, requests) {
+    const keys = [];
+    // CHUNKED, because one batch means one stdout buffer. `git show` capped each response at
+    // `maxBuffer` (64 MB) INDIVIDUALLY; a single batch would have to hold every blob at once, and
+    // overflowing it is fail-silent in the dangerous direction — execFile errors, every key comes
+    // back null, and the contamination report reads as "this org delivered nothing" rather than as a
+    // failure. A live mirror runs ~2.3 KB per snapshot (measured: 300 components, 737 KB), so 500 per
+    // chunk is ~1 MB of buffer with a 64 MB ceiling — two orders of margin, and still one process per
+    // 500 components rather than one per component.
+    for (let start = 0; start < requests.length; start += BLOB_BATCH_SIZE) {
+        keys.push(...(await keysFromBlobChunk(dir, requests.slice(start, start + BLOB_BATCH_SIZE))));
+    }
+    return keys;
+}
+const BLOB_BATCH_SIZE = 500;
+/**
+ * How many CONTENT BYTES follow this `git cat-file --batch` header line, or NaN if it carries none.
+ *
+ * THE ANTI-DESYNC GUARD, exported so it can be pinned directly. Git answers each request with either
+ * `<sha> <type> <size>` followed by that many bytes, or a non-answer that echoes the INPUT LINE
+ * (`<sha>:<path> missing`) and carries no content at all. Splitting on spaces cannot tell those
+ * apart: a path containing a space makes a non-answer split into three parts too, and reading its
+ * last field as a content length would consume a bogus number of bytes and shift every record after
+ * it — returning one component's identity under another's name, silently, in a report that names
+ * people's work.
+ *
+ * So the object id and the size must BOTH look like what git emits. `safeName` keeps spaces out of
+ * the paths this repo writes today, which makes this defence in depth rather than a live fix; it
+ * costs one regex, and the failure it guards against is silent and unrecoverable.
+ */
+export function blobContentLength(header) {
+    const match = /^([0-9a-f]{40,64}) [a-z]+ (\d+)$/.exec(header);
+    return match ? Number(match[2]) : Number.NaN;
+}
+async function keysFromBlobChunk(dir, requests) {
+    if (requests.length === 0)
+        return [];
+    // `--buffer` keeps git from flushing per record, which matters once the input is hundreds of
+    // lines: without it the read side pays a syscall per blob and the batching buys much less.
+    const run = await gitRaw(dir, ["cat-file", "--batch", "--buffer"], {
+        input: `${requests.map((r) => `${r.sha}${r.removed ? "^" : ""}:${r.file}`).join("\n")}\n`
+    });
+    if (!run.ok) {
+        // The batch itself failed (a broken repo, git missing a feature). Nothing is guessed: every
+        // request resolves to "unnamed", which is what a failed per-blob read already produced.
+        return requests.map(() => null);
+    }
+    const out = run.stdoutBuffer;
+    const keys = [];
+    let cursor = 0;
+    for (let i = 0; i < requests.length; i++) {
+        const newline = out.indexOf(0x0a, cursor);
+        if (newline === -1)
+            break; // truncated output — remaining requests stay unresolved
+        const header = out.toString("utf8", cursor, newline);
+        cursor = newline + 1;
+        // `<sha> <type> <size>` is the only shape carrying content. Every other answer git gives —
+        // `<input> missing`, `<input> ambiguous` — is a non-answer whose record ends at this newline,
+        // so nothing may be skipped past it.
+        //
+        // MATCHED STRICTLY rather than by splitting on spaces. A non-answer echoes the INPUT LINE
+        // (`<sha>:<path> missing`), and a path containing a space would split into three parts and be
+        // mistaken for a header — consuming a bogus content length and DESYNCHRONIZING the rest of the
+        // stream, which returns one component's identity under another's name in a report that names
+        // people's work. The projection's own `safeName` maps spaces out of the paths it writes, so
+        // this is defence in depth against a future path source rather than a bug being fixed; the
+        // cost is a regex, and the failure it guards is silent and unrecoverable.
+        // (The size prefix itself is NOT defence in depth — see the byte-offset note above; a
+        // character-indexed read really does corrupt this stream, and a test pins it.)
+        const size = blobContentLength(header);
+        if (!Number.isSafeInteger(size) || size < 0 || cursor + size > out.length) {
+            keys.push(null);
+            continue;
+        }
+        keys.push(keyFromSnapshotJson(out.toString("utf8", cursor, cursor + size)));
+        cursor += size + 1; // the trailing newline git writes after every blob's content
+    }
+    while (keys.length < requests.length)
+        keys.push(null);
+    return keys;
+}
+/**
+ * The container's snapshot with the named child entries removed from the collections that embed
+ * them.
+ *
+ * Scoped twice over, because this function's whole job is to make a difference disappear: only the
+ * collections `projection/diff.ts` already classifies as child components are touched, and within
+ * them only entries whose `fullName` is one of `leaves`. A parent-level facet and a child this
+ * mirror never delivered both survive into the comparison, which is what keeps a suppression from
+ * ever being wider than its evidence.
+ */
+function withoutChildren(canonical, leaves) {
+    const snapshot = JSON.parse(canonical);
+    const metadata = snapshot.state?.metadata;
+    if (!metadata)
+        return canonical;
+    for (const name of CHILD_COLLECTION_NAMES) {
+        const collection = metadata[name];
+        if (!Array.isArray(collection))
+            continue;
+        metadata[name] = collection.filter((entry) => {
+            const fullName = entry?.fullName;
+            return !(typeof fullName === "string" && leaves.has(fullName));
+        });
+    }
+    return `${JSON.stringify(snapshot, null, 2)}\n`;
+}
+/**
+ * Can this mirror's OWN recorded history account for the whole disagreement? (live-caught, PV Arm A)
+ *
+ * A `CustomObject` read-back EMBEDS its children, but the children project as their own components
+ * — so a wave delivering only fields or list views writes the CHILD files and leaves the parent's
+ * file untouched. The parent's copy is then stale by construction, and the next wave to read the
+ * parent found a shape this install had itself produced and carded it as an outside edit. On the PV
+ * corpus run that fired on `CustomObject:PV_Asset__c` at w5, where the entire delta was w2's four
+ * fields and w4's list views, validation rules and compact layout.
+ *
+ * ATTRIBUTION IS POSITIVE OR IT DOES NOT HAPPEN. A child only counts when this mirror holds a
+ * commit delivering it that is STRICTLY NEWER than the parent's last recorded read — otherwise the
+ * parent's file already carried that child and is not stale. Both snapshots then have exactly those
+ * entries removed and must come out IDENTICAL; one unexplained byte anywhere and this returns null,
+ * the component is carded in full, and nothing is suppressed. Anything that goes wrong reading git
+ * lands in the same place, because "drift stands" is the direction a failure here must fail in.
+ *
+ * WHAT THIS DOES NOT SEE, stated rather than implied: if an admin edited one of those same children
+ * after IN2 delivered it, that edit is inside the removed region and this will not notice. It is not
+ * lost — each child has its own mirrored file, so the edit surfaces as drift on the CHILD the moment
+ * a wave's pre-image includes it, which is where a claim about that child belongs. Comparing the
+ * embedded entry against the child's own snapshot is not available as a shortcut: the org returns
+ * the two at different depths (measured on the PV run — a field's `defaultValue` is present standalone
+ * and absent inline), so a byte comparison there would manufacture exactly the false card this fixes.
+ */
+async function attributeToOwnHistory(args) {
+    const { repoDir, component, committed, pre } = args;
+    // Only a CustomObject read-back embeds other components. Every other type's snapshot is its own
+    // content, so a disagreement there is a disagreement about that component and nothing else.
+    if (component.typeName !== "CustomObject")
+        return null;
+    try {
+        const rel = gitPath("projection", safeRelPath(component.file));
+        const lastRead = (await git(repoDir, ["log", "-1", "--format=%H", "--", rel])).stdout.trim();
+        if (!lastRead)
+            return null;
+        const out = await gitOrThrow(repoDir, [
+            "log",
+            `${lastRead}..HEAD`,
+            "--name-status",
+            "--no-renames",
+            `--format=${RECORD}%H${FIELD}%b${FIELD}`,
+            "--",
+            "projection"
+        ]);
+        const prefix = `${component.fullName}.`;
+        const children = new Map(); // component key -> "<sessionId>/<wave>"
+        const leaves = new Set();
+        // Collected first, resolved in ONE `git cat-file --batch` — see keysFromBlobs. This runs on the
+        // APPLY path (every wave that finds drift on a CustomObject), and a `git show` per changed file
+        // put a process launch behind each one of them.
+        const requests = [];
+        const attribution = [];
+        for (const record of out.split(RECORD)) {
+            if (!record.trim())
+                continue;
+            const [sha = "", body = "", changes = ""] = record.split(FIELD);
+            const trailers = parseTrailers(body);
+            for (const line of changes.split("\n")) {
+                const match = /^([AMD])\t(projection\/.+)$/.exec(line);
+                if (!match)
+                    continue;
+                requests.push({ file: match[2], sha, removed: match[1] === "D" });
+                attribution.push(`${trailers.get("session-id")?.[0] ?? "?"}/${trailers.get("wave")?.[0] ?? "?"}`);
+            }
+        }
+        const keys = await keysFromBlobs(repoDir, requests);
+        for (const [i, key] of keys.entries()) {
+            if (!key)
+                continue;
+            const fullName = key.slice(key.indexOf(":") + 1);
+            if (!fullName.startsWith(prefix))
+                continue;
+            leaves.add(fullName.slice(prefix.length));
+            // FIRST mention wins, exactly as before: the walk is newest-commit-first, so the first
+            // attribution seen for a key is the most recent wave to have delivered it.
+            if (!children.has(key))
+                children.set(key, attribution[i]);
+        }
+        if (children.size === 0)
+            return null;
+        if (withoutChildren(committed, leaves) !== withoutChildren(pre, leaves))
+            return null;
+        return {
+            key: componentKey(component),
+            children: [...children.keys()].sort(),
+            waves: [...new Set(children.values())].sort()
+        };
+    }
+    catch {
+        // Git could not answer. An unproven attribution is not an attribution.
+        return null;
+    }
+}
+/**
+ * Which touched components disagree with what the mirror last committed (R15).
+ *
+ * Positive evidence only, in both directions. A component the mirror has never held is UNKNOWN, not
+ * drifted — this history covers what IN2 touched, so absence says nothing about the org. And a
+ * disagreement is only downgraded out of `drifted` when this mirror's own commits account for every
+ * byte of it (`attributeToOwnHistory`); partial attribution leaves the warning standing.
+ *
+ * THREE OUTCOMES, not two. Before a disagreement can be attributed or carded it has to be a
+ * disagreement about the ORG, and a pair of snapshots read by different readers is not (PV Arm B —
+ * see `snapshotComparability.ts`). Those come back as `incomparable`: reported in their own right,
+ * never as drift, never dropped. The order matters — comparability is asked FIRST, because
+ * attributing a reader-shape difference to this history's own children would be a second wrong
+ * answer dressed as a right one.
+ *
+ * A COMPONENT DELIVERED TWICE IN ONE BATCH NEEDS NOTHING HERE (plan 2026-08-03-002 U7). The second
+ * wave's pre-image is the org as the FIRST wave left it, and the first wave committed exactly that
+ * — so the two agree and no `Drift:` trailer is written. That is not a special case being handled;
+ * it is the ordinary comparison coming out clean, which is why a trailer appearing on such a chain
+ * would be a real defect (the second wave measuring against something other than the first wave's
+ * work) rather than an over-eager warning. `applyLoopMirror.test.ts` pins it end to end against real
+ * git for that reason.
+ */
+async function computeDrift(repoDir, preComponents) {
+    const drifted = [];
+    const attributed = [];
+    const incomparable = [];
+    for (const component of preComponents) {
+        const abs = path.join(repoDir, "projection", safeRelPath(component.file));
+        const committed = await fs.readFile(abs, "utf8").catch(() => null);
+        if (committed === null)
+            continue;
+        const pre = canonicalSnapshot(component.snapshot);
+        if (committed === pre)
+            continue;
+        const errors = component.snapshot?.errors;
+        const verdict = assessComparability({
+            recorded: committed,
+            observed: pre,
+            ...(Array.isArray(errors) ? { observedErrors: errors } : {})
+        });
+        if (verdict.kind !== "COMPARABLE") {
+            incomparable.push({
+                key: componentKey(component),
+                reason: verdict.kind,
+                ...(verdict.kind === "READER_CHANGED"
+                    ? { recorded: readerIdentityLabel(verdict.recorded), observed: readerIdentityLabel(verdict.observed) }
+                    : { facets: verdict.facets }),
+                differingKeys: verdict.differingKeys
+            });
+            continue;
+        }
+        const explained = await attributeToOwnHistory({ repoDir, component, committed, pre });
+        if (explained)
+            attributed.push(explained);
+        else
+            drifted.push(componentKey(component));
+    }
+    return {
+        drifted: drifted.sort(),
+        attributed: attributed.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0)),
+        incomparable: incomparable.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+    };
+}
+async function overlayAndCommitLocked(input) {
+    const { wave } = input;
+    const repoDir = await ensureRepo(wave.orgId, input);
+    // A wave carrying its own `drifted` states the finding outright and is taken at its word; there
+    // is no attribution to redo, because the analysis that produced it is not on offer here.
+    const analysis = wave.drifted
+        ? { drifted: wave.drifted, attributed: [], incomparable: [] }
+        : input.preComponents
+            ? await computeDrift(repoDir, input.preComponents)
+            : { drifted: [], attributed: [], incomparable: [] };
+    const { drifted, attributed, incomparable } = analysis;
+    for (const component of wave.components) {
+        await writeRepoFile(repoDir, path.join("projection", component.file), canonicalSnapshot(component.snapshot));
+    }
+    for (const file of wave.sourceFiles) {
+        await writeRepoFile(repoDir, path.join("source", file.relPath), file.content);
+    }
+    for (const removal of wave.removed) {
+        await fs.rm(path.join(repoDir, "projection", safeRelPath(removal.file)), { force: true });
+        for (const rel of removal.sourceRelPaths ?? []) {
+            await fs.rm(path.join(repoDir, "source", safeRelPath(rel)), { force: true });
+        }
+    }
+    await gitOrThrow(repoDir, ["add", "-A", "."]);
+    // Commit IFF the tree actually moved. A re-delivery of unchanged content is a real and common
+    // case (a wave re-run after a lint fix elsewhere), and recording it would turn history into a
+    // log of applies rather than a record of the org.
+    const dirty = await git(repoDir, ["diff", "--cached", "--quiet"]);
+    if (dirty.exitCode === 0)
+        return { sha: null, committed: false, drifted, attributed, incomparable };
+    const date = new Date(wave.windowStart);
+    const stamp = Number.isNaN(date.getTime()) ? EPOCH : date.toISOString();
+    await gitOrThrow(repoDir, ["commit", "--quiet", "-F", "-"], {
+        date: stamp,
+        input: commitMessage(wave, wave.components.length, wave.removed.length, drifted, attributed, incomparable)
+    });
+    const sha = (await gitOrThrow(repoDir, ["rev-parse", "HEAD"])).trim();
+    return { sha, committed: true, drifted, attributed, incomparable };
+}
+/** Overlay one wave onto its org's mirror and commit iff the tree changed. Serialized per org. */
+export async function overlayAndCommit(input) {
+    return withOrgLock(input.wave.orgId, input, () => overlayAndCommitLocked(input));
+}
+// ---------------------------------------------------------------------------------------------
+// bundles in, history out
+// ---------------------------------------------------------------------------------------------
+async function readJson(file) {
+    try {
+        return JSON.parse(await fs.readFile(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * What the wave TOUCHED, as its own request records it — or null when the bundle cannot say.
+ *
+ * A wave's projection is deliberately WIDER than its work: it samples precedent (see
+ * projection/precedent.ts), and a wide-object scope enumerates an object's whole field list to read
+ * two of them. `request.json` is the only artifact in the bundle that states intent rather than
+ * observation, which is what makes it the authority here.
+ *
+ * CONTAINERS ARE EXPANDED, and the boundary is exactly the deployed BYTES. A CustomObject file can
+ * carry `<fields>` inline, so a child the request never names on its own is still a real
+ * wave-caused change — `expandComponent` reads the submitted XML and names it. What is NOT expanded
+ * is a container's other children: an `objectFacetUpdates` entry structurally cannot carry child
+ * collections (the apply loop refuses one that does), so a facet update touches the object and
+ * nothing beneath it. Measured on the live corpus, the difference is 63 components that a
+ * whole-subtree rule would have attributed to a wave that only reassigned a compact layout.
+ *
+ * NULL IS NOT AN EMPTY SET. A bundle with no request — a pre-U2 artifact, or a foreign parcel
+ * built by something else — knows nothing about what was touched, and an empty set would silently
+ * erase real deliveries from history. Null means "fall back to the manifest flag"; an empty set
+ * means "this request touched nothing", which is a different and answerable claim.
+ *
+ * DELIBERATELY BLIND TO INTENT (plan 2026-08-03-002 U7). Each edit in `request.json` now also carries
+ * an `intent` of `create`/`update`, and nothing here reads it. Identity is still
+ * `(typeName, fullName)`: a component this batch delivers twice produces two waves naming the same
+ * key, which is exactly right — the mirror records a SEQUENCE of states of one component, and two
+ * commits touching one key is what that looks like. Branching on intent would only let a mis-declared
+ * entry decide what the mirror believes was touched, and the deployed bytes already answer that.
+ *
+ * A bundle written before intent existed carries none, parses identically, and is graded identically.
+ */
+function touchedKeys(request) {
+    if (!request)
+        return null;
+    // A request that states none of the three says nothing about what was touched — see NULL above.
+    if (![request.edits, request.deletes, request.facetUpdates].some(Array.isArray))
+        return null;
+    const keys = new Set();
+    for (const item of request.edits ?? []) {
+        if (typeof item?.typeName !== "string" || typeof item?.fullName !== "string")
+            continue;
+        // The file itself AND what it contains. `expandComponent` answers a different question — which
+        // CONFIGURABLE components a deploy produced, and a pure container like SharingRules is not one
+        // of those, so it drops the parent. The mirror wants the post-image of the artifact that was
+        // deployed, and `SharingRules:Obj__c` is exactly what a projection records for that deploy.
+        // Live-caught while measuring this change: taking the expansion alone silently stopped three
+        // sharing-rule waves from committing at all.
+        keys.add(`${item.typeName}:${item.fullName}`);
+        for (const part of expandComponent(item.typeName, item.fullName, item.xml)) {
+            keys.add(`${part.typeName}:${part.fullName}`);
+        }
+    }
+    // A delete carries no XML; it names exactly what it removes.
+    for (const item of request.deletes ?? []) {
+        if (typeof item?.typeName === "string" && typeof item?.fullName === "string") {
+            keys.add(`${item.typeName}:${item.fullName}`);
+        }
+    }
+    // A facet update edits the object itself; the object IS the touched component.
+    for (const facet of request.facetUpdates ?? []) {
+        if (typeof facet?.objectApiName === "string")
+            keys.add(`CustomObject:${facet.objectApiName}`);
+    }
+    return keys;
+}
+/**
+ * Does this manifest entry belong in the mirror — i.e. did the wave touch it?
+ *
+ * Two filters, because they cover different bundles and neither covers all of them:
+ *
+ *   the FLAG    marks precedent at projection time, so it travels with every bundle written from
+ *               here on, including into a parcel a rebuild on another machine replays.
+ *   the REQUEST covers everything already on disk, which carries no flag and never will.
+ *
+ * Nothing beyond the request is inferred. In particular, the default Layout the org auto-creates
+ * alongside a new object is a genuine wave-caused change that this does NOT record, because the
+ * wave's projection never read it and the mirror has no post-image to commit. That is a bounded,
+ * one-directional gap: the mirror under-claims, and under-claiming reads as UNKNOWN, which is what
+ * the whole design already says absence means. Over-claiming does not — it reads as a delivery,
+ * and a delivery is a claim about somebody's work.
+ */
+function isTouched(entry, touched) {
+    if (entry.precedent)
+        return false;
+    if (!touched)
+        return true;
+    return touched.has(`${entry.typeName}:${entry.fullName}`);
+}
+async function readProjectionComponents(dir, touched) {
+    const manifest = await readJson(path.join(dir, "projection.json"));
+    if (!manifest?.components)
+        return { components: [] };
+    const components = [];
+    for (const entry of manifest.components) {
+        if (!entry.found)
+            continue;
+        if (!isTouched(entry, touched))
+            continue;
+        const snapshot = await readJson(path.join(dir, entry.file));
+        if (snapshot === null)
+            continue;
+        components.push({ typeName: entry.typeName, fullName: entry.fullName, file: entry.file, snapshot });
+    }
+    // The org id is a fact about the PROJECTION, not about any component, so it survives the filter —
+    // a wave whose every component was filtered out still knows which mirror it belongs to.
+    return { ...(manifest.orgId ? { orgId: manifest.orgId } : {}), components };
+}
+/** Every file under `dir`, as repo-relative paths with their bytes. Used for the deployed tree. */
+async function readTree(dir, prefix = "") {
+    const out = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            out.push(...(await readTree(path.join(dir, entry.name), rel)));
+        // Bytes, not text: see MirrorWave.sourceFiles.
+        else if (entry.isFile())
+            out.push({ relPath: rel, content: await fs.readFile(path.join(dir, entry.name)) });
+    }
+    return out;
+}
+/**
+ * Parse one evidence bundle into the replay unit, or null when it never changed the org.
+ *
+ * This is the other half of "one overlay function": a live apply hands `overlayAndCommit` a wave it
+ * built in memory, and a rebuild hands it a wave read back off disk. If the two disagreed about
+ * what a bundle means, rebuilding would silently produce a different history than the machine that
+ * ran the waves — which is exactly the failure the version trailer exists to make visible.
+ */
+export async function readWaveFromBundle(bundleDir) {
+    const verdictFile = await readJson(path.join(bundleDir, "verdict.json"));
+    const verdict = verdictFile?.verdict;
+    if (!verdict || !isStateChanging(verdict))
+        return null;
+    // The request is read FIRST because it decides which components the projections contribute: the
+    // mirror holds what the wave touched, and a projection reads more than that by design.
+    const request = await readJson(path.join(bundleDir, "request.json"));
+    const touched = touchedKeys(request);
+    const post = await readProjectionComponents(path.join(bundleDir, "post"), touched);
+    // The PRE image goes through the SAME filter, and for the same reason twice over: it is what
+    // `computeDrift` compares against the mirror, so an untouched component that a third party edited
+    // would otherwise surface as CHANGED-OUTSIDE-HISTORY against a wave that never went near it.
+    const pre = await readProjectionComponents(path.join(bundleDir, "pre"), touched);
+    const orgId = post.orgId ?? pre.orgId;
+    if (!orgId || !ORG_ID_RE.test(orgId))
+        return null;
+    const window = await readJson(path.join(bundleDir, "mutation-window.json"));
+    const attemptFile = await readJson(path.join(bundleDir, "attempt.json"));
+    const scan = await readJson(path.join(bundleDir, "change-scan.json"));
+    // <session>/direct/<wave> — the bundle's own location IS its identity, which is what makes the
+    // sort key derivable from a foreign parcel that carries no session record with it.
+    const waveLabel = path.basename(bundleDir);
+    const sessionId = path.basename(path.resolve(bundleDir, "..", ".."));
+    const preByKey = new Map(pre.components.map((c) => [componentKey(c), c]));
+    const removed = [];
+    for (const del of request?.deletes ?? []) {
+        const previous = preByKey.get(componentKey(del));
+        if (previous)
+            removed.push({ typeName: del.typeName, fullName: del.fullName, file: previous.file });
+    }
+    const wave = {
+        orgId,
+        sessionId,
+        wave: waveLabel,
+        attempt: attemptFile?.attempt ?? 1,
+        verdict,
+        windowStart: window?.start ?? EPOCH,
+        ...(scan?.windowSuspect ? { windowSuspect: true } : {}),
+        ...(verdict === "AMBIGUOUS_DELIVERY" ? { ambiguous: true } : {}),
+        ...(request?.batchId ? { batchId: request.batchId } : {}),
+        ...(request?.requirementIds?.length ? { requirementIds: request.requirementIds } : {}),
+        ...(request?.operator ? { operator: request.operator } : {}),
+        ...(request?.revertOf ? { revertOf: request.revertOf } : {}),
+        components: post.components,
+        sourceFiles: await readTree(path.join(bundleDir, "deployed")),
+        removed
+    };
+    return { wave, preComponents: pre.components };
+}
+/**
+ * The total sort key (R5): mutation-window start, then session id, then wave label, then attempt.
+ *
+ * ATTEMPT IS THE LAST TERM AND IT IS LOAD-BEARING. Two attempts at one wave are two entries (see
+ * `waveIdentity`), and a retry whose mutation window is indistinguishable from the attempt before it
+ * — a re-run seconds later, or one whose window could not be narrowed — would otherwise be ordered
+ * by nothing at all, which is how two machines holding the same pair could commit them in opposite
+ * orders. With attempt on the end the pair is ordered by construction, ascending, on every machine.
+ *
+ * It approximates org chronology only within clock skew and never claims more — a `windowSuspect`
+ * wave says so in its own trailer. What it DOES guarantee is totality: the same bundle set orders
+ * the same way on every machine, in any arrival order, which is what makes a foreign parcel
+ * insertable by rebuilding rather than merging.
+ *
+ * If `deploy.json`'s raw result is later found to carry Salesforce's server-stamped completion
+ * time, that becomes the primary term and this comment is the place it goes. Checked at U2: the
+ * parsed deploy result exposes `status` and `id`; no completion timestamp is surfaced through
+ * `parseDeployOutput`, so the mutation window remains the anchor.
+ *
+ * NUL joins the terms because it cannot occur in any of them, so no term can bleed into the next.
+ * Written as the ESCAPE rather than as a literal NUL byte: a raw one in the source makes git
+ * classify the whole file as binary — it sniffs the first 8000 bytes, and `projection/diff.ts`
+ * already renders as `Bin` in commit diffs for exactly this reason — which silently costs every
+ * future reviewer the diff. Identical string at runtime, identical ordering.
+ */
+function sortKey(wave) {
+    return [wave.windowStart, wave.sessionId, wave.wave, String(wave.attempt)].join("\u0000");
+}
+/**
+ * Every evidence bundle this install holds, as `<session>/direct/<wave>` directories.
+ *
+ * The bundle set IS the input to a rebuild, and it is spread across sessions rather than kept in a
+ * list, so enumerating it is the one step between "the materializer changed" and "history reflects
+ * the change". Bundles that belong to another org, or that never changed one, are `rebuild`'s to
+ * skip — this only finds them.
+ */
+export async function workspaceBundleDirs(workspaceRoot = WORKSPACE_ROOT) {
+    const sessions = await fs.readdir(workspaceRoot, { withFileTypes: true }).catch(() => []);
+    const dirs = [];
+    for (const session of sessions.filter((e) => e.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+        const directDir = path.join(workspaceRoot, session.name, "direct");
+        const waves = await fs.readdir(directDir, { withFileTypes: true }).catch(() => []);
+        for (const wave of waves.filter((e) => e.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+            dirs.push(path.join(directDir, wave.name));
+        }
+    }
+    return dirs;
+}
+/**
+ * ONE WAVE, wherever its bundle came from — the dedupe key for a united set (U8).
+ *
+ * Not the sort key: `windowStart` leads that one so history orders by org chronology, and two copies
+ * of one wave agree about it anyway. What identifies a wave is (session, label, attempt), and a
+ * retry is deliberately a DIFFERENT wave here for the same reason it is a different commit (U2's
+ * KTD): amending would rewrite history, so attempt 2 is its own entry, not a correction of attempt 1.
+ *
+ * NUL joins the terms, written as the ESCAPE for the reason `sortKey` gives: it cannot occur in any
+ * term, so no term can bleed into the next and collapse two distinct waves into one.
+ */
+const waveIdentity = (wave) => [wave.sessionId, wave.wave, String(wave.attempt)].join("\u0000");
+function scopeOf(args) {
+    const { local, foreign, duplicates, unreadable, foreignSet } = args;
+    // WAVES, not bundles: a bundle whose verdict never changed the org contributes nothing to
+    // history, and counting it here would overstate what this mirror covers.
+    const held = `${local} wave(s) of its own`;
+    if (!foreignSet || foreignSet.unavailable !== undefined) {
+        const why = !foreignSet
+            ? "no foreign parcels were fetched"
+            : `foreign parcels could NOT be fetched (${foreignSet.unavailable})`;
+        return {
+            kind: "local-only",
+            // The second sentence is the point of the whole note: absence in this mirror has always meant
+            // UNKNOWN, and a local-only rebuild widens what is unknown without changing what it means.
+            note: `LOCAL ONLY — ${why}, so this history is built from this machine's ${held}. ` +
+                `Waves run on another machine are absent from it, and that absence is not evidence that none exist.`
+        };
+    }
+    const parts = [`united ${held} with ${foreign} wave(s) from parcels fetched for this org`];
+    if (duplicates > 0)
+        parts.push(`${duplicates} wave(s) arrived twice and were replayed once`);
+    if (foreignSet.missing) {
+        parts.push(`${foreignSet.missing} listed parcel(s) could NOT be staged, so waves may still be missing`);
+    }
+    // Staged and unreadable is a THIRD state, distinct from both of the above: the parcel arrived
+    // whole and this build could not make a wave of it. Said in its own words because the operator's
+    // next move differs — a staging failure is usually the network, an unreadable parcel is a bundle
+    // this install does not understand, and the fix for that one is a version, not a retry.
+    if (unreadable > 0) {
+        parts.push(`${unreadable} fetched parcel(s) could NOT be read as a wave, so waves may still be missing`);
+    }
+    return {
+        kind: "united",
+        // The "nothing to add" sentence is a claim about the LEDGER's contents, so every way the fetch
+        // could have held something this build failed to see has to disqualify it — including the case
+        // where every parcel arrived and none of them parsed, which reaches here as `foreign: 0` and
+        // would otherwise read as an empty ledger.
+        note: `${parts.join("; ")}. ` +
+            (foreign === 0 && duplicates === 0 && !foreignSet.missing && unreadable === 0
+                ? "The ledger holds nothing for this org that this machine did not already have. "
+                : "") +
+            "Any machine replaying this same set materializes these same commit ids."
+    };
+}
+/**
+ * Re-materialize an org's mirror from a bundle set — this machine's, another machine's, or both.
+ *
+ * DESTRUCTIVE by design and safe for the same reason: the mirror holds nothing the bundles do not,
+ * so rebuilding is how a newly arrived foreign bundle takes its correct place in history without a
+ * merge (R6). Every SHA changes; nothing may persist one (origin R17's alias rule).
+ *
+ * CONVERGENCE IS BY CONSTRUCTION, NOT BY EFFORT (AE3). Nothing here reconciles anything: the sort
+ * key is total, the materializer is deterministic, and the rebuild is from scratch — so a foreign
+ * wave whose mutation window predates every local commit simply sorts first and is committed first,
+ * exactly as it would have been on the machine that ran it. Two installs given the same set in
+ * opposite orders produce byte-identical history because neither install's ARRIVAL ORDER is an
+ * input. The only thing this function adds over the local-only case is the union and the dedupe.
+ *
+ * LOCAL WINS A TIE, and it is a tie about bytes rather than about authority: a parcel is a tar of a
+ * bundle directory, so this machine's copy and the copy it uploaded are the same artifact. Ordering
+ * local first means a machine holding both replays its own file, and a machine holding only the
+ * parcel replays the parcel — the same wave either way, which is what keeps the dedupe from being a
+ * second thing two machines could disagree about.
+ *
+ * A MATERIALIZER MISMATCH IS WHY THIS IS ALWAYS A FULL REBUILD. A mirror carrying a commit from
+ * another version of this file cannot have a differently-shaped commit appended onto it and still
+ * be one history; the versions are read off the OLD mirror before it is replaced and reported, so
+ * the answer to "why did every SHA move" is in the result rather than in a guess.
+ *
+ * It is also the REPAIR PATH when this file's reading of a bundle changes: a mirror materialized by
+ * an older rule keeps whatever that rule let in until something replays the bundles. `in2
+ * rebuild-mirror <orgId>` is that something.
+ */
+export async function rebuildFromSets(orgId, localBundleDirs, foreignSet, opts = {}) {
+    assertOrgId(orgId);
+    // Read BEFORE the mirror is removed — afterwards there is nothing left to have carried a trailer.
+    const priorMaterializers = await mirrorMaterializerVersions(orgId, opts.root);
+    const materializerMismatch = priorMaterializers.some((version) => version !== MATERIALIZER_VERSION);
+    const sources = [
+        ...localBundleDirs.map((dir) => ({ dir, origin: "local" })),
+        ...(foreignSet?.dirs ?? []).map((dir) => ({ dir, origin: "foreign" }))
+    ];
+    const chosen = new Map();
+    let skipped = 0;
+    let duplicates = 0;
+    let unreadable = 0;
+    for (const source of sources) {
+        const read = await readWaveFromBundle(source.dir);
+        if (!read) {
+            // A fetched parcel that yields no wave is a hole in coverage, not a bundle correctly passed
+            // over — see `RebuildResult.unreadable`. A local one is this machine's own and stays a skip.
+            if (source.origin === "foreign")
+                unreadable += 1;
+            else
+                skipped += 1;
+            continue;
+        }
+        if (read.wave.orgId.slice(0, 15) !== orgId.slice(0, 15)) {
+            skipped += 1;
+            continue;
+        }
+        // Replay under the mirror's own key, so a 15-char id in an older bundle cannot fork the
+        // history of an org already mirrored under its 18-char form.
+        read.wave.orgId = orgId;
+        const identity = waveIdentity(read.wave);
+        if (chosen.has(identity)) {
+            duplicates += 1;
+            continue;
+        }
+        chosen.set(identity, { ...read, origin: source.origin });
+    }
+    const parsed = [...chosen.values()];
+    parsed.sort((a, b) => (sortKey(a.wave) < sortKey(b.wave) ? -1 : sortKey(a.wave) > sortKey(b.wave) ? 1 : 0));
+    const local = parsed.filter((entry) => entry.origin === "local").length;
+    const foreign = parsed.length - local;
+    return withOrgLock(orgId, opts, async () => {
+        await fs.rm(mirrorPath(orgId, opts.root), { recursive: true, force: true });
+        await ensureRepo(orgId, opts);
+        let commits = 0;
+        for (const entry of parsed) {
+            const result = await overlayAndCommitLocked({ ...opts, wave: entry.wave, preComponents: entry.preComponents });
+            if (result.committed)
+                commits += 1;
+        }
+        const head = commits > 0 ? (await gitOrThrow(mirrorPath(orgId, opts.root), ["rev-parse", "HEAD"])).trim() : null;
+        return {
+            orgId,
+            commits,
+            head,
+            skipped,
+            unreadable,
+            duplicates,
+            local,
+            foreign,
+            scope: scopeOf({ local, foreign, duplicates, unreadable, ...(foreignSet ? { foreignSet } : {}) }),
+            priorMaterializers,
+            materializerMismatch
+        };
+    });
+}
+/**
+ * Rebuild from this machine's bundles alone.
+ *
+ * Kept as its own name because it is the common call and because the scope it produces is a real,
+ * different claim — `local-only`, said out loud — rather than a united rebuild that happened to find
+ * nothing foreign.
+ */
+export async function rebuild(orgId, bundleDirs, opts = {}) {
+    return rebuildFromSets(orgId, bundleDirs, undefined, opts);
+}
+// ASCII record/unit separators. A commit body is multi-line free text, so newline-delimited
+// parsing of `git log` output cannot tell where one commit ends — these cannot occur inside a
+// message, because `trailerValue` strips every control character before one is written.
+const RECORD = "\u001e";
+const FIELD = "\u001f";
+function parseTrailers(body) {
+    const out = new Map();
+    for (const line of body.split("\n")) {
+        const match = /^([A-Za-z][A-Za-z0-9-]*): (.*)$/.exec(line.trim());
+        if (!match)
+            continue;
+        const key = match[1].toLowerCase();
+        out.set(key, [...(out.get(key) ?? []), match[2]]);
+    }
+    return out;
+}
+/**
+ * Pathspecs matching one component's files, from a `Type:FullName` key.
+ *
+ * A glob rather than an exact path on purpose. The projection decides where a component's snapshot
+ * lands (`objects/<obj>/fields/<field>.json`, `components/<Type>/<name>.json`, …) and a caller of a
+ * READ tool has no reason to know that layout; reproducing it exactly here would also be a second
+ * copy of a mapping that lives in `projection/project.ts` and would drift from it silently. The
+ * globs are still narrow enough that `Account.Status__c` cannot match `Contact.Status__c`.
+ */
+function componentPathspecs(component) {
+    const [typeName, ...rest] = component.split(":");
+    const fullName = rest.join(":");
+    if (!typeName || !fullName) {
+        throw new OrgRepoError("INVALID_REF", `component must be "Type:FullName", got ${JSON.stringify(component)}`);
+    }
+    // The projection's own file-name sanitizer, mirrored: anything outside this set becomes "_".
+    const safe = (value) => value.replace(/[^A-Za-z0-9_.-]/g, "_");
+    if (typeName === "CustomObject")
+        return [`:(glob,top)*/objects/${safe(fullName)}/object.*`];
+    if (fullName.includes(".")) {
+        const object = fullName.slice(0, fullName.indexOf("."));
+        const leaf = fullName.slice(fullName.indexOf(".") + 1);
+        return [
+            `:(glob,top)*/objects/${safe(object)}/*/${safe(leaf)}.*`,
+            `:(glob,top)*/objects/${safe(object)}/*/*/${safe(leaf)}.*`
+        ];
+    }
+    return [`:(glob,top)*/**/${safe(fullName)}.*`];
+}
+async function repoIfPresent(orgId, root) {
+    const dir = mirrorPath(orgId, root);
+    return (await fs
+        .stat(path.join(dir, ".git"))
+        .then(() => true)
+        .catch(() => false))
+        ? dir
+        : null;
+}
+/**
+ * The mirror's commits, newest first — history readable without anyone touching git (R8).
+ *
+ * The root commit is excluded: it is a materialization artifact (an empty tree carrying the org
+ * id), not something that happened to the org.
+ */
+export async function historyLog(args) {
+    const dir = await repoIfPresent(args.orgId, args.root);
+    if (!dir)
+        return [];
+    const gitArgs = [
+        "log",
+        `--max-count=${Math.min(Math.max(args.limit ?? 50, 1), 500)}`,
+        `--format=${RECORD}%H${FIELD}%aI${FIELD}%s${FIELD}%b`
+    ];
+    // `--follow` is deliberately absent: a rename in this tree means a component was RENAMED in the
+    // org, which is a different component to Salesforce and should read as one here too.
+    if (args.component)
+        gitArgs.push("--", ...componentPathspecs(args.component));
+    const out = await gitOrThrow(dir, gitArgs);
+    const entries = [];
+    for (const record of out.split(RECORD)) {
+        if (!record.trim())
+            continue;
+        const [sha = "", date = "", subject = "", body = ""] = record.split(FIELD);
+        const trailers = parseTrailers(body);
+        if (subject.startsWith("mirror: "))
+            continue; // the root commit
+        entries.push({
+            sha,
+            date,
+            subject,
+            ...(trailers.get("session-id")?.[0] ? { sessionId: trailers.get("session-id")?.[0] } : {}),
+            ...(trailers.get("wave")?.[0] ? { wave: trailers.get("wave")?.[0] } : {}),
+            ...(trailers.get("attempt")?.[0] ? { attempt: Number(trailers.get("attempt")?.[0]) } : {}),
+            ...(trailers.get("verdict")?.[0] ? { verdict: trailers.get("verdict")?.[0] } : {}),
+            ...(trailers.get("batch-id")?.[0] ? { batchId: trailers.get("batch-id")?.[0] } : {}),
+            ...(trailers.get("operator")?.[0] ? { operator: trailers.get("operator")?.[0] } : {}),
+            ...(trailers.get("materializer")?.[0] ? { materializer: trailers.get("materializer")?.[0] } : {}),
+            ...(trailers.get("revert-of")?.[0] ? { revertOf: trailers.get("revert-of")?.[0] } : {}),
+            requirementIds: trailers.get("requirement-id") ?? [],
+            drifted: trailers.get("drift") ?? [],
+            driftExplained: trailers.get("drift-explained") ?? [],
+            notComparable: trailers.get("drift-not-comparable") ?? [],
+            incompleteFacets: trailers.get("incomplete-facet") ?? [],
+            ambiguous: trailers.get("ambiguous-delivery")?.[0] === "true",
+            orderingUnreliable: trailers.get("ordering-unreliable")?.[0] === "true"
+        });
+    }
+    return entries;
+}
+/**
+ * Every distinct `Materializer:` an existing mirror's commits carry, sorted.
+ *
+ * THE DOCTRINE'S DETECTOR (U8): a mirror holding a commit from another version of this file cannot
+ * have a differently-shaped commit appended onto it and still be one history — the serialization is
+ * the one input determinism cannot pin, which is why it is stamped rather than pretended away. So a
+ * mismatch means FULL REBUILD, and this is what a caller asks before deciding.
+ *
+ * The root commit carries one too, deliberately: a mirror initialized by an older version and never
+ * written to since is still an older mirror, and answering "no versions" for it would let it be
+ * appended to.
+ *
+ * Empty for an org with no mirror — nothing to disagree with is not a disagreement.
+ */
+export async function mirrorMaterializerVersions(orgId, root) {
+    const dir = await repoIfPresent(orgId, root);
+    if (!dir)
+        return [];
+    const out = await git(dir, ["log", `--format=${RECORD}%b`]);
+    if (!out.ok)
+        return [];
+    const versions = new Set();
+    for (const record of out.stdout.split(RECORD)) {
+        if (!record.trim())
+            continue;
+        for (const value of parseTrailers(record).get("materializer") ?? [])
+            versions.add(value.trim());
+    }
+    return [...versions].sort();
+}
+/**
+ * Every component this org's history records as delivered, newest commit first.
+ *
+ * The contamination report (U5; origin R22) is the consumer: it needs the delivered SET per session,
+ * which `historyLog` cannot give because trailers carry wave identity, not component identity.
+ * Adding a `Component:` trailer would have moved every SHA in every existing mirror for a read-side
+ * need, so this derives the same fact from the tree instead — a read helper, changing nothing about
+ * materialization.
+ *
+ * IDENTITY COMES FROM THE SNAPSHOT, NEVER FROM THE PATH. The projection decides where a component's
+ * file lands and sanitizes the name on the way (`projection/project.ts` `safeName` maps anything
+ * outside `[A-Za-z0-9_.-]` to `_`), so inverting a path is a guess — and a guessed key in a
+ * contamination report is a false accusation about somebody's run. The committed snapshot carries
+ * `typeName` and `fullName` verbatim, so the blob is read and a file that does not name itself
+ * contributes nothing rather than something plausible.
+ *
+ * Cost: one blob read per DISTINCT file, not per commit-file pair — a path names the same component
+ * for as long as it exists, so the mapping is resolved once and reused. All of those reads are one
+ * `git cat-file --batch` process (see `keysFromBlobs`), where this once launched a `git show` per
+ * file and therefore one child process per component. Callers run this at batch end, off the
+ * delivery path.
+ */
+export async function deliveredComponents(args) {
+    const dir = await repoIfPresent(args.orgId, args.root);
+    if (!dir)
+        return [];
+    const out = await gitOrThrow(dir, [
+        "log",
+        `--max-count=${Math.min(Math.max(args.limit ?? 200, 1), 2000)}`,
+        "--name-status",
+        // A rename in this tree means the component was RENAMED in the org, which is a DIFFERENT
+        // component to Salesforce. Keeping the delete and the add separate says exactly that.
+        "--no-renames",
+        `--format=${RECORD}%H${FIELD}%aI${FIELD}%s${FIELD}%b${FIELD}`
+    ]);
+    const pending = [];
+    const blobRequests = [];
+    const requestIndexByFile = new Map();
+    for (const record of out.split(RECORD)) {
+        if (!record.trim())
+            continue;
+        const [sha = "", date = "", subject = "", body = "", changes = ""] = record.split(FIELD);
+        if (subject.startsWith("mirror: "))
+            continue; // the root commit, a materialization artifact
+        const trailers = parseTrailers(body);
+        for (const line of changes.split("\n")) {
+            // `source/` is deliberately not consulted: it is a DEPLOY LOG that keeps a deleted
+            // component's last bytes, so it would report a removal as a live delivery.
+            const match = /^([AMD])\t(projection\/.+)$/.exec(line);
+            if (!match)
+                continue;
+            const removed = match[1] === "D";
+            const file = match[2];
+            if (!requestIndexByFile.has(file)) {
+                requestIndexByFile.set(file, blobRequests.length);
+                // The revision recorded is the FIRST one that mentioned this path — a delete reads its
+                // parent, an add or modify reads the commit itself, which is the same choice `git show`
+                // made per call.
+                blobRequests.push({ file, sha, removed });
+            }
+            pending.push({ sha, date, removed, trailers, file });
+        }
+    }
+    const keys = await keysFromBlobs(dir, blobRequests);
+    const delivered = [];
+    for (const entry of pending) {
+        const index = requestIndexByFile.get(entry.file);
+        const key = index === undefined ? null : keys[index];
+        if (!key)
+            continue;
+        delivered.push({
+            key,
+            sha: entry.sha,
+            date: entry.date,
+            removed: entry.removed,
+            // `sessionId` absent means the commit predates the trailer or came from a foreign
+            // materializer. Left undefined rather than defaulted: the consumer decides what an
+            // unattributed delivery means, and no caller may read a default as an attribution.
+            ...(entry.trailers.get("session-id")?.[0] ? { sessionId: entry.trailers.get("session-id")?.[0] } : {}),
+            ...(entry.trailers.get("wave")?.[0] ? { wave: entry.trailers.get("wave")?.[0] } : {}),
+            ...(entry.trailers.get("verdict")?.[0] ? { verdict: entry.trailers.get("verdict")?.[0] } : {}),
+            ...(entry.trailers.get("batch-id")?.[0] ? { batchId: entry.trailers.get("batch-id")?.[0] } : {})
+        });
+    }
+    return delivered;
+}
+/** `<key> <> <facet, facet>` trailer values, back into the pair they encode. */
+function parseIncompleteFacets(values) {
+    const out = [];
+    for (const value of values) {
+        const [component = "", facets = ""] = value.split(" <> ");
+        if (!component.trim() || !facets.trim())
+            continue;
+        out.push({
+            component: component.trim(),
+            facets: facets
+                .split(",")
+                .map((f) => f.trim())
+                .filter(Boolean)
+        });
+    }
+    return out;
+}
+/**
+ * The facets one commit's post-image could not read — for a caller that has a ref and wants the
+ * bound without re-deriving it from trailers.
+ */
+export async function historyIncompleteFacets(args) {
+    const ref = assertRef(args.ref);
+    const dir = await repoIfPresent(args.orgId, args.root);
+    if (!dir)
+        return [];
+    const body = await git(dir, ["log", "-1", "--format=%b", ref]);
+    if (!body.ok)
+        return [];
+    return parseIncompleteFacets(parseTrailers(body.stdout).get("incomplete-facet") ?? []);
+}
+export async function historyShow(args) {
+    const ref = assertRef(args.ref);
+    const dir = await repoIfPresent(args.orgId, args.root);
+    if (!dir)
+        return { sha: "", message: "", files: [], incompleteFacets: [] };
+    const sha = (await gitOrThrow(dir, ["rev-parse", `${ref}^{commit}`])).trim();
+    const message = await gitOrThrow(dir, ["log", "-1", "--format=%B", sha]);
+    const names = await gitOrThrow(dir, ["show", "--name-status", "--format=", sha]);
+    const files = names
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => {
+        const [status = "", filePath = ""] = line.split("\t");
+        return { status, path: filePath };
+    });
+    // Parsed from the message already in hand rather than by a second git call.
+    const incompleteFacets = parseIncompleteFacets(parseTrailers(message).get("incomplete-facet") ?? []);
+    return { sha, message, files, incompleteFacets };
+}
+export async function historyDiff(args) {
+    const ref = assertRef(args.ref);
+    const dir = await repoIfPresent(args.orgId, args.root);
+    if (!dir)
+        return "";
+    const gitArgs = args.against
+        ? ["diff", assertRef(args.against), ref]
+        : ["show", "--format=", "--patch", ref];
+    if (args.component)
+        gitArgs.push("--", ...componentPathspecs(args.component));
+    return gitOrThrow(dir, gitArgs);
+}