in2-agent-server 0.20260821.185429

package/dist/direct/applyLoop.js

@@ -0,0 +1,2516 @@
+import os from "node:os";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { flushParcels, queueWaveParcel } from "../core/parcels.js";
+import { runProcess, sfCliEnv } from "../core/spawn.js";
+import { orgCallPhase, resetOrgCallMeter } from "../core/orgCallMeter.js";
+import { ScopeTooLargeError, runProjection } from "../projection/project.js";
+import { PRECEDENT_TYPE_NAMES } from "../projection/precedent.js";
+import { canonJson, diffProjections, diffMetadata } from "../projection/diff.js";
+import { incompleteFacetsOf, normalizeCustomFieldMetadata, valueSetDefaultValue } from "../projection/bridge.js";
+import { parseMetadataXml, runLint } from "./lint.js";
+import { applyRefVerification, candidateObjects, escalatePendingDependencies, referentialTokens, verifyRefsAgainstOrg } from "./refVerify.js";
+import { collectSessionProjection, viewKnownTokens, viewProvenValues } from "./sessionProjection.js";
+import { findRemovals, isSourceFormatArtifact, renderRemovals } from "./removals.js";
+import { findUnstatedChanges, renderUnstatedChanges } from "./unstatedChanges.js";
+import { PLATFORM_DEFAULT_WHEN_OMITTED, canonicalizeCurrencyish, coerceLeaf, isEmptyish, isPlainObj } from "./comparatorNoise.js";
+import { preImageTargets } from "./preImageTargets.js";
+import { registryDeployableTypes, resolveFromRegistry } from "./registry.js";
+import { isStateChanging, overlayAndCommit, readWaveFromBundle } from "./orgRepo.js";
+import { destructivePackageXml, emptyPackageXml, parseDestructiveResult } from "./destructive.js";
+/** Plain-language rendering of a result for operator surfaces — see harness/reference/operator-voice.md. */
+export function operatorSummaryFor(r) {
+    return `${verdictSentence(r)}${driftSentence(r.mirror?.drifted ?? [])}${notComparableSentence(r.mirror?.incomparable ?? [])}`;
+}
+/**
+ * The gap in the record, in the operator's language.
+ *
+ * Says "could not check", never "unchanged". The temptation is to leave this out entirely — it is
+ * our own tooling's limitation and it reads like an excuse — but a check that did not happen is
+ * exactly the thing an operator must not be allowed to mistake for a check that passed.
+ */
+function notComparableSentence(incomparable) {
+    if (incomparable.length === 0)
+        return "";
+    const named = incomparable.slice(0, 3).map((e) => e.key).join(", ");
+    const rest = incomparable.length > 3 ? ` and ${incomparable.length - 3} more` : "";
+    return (` Also: for ${incomparable.length} component(s) (${named}${rest}) this machine could NOT check whether ` +
+        `anything had changed since IN2 last touched them — its record of them was taken by an older version of ` +
+        `the software that reads the org, so the two are not comparable. That is not a clean result and not a ` +
+        `warning; it is a check that could not run. It fixes itself: this wave re-records them the current way.`);
+}
+/**
+ * R15's card text. A WARNING appended to whatever the verdict says, never a verdict of its own —
+ * the wave succeeded, and someone having edited the component beforehand does not change that.
+ *
+ * The claim is deliberately narrow. Until parcels sync (R7/R24), this machine's mirror holds only
+ * the waves THIS install delivered, so a component another consultant changed last week looks
+ * identical to one a client admin changed in Setup. "Outside this machine's history" is what the
+ * evidence actually supports; "changed in Setup" would be a guess wearing a fact's clothes.
+ */
+function driftSentence(drifted) {
+    if (drifted.length === 0)
+        return "";
+    const named = drifted.slice(0, 3).join(", ");
+    const rest = drifted.length > 3 ? ` and ${drifted.length - 3} more` : "";
+    return (` Heads-up: ${drifted.length} component(s) had already been changed outside this machine's history ` +
+        `since IN2 last touched them (${named}${rest}) — a client admin in Setup, or another machine whose ` +
+        `history has not reached here. The wave still went in; check that it did not overwrite someone else's edit.`);
+}
+function verdictSentence(r) {
+    switch (r.verdict) {
+        case "DIFF_VERIFIED":
+            return "Deployed and verified — every setting matches the specification.";
+        case "VALIDATED": {
+            // Files AND deletes are both submitted to the org for a real practice run. Object facet
+            // updates are the one path with no validation step, so a dry run over them checked NOTHING —
+            // and this sentence is what an operator reads instead of the result. Claiming "Salesforce
+            // accepted everything" over work that was never submitted anywhere is the same class of
+            // overstatement `facetVerifiedStatus` exists to prevent one stage later.
+            // Read from `dryRun.checked` rather than inferred: a delete-only wave still produces a
+            // `dryRun` section, and inferring files from its presence would tell the operator that files
+            // were deployed in a wave that carried none.
+            const ran = r.dryRun?.checked ?? (r.dryRun ? ["files"] : []);
+            const checked = [
+                ...(ran.includes("files") ? ["the deployed files"] : []),
+                ...(ran.includes("deletes") && r.deletes?.length ? [`${r.deletes.length} deletion(s)`] : [])
+            ];
+            if (!r.facetUpdates?.length) {
+                return "Salesforce accepted everything in a practice run — nothing has been changed in the org yet.";
+            }
+            const accepted = checked.length
+                ? `Salesforce accepted ${checked.join(" and ")} in a practice run, but `
+                : "Nothing here was checked at all: ";
+            return (`${accepted}${r.facetUpdates.length} object setting change(s) cannot be practice-run — Salesforce offers ` +
+                `no validation step for that path, so this result says nothing about whether they would work. Re-run ` +
+                `without the practice-run option to apply them and get real verification. Either way, nothing has been ` +
+                `changed in the org yet.`);
+        }
+        case "LINT_BLOCKED":
+            return "Stopped by pre-flight checks before touching the org — nothing was changed; fix the named findings and re-run.";
+        case "REJECTED_BY_ORG":
+            return "Salesforce declined this step, so nothing from it was applied — the org's exact reasons are in the result.";
+        case "AMBIGUOUS_DELIVERY":
+            return "The change was sent but confirmation timed out — it may have landed. Do not re-send; re-read the org first.";
+        case "DELIVERED_WITH_DRIFT": {
+            const mismatches = (r.intent ?? []).reduce((n, i) => n + i.mismatches.length, 0);
+            const parts = [];
+            if (mismatches > 0)
+                parts.push(`${mismatches} setting(s) read back differently than authored`);
+            if (r.sideChanges?.length)
+                parts.push(`${r.sideChanges.length} other component(s) also moved`);
+            if (r.removals?.length)
+                parts.push(`${r.removals.length} component(s) lost content in a full replace`);
+            if (r.unstatedChanges?.length) {
+                parts.push(`${r.unstatedChanges.length} component(s) had a setting change that nobody asked for`);
+            }
+            if (r.scanIncomplete)
+                parts.push("the org-wide check for concurrent changes could not finish, so nothing here rules one out");
+            return `Deployed; a few readings need checking before calling it done (${parts.join("; ") || "see the result"}). This is often Salesforce normalizing values — classify each against the evidence, then report in plain terms.`;
+        }
+    }
+}
+// Source-format layout per metadata type. Types outside this table refuse loudly —
+// an honest, extensible ceiling (the direct tier's coverage grows by adding rows,
+// not by building five toolchain seams).
+const SOURCE_LAYOUT = {
+    CustomObject: (f) => `objects/${f}/${f}.object-meta.xml`,
+    CustomField: (f) => {
+        const [obj, field] = f.split(".");
+        return `objects/${obj}/fields/${field}.field-meta.xml`;
+    },
+    ValidationRule: (f) => {
+        const [obj, rule] = f.split(".");
+        return `objects/${obj}/validationRules/${rule}.validationRule-meta.xml`;
+    },
+    ListView: (f) => {
+        const [obj, view] = f.split(".");
+        return `objects/${obj}/listViews/${view}.listView-meta.xml`;
+    },
+    CompactLayout: (f) => {
+        const [obj, cl] = f.split(".");
+        return `objects/${obj}/compactLayouts/${cl}.compactLayout-meta.xml`;
+    },
+    RecordType: (f) => {
+        const [obj, rt] = f.split(".");
+        return `objects/${obj}/recordTypes/${rt}.recordType-meta.xml`;
+    },
+    Layout: (f) => `layouts/${f}.layout-meta.xml`,
+    Flow: (f) => `flows/${f}.flow-meta.xml`,
+    FlexiPage: (f) => `flexipages/${f}.flexipage-meta.xml`,
+    CustomTab: (f) => `tabs/${f}.tab-meta.xml`,
+    PermissionSet: (f) => `permissionsets/${f}.permissionset-meta.xml`,
+    CustomApplication: (f) => `applications/${f}.app-meta.xml`,
+    Queue: (f) => `queues/${f}.queue-meta.xml`,
+    Group: (f) => `groups/${f}.group-meta.xml`,
+    // SharingRules deploys as the per-object CONTAINER (fullName = object API name).
+    SharingRules: (f) => `sharingRules/${f}.sharingRules-meta.xml`,
+    ApprovalProcess: (f) => `approvalProcesses/${f}.approvalProcess-meta.xml`,
+    // Profiles deploy as MERGES — a fragment carrying only the changed sections is
+    // legal and is the sanctioned way to grant e.g. applicationVisibilities.
+    Profile: (f) => `profiles/${f}.profile-meta.xml`,
+    // Real-corpus wave (2026-07-22 classification): PSG alone uncapped 27 of 162 reqs.
+    PermissionSetGroup: (f) => `permissionsetgroups/${f}.permissionsetgroup-meta.xml`,
+    Report: (f) => `reports/${f}.report-meta.xml`, // fullName carries Folder/Name
+    ReportFolder: (f) => `reports/${f}.reportFolder-meta.xml`,
+    Dashboard: (f) => `dashboards/${f}.dashboard-meta.xml`,
+    DashboardFolder: (f) => `dashboards/${f}.dashboardFolder-meta.xml`,
+    DuplicateRule: (f) => `duplicateRules/${f}.duplicateRule-meta.xml`,
+    MatchingRules: (f) => `matchingRules/${f}.matchingRule-meta.xml`, // per-object container
+    AssignmentRules: (f) => `assignmentRules/${f}.assignmentRules-meta.xml`, // per-object container
+    CustomMetadata: (f) => `customMetadata/${f}.md-meta.xml`
+};
+// The explicit object-child layouts (fields/rules/… under objects/) plus every
+// deployable type the SDR registry knows (single-file XML + content-file) — the
+// derived open-world surface (bundles excluded until the files[] contract).
+export function supportedDirectTypes() {
+    return [...new Set([...Object.keys(SOURCE_LAYOUT), ...registryDeployableTypes()])].sort();
+}
+// Explicit object-child map first (stable, tested), then registry-derived. Content-file
+// types require a `content` value; refused with a clear message when it's missing.
+export function resolveSourcePath(edit) {
+    const explicit = SOURCE_LAYOUT[edit.typeName];
+    if (explicit)
+        return { files: [{ relPath: explicit(edit.fullName), from: "xml" }] };
+    const r = resolveFromRegistry(edit.typeName, edit.fullName);
+    if (!r.ok)
+        return { error: r.message };
+    if (r.kind === "content") {
+        if (edit.content === undefined) {
+            return { error: `${edit.typeName} is a content-file type — provide a \`content\` value (the ${r.contentPath.split(".").pop()} body).` };
+        }
+        return { files: [{ relPath: r.metaPath, from: "xml" }, { relPath: r.contentPath, from: "content" }] };
+    }
+    if (r.kind === "container-child") {
+        return { container: { containerPath: r.containerPath, parentRoot: r.parentRoot, childElementName: r.childElementName } };
+    }
+    return { files: [{ relPath: r.relPath, from: "xml" }] };
+}
+// Re-root a decomposed child's XML into its parent container element: strip the declaration,
+// swap `<ChildType …>…</ChildType>` for `<childElementName>…</childElementName>`.
+function wrapChildElement(childXml, childType, elementName) {
+    let inner = childXml.trim().replace(/^<\?xml[^>]*\?>\s*/, "");
+    inner = inner.replace(new RegExp(`^<${childType}(\\s[^>]*)?>`), `<${elementName}>`);
+    inner = inner.replace(new RegExp(`</${childType}>\\s*$`), `</${elementName}>`);
+    return inner;
+}
+const XML_NS = 'xmlns="http://soap.sforce.com/2006/04/metadata"';
+// Ensure the root element declares every namespace the document actually USES.
+// The default sforce namespace is added when absent; and — live-caught on CF65
+// CustomMetadata seed records — the schema-instance prefixes (`xsi`, `xsd`) must be
+// BOUND whenever the XML uses them (CustomMetadata `<value xsi:type="xsd:string">`,
+// or `xsi:nil`). An unbound prefix makes SF's mdapi reject the whole file with a
+// 0-component UNKNOWN_EXCEPTION rather than a real component error. Exported for tests.
+export function ensureDeployableXml(xml) {
+    let out = xml.trim();
+    if (!out.startsWith("<?xml"))
+        out = `<?xml version="1.0" encoding="UTF-8"?>\n${out}`;
+    const needed = [];
+    if (!/\sxmlns\s*=/.test(out))
+        needed.push(XML_NS);
+    if (/\bxsi:/.test(out) && !/xmlns:xsi\s*=/.test(out)) {
+        needed.push('xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"');
+    }
+    if (/\bxsd:/.test(out) && !/xmlns:xsd\s*=/.test(out)) {
+        needed.push('xmlns:xsd="http://www.w3.org/2001/XMLSchema"');
+    }
+    if (needed.length > 0) {
+        // Insert on the first real element (skips the <?xml …?> declaration).
+        out = out.replace(/<([A-Za-z][A-Za-z0-9]*)(\s|>)/, (_m, tag, tail) => `<${tag} ${needed.join(" ")}${tail}`);
+    }
+    return out;
+}
+// THE READ-BACK BACKOFF IS GONE, and the corpus is why.
+//
+// It was sized TWICE against evidence that turned out to be confounded: "component reads back absent
+// after a successful deploy" was never Salesforce, it was the reader serving the pre-projection's
+// not-found rows to the post-projection. Every apparent settle time — 17s, 22s, 38s — was the
+// operator re-running project_org against a FRESH reader, so those numbers measured our own cache.
+// After `invalidate()` landed, the sleep ladder stayed on the hypothesis that a genuine propagation
+// delay might still exist, and the comment on `readbackWaitMs` said outright what would retire it:
+// "if `readbackWaitMs` is 0 across a corpus, the loop can go."
+//
+// It is 0 across the corpus. 28 of 28 waves that recorded it waited exactly zero milliseconds —
+// `settlingIsPlausible` short-circuits every one of them. The 17 older bundles where the ladder DID
+// fire are the other half of the answer: not one of them settled. They paid 9.5s (four of them 47s,
+// on the schedule bad evidence bought) and then reported drift anyway. So the loop's measured record
+// is zero benefit and a per-wave landmine of a sleep plus a full extra post-projection.
+//
+// `settlingIsPlausible` STAYS — it is the thing that makes the wait zero, and it is now what decides
+// the note instead of what decides the sleep. A facet that genuinely does need settling reports
+// DELIVERED_WITH_DRIFT on the first read, which the loop already documents as noisy-but-safe, and
+// the operator re-reads. `readbackWaitMs: 0` is still emitted, so the ledger's history stays
+// continuous rather than developing a hole where this build starts.
+/**
+ * Facets Salesforce settles ASYNCHRONOUSLY, so re-reading them later could legitimately change the
+ * answer. Matched on the mismatch's leaf name.
+ *
+ * This list used to be the reason the backoff survived. With the backoff gone (see above) it is no
+ * longer a wait/no-wait switch — nothing waits — but it is still the honest catalogue of which
+ * mismatches are the org's FINAL answer and which are a read taken mid-recalculation, and that is
+ * what the note tells the operator. The three cases that ever settled were:
+ *   w1  a component read back absent      — that one was our own reader cache, now fixed
+ *   w4b compactLayoutAssignment → SYSTEM  — present, facet still the old value
+ *   w7  sharingOwnerRules → []            — present, and recalculating; Salesforce documents
+ *                                           sharing recalculation as asynchronous
+ * Only the last two are real org behaviour, and both are narrow and nameable.
+ *
+ * The sharing-rules entries were the whole of the sharing story until the EV-31…40 run, which asked
+ * for a `sharingModel` change and got a false "NOT APPLIED — the org accepted the request but still
+ * reads …" on the first read; both APIs showed it applied moments later. Same asynchronous
+ * recalculation, one level up — the rules were catalogued and the MODEL that drives them was not,
+ * which is the narrowest possible version of the gap this list is for. `internalSharingModel` and
+ * `externalSharingModel` join it: they are the same facet under the spellings an org with external
+ * sharing enabled reads back.
+ *
+ * Everything NOT on this list concludes on the first read. A field whose length came back 255
+ * instead of 40 is the org's answer, not a work in progress, and waiting 9.5s to ask again was pure
+ * cost — paid on every drifted wave, to re-learn what the first read already said.
+ *
+ * Membership now changes the WORDING and nothing else, which makes the whole list cheap to be wrong
+ * about in either direction: every mismatch reports DELIVERED_WITH_DRIFT immediately, and the note
+ * says whether re-reading is worth the operator's time.
+ */
+const ASYNC_SETTLING_LEAVES = new Set([
+    "compactlayoutassignment",
+    "sharingmodel",
+    "internalsharingmodel",
+    "externalsharingmodel",
+    "sharingownerrules",
+    "sharingcriteriarules",
+    "sharingguestrules",
+    "sharingterritoryrules"
+]);
+/** Is this mismatch one that re-reading could plausibly resolve? Exported for tests: each entry in
+ *  the set above is a claim about platform behaviour that should be pinned by a case. */
+export function settlingIsPlausible(entries) {
+    return entries.some((entry) => 
+    // A component the org has not shown us yet may simply not be readable back yet. Kept because a
+    // create that reads back absent is the ambiguous-delivery case — with the cache bug fixed it
+    // should be rare, and when it does happen "re-read it" is the right advice.
+    entry.absent ||
+        entry.paths.some((path) => ASYNC_SETTLING_LEAVES.has(path.slice(path.lastIndexOf(".") + 1).toLowerCase())));
+}
+// Types the org replaces WHOLESALE: it keeps exactly what the deployed file carries and deletes the
+// rest. These are the only types where omitting an element is destructive rather than merely silent,
+// which is what makes a pre-flight comparison worth its noise.
+// MEASURED on T-Pinto, 2026-07-28, by controlled probe against seeded clones. Not assumption.
+//
+//   Layout         REPLACE  — a 2-field file against a clone of a real 99-field layout left
+//                             4 fields and ZERO of its 16 related lists (12 managed-package).
+//                             31,578 bytes -> 3,846.
+//   PermissionSet  REPLACE  — a set carrying 1 of 3 field permissions REVOKED the other two.
+//                             Silent privilege loss, which is worse than content loss.
+//   CustomObject   MERGE    — deploying an object file with its validationRules/ directory
+//                             absent left all 3 rules intact. Child components are not
+//                             collateral, which is why CustomObject is not on this list.
+//
+// The earlier "13 modify cases, 0 losses" analysis was measuring careful AUTHORS, not platform
+// behaviour: every one of those files carried the pre-image forward. Absence of observed loss was
+// never evidence of merge, and treating it as such is what made this list unverified for a day.
+const PROVEN_REPLACE_TYPES = new Set(["Layout", "PermissionSet"]);
+// Same suspicion, no evidence either way: never deployed on this machine, so nothing has been
+// measured. Warned about rather than blocked, so a false assumption cannot refuse a valid deploy.
+// Promote to PROVEN only by probing, the way Layout and PermissionSet were.
+const SUSPECTED_REPLACE_TYPES = new Set(["Profile", "SharingRules", "Workflow", "CustomLabels", "MatchingRules", "AssignmentRules", "AutoResponseRules", "EscalationRules"]);
+const FULL_FILE_REPLACE_TYPES = new Set([...PROVEN_REPLACE_TYPES, ...SUSPECTED_REPLACE_TYPES]);
+// Exposed for tests: these encode live measurements, so a change to either set is a claim about
+// platform behaviour and should be backed by a probe.
+export const provenReplaceTypes = () => PROVEN_REPLACE_TYPES;
+export const fullFileReplaceTypes = () => FULL_FILE_REPLACE_TYPES;
+/**
+ * Read the earlier authored files a wave request names, so the preview below has something to
+ * compare against.
+ *
+ * FAIL-OPEN, one file at a time: an unreadable earlier file costs its own preview and nothing else.
+ * This is a warning that has not been earned by measurement yet (the promotion to a refusal waits on
+ * a false-positive rate from a real batch), so it must never be able to interrupt a delivery.
+ */
+export async function loadPredecessorPreImages(revisions) {
+    const out = [];
+    for (const r of revisions) {
+        if (!r.predecessorFile)
+            continue;
+        const xml = await fs.readFile(r.predecessorFile, "utf8").catch(() => null);
+        if (xml === null)
+            continue;
+        out.push({ typeName: r.typeName, fullName: r.fullName, xml, label: r.predecessor ?? r.predecessorFile });
+    }
+    return out;
+}
+/**
+ * THE DROP CHECK, RUN STATICALLY — before any org read, before any ~45s checkOnly.
+ *
+ * `PREFLIGHT_REPLACE_DROPS_*` is the real thing and stays the real thing: it compares the org's own
+ * pre-image against the authored file, so it knows what is actually there. But it can only run once
+ * there IS a pre-image, which means once the earlier state has already been deployed — and for a
+ * component this batch delivers twice, the first deploy is minutes of checkOnly away from the moment
+ * the omission was written.
+ *
+ * When the batch itself holds the earlier state as a FILE, that file is a usable stand-in: it is what
+ * the org is about to be told to hold, so anything in it that the later file does not carry is
+ * content the later deploy would take away. Same comparison, same `findRemovals`, same
+ * `isSourceFormatArtifact` noise filter — no second noise catalogue to drift out of step with the
+ * first.
+ *
+ * THREE DELIBERATE NARROWINGS, all of them about not shipping a warning that is usually wrong:
+ *
+ *   TYPE-GATED to `FULL_FILE_REPLACE_TYPES`, exactly like the pre-flight check. Outside that set the
+ *   org KEEPS what the file omits (CustomObject was measured to: an object file deployed without its
+ *   validationRules/ directory left all three rules intact), so an omission is not a loss and
+ *   reporting it would fire on the ordinary create-then-adjust shape every time.
+ *
+ *   UNSTATED ONLY. A facet the later file mentions and carries less of is the author's own decision
+ *   about their own element; the alarming class — the one this exists for — is a facet the later
+ *   file never mentions at all.
+ *
+ *   WARNING, never a block, and never ackable: there is nothing to acknowledge, because nothing is
+ *   being withheld. Promotion to a refusal is gated on a measured false-positive rate from a real
+ *   batch (origin §8), not on how convincing this comment is.
+ */
+export function previewPredecessorDrops(edits, predecessors) {
+    const byKey = new Map(predecessors.map((p) => [`${p.typeName}:${p.fullName}`, p]));
+    const out = [];
+    for (const edit of edits) {
+        if (!FULL_FILE_REPLACE_TYPES.has(edit.typeName))
+            continue;
+        const earlier = byKey.get(`${edit.typeName}:${edit.fullName}`);
+        if (!earlier)
+            continue;
+        // BOTH sides through the same normalizer, so this compares parsed source against parsed source
+        // — quieter than the pre-flight check, which has to compare an org read-back against one of them.
+        const before = normalizeIntent(edit.typeName, earlier.xml);
+        const after = normalizeIntent(edit.typeName, edit.xml);
+        if (!before || !after)
+            continue; // unparseable XML is already its own finding
+        const dropped = findRemovals(before, after, after).filter((r) => !isSourceFormatArtifact(r) && !r.stated);
+        if (dropped.length === 0)
+            continue;
+        const proven = PROVEN_REPLACE_TYPES.has(edit.typeName);
+        out.push({
+            rule: "PREVIEW_REPLACE_DROPS_EARLIER",
+            severity: "warning",
+            component: `${edit.typeName}:${edit.fullName}`,
+            message: `This batch changes ${edit.typeName}:${edit.fullName} more than once, and this file does not carry ` +
+                `${dropped.length} thing(s) that ${earlier.label} — the earlier file for it in this batch — establishes:\n` +
+                renderRemovals(`${edit.typeName}:${edit.fullName}`, dropped) +
+                `\n${edit.typeName} ${proven ? "IS full-file replace (MEASURED on a live org, not inferred)" : "may be full-file replace (SUSPECTED — never probed)"}, ` +
+                "so the org keeps only what the LAST file deployed carries. This file states the component's complete " +
+                "desired end state, which means anything above that is still wanted has to be written into it — nothing " +
+                "composes the two files together.\n" +
+                "PREVIEW, and a warning only: it compares two authored files, not the org, so it cannot see anything the " +
+                "org holds that neither file mentions. The org-grounded check runs at deploy time either way.",
+            ackable: false
+        });
+    }
+    return out;
+}
+/**
+ * A `ListView` delete may be refused by the org for a reason no static check can see.
+ *
+ * LIVE ORIGIN (2026-08-03, RV corpus, `ListView:PV_Asset__c.Active_High_Value`): a destructive
+ * checkOnly came back `cannot delete last filter` — TWICE. Once bundled with two other deletes, and
+ * then again with the ListView alone in its own package, which is what rules out package rollback as
+ * the cause. Nothing referenced the view: the analyzer had established that correctly from the
+ * projection, and the approval card told the operator on that basis that it would delete cleanly.
+ * It was wrong, and the reference reasoning was not the flaw — the org refuses for its own reason.
+ *
+ * WHAT THE MESSAGE PROBABLY MEANS, and how far that goes. "Filter" is Salesforce's own legacy word
+ * for a list view (Classic's `fcf=00B…` parameter; `getFilterId()` is documented as returning "the
+ * filter ID of the last used list view"), and this was the ONLY Metadata-API-visible list view on
+ * its object — so it reads as "cannot delete the object's last list view" rather than "cannot delete
+ * the last filter ROW", which the view's two filter criteria already contradict. That is a
+ * hypothesis, not a rule: the exact string is undocumented, the ListView metadata reference states
+ * no minimum-filter constraint, and this is one view on one object in one org.
+ *
+ * So the finding does NOT try to predict the refusal — it cannot, and a delete of a non-last view
+ * may well succeed. WARNING, never a block, never ackable: it names the manual-Setup route before a
+ * wave is spent discovering it, and the dry run remains the thing that actually answers.
+ */
+export function listViewDeleteWarnings(deletes) {
+    return deletes
+        .filter((d) => d.typeName === "ListView")
+        .map((d) => ({
+        rule: "LEMMA_LISTVIEW_DELETE_MAY_REFUSE",
+        severity: "warning",
+        component: `ListView:${d.fullName}`,
+        message: `Salesforce has been measured refusing a ListView delete through the deployment API for a reason ` +
+            `UNRELATED to references: "cannot delete last filter" (live-caught 2026-08-03, twice — bundled and ` +
+            `then isolated in its own destructive package). "Nothing references it" is therefore not evidence ` +
+            `that ${d.fullName} will delete, and no local check can tell you whether this one will. ` +
+            `Plan a ListView removal as a MANUAL SETUP TASK by default, and run the delete \`dryRunOnly\` first so ` +
+            `the org's verbatim answer lands in deletes.json either way — a non-last view may well delete cleanly, ` +
+            `which is why this warns rather than blocks.`,
+        ackable: false
+    }));
+}
+/**
+ * The pre-flight replace check's own blind spot, made visible.
+ *
+ * That check compares the pre-image against the authored intent and names what the replace would
+ * drop — but it can only report facets the pre-image CONTAINS. When a read path cannot see a facet
+ * at all, the comparison finds nothing to lose and reports the silence as safety. That is not a
+ * hypothetical: SOAP readMetadata omits Layout related lists and jsforce renders the omission as
+ * `[]`, so on 2026-08-02 the pre-flight walked an Account layout's empty `relatedLists` and would
+ * have certified a replace that deleted one (PV corpus Arm A; caught by hand, not by the tool).
+ *
+ * orgread/layoutSnapshot.ts fixes the read by going to a second source. This covers the residue:
+ * when even that source cannot answer, the snapshot says INCOMPLETE instead of guessing, and a
+ * full-file replace grounded on it must not be certified. Silence is the defect either way.
+ */
+export function incompleteFacetRisks(edits, manifest) {
+    const byKey = new Map(manifest.components.map((c) => [`${c.typeName}:${c.fullName}`, c]));
+    const out = [];
+    for (const edit of edits) {
+        // A merge type keeps what the file omits, so an unreadable facet is not at risk from THIS
+        // deploy; and a create has no pre-image to be incomplete.
+        if (!FULL_FILE_REPLACE_TYPES.has(edit.typeName))
+            continue;
+        const entry = byKey.get(`${edit.typeName}:${edit.fullName}`);
+        if (!entry?.found)
+            continue;
+        const facets = incompleteFacetsOf(entry.errors);
+        if (facets.length === 0)
+            continue;
+        out.push({
+            component: `${edit.typeName}:${edit.fullName}`,
+            typeName: edit.typeName,
+            facets,
+            reasons: (entry.errors ?? []).filter((e) => incompleteFacetsOf([e]).length > 0),
+            proven: PROVEN_REPLACE_TYPES.has(edit.typeName)
+        });
+    }
+    return out;
+}
+/**
+ * Retrieve the org's CURRENT source XML for the given components into destDir — the same dialect
+ * we author, so carrying an existing component forward is an edit, not a JSON transcription (the
+ * transcription is where SM301's layout picked up two real divergences; see plan 2026-07-29-002).
+ * Fail-open by contract: this is an authoring convenience, never verification — a failed retrieve
+ * costs a note, and the canonical JSON under pre/ remains the comparison substrate either way.
+ */
+export async function retrievePreImageSource(targets, targetOrg, apiVersion, destDir) {
+    const projectDir = await fs.mkdtemp(path.join(os.tmpdir(), "cc-mcp-preimg-"));
+    try {
+        // The package directory must EXIST on disk, not just be named in sfdx-project.json. The CLI
+        // resolves packageDirectories before it talks to the org and refuses outright when the path is
+        // absent (`MissingPackageDirectoryError`, exit 1) — so a temp project carrying only the JSON
+        // manifest fails 100% of the time, against any org, on any machine.
+        //
+        // Live-caught 2026-08-02 on the PV corpus run: EVERY wave that had a pre-image to retrieve lost
+        // it, which is every brownfield wave's deployable rollback image (origin R17). It read as
+        // environment-specific and was not — `preImageTargets` is pure and fully unit-tested, while the
+        // retrieve itself had no test that ran the real command in the real temp layout. That is why
+        // preImage.test.ts now drives THIS function through a stub `sf` on PATH.
+        await fs.mkdir(path.join(projectDir, PRE_IMAGE_PACKAGE_DIR), { recursive: true });
+        await fs.writeFile(path.join(projectDir, "sfdx-project.json"), JSON.stringify({
+            packageDirectories: [{ path: PRE_IMAGE_PACKAGE_DIR, default: true }],
+            sourceApiVersion: apiVersion
+        }), "utf8");
+        const args = ["project", "retrieve", "start", "--target-org", targetOrg, "--json"];
+        for (const t of targets)
+            args.push("--metadata", `${t.typeName}:${t.fullName}`);
+        const run = await runProcess("sf", args, { env: sfCliEnv(), cwd: projectDir, timeoutMs: 180_000 });
+        if (run.timedOut)
+            return { ok: false, error: "retrieve killed at 180s timeout" };
+        if (run.exitCode !== 0)
+            return { ok: false, error: `retrieve exit ${run.exitCode}: ${sfFailureDetail(run)}` };
+        // Exit 0 does NOT mean every target came back: a component the org cannot find is reported as a
+        // per-file `Failed` state on a status-0 run (measured against 00Dfn00000BFjbBEAT 2026-08-02).
+        // Counting targets instead of arrivals would promise a rollback image for components that have
+        // none — the same false assurance as the silent failure above, one layer in.
+        const outcome = parseRetrieveOutcome(run.stdout, targets);
+        const retrievedDir = path.join(projectDir, PRE_IMAGE_PACKAGE_DIR, "main", "default");
+        if (outcome.retrieved === 0) {
+            // The CLI never creates the directory when nothing lands, so copying it would throw ENOENT and
+            // surface as a bare filesystem path. Say what actually happened instead.
+            return { ok: false, error: `retrieve returned no source for any of the ${targets.length} target(s)${outcome.problem ? ` — ${outcome.problem}` : ""}` };
+        }
+        await fs.cp(retrievedDir, destDir, { recursive: true });
+        return { ok: true, retrieved: outcome.retrieved, missing: outcome.missing };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        await fs.rm(projectDir, { recursive: true, force: true });
+    }
+}
+/** Package directory of the throwaway sfdx project the pre-image retrieve runs in. */
+const PRE_IMAGE_PACKAGE_DIR = "force-app";
+/**
+ * The actionable line out of a failed `sf --json` run.
+ *
+ * `--json` puts the error payload on STDOUT and leaves stderr EMPTY (measured on @salesforce/cli
+ * 2.137.7), so a stderr tail — the obvious thing to attach — carries nothing. The live failure
+ * reported only "retrieve exit 1", which told the supervisor there was no rollback image but not
+ * one thing they could do about it.
+ */
+function sfFailureDetail(run) {
+    try {
+        const parsed = JSON.parse(run.stdout);
+        const message = typeof parsed.message === "string" ? parsed.message : "";
+        const name = typeof parsed.name === "string" ? parsed.name : "";
+        if (message)
+            return name ? `${name}: ${message}` : message;
+    }
+    catch {
+        // Not JSON — a crash before the CLI's own error handler, or a non-CLI failure. Fall through.
+    }
+    const tail = (run.stderr || run.stdout).trim().split("\n").slice(-3).join(" | ").slice(0, 400);
+    return tail || "no output";
+}
+/** Which of the requested targets the retrieve actually produced source for. */
+function parseRetrieveOutcome(stdout, targets) {
+    let files = [];
+    let problem = "";
+    try {
+        const parsed = JSON.parse(stdout);
+        if (Array.isArray(parsed.result?.files))
+            files = parsed.result.files;
+        const messages = parsed.result?.messages;
+        const first = Array.isArray(messages) ? messages[0] : messages;
+        if (first && typeof first === "object" && typeof first.problem === "string") {
+            problem = first.problem;
+        }
+    }
+    catch {
+        // Unparseable success output: trust the exit code and claim every target, which is what this
+        // did before it read the payload at all.
+        return { retrieved: targets.length, missing: [], problem: "" };
+    }
+    const arrived = new Set(files
+        .filter((f) => f.state !== "Failed")
+        .map((f) => `${String(f.type)}:${String(f.fullName)}`));
+    const missing = targets.filter((t) => !arrived.has(`${t.typeName}:${t.fullName}`));
+    return { retrieved: targets.length - missing.length, missing, problem };
+}
+/**
+ * Tooling objects that carry a usable LastModifiedDate, probed live against T-Pinto 2026-07-31.
+ *
+ * The `id` column differs per type and several have no `Name` at all, so each entry names the
+ * column that identifies the row. EntityDefinition is deliberately ABSENT: it exposes
+ * LastModifiedDate but the org returns null for it, so object-level changes are found via
+ * CustomObject instead.
+ *
+ * A type missing from this list is simply unscanned — the report says which types it covered rather
+ * than implying it looked everywhere.
+ */
+const CHANGE_SCAN_TYPES = [
+    // `parentField` qualifies the row with its OBJECT. Without it the scan selects a bare
+    // DeveloperName, so a foreign `Contact.Status__c` is indistinguishable from our
+    // `Account.Status__c` and gets suppressed — and `Status__c`, `Name__c`, `Active__c`,
+    // `Description__c` are exactly the names a delivery deploys most. That blinded the scan to a
+    // common name across the WHOLE org for the duration of the wave. Probed live 2026-07-31:
+    // EntityDefinition.QualifiedApiName returns the object API name on both types.
+    { type: "CustomField", nameField: "DeveloperName", metadataType: "CustomField", parentField: "EntityDefinition.QualifiedApiName" },
+    { type: "ValidationRule", nameField: "ValidationName", metadataType: "ValidationRule", parentField: "EntityDefinition.QualifiedApiName" },
+    { type: "Layout", nameField: "Name", metadataType: "Layout" },
+    { type: "CustomObject", nameField: "DeveloperName", metadataType: "CustomObject" },
+    { type: "CompactLayout", nameField: "DeveloperName", metadataType: "CompactLayout" },
+    // Probed live against vfppartial 2026-07-31 with the exact query shape above (NamespacePrefix
+    // filter + window), all three returning cleanly. fc19eae's message said Flow and CustomTab
+    // "carry a usable LastModifiedDate" and then shipped without them.
+    //
+    // Flow is scanned as FlowDefinition, not Flow: `Flow` rows are VERSIONS and have no
+    // DeveloperName at all (INVALID_FIELD), while FlowDefinition carries the API name the metadata
+    // type is addressed by. CustomTab needs DeveloperName rather than Name for the same reason
+    // precedent.ts already documents for object tabs.
+    { type: "FlowDefinition", nameField: "DeveloperName", metadataType: "Flow" },
+    { type: "CustomTab", nameField: "DeveloperName", metadataType: "CustomTab" },
+    { type: "QuickActionDefinition", nameField: "DeveloperName", metadataType: "QuickAction" },
+    // PROFILE IS DELIBERATELY ABSENT, and this is the gap worth knowing about: with PermissionSet
+    // filtered to IsOwnedByProfile = false, profile and field-level-security changes are structurally
+    // invisible to this scan. Two reasons, both checked rather than assumed. It has no
+    // NamespacePrefix column (INVALID_FIELD against the query above), so it cannot use this shape at
+    // all. And profiles are touched by so much routine org activity that including them would
+    // reproduce the 72/76 noise that got profile-owned permission sets excluded — an alarm that fires
+    // on every wave teaches operators to ignore the one that matters.
+    {
+        type: "PermissionSet",
+        nameField: "Name",
+        metadataType: "PermissionSet",
+        // Salesforce keeps a hidden PermissionSet row per PROFILE, and they churn constantly: a live
+        // 10-minute window on T-Pinto returned 76 rows of which 72 were profile-owned, with generated
+        // names like `X00ex00000018ozT_128_09_43_34_1`. Unfiltered, this one type would have buried
+        // every genuine candidate under machine noise. The 4 that survive the filter were the real
+        // permission sets the EV arms deployed.
+        extraWhere: "IsOwnedByProfile = false"
+    }
+];
+/**
+ * Ask the org what moved during the mutation window, rather than reading every sibling component
+ * before and after on the chance that one of them did.
+ *
+ * Replaces the parent-object projection expansion (plan -002). Measured: the expansion read 4.6
+ * components per component touched and found one side change in 70 bundles; this is one Tooling
+ * query per type — 2.3s org-wide on T-Pinto, the same cost as querying a single object — and it
+ * also sees objects that were never in scope at all, which the expansion structurally could not.
+ *
+ * `NamespacePrefix = null` skips managed components: they cannot change as a result of our deploys,
+ * and on T-Pinto's Account they are 192 of 354 fields.
+ *
+ * IMPORTANT — this establishes "changed during your window", never "caused by your deploy". Live
+ * evidence that the distinction is real: on 2026-07-29 two EV arms deployed to the same org four
+ * minutes apart, so each would appear in the other's window. Causation stays the intent check's job.
+ */
+// Salesforce's Tooling rows do NOT name components the way a projection key does, and matching the
+// two by string surgery is where this check accused a wave of being someone else's work.
+//
+// Two shapes broke it, both live-caught on CF63 w4, and both reported the wave's OWN components back
+// as "changed in the org during this deploy that this wave did not deploy":
+//   CustomObject.DeveloperName → "CF63_Intake_Request"          vs key "CustomObject:CF63_Intake_Request__c"
+//   Layout.Name                → "CF63 Intake Request Layout"   vs key "Layout:CF63_Intake_Request__c-CF63 Intake Request Layout"
+// DeveloperName carries no `__c`, and the Layout key joins object and label with a DASH while the
+// old test only knew about a dot. Neither matched, so both became phantom side changes — and
+// sideChanges is load-bearing: any entry downgrades DIFF_VERIFIED to DELIVERED_WITH_DRIFT. A wave
+// whose intent report was spotless (32/6/11/1 matched, zero mismatches) still read as drifted.
+//
+// Compared against every segment of the key rather than the whole, with the custom-object suffix
+// normalized off both sides. Errs toward silence over false accusation, as before: a real
+// concurrent change that happens to share a leaf name with something we deployed is missed, which
+// is the cheaper error — the intent check still owns causation.
+// Scoped BY TYPE. Normalizing the suffix away makes names collide across types that never used to:
+// a wave deploying `CustomObject:CF63_Intake_Request__c` would otherwise silence a foreign
+// `CustomField` whose DeveloperName is `CF63_Intake_Request` — which is exactly what the Salesforce
+// UI names a lookup to that object. Silencing the one check watching for a concurrent admin is a
+// worse failure than the false positive this function was written to remove, so the comparison only
+// considers keys of the row's own type.
+//
+// ONE cross-type match survives, because it is real rather than coincidental: deploying a CHILD
+// bumps its parent object's LastModifiedDate, so a CustomObject row matching the object half of any
+// key is ours. That relationship is what the original dot-prefix test was reaching for.
+const CUSTOM_SUFFIX_RE = /__(c|mdt|e|b|x|kav|share|history|feed|tag|changeevent)$/i;
+const bareName = (s) => s.replace(CUSTOM_SUFFIX_RE, "").toLowerCase();
+export function changeScanNameIsOurs(ours, name, metadataType, parentObject) {
+    const want = bareName(name);
+    // When the scan knows the row's OBJECT, the leaf name alone is no longer enough to claim the row
+    // as ours. Deploying `Account.Status__c` used to suppress a concurrent `Contact.Status__c` — and
+    // a foreign change to a same-named field is not a coincidence worth tolerating, it is the single
+    // most likely collision on a real org.
+    const wantParent = parentObject ? bareName(parentObject) : undefined;
+    for (const key of ours) {
+        const colon = key.indexOf(":");
+        const keyType = key.slice(0, colon);
+        const leaf = key.slice(colon + 1);
+        // A key is either bare (`Obj__c`), dot-qualified (`Obj__c.Field__c`) or dash-qualified
+        // (`Obj__c-Layout Label`). API names contain neither separator, so the FIRST one splits it.
+        const dot = leaf.indexOf(".");
+        const dash = leaf.indexOf("-");
+        const parent = dot >= 0 ? leaf.slice(0, dot) : dash >= 0 ? leaf.slice(0, dash) : leaf;
+        if (metadataType === "CustomObject" && bareName(parent) === want)
+            return true;
+        if (metadataType && keyType !== metadataType)
+            continue;
+        // Qualified comparison when the object is known: both halves must agree, so a same-named field
+        // on a different object stays visible as a side change.
+        if (wantParent !== undefined) {
+            const child = dot >= 0 ? leaf.slice(dot + 1) : dash >= 0 ? leaf.slice(dash + 1) : leaf;
+            if (bareName(parent) === wantParent && bareName(child) === want)
+                return true;
+            continue;
+        }
+        const segments = [leaf, parent];
+        if (dot >= 0)
+            segments.push(leaf.slice(dot + 1));
+        if (dash >= 0)
+            segments.push(leaf.slice(dash + 1));
+        if (segments.some((s) => bareName(s) === want))
+            return true;
+    }
+    return false;
+}
+/**
+ * What a facet update is worth SAYING once the post-projection has looked.
+ *
+ * The CRUD Metadata API's `success: true` acknowledges the REQUEST — Salesforce returns it for
+ * facets it then silently ignores. Live-caught CF63 w1: `sharingModel` reported success twice while
+ * `EntityDefinition.InternalSharingModel` stayed ReadWrite. The read-back caught it, but the same
+ * response still carried `status: "updated"` beside that mismatch, so one payload made two
+ * contradictory claims and only the operator noticing the disagreement kept the report honest.
+ *
+ * So the word is withheld until there is evidence for it, and when there is not, the status says
+ * what the org actually reads and what to do about it — a summary quoting this line alone must not
+ * be able to mislead.
+ */
+export function facetVerifiedStatus(mismatches) {
+    if (mismatches.length === 0)
+        return "verified";
+    const detail = mismatches.map((m) => `${m.path}=${m.observed} (asked for ${m.intended})`).join(", ");
+    return (`NOT APPLIED — the org accepted the request but still reads ${detail}. ` +
+        `Salesforce silently ignores some facets on this path, so this is USUALLY the org's answer: change it in Setup ` +
+        `or find another mechanism, and do NOT re-send blindly. It is a SINGLE read, taken immediately after the write ` +
+        `— the read-back no longer waits (the backoff settled zero of the 17 waves it ever fired on), so a facet ` +
+        `Salesforce recalculates asynchronously can read stale here. The notes above say which kind this is; ` +
+        `re-project the scope to settle it either way.`);
+}
+export async function scanChangedInWindow(reader, window, ours, 
+/**
+ * Components that MUST show up in the scan if the window is aimed correctly — edits and facet
+ * updates, never DELETES.
+ *
+ * A deleted component has no row left to carry a LastModifiedDate, so a delete-only wave would
+ * witness nothing and report every window as suspect. Defaults to `ours` for callers that do not
+ * separate them, which is safe only when the wave contains no deletes.
+ */
+witnesses = ours) {
+    const candidates = [];
+    const typesCovered = [];
+    const notes = [];
+    // Types this wave actually touched, restricted to ones the scan can see. These are the components
+    // whose presence in the results proves the window is aimed correctly.
+    const ourTypes = new Set([...witnesses].map((key) => key.slice(0, key.indexOf(":"))));
+    const witnessTypes = new Set(CHANGE_SCAN_TYPES.filter((t) => ourTypes.has(t.metadataType)).map((t) => t.type));
+    const witnessed = new Set();
+    if (!window.start || !window.end) {
+        return { candidates, typesCovered, windowSuspect: false, notes: ["no mutation window recorded — scan skipped"] };
+    }
+    for (const { type, nameField, metadataType, extraWhere, parentField } of CHANGE_SCAN_TYPES) {
+        try {
+            const res = await reader.toolingQuery(`SELECT ${nameField}${parentField ? `, ${parentField}` : ""}, LastModifiedDate FROM ${type} ` +
+                `WHERE NamespacePrefix = null${extraWhere ? ` AND ${extraWhere}` : ""} ` +
+                `AND LastModifiedDate >= ${window.start} AND LastModifiedDate <= ${window.end}`);
+            typesCovered.push(type);
+            for (const row of res.records) {
+                const name = row[nameField];
+                if (typeof name !== "string" || !name)
+                    continue;
+                // A dotted Tooling path comes back NESTED, not flattened:
+                // `EntityDefinition.QualifiedApiName` arrives as `{EntityDefinition: {QualifiedApiName}}`.
+                const parent = parentField
+                    ? parentField.split(".").reduce((node, seg) => node?.[seg], row)
+                    : undefined;
+                const qualified = typeof parent === "string" && parent ? `${parent}.${name}` : name;
+                if (changeScanNameIsOurs(ours, name, metadataType, typeof parent === "string" ? parent : undefined)) {
+                    witnessed.add(type);
+                }
+                else {
+                    candidates.push(`${metadataType}:${qualified}`);
+                }
+            }
+        }
+        catch (error) {
+            notes.push(`change scan skipped ${type}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // Every type that both carried one of our components AND was successfully queried should have
+    // returned at least one of ours. A miss means the window is not over the interval the deploy
+    // actually happened in — clock skew being the likely cause, since the window comes from this
+    // machine's clock and LastModifiedDate comes from the org's.
+    const missedWitnesses = [...witnessTypes].filter((type) => typesCovered.includes(type) && !witnessed.has(type));
+    const windowSuspect = missedWitnesses.length > 0;
+    if (windowSuspect) {
+        notes.push(`The change scan's window did not contain this wave's OWN changes to ${missedWitnesses.join(", ")}, ` +
+            `so it is not looking at the interval the deploy happened in — most likely clock skew between this machine ` +
+            `and the org (the window is stamped locally; LastModifiedDate is stamped by Salesforce). ` +
+            `Treat "no concurrent changes found" as unproven for this wave rather than as a clean result.`);
+    }
+    return { candidates: [...new Set(candidates)].sort(), typesCovered, windowSuspect, notes };
+}
+/**
+ * True/false history-tracking state for every edited CustomField, read from Tooling
+ * `FieldDefinition.IsFieldHistoryTracked` — the only surface that reports it.
+ *
+ * EVERY edited field, not only the ones whose intent STATES trackHistory. That narrower filter was
+ * right for the job this probe was first written for (verifying a stated `trackHistory`) and wrong
+ * for the one the EV-31…40 run exposed: a DIFF_VERIFIED deploy switched history tracking OFF on a
+ * field whose file never mentioned it. The facet is invisible to the Metadata API — omitted whatever
+ * its value — so the pre/post image comparison that catches every other unstated change is
+ * structurally blind to this one, and a probe that only looks where the author already looked cannot
+ * see it either. Called on BOTH sides of the deploy; a value that moved with the intent silent is
+ * reported as an unstated change.
+ *
+ * Costs one Tooling query per OBJECT per side, and nothing at all on a wave that edits no fields.
+ * Keyed by the edit's fullName (`Object.Field__c`) because that is what the caller holds.
+ *
+ * Fail-open by contract: a probe that throws returns an empty map — every field falls back to the
+ * projection's (absent) value and no tracking change can be claimed. That is the pre-existing
+ * false-drift behaviour: noisy, never wrong in the dangerous direction.
+ */
+export async function probeFieldHistoryTracking(reader, edits) {
+    const wanted = edits.filter((e) => e.typeName === "CustomField" && e.fullName.includes("."));
+    const out = new Map();
+    if (wanted.length === 0)
+        return out;
+    const byObject = new Map();
+    for (const e of wanted) {
+        const [obj, field] = [e.fullName.slice(0, e.fullName.indexOf(".")), e.fullName.slice(e.fullName.indexOf(".") + 1)];
+        if (!obj || !field)
+            continue;
+        (byObject.get(obj) ?? byObject.set(obj, []).get(obj)).push(field);
+    }
+    for (const [obj, fields] of byObject) {
+        try {
+            const quoted = fields.map((f) => `'${f.replace(/'/g, "\\'")}'`).join(",");
+            const res = await reader.toolingQuery(`SELECT QualifiedApiName, IsFieldHistoryTracked FROM FieldDefinition ` +
+                `WHERE EntityDefinition.QualifiedApiName = '${obj.replace(/'/g, "\\'")}' AND QualifiedApiName IN (${quoted})`);
+            for (const r of res.records)
+                out.set(`${obj}.${r.QualifiedApiName}`, Boolean(r.IsFieldHistoryTracked));
+        }
+        catch {
+            // Probe unavailable for this object — leave those fields to the projection's view.
+        }
+    }
+    return out;
+}
+/**
+ * Did this deploy move history tracking on a field whose file never mentioned it?
+ *
+ * The generic pre/post comparison cannot answer this — the Metadata API omits trackHistory from
+ * every read-back — so the two Tooling probes stand in for the pre- and post-image of that one facet.
+ *
+ * Silent when the intent STATES trackHistory: compareIntent already verifies that against the same
+ * probe, and reporting it here as well would make one finding look like two. Silent when either side
+ * is unknown, which covers both a create (the field had no pre-deploy row) and a failed probe.
+ */
+export function unstatedTrackingChange(edit, intent, before, after) {
+    if (edit.typeName !== "CustomField")
+        return null;
+    if (intent && "trackHistory" in intent)
+        return null;
+    const was = before.get(edit.fullName);
+    const now = after.get(edit.fullName);
+    if (was === undefined || now === undefined || was === now)
+        return null;
+    // Rendered the way diffMetadata renders a coerced leaf, so a reader cannot tell which check
+    // produced which line — they are answering the same question about the same component.
+    return { path: "metadata.trackHistory", before: JSON.stringify(String(was)), after: JSON.stringify(String(now)) };
+}
+export function deriveScope(edits, deletes) {
+    const objects = new Set();
+    const components = [];
+    for (const item of [...edits, ...deletes]) {
+        if (item.typeName === "CustomObject")
+            objects.add(item.fullName);
+        else if (["CustomField", "ValidationRule", "ListView", "CompactLayout", "RecordType"].includes(item.typeName)) {
+            const obj = item.fullName.split(".")[0];
+            if (obj)
+                objects.add(obj);
+            if (["ListView", "CompactLayout", "RecordType"].includes(item.typeName)) {
+                components.push({ typeName: item.typeName, fullName: item.fullName });
+            }
+        }
+        else
+            components.push({ typeName: item.typeName, fullName: item.fullName });
+    }
+    return {
+        ...(objects.size ? { objects: [...objects].sort() } : {}),
+        ...(components.length ? { components } : {})
+    };
+}
+// THE DEFAULT since plan -002. (It began as the fallback for when deriveScope's parent-object expansion tripped the projection's component
+// cap. Live-caught (T-Pinto, 2026-07-29): deleting 28 debris CustomFields on Account was refused
+// because Account's expansion resolves to 342 components — the tool could not delete a FIELD off
+// any large standard object at all, and the work went through a raw destructive deploy with no
+// evidence bundle. This scope names exactly the touched components instead: intent verification
+// and the pre/post diff still cover everything the bundle changes; what is given up is sibling
+// side-change detection and the pre-projection's referential lint breadth (session-level tokens
+// still apply). deriveScope survives behind direct_apply's `wideObjectScope` flag for a deliberate
+// whole-object before/after; it is no longer what an ordinary wave pays for.
+export function narrowScope(edits, deletes, facetObjects) {
+    const components = [];
+    const seen = new Set();
+    const push = (typeName, fullName) => {
+        const key = `${typeName}:${fullName}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        components.push({ typeName, fullName });
+    };
+    for (const item of [...edits, ...deletes])
+        push(item.typeName, item.fullName);
+    for (const obj of facetObjects)
+        push("CustomObject", obj);
+    return { components };
+}
+// The org MATERIALIZES default:"false" and label=fullName onto every picklist/value-set
+// entry on read-back (stress-caught case E, 2026-07-22; GVS customValue, 6.5.1 run). Intent
+// omitting them would false-mismatch the whole array — canonicalize the intent side to match.
+function materializePicklistEntries(list) {
+    const values = Array.isArray(list) ? list : [list];
+    return values.map((v) => {
+        if (!v || typeof v !== "object")
+            return v;
+        const entry = { ...v };
+        if (entry.default === undefined)
+            entry.default = "false";
+        if (entry.label === undefined && typeof entry.fullName === "string")
+            entry.label = entry.fullName;
+        return entry;
+    });
+}
+// Intent = the submitted XML parsed to JSON and pushed through the SAME normalizations
+// the projection applies to org read-backs, so intent-vs-observed compares like with like.
+export function normalizeIntent(typeName, xml) {
+    const parsed = parseMetadataXml(xml);
+    if (!parsed)
+        return null;
+    if (typeName === "CustomField") {
+        const md = normalizeCustomFieldMetadata(parsed.body);
+        // The defaultValue projection (EXT-2040: picklist default lives on the VALUE)
+        // happens in the snapshot READER, not the shared normalizer — mirror it here so
+        // intent compares like-with-like against the projected read-back.
+        if (md && md.defaultValue === undefined) {
+            const projected = valueSetDefaultValue(md.valueSet);
+            if (projected !== undefined)
+                md.defaultValue = projected;
+        }
+        const valueSet = md?.valueSet;
+        const def = valueSet?.valueSetDefinition;
+        if (def?.value !== undefined)
+            def.value = materializePicklistEntries(def.value);
+        // fieldManageability is a design-time-only facet for CustomMetadata (__mdt) fields;
+        // an unmanaged org OMITS it on read-back, so comparing it always false-mismatches
+        // (6.5.1 run: 3 __mdt fields drifted "DeveloperControlled" vs absent). It carries no
+        // deliverable meaning here — drop it from intent so it never manufactures drift.
+        if (md && "fieldManageability" in md)
+            delete md.fieldManageability;
+        return md;
+    }
+    if (typeName === "GlobalValueSet") {
+        // Same value materialization as CustomField picklists — the org stamps default:"false"
+        // + label onto every customValue on read-back (6.5.1 run: CF66_Case_Category_GVS drifted).
+        const body = parsed.body;
+        if (body.customValue !== undefined)
+            body.customValue = materializePicklistEntries(body.customValue);
+        return body;
+    }
+    return parsed.body;
+}
+const INTENT_IDENTITY_KEYS = ["fullName", "name", "label", "field", "relatedList", "apiName", "tab"];
+// Subset check: every leaf the intent states must hold in the observed metadata.
+// Org-added facets are ignored; orderOnly array differences are tolerated and counted.
+export function compareIntent(intent, observed) {
+    if (!observed)
+        return { matched: 0, mismatches: [{ path: "metadata", intended: "(component)", observed: "(absent)" }], orderOnly: 0 };
+    let matched = 0;
+    let orderOnly = 0;
+    const mismatches = [];
+    const walk = (want, have, at) => {
+        // SAME CLASS as the boolean-false rule below, but the platform default is a NAMED value rather
+        // than false, so that rule never caught it. Live-caught CF74 wave 3: the author states
+        // formulaTreatBlanksAs=BlankAsBlank, the org drops the element because it IS the default, and
+        // the wave reported DELIVERED_WITH_DRIFT on a field that was perfectly correct.
+        //
+        // This must be CANONICALIZED, not merely tolerated: the element is omitted permanently, so no
+        // amount of re-reading would ever resolve it. (When a backoff still existed here, an
+        // uncatalogued entry burned the whole sleep on every apply and reported drift anyway.)
+        const leafName = at.slice(at.lastIndexOf(".") + 1);
+        if ((have === undefined || have === null) &&
+            leafName in PLATFORM_DEFAULT_WHEN_OMITTED &&
+            // Deep, not ===: rejectBehavior's default is an OBJECT, which reference equality never matches.
+            canonJson(PLATFORM_DEFAULT_WHEN_OMITTED[leafName]) === canonJson(want)) {
+            matched += 1;
+            return;
+        }
+        // INVERSE of the materialization class (live-caught 6.5.4 wave 1): the author states a
+        // boolean explicitly FALSE (externalId, trackHistory, trackTrending, unique, …) and the org
+        // DROPS it on read-back because it equals the platform default. Absent means false, so this
+        // is agreement, not drift. An intended TRUE that comes back absent stays a real mismatch.
+        if ((want === false || want === "false") && (have === undefined || have === null)) {
+            matched += 1;
+            return;
+        }
+        // Benchmark-caught (2026-07-22, 11/26 units): the XML parser collapses a single
+        // repeatable child to an OBJECT while the org read-back always returns an ARRAY
+        // (and materializes empty ones). Normalize the singleton/empty representations
+        // before comparing — they are the same metadata.
+        if (Array.isArray(have) && !Array.isArray(want)) {
+            if (have.length === 1)
+                return walk(want, have[0], at);
+            if (have.length === 0 && (want === undefined || want === null)) {
+                matched += 1;
+                return;
+            }
+        }
+        if (Array.isArray(want) && !Array.isArray(have) && want.length === 1) {
+            return walk(want[0], have, at);
+        }
+        // BOTH arrays. Previously this fell straight through to a whole-array structural diff, which
+        // is NOT a subset check — so ONE org-injected key inside ONE element failed the entire
+        // collection. That single gap produced most of CF77's false drift: the platform injects
+        // `processMetadataValues: []` into every Flow inputAssignment, and both Flows plus the Layout
+        // reported DELIVERED_WITH_DRIFT on content that matched the author's intent exactly.
+        //
+        // Matched by identity where the elements carry one, so a reorder on read-back is not a
+        // difference either; positionally only when there is nothing to key on.
+        if (isEmptyish(want) && isEmptyish(have)) {
+            matched += 1;
+            return;
+        }
+        if (Array.isArray(want) && Array.isArray(have)) {
+            // Same members, different order. The org re-sorts collections freely on read-back (CF77's
+            // console app came back with its six workspace tabs reordered), and a reorder is explicitly
+            // tolerated everywhere else in this comparator — so recognise it before doing any positional
+            // work, which would otherwise manufacture one mismatch per shifted element.
+            if (canonJson([...want].map(canonJson).sort()) === canonJson([...have].map(canonJson).sort())) {
+                orderOnly += 1;
+                matched += 1;
+                return;
+            }
+            const key = INTENT_IDENTITY_KEYS.find((k) => want.every((e) => isPlainObj(e) && typeof e[k] === "string") &&
+                have.every((e) => isPlainObj(e) && typeof e[k] === "string") &&
+                new Set(have.map((e) => e[k])).size === have.length);
+            if (key) {
+                const byId = new Map(have.map((e) => [e[key], e]));
+                for (const el of want) {
+                    const id = el[key];
+                    walk(el, byId.get(id), `${at}[${key}=${id}]`);
+                }
+                return;
+            }
+            if (want.length === have.length) {
+                for (let i = 0; i < want.length; i += 1)
+                    walk(want[i], have[i], `${at}[${i}]`);
+                return;
+            }
+        }
+        if (want !== null && typeof want === "object" && !Array.isArray(want) && have !== null && typeof have === "object" && !Array.isArray(have)) {
+            for (const key of Object.keys(want)) {
+                walk(want[key], have[key], `${at}.${key}`);
+            }
+            return;
+        }
+        const changes = diffMetadata(coerceLeaf(canonicalizeCurrencyish(want)), coerceLeaf(canonicalizeCurrencyish(have)), at);
+        if (changes.length === 0)
+            matched += 1;
+        else if (changes.every((c) => c.orderOnly)) {
+            matched += 1;
+            orderOnly += 1;
+        }
+        else {
+            for (const c of changes)
+                mismatches.push({ path: c.path, intended: c.before, observed: c.after });
+        }
+    };
+    for (const key of Object.keys(intent)) {
+        if (key === "fullName")
+            continue; // path-derived on the wire, unreliable to compare
+        walk(intent[key], observed[key], `metadata.${key}`);
+    }
+    return { matched, mismatches, orderOnly };
+}
+async function writeJson(dir, name, value) {
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, name), `${JSON.stringify(value, null, 1)}\n`, "utf8");
+}
+// Exported for tests: the sf CLI speaks TWO different JSON envelopes and getting this wrong
+// costs a blind debugging session (see the 6.5.4 note below).
+export function parseDeployOutput(stdout, stderr) {
+    try {
+        const parsed = JSON.parse(stdout);
+        const cf = parsed.result?.details?.componentFailures;
+        const failures = cf === undefined ? [] : Array.isArray(cf) ? cf : [cf];
+        if (parsed.result?.status) {
+            return { status: parsed.result.status, id: parsed.result.id, failures, raw: parsed.result };
+        }
+        // No result.status — read the error envelope instead of reporting a bare "UNKNOWN".
+        // Live-caught (6.5.4 run): a wave-4 checkOnly returned status UNKNOWN with an EMPTY
+        // failures array and no diagnostic at all, so the operator had to split the wave blind to
+        // find which component was at fault. The CLI's message was there the whole time.
+        const name = parsed.name ?? "UNPARSEABLE_RESULT";
+        const message = parsed.message ?? (stderr.slice(-600) || stdout.slice(-600));
+        return {
+            status: name,
+            failures: failures.length > 0 ? failures : [{ name, message }],
+            raw: parsed
+        };
+    }
+    catch {
+        return { status: "UNPARSEABLE", failures: [{ stdoutTail: stdout.slice(-800), stderrTail: stderr.slice(-400) }] };
+    }
+}
+async function sfDeploy(projectDir, targetOrg, dryRun, timeoutMs, 
+/**
+ * Recover the job after a timeout instead of reporting an unknown outcome.
+ *
+ * OFF for the dry run: a validation mutates nothing, so an abandoned one costs nothing and there
+ * is no ambiguity to resolve — the caller retries it once, which is cheaper than reporting on it.
+ * ON for the real deploy, where the whole point is that the job is still writing.
+ */
+recover) {
+    // `--wait` under our own kill, so a slow deploy returns a parseable result naming its job rather
+    // than dying mid-poll. See waitFlagMinutes.
+    const waitMinutes = waitFlagMinutes(timeoutMs);
+    const args = [
+        "project",
+        "deploy",
+        "start",
+        ...(dryRun ? ["--dry-run"] : []),
+        "-o",
+        targetOrg,
+        ...(waitMinutes ? ["--wait", String(waitMinutes)] : []),
+        "--json"
+    ];
+    // Captured BEFORE the spawn: it is what distinguishes this call's cache entry from a concurrent
+    // wave's, and it has to predate anything the CLI could have written.
+    const startedAtMs = Date.now();
+    const run = await runProcess("sf", args, { env: sfCliEnv(), cwd: projectDir, timeoutMs });
+    if (!run.timedOut)
+        return parseDeployOutput(run.stdout, run.stderr);
+    if (!recover)
+        return { status: "TIMED_OUT", failures: [], timedOut: true };
+    return await recoverTimedOutDeploy(projectDir, targetOrg, startedAtMs, timeoutMs, recover.notes);
+}
+/**
+ * Turn a killed watcher into a determinate answer, or say honestly that it could not.
+ *
+ * Best-effort at every step, and every failure lands back on the OLD behaviour (`TIMED_OUT` →
+ * `AMBIGUOUS_DELIVERY`), because the thing being recovered from is already the ambiguous case. What
+ * it must never do is manufacture certainty: a job we cannot identify, cannot report on, or cannot
+ * stop leaves the wave exactly as ambiguous as it was, with a note saying which.
+ */
+async function recoverTimedOutDeploy(projectDir, targetOrg, startedAtMs, timeoutMs, notes) {
+    const jobId = selectOwnJobId(await readDeployCache(), targetOrg, startedAtMs);
+    if (!jobId) {
+        notes.push("deploy killed at timeout and the job id could NOT be recovered from the sf deploy cache — the Salesforce job may still be running and still writing. The post-projection below is the authority; nothing here was cancelled.");
+        return { status: "TIMED_OUT", failures: [], timedOut: true };
+    }
+    // Bounded: this runs AFTER we already spent the full deploy timeout, so it gets a fraction rather
+    // than another full budget. A report that cannot answer inside it is the same answer as no report.
+    const reportTimeout = Math.max(30_000, Math.floor(timeoutMs / 4));
+    const reported = await sfDeployReport(projectDir, targetOrg, jobId, reportTimeout);
+    if (!reported.timedOut && !deployStillRunning(reported) && reported.status !== "UNPARSEABLE") {
+        notes.push(`deploy watcher was killed at timeout, but the Salesforce job (${jobId}) was recovered from the sf deploy cache and reported ${reported.status} — this verdict is the ORG's answer, not a guess. The kill destroyed our watcher, never the job.`);
+        return reported;
+    }
+    // Still running (or unanswerable). This is the case where the mutation window below is knowably
+    // wrong: it will stamp itself shut while the job keeps writing. Stop the job so it cannot.
+    if (deployStillRunning(reported)) {
+        const cancelled = await sfDeployCancel(projectDir, targetOrg, jobId, reportTimeout);
+        notes.push(cancelled.status === "Canceled" || cancelled.status === "Succeeded"
+            ? `deploy killed at timeout; the Salesforce job (${jobId}) was still running and has been CANCELLED, so it cannot keep writing after this call's mutation window closes. Salesforce rolls a cancelled deploy back (rollbackOnError), but the wave is AMBIGUOUS until the read-back below says otherwise.`
+            : `deploy killed at timeout; the Salesforce job (${jobId}) was still running and the cancel did NOT succeed (${cancelled.status}) — it may have reached Finalizing, in which case it is landing now. The job may still be writing AFTER this call's mutation window closes, so the change scan below cannot see everything it does.`);
+        return { status: "TIMED_OUT", failures: [], timedOut: true };
+    }
+    notes.push(`deploy killed at timeout; the Salesforce job (${jobId}) was found but could not be reported on (${reported.status}). Its outcome is unknown here — the post-projection below is the authority.`);
+    return { status: "TIMED_OUT", failures: [], timedOut: true };
+}
+export function parseDeployCache(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return [];
+        return Object.entries(parsed)
+            .filter(([jobId]) => /^0Af[A-Za-z0-9]{12,15}$/.test(jobId))
+            .map(([jobId, v]) => ({ jobId, targetOrg: v?.["target-org"], timestamp: v?.timestamp }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The job this call started, and NOT a concurrent wave's.
+ *
+ * The cache is global to `~/.sf` — not per-project and not per-org — which is exactly why
+ * `--use-most-recent` is banned everywhere in this file (survey §4): with two waves in flight it
+ * resolves to whichever finished writing last, and reporting on the wrong job is worse than
+ * reporting on none. So the caller passes the instant the deploy STARTED, and only an entry for this
+ * org stamped at or after that instant can be ours.
+ *
+ * Still not a proof of identity — two waves against the SAME org overlapping within one second would
+ * be indistinguishable — so the caller treats a recovered result as evidence, and any ambiguity
+ * keeps the ambiguous verdict.
+ */
+export function selectOwnJobId(entries, targetOrg, startedAtMs) {
+    const mine = entries
+        .filter((e) => e.targetOrg === targetOrg && e.timestamp)
+        .map((e) => ({ ...e, at: Date.parse(e.timestamp) }))
+        .filter((e) => Number.isFinite(e.at) && e.at >= startedAtMs - 1000)
+        .sort((a, b) => b.at - a.at);
+    return mine[0]?.jobId ?? null;
+}
+async function readDeployCache() {
+    try {
+        return parseDeployCache(await fs.readFile(path.join(os.homedir(), ".sf", "deploy-cache.json"), "utf8"));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Ask the org what actually happened to a deploy we stopped watching.
+ *
+ * `report --job-id` reaches the org; it is not a cache read. Two ordering constraints, both
+ * load-bearing:
+ *
+ *   - It must run BEFORE the `finally` that `fs.rm`s `projectDir`. When the cache entry is missing,
+ *     `report` falls back to `SfProject.resolve()` to build a ComponentSet for nicer output
+ *     (`report.js:88-96`), and a deleted temp project turns that into a confusing failure.
+ *   - `--job-id` ALWAYS, `--use-most-recent` NEVER. See selectOwnJobId.
+ *
+ * `--wait` makes it poll; without the flag it checks once and returns (help text, confirmed at
+ * `report.js:127`). We poll, because the whole point is to let a slow deploy finish.
+ */
+async function sfDeployReport(cwd, targetOrg, jobId, timeoutMs) {
+    const args = ["project", "deploy", "report", "--job-id", jobId, "--target-org", targetOrg, "--json"];
+    const waitMinutes = waitFlagMinutes(timeoutMs);
+    if (waitMinutes)
+        args.push("--wait", String(waitMinutes));
+    const run = await runProcess("sf", args, { env: sfCliEnv(), cwd, timeoutMs });
+    if (run.timedOut)
+        return { status: "TIMED_OUT", failures: [], timedOut: true };
+    return parseDeployOutput(run.stdout, run.stderr);
+}
+/**
+ * Write the edits into a temp SFDX project — the bytes Salesforce will actually be handed.
+ *
+ * EXTRACTED SO THERE IS EXACTLY ONE OF THESE. `validate_components` submits the analyzer's own
+ * files as a checkOnly, and the whole value of that call is that a clean result means the same
+ * thing the supervisor's later checkOnly will mean. Two copies of this staging would break that
+ * quietly: the same authored file could stage differently in the two paths — a container child
+ * grouped one way here and another way there, a namespace added on one side only — and the
+ * analyzer's green would stop predicting the wave's green while still looking like it did.
+ *
+ * The three shapes it has to get right are all here for that reason: content-file types write a
+ * meta and a body, decomposed children accumulate into ONE parent container file per path, and
+ * every XML root gets its namespaces bound (`ensureDeployableXml`).
+ *
+ * The caller owns the directory and must remove it.
+ */
+export async function stageDeployProject(edits, apiVersion) {
+    const projectDir = await fs.mkdtemp(path.join(os.tmpdir(), "cc-mcp-direct-"));
+    await fs.writeFile(path.join(projectDir, "sfdx-project.json"), JSON.stringify({ packageDirectories: [{ path: "force-app", default: true }], sourceApiVersion: apiVersion }), "utf8");
+    // Decomposed children accumulate into their parent container file, keyed by path.
+    const containers = new Map();
+    for (const edit of edits) {
+        const resolved = resolveSourcePath(edit);
+        if ("error" in resolved)
+            continue; // unreachable in runDirectApply: filtered above
+        if ("container" in resolved) {
+            const { containerPath, parentRoot, childElementName } = resolved.container;
+            const group = containers.get(containerPath) ?? { parentRoot, elements: [] };
+            group.elements.push(wrapChildElement(edit.xml, edit.typeName, childElementName));
+            containers.set(containerPath, group);
+            continue;
+        }
+        for (const file of resolved.files) {
+            const abs = path.join(projectDir, "force-app", "main", "default", file.relPath);
+            await fs.mkdir(path.dirname(abs), { recursive: true });
+            if (file.from === "xml") {
+                await fs.writeFile(abs, ensureDeployableXml(edit.xml), "utf8");
+            }
+            else {
+                // content file: written raw (utf8), or base64-decoded for binary static resources.
+                const buf = edit.contentEncoding === "base64" ? Buffer.from(edit.content ?? "", "base64") : edit.content ?? "";
+                await fs.writeFile(abs, buf);
+            }
+        }
+    }
+    // Emit one parent container file per group (all same-parent children together).
+    for (const [relPath, { parentRoot, elements }] of containers) {
+        const abs = path.join(projectDir, "force-app", "main", "default", relPath);
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        const doc = `<?xml version="1.0" encoding="UTF-8"?>\n<${parentRoot} ${XML_NS}>\n    ${elements.join("\n    ")}\n</${parentRoot}>\n`;
+        await fs.writeFile(abs, doc, "utf8");
+    }
+    return projectDir;
+}
+/**
+ * Submit components to the org as a checkOnly deploy and report what it said. NOTHING ELSE.
+ *
+ * This is the apply loop's step 4 — the authoritative rejection tier — with every stage around it
+ * removed. No pre-projection, no post-projection, no diff, no evidence bundle, no mirror commit, no
+ * verdict. It exists so an ANALYZER can ask the org "would you accept this?" about the components
+ * its own plan.json owns, in parallel with fourteen other analyzers, during Ch.4 authoring rather
+ * than at Ch.7 deploy.
+ *
+ * IT MUTATES NOTHING, which is why it needs no write gate. `--dry-run` is a deploy-API option, and
+ * the measurement backing that claim is in `.audit/parallel-validation.md`: 26 concurrent validation
+ * deploys against a live org, 8 of them refused, left zero rows behind in `FieldDefinition`.
+ *
+ * FAILURES ARE VERBATIM. The whole point of moving refusal discovery earlier is that the analyzer
+ * gets Salesforce's own sentence — "length must be specified", "Cannot delete last filter" — while
+ * it is still holding the context that produced the file. Paraphrasing here would destroy the value
+ * of the call, so `problem` is passed through untouched.
+ */
+export async function validateComponents(args) {
+    const startedAt = Date.now();
+    const projectDir = await stageDeployProject(args.edits, args.apiVersion);
+    try {
+        const outcome = await sfDeploy(projectDir, args.targetOrg, true, args.timeoutMs ?? 300_000);
+        const failures = (Array.isArray(outcome.failures) ? outcome.failures : [])
+            .filter((f) => typeof f === "object" && f !== null)
+            .map((f) => ({
+            // A CLI ERROR envelope has no component at all (parseDeployOutput synthesizes
+            // `{name, message}`), and reporting that as a component named "undefined" would read as a
+            // refusal of something rather than as the org never answering about anything.
+            component: typeof f.fullName === "string" ? f.fullName : typeof f.name === "string" ? f.name : "(whole deploy)",
+            problem: typeof f.problem === "string" ? f.problem : typeof f.message === "string" ? f.message : JSON.stringify(f),
+            ...(typeof f.problemType === "string" ? { problemType: f.problemType } : {}),
+            ...(typeof f.lineNumber === "number" ? { line: f.lineNumber } : {}),
+            ...(typeof f.columnNumber === "number" ? { column: f.columnNumber } : {})
+        }));
+        return {
+            status: outcome.status,
+            // A TIMED_OUT run is NOT accepted and NOT refused — the org never answered. Reading it as
+            // either would be the "a check that was ATTEMPTED is not a check that ANSWERED" failure this
+            // codebase already refuses everywhere else.
+            accepted: outcome.status === "Succeeded",
+            failures,
+            timedOut: outcome.timedOut === true,
+            componentCount: args.edits.length,
+            durationMs: Date.now() - startedAt,
+            raw: outcome.raw ?? null
+        };
+    }
+    finally {
+        await fs.rm(projectDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Stop a deploy nobody is watching any more.
+ *
+ * Today an abandoned job keeps writing to the operator's org while `mutation-window.json` stamps
+ * itself shut — so the change scan asks "what moved between these timestamps" over a window that
+ * closed before the writing did, and a component the abandoned deploy lands afterwards is invisible
+ * to it. That is the one case where our window is knowably wrong.
+ *
+ * ONLY after `report` says the job is still running. Cancelling is itself a deploy operation with
+ * its own id and its own poll (`deploy.js:cancelDeploy`), and it fails once the deploy reaches
+ * Finalizing — a failed cancel leaves the wave ambiguous, which is what the caller already says.
+ */
+async function sfDeployCancel(cwd, targetOrg, jobId, timeoutMs) {
+    const args = ["project", "deploy", "cancel", "--job-id", jobId, "--target-org", targetOrg, "--json"];
+    const waitMinutes = waitFlagMinutes(timeoutMs);
+    if (waitMinutes)
+        args.push("--wait", String(waitMinutes));
+    const run = await runProcess("sf", args, { env: sfCliEnv(), cwd, timeoutMs });
+    if (run.timedOut)
+        return { status: "TIMED_OUT", failures: [], timedOut: true };
+    return parseDeployOutput(run.stdout, run.stderr);
+}
+/** Is this job still running — i.e. is there anything to cancel? Never cancel a finished deploy. */
+export function deployStillRunning(outcome) {
+    return /^(Pending|InProgress|Canceling)$/i.test(outcome.status);
+}
+/**
+ * May this wave skip its checkOnly and submit once?
+ *
+ * THE CORPUS MAKES THE CASE. Across 121 recorded applies: 13 waves had a failing dry run, which
+ * correctly stopped them, and ZERO had a real deploy fail after a clean one. Every real deploy ran
+ * with `rollbackOnError: true` (confirmed in all 86 `deploy.json` raws), so a rejected deploy is
+ * already atomic — nothing partial lands. On that evidence the checkOnly is buying a nicer error
+ * SURFACE, not safety, at a measured median 9.3s / p90 19.3s per wave.
+ *
+ * WHAT THE CORPUS DOES NOT SAY is what happens on the runs nobody has made yet, and "13 waves were
+ * stopped by the dry run" is the number that argues for keeping it: those 13 got their failure from
+ * a submission that could not have written anything, which is a materially calmer thing to hand a
+ * non-technical operator than a real deploy's rejection. So this is OFF unless an env var turns it
+ * on, and the note it pushes says exactly what was given up.
+ *
+ * THREE HARD GATES, none of them env-overridable:
+ *
+ *   - DELETES keep their checkOnly unconditionally. A destructive checkOnly is not a rehearsal, it
+ *     is the only way to get PER-MEMBER outcomes (blocked by a live reference, with the referrer
+ *     named) — `destructive.ts` exists for that payload, and a real destructive deploy destroys
+ *     things while answering the same question.
+ *   - FACET UPDATES keep it. They go through a CRUD read-modify-write with no validation step of
+ *     their own, so the file half's dry run is the only pre-flight the wave has.
+ *   - `dryRunOnly` keeps it, obviously and structurally: the dry run IS the deliverable there, and a
+ *     skip would return VALIDATED having submitted nothing anywhere.
+ */
+export function checkOnlyIsSkippable(wave, env) {
+    if (env.CC_MCP_SKIP_CHECKONLY !== "1")
+        return false;
+    if (wave.dryRunOnly)
+        return false;
+    if (wave.edits.length === 0)
+        return false;
+    return wave.deletes.length === 0 && wave.facetUpdates.length === 0;
+}
+/**
+ * `--wait`, in minutes, aligned JUST UNDER our own SIGKILL — or `null` when there is no room.
+ *
+ * We passed no `--wait` at all, so the CLI used its 33-minute default against our 300s kill: the CLI
+ * was willing to watch 6.6x longer than we let it live, which made OUR kill the binding constraint
+ * and guaranteed the loss was a SIGKILL mid-poll rather than a parseable result naming its job.
+ * Landing a minute under the kill lets the CLI give up first and return that result.
+ *
+ * `min: 1` on the flag (`start.js:139`), and the tests run a 1000ms timeout — so anything that
+ * cannot fit a whole minute under the kill omits the flag entirely rather than asking for a wait
+ * longer than the process will live.
+ */
+export function waitFlagMinutes(timeoutMs) {
+    const minutes = Math.floor(timeoutMs / 60_000) - 1;
+    return minutes >= 1 ? minutes : null;
+}
+/**
+ * Submit a destructiveChanges.xml package — as a practice run (`dryRun`) or for real.
+ *
+ * `--metadata-dir` takes `--dry-run` just as a source deploy does, which is what makes a delete
+ * checkable at all. Both modes go through here so the two cannot drift apart: measured on T-Pinto,
+ * the identical package with and without `--dry-run` returned byte-identical failure payloads, and
+ * that equivalence is only worth anything while the same package builder feeds both.
+ *
+ * `--ignore-warnings` is NEVER passed, and this is load-bearing rather than an omission. A
+ * destructive member that does not exist in the org is reported as a WARNING, and with warnings
+ * ignored the org returns `Succeeded` with the missing member erased from the response entirely —
+ * no failure, no warning, nothing. Default flags are what make a typo'd member name fail loudly.
+ */
+async function sfDestructiveDeploy(deletes, targetOrg, apiVersion, dryRun, timeoutMs, cwd) {
+    const mdapiDir = await fs.mkdtemp(path.join(os.tmpdir(), "cc-mcp-direct-del-"));
+    try {
+        await fs.writeFile(path.join(mdapiDir, "destructiveChanges.xml"), destructivePackageXml(deletes), "utf8");
+        await fs.writeFile(path.join(mdapiDir, "package.xml"), emptyPackageXml(apiVersion), "utf8");
+        const args = [
+            "project",
+            "deploy",
+            "start",
+            "--metadata-dir",
+            mdapiDir,
+            ...(dryRun ? ["--dry-run"] : []),
+            "-o",
+            targetOrg,
+            "--json"
+        ];
+        const run = await runProcess("sf", args, { env: sfCliEnv(), cwd, timeoutMs });
+        if (run.timedOut)
+            return { status: "TIMED_OUT", failures: [], timedOut: true };
+        return parseDeployOutput(run.stdout, run.stderr);
+    }
+    finally {
+        await fs.rm(mdapiDir, { recursive: true, force: true });
+    }
+}
+// A read-back failure AFTER the mutations landed (deploy/deletes/facets already ran) must
+// NOT discard them. This is the same contract as a deploy timeout — AMBIGUOUS_DELIVERY, not
+// an INTERNAL_ERROR that throws away a successful deploy. Live-caught (6.5.1 run, 2026-07-24):
+// a `fetch failed` on the post-projection read crashed a QuickAction deploy that had in fact
+// LANDED (id 0Aff…). The operator re-projects to confirm rather than blind-re-applying.
+export function ambiguousReadbackResult(args) {
+    const msg = args.error instanceof Error ? args.error.message : String(args.error);
+    return {
+        verdict: "AMBIGUOUS_DELIVERY",
+        bundleDir: args.bundleDir,
+        lint: args.lint,
+        ...(args.deploy ? { deploy: args.deploy } : {}),
+        ...(args.deletes?.length ? { deletes: args.deletes } : {}),
+        ...(args.facetUpdates?.length ? { facetUpdates: args.facetUpdates } : {}),
+        notes: [
+            ...args.priorNotes,
+            `post-deploy read-back FAILED (${msg}) — the deploy/mutations above may have LANDED; verdict is AMBIGUOUS_DELIVERY, not a failure. Re-project the scope (project_org) to confirm final state before any re-apply — a blind re-create of a landed component hits the anti-tamper refusal.`
+        ]
+    };
+}
+/**
+ * Materialize the wave into its org's mirror, then finish the result and persist it.
+ *
+ * A POST-VERDICT SIDE EFFECT in the strict sense: the verdict is already decided and already on
+ * disk before this runs, and nothing here can change it. Three independent things keep it that way,
+ * and the redundancy is deliberate because the failure is silent in every direction:
+ *
+ *   1. It is only ever called from the two paths that reach a verdict AFTER the deploy.
+ *   2. `dryRunOnly` returns immediately — a practice run mutated nothing, so there is nothing to
+ *      record. (Step 4c already returns before this point; this is the second lock on that door,
+ *      in the spirit of the structural guard the dryRunOnly fix installed there.)
+ *   3. `readWaveFromBundle` yields nothing for a verdict that did not change the org, so
+ *      LINT_BLOCKED / REJECTED_BY_ORG / VALIDATED cannot commit even if a future caller forgets.
+ *
+ * And it reads the wave back OUT OF THE BUNDLE rather than from the variables in scope, which is
+ * why verdict.json is written more than once. A rebuild on another machine has only the bundle; if
+ * the live commit were assembled from richer in-memory state, the two would materialize differently
+ * and the divergence would surface as mismatched SHAs long after the wave that caused it. Same
+ * reader, same commit, by construction.
+ *
+ * The wave's provenance parcel (U6) rides the same seam and goes LAST, so what ships is the finished
+ * bundle rather than one revision of it.
+ */
+async function recordInMirror(result, opts) {
+    await writeJson(opts.bundleDir, "verdict.json", result);
+    // The wave, once, for both side effects. Null keeps the parcel step from running for a verdict
+    // that changed nothing or a bundle with no org id — the same gate the mirror commit sits behind.
+    let parcelFor = null;
+    if (!opts.dryRunOnly && isStateChanging(result.verdict)) {
+        let read = null;
+        try {
+            read = await readWaveFromBundle(opts.bundleDir);
+            if (!read) {
+                result.notes.push("org history NOT recorded for this wave — the projection carries no org id to key the mirror by. The delivery is unaffected; the evidence bundle is intact and a later rebuild will pick this wave up once the id is present. No provenance parcel was queued for it either, for the same reason.");
+            }
+            else {
+                const outcome = await overlayAndCommit({ wave: read.wave, preComponents: read.preComponents });
+                result.mirror = {
+                    committed: outcome.committed,
+                    ...(outcome.sha ? { sha: outcome.sha } : {}),
+                    ...(outcome.drifted.length ? { drifted: outcome.drifted } : {}),
+                    ...(outcome.attributed.length ? { attributed: outcome.attributed } : {}),
+                    ...(outcome.incomparable.length ? { incomparable: outcome.incomparable } : {})
+                };
+                for (const entry of outcome.incomparable) {
+                    // NOT a drift card and NOT a clean bill. The mirror's copy and this wave's pre-image came
+                    // out of different readers, so the difference between them is a fact about OUR code, not
+                    // about the org — and an accusation built on it would be false. Reported in full, with
+                    // the facets that actually differ, because the one thing this must never become is a
+                    // silent skip: a genuine outside edit in this window is invisible to the comparison, and
+                    // saying so is the only honest position available.
+                    const cause = entry.reason === "READER_CHANGED"
+                        ? `this machine recorded it with the "${entry.recorded}" reader and read it this time with "${entry.observed}"`
+                        : `the reader reported it could not read ${(entry.facets ?? []).join(", ")} on this pass`;
+                    result.notes.push(`NOT COMPARABLE, so NOT evidence either way — ${entry.key}. ` +
+                        `Its recorded shape could not be checked against this wave's pre-image: ${cause}. ` +
+                        `The facet(s) that differ: ${entry.differingKeys.join(", ") || "none outside the reader's own fields"}. ` +
+                        `An outside edit to this component before the wave would be indistinguishable from the reader change here, so no claim is made in either direction — this is NOT a clean result. ` +
+                        `It self-corrects: this wave records the component under the current reader, so the next comparison is a real one.`);
+                }
+                for (const entry of outcome.attributed) {
+                    // NOT a drift card. The mirror's copy of the container was stale because THIS install
+                    // delivered its children — children ride inside a CustomObject's read-back but are
+                    // recorded as their own components, so the parent's file was never refreshed. Reported
+                    // because a silent correction is still a correction, and the operator should be able to
+                    // see that the system knew the difference.
+                    result.notes.push(`STALE PARENT IN THIS MACHINE'S OWN RECORD, not an outside change — ${entry.key}. ` +
+                        `Its recorded shape predates this install's own delivery of ${entry.children.join(", ")} ` +
+                        `(${entry.waves.join(", ")}), which ride inside the object's read-back but are recorded separately. ` +
+                        `Every difference was accounted for by those deliveries; one that was not would have been carded. ` +
+                        `Nothing to ask the operator. Edits to those children themselves are checked against their own records, not this one.`);
+                }
+                if (outcome.drifted.length > 0) {
+                    result.notes.push(`CHANGED OUTSIDE THIS MACHINE'S HISTORY — ${outcome.drifted.join(", ")}. ` +
+                        `Before this wave ran, ${outcome.drifted.length === 1 ? "that component did" : "those components did"} not match what this machine last recorded after IN2 touched ${outcome.drifted.length === 1 ? "it" : "them"}. ` +
+                        `A client admin editing in Setup and another machine's wave that has not synced here look IDENTICAL from this side — this install now ships its own parcels, but nothing fetches another machine's yet, so this history still covers only what THIS install delivered, and the claim stops there. ` +
+                        `A warning, never a refusal: the wave proceeded. Check that it did not overwrite an edit someone else meant to keep.`);
+                }
+            }
+        }
+        catch (error) {
+            // R4: a mirror that cannot write must never fail, delay or mask a delivery that landed.
+            const message = error instanceof Error ? error.message : String(error);
+            result.mirror = { committed: false, error: message };
+            result.notes.push(`org history NOT recorded for this wave (${message}) — the delivery itself is unaffected and its evidence bundle is complete. The mirror is a rebuildable cache: this wave rejoins history on the next rebuild.`);
+        }
+        parcelFor = read;
+    }
+    result.operatorSummary = operatorSummaryFor(result);
+    await writeJson(opts.bundleDir, "verdict.json", result);
+    // The provenance parcel (R7), built LAST and from the bundle on disk.
+    //
+    // Ordering is the point. The parcel tars the directory, so anything written after it would ship a
+    // bundle that is a revision behind the one a rebuild reads — the mirror outcome, the drift note
+    // and the operator summary all land in the write immediately above. The only thing the shipped
+    // copy cannot carry is `result.parcel` itself, which is a statement about the parcel and could
+    // not be inside it; that is what the third write below records locally.
+    //
+    // Deliberately OUTSIDE the mirror's try as well: a mirror that could not commit says nothing
+    // about whether this bundle can ship, and folding the two would let a git failure report itself
+    // as a parcel failure. The network flush is fire-and-forget and runs again before the process
+    // exits, so nothing here can delay a delivery that already landed.
+    if (parcelFor) {
+        // The try is redundant with `queueWaveParcel`'s own no-throw contract, and kept for the reason
+        // the mirror keeps its three locks: the org has already been changed by the time this line
+        // runs, so "the callee promises not to throw" is not good enough to bet a landed delivery on.
+        try {
+            const queued = await queueWaveParcel({
+                bundleDir: opts.bundleDir,
+                orgId: parcelFor.wave.orgId,
+                orgAlias: opts.targetOrg,
+                verdict: result.verdict,
+                attempt: parcelFor.wave.attempt,
+                ...(parcelFor.wave.batchId ? { batchId: parcelFor.wave.batchId } : {})
+            });
+            result.parcel = {
+                queued: queued.queued,
+                ...(queued.bytes !== undefined ? { bytes: queued.bytes } : {}),
+                ...(queued.suppressed ? { suppressed: true } : {}),
+                ...(queued.reason ? { error: queued.reason } : {})
+            };
+            if (queued.queued)
+                void flushParcels().catch(() => undefined);
+        }
+        catch (error) {
+            result.parcel = { queued: false, error: error instanceof Error ? error.message : String(error) };
+        }
+        await writeJson(opts.bundleDir, "verdict.json", result);
+    }
+    return result;
+}
+export async function runDirectApply(opts) {
+    const notes = [];
+    // The org-call meter measures ONE WAVE, so it is cleared at the wave's entry rather than at
+    // process start. One server serves one session's waves serially, which is what makes a
+    // process-global meter a per-wave reading — see core/orgCallMeter.ts.
+    resetOrgCallMeter();
+    const deployTimeout = opts.deployTimeoutMs ?? 300_000;
+    const editKeys = new Set(opts.edits.map((e) => `${e.typeName}:${e.fullName}`));
+    const deleteKeys = new Set(opts.deletes.map((d) => `${d.typeName}:${d.fullName}`));
+    for (const fu of opts.facetUpdates) {
+        const banned = Object.keys(fu.facets).filter((k) => ["fields", "listViews", "compactLayouts", "validationRules", "recordTypes", "fullName"].includes(k));
+        if (banned.length)
+            throw new Error(`objectFacetUpdates carries child collections (${banned.join(", ")}) — use components/deletes for children.`);
+    }
+    const refusals = [];
+    for (const item of opts.edits) {
+        const r = resolveSourcePath(item);
+        if ("error" in r)
+            refusals.push(r.error);
+    }
+    for (const del of opts.deletes) {
+        // deletes carry no xml/content; resolve on typeName/fullName alone.
+        const r = resolveSourcePath({ typeName: del.typeName, fullName: del.fullName, xml: "" });
+        if ("error" in r && !/content-file type/.test(r.error))
+            refusals.push(r.error);
+    }
+    if (refusals.length > 0) {
+        throw new Error(`Unsupported metadata type(s) for the direct tier:\n- ${[...new Set(refusals)].join("\n- ")}`);
+    }
+    // Per-key revision facts, matched to the edits by component key. Built once — the drop guard, the
+    // static preview and `request.json` all read the same map, so they cannot disagree about which
+    // state of a component this wave is deploying.
+    const revisionByKey = new Map((opts.revisions ?? []).map((r) => [`${r.typeName}:${r.fullName}`, r]));
+    // INTENT PER EDIT, and additive on purpose. `request.json` is the only artifact in the bundle that
+    // states what a wave MEANT to do, and until now it could not distinguish "bring this component into
+    // being" from "change what is already there" — the Campfire writeback had to infer ownership from
+    // which requirement got there first (`campfire/deriveFromBundle.ts`), and the mirror had no way to
+    // read it at all.
+    //
+    // Written as one more field on each edit rather than as a parallel structure, so every existing
+    // reader keeps working untouched: `orgRepo.touchedKeys`, `waveGrade.readRequest`,
+    // `batchReport` and `deriveFromBundle` all pick named fields off these objects and ignore the rest.
+    // Bundles written before today carry no `intent`, and every one of them still parses.
+    await writeJson(opts.bundleDir, "request.json", {
+        targetOrg: opts.targetOrg,
+        apiVersion: opts.apiVersion,
+        edits: opts.edits.map((edit) => {
+            const revision = revisionByKey.get(`${edit.typeName}:${edit.fullName}`);
+            return revision?.intent ? { ...edit, intent: revision.intent } : edit;
+        }),
+        ...(opts.revisions?.length ? { revisions: opts.revisions } : {}),
+        deletes: opts.deletes,
+        facetUpdates: opts.facetUpdates,
+        acks: opts.acks,
+        ...(opts.ackInline ? { ackInline: true } : {}),
+        ...(opts.batchId ? { batchId: opts.batchId } : {}),
+        ...(opts.requirementIds?.length ? { requirementIds: opts.requirementIds } : {}),
+        ...(opts.operator ? { operator: opts.operator } : {}),
+        ...(opts.revertOf ? { revertOf: opts.revertOf } : {}),
+        dryRunOnly: opts.dryRunOnly
+    });
+    // 1. Pre-projection. `scope` is a `let` because the post-projection below closes over the same
+    // binding — pre and post MUST project the identical scope or the three-way diff compares
+    // different worlds.
+    //
+    // NARROW BY DEFAULT (plan -002): exactly the touched components, not their parent objects. The
+    // object expansion read 4.6 components for every one touched and found one side change in 70
+    // bundles.
+    //
+    // The referential lint DOES depend on breadth, and this narrowing broke it before the dependency
+    // was made real. The justification written here originally claimed the session union already read
+    // the session's project_org runs; it did not — it read wave post-images only, which this change
+    // had just shrunk to the touched set. CF63 w4 paid for it: a clean `direct_lint
+    // {projection: "ground"}` followed by REF_UNKNOWN at apply on the same files. Breadth now comes
+    // from `collectSessionProjection` below, which unions org-projection/<org>/* as well, so the
+    // claim above is true rather than assumed.
+    const facetObjects = opts.facetUpdates.map((fu) => fu.objectApiName);
+    let scope = opts.wideObjectScope
+        ? deriveScope(opts.edits, opts.deletes)
+        : narrowScope(opts.edits, opts.deletes, facetObjects);
+    if (opts.wideObjectScope) {
+        for (const obj of facetObjects) {
+            scope.objects = [...new Set([...(scope.objects ?? []), obj])].sort();
+        }
+    }
+    // PRECEDENT IS SKIPPED UNLESS THIS WAVE COULD CONSUME IT, and this is the one caller that gets to
+    // decide that (see RunProjectionOptions.skipPrecedent; `project_org` keeps sampling
+    // unconditionally, which is where the vocabulary actually comes from).
+    //
+    // Measured: the sweep contributed 1,296 of 1,977 pre-projection component reads across the corpus
+    // — 66%, on a median of 3 touched components per wave — and an apply pays for it TWICE because
+    // the post projection re-reads the identical scope. 90 of 115 recorded waves touched no
+    // FlexiPage or CustomTab at all, so 90 waves bought ~24 extra reads on each side of their deploy
+    // to feed a lint tier that keys on the EDIT'S typeName and therefore could not have matched them.
+    //
+    // Keyed on the type alone rather than on whether the XML carries <motif>/<componentName>: the
+    // element scan would be a second implementation of what runLint already walks, and on this corpus
+    // the two gates select the identical 25 waves. Type is the coarser, cheaper, and more honest one —
+    // a FlexiPage wave that grows an org-enforced element later keeps its precedent without anyone
+    // remembering to update a predicate here.
+    //
+    // BOTH SIDES OR NEITHER. The post projection must resolve the SAME scope as the pre — the
+    // three-way diff pairs them by key, so precedent present on one side and absent on the other would
+    // surface all ~24 samples as `diff.removed` and land them in `sideChanges` on every single wave,
+    // turning a saving into a false drift report. It also matters after the call: a wave's post image
+    // is what `collectSessionProjection` grounds later waves against, so dropping precedent from the
+    // post alone would quietly narrow the vocabulary the NEXT wave's lint sees.
+    const needsPrecedent = opts.edits.some((edit) => PRECEDENT_TYPE_NAMES.has(edit.typeName));
+    const skipPrecedent = !needsPrecedent;
+    const preDir = path.join(opts.bundleDir, "pre");
+    // Phased for the meter: a projection is TENS of jsforce round-trips (batched ten-per-call, five
+    // in flight), which is where a wave's org time actually goes — against three sf spawns for the
+    // whole tier. Attributing them is the difference between a measurement and a guess.
+    const projectPre = () => orgCallPhase("preProjection", () => runProjection(opts.reader, {
+        scope,
+        outDir: preDir,
+        orgAlias: opts.targetOrg,
+        apiVersion: opts.apiVersion,
+        label: "pre",
+        skipPrecedent
+    }));
+    let pre;
+    try {
+        pre = await projectPre();
+    }
+    catch (error) {
+        if (!(error instanceof ScopeTooLargeError))
+            throw error;
+        // Only reachable with wideObjectScope: the narrow scope names its components, so it cannot
+        // overflow. Parent-object expansion can (a large standard object resolves to hundreds of
+        // components). Fall back to exactly the touched components — the cap exists to stop accidental
+        // breadth, and a bundle that names its components is not accidental. The refusal happens before
+        // any snapshot writes, so retrying into the same preDir is clean.
+        scope = narrowScope(opts.edits, opts.deletes, facetObjects);
+        pre = await projectPre();
+        notes.push(`pre/post projection narrowed to the ${scope.components?.length ?? 0} touched component(s): the full-object scope resolves to ${error.total} components (cap ${error.limit}). Verification of everything this bundle changes is unaffected; sibling side-change detection on the parent object(s) is off for this bundle.`);
+    }
+    // 1b. Deployable pre-image for every touched existing component (plan 2026-07-29-002, widened by
+    // 2026-08-02-002 U1). The canonical JSON under pre/ is the COMPARISON substrate; this is the
+    // DEPLOYABLE one — the bytes an author edits to carry content forward, and the bytes a rollback
+    // redeploys to put a component back. Fail-open by contract: a failed retrieve costs a note and
+    // never touches the verdict.
+    const preImages = preImageTargets(opts.edits, opts.deletes, facetObjects, pre.manifest);
+    if (preImages.length > 0) {
+        const sourceDir = path.join(preDir, "source");
+        const outcome = await orgCallPhase("preImageRetrieve", () => retrievePreImageSource(preImages, opts.targetOrg, opts.apiVersion, sourceDir));
+        if (!outcome.ok) {
+            notes.push(`pre-image source retrieve failed (${outcome.error}) — fall back to the JSON snapshots under pre/; verification is unaffected, but this wave has NO deployable rollback image`);
+        }
+        else {
+            notes.push(`deployable pre-image source for ${outcome.retrieved} touched component(s) at ${sourceDir} — when carrying existing content forward, edit THAT file rather than transcribing the JSON snapshot; it is also what a rollback would redeploy`);
+            // A partial retrieve is not a failure of the wave, but "there is a rollback image" is now true
+            // of some components and false of others — and only the note can say which.
+            if (outcome.missing.length > 0) {
+                notes.push(`pre-image source is INCOMPLETE — the org returned no source for ${outcome.missing
+                    .map((m) => `${m.typeName}:${m.fullName}`)
+                    .join(", ")}. Those component(s) have NO deployable rollback image; the rest do.`);
+            }
+        }
+    }
+    // 2. Lint, grounded the SAME way direct_lint grounds by default: every projection this session
+    // holds of the target org, freshest observation per component, with this wave's own
+    // pre-projection applied last as the newest read there is. One grounding path for both tiers is
+    // the point — CF63 w4 was apply and lint unioning different sources and disagreeing about what
+    // exists on identical input, and CF79 w2 was apply-time lint warning "no precedent — widen the
+    // projection" at a session that had already widened it.
+    // The bundle sits at <session>/direct/<wave>, so the session root is two levels up.
+    const sessionRoot = path.resolve(opts.bundleDir, "..", "..");
+    const grounding = await collectSessionProjection(sessionRoot, opts.targetOrg, [{ dir: preDir, manifest: pre.manifest }]);
+    const lint = runLint(opts.edits, viewKnownTokens(grounding), opts.acks, await viewProvenValues(grounding), opts.plannedTokens ?? null);
+    // 2-ref. THE REFERENTIAL TIER'S ORG HALF (QA round 1, item 10). The lint just classified every
+    // unknown reference against projections and the batch plan — both of which are somebody's chosen
+    // scope, not the org. Before an unknown decides anything, ask the org itself: a token it proves
+    // PRESENT was only ever outside the projection (CF72's false positives) and stops being a
+    // finding; one it proves ABSENT is a typo or a wrong relationship name about to deploy broken,
+    // and that blocks (ackable). Every failure to answer fails OPEN to the pre-existing warning.
+    // A planned-but-unlanded dependency needs no org read — the plan already explains it — but on a
+    // REAL deploy it means the creator has not run, so it escalates the same way.
+    {
+        const flagged = referentialTokens(lint);
+        if (flagged.length > 0) {
+            const verification = await orgCallPhase("refVerify", () => verifyRefsAgainstOrg(flagged, candidateObjects(opts.edits, grounding.objects), opts.reader));
+            notes.push(...applyRefVerification(lint, verification, opts.acks).notes);
+        }
+        if (!opts.dryRunOnly)
+            escalatePendingDependencies(lint, opts.acks);
+    }
+    // 2a. THE STATIC DROP PREVIEW, over the earlier authored files this batch holds.
+    //
+    // Scoped to components the org does NOT already have, and that is the whole rule: once the earlier
+    // state has landed, 2b below compares against the ORG rather than against a file, which is strictly
+    // better evidence about the same question. Running both would report one omission twice, under two
+    // rule names, with the weaker one arriving first.
+    //
+    // So this covers exactly the window 2b cannot: a wave whose predecessor has not been deployed yet
+    // (an out-of-order apply, a `dryRunOnly` rehearsal of the whole ladder, or simply the first look at
+    // a batch), where the org has nothing to compare against and the batch does.
+    const preFound = new Set(pre.manifest.components.filter((c) => c.found).map((c) => `${c.typeName}:${c.fullName}`));
+    lint.findings.push(...previewPredecessorDrops(opts.edits, await loadPredecessorPreImages((opts.revisions ?? []).filter((r) => !preFound.has(`${r.typeName}:${r.fullName}`)))));
+    // 2a-ii. The destructive path's one static warning. Deletes never reach `runLint` — it takes
+    // authored FILES, and a delete has none — so this is the only place before the org round-trip
+    // where a delete member can be looked at at all.
+    lint.findings.push(...listViewDeleteWarnings(opts.deletes));
+    // 2b. PRE-FLIGHT full-file-replace check.
+    //
+    // `removals` already catches this — but AFTER the deploy, which for a first replace is after the
+    // content is gone. CF76 authored a Layout that omitted CurrencyIsoCode on a multi-currency org,
+    // next to a Currency field; nothing in the toolchain would have caught it, and it was found only
+    // because the supervisor hand-diffed the org image against the authored file — a step that appears
+    // nowhere in the skill.
+    //
+    // The pre-image is already on disk by now, so the same comparison runs BEFORE the deploy. It is
+    // noisier than the post-deploy one by construction: that compares two org read-backs, this
+    // compares an org read-back against parsed intent, so the org's materialized defaults can look
+    // like losses. Hence the split the removals module already draws — UNSTATED removals (a facet the
+    // author never mentioned, about to be wiped) block and are ackable; STATED ones, where the
+    // author's own replacement carries less, only warn.
+    // 2b-i. The drop check's own precondition: a pre-image with a facet the read path could NOT
+    // answer for cannot support "nothing else would be lost". Raised BEFORE the drop findings so the
+    // reader sees the caveat before the clean-looking list it qualifies.
+    for (const risk of incompleteFacetRisks(opts.edits, pre.manifest)) {
+        const acked = opts.acks.includes("PREFLIGHT_PREIMAGE_FACET_INCOMPLETE");
+        const blocks = risk.proven && !acked;
+        lint.findings.push({
+            rule: "PREFLIGHT_PREIMAGE_FACET_INCOMPLETE",
+            severity: blocks ? "error" : "warning",
+            component: risk.component,
+            message: `The pre-image for this component is INCOMPLETE: the org read could not answer for ${risk.facets.join(", ")}. ` +
+                `${risk.reasons.join(" ")} ` +
+                `${risk.typeName} ${risk.proven ? "IS full-file replace (MEASURED on a live org)" : "may be full-file replace (SUSPECTED)"}, ` +
+                `so the org will keep only what your file carries — and the pre-flight drop check below CANNOT tell you whether this ` +
+                `file drops anything from ${risk.facets.join(", ")}, because that content is not in the image it compares against. ` +
+                `A clean drop report is therefore not evidence for ${risk.facets.join(", ")}. ` +
+                `Read the component's DEPLOYABLE source XML under ${path.join(preDir, "source")} — a retrieve, which does carry these ` +
+                `facets faithfully — and carry them forward. Ack PREFLIGHT_PREIMAGE_FACET_INCOMPLETE once you have.`,
+            ackable: true
+        });
+        if (blocks)
+            lint.blocked = true;
+    }
+    const preByKey = new Map(pre.manifest.components.map((c) => [`${c.typeName}:${c.fullName}`, c]));
+    for (const edit of opts.edits) {
+        // THE TYPE GATE, AND ITS BOUNDARY IS DELIBERATE. A declared `create` on a component that already
+        // exists is a hazard for EVERY type, but this loop is not where the general case belongs: a merge
+        // type keeps what the file omits, so there is nothing here to name, and the finding would be a
+        // claim about ownership rather than about content loss. `plan_waves` raises that one at plan time,
+        // against the session projection, before any org round-trip is spent (R7). What survives here is
+        // the replace-type SUBSET, where the create is also a wholesale overwrite of real content.
+        if (!FULL_FILE_REPLACE_TYPES.has(edit.typeName))
+            continue;
+        const entry = preByKey.get(`${edit.typeName}:${edit.fullName}`);
+        // Nothing in the org, so nothing to lose. EVIDENCE decides this, never the declared intent —
+        // which is the point of reading it here at all. The exclusion used to be justified as "a create
+        // cannot lose anything", and that sentence is true of a create the org agrees is new; a declared
+        // create whose component the org ALREADY HOLDS is precisely the case that must reach the check
+        // below, because it deploys a full-file replacement over content its author does not know is
+        // there. Symmetrically, a declared `update` the org does not hold still drops nothing.
+        if (!entry?.found)
+            continue;
+        // What the wave request said this file was for. Absent on inline corrections and hand-authored
+        // waves, and everything below degrades to the existing wording when it is.
+        const declaredCreate = revisionByKey.get(`${edit.typeName}:${edit.fullName}`)?.intent === "create";
+        const intent = normalizeIntent(edit.typeName, edit.xml);
+        if (!intent)
+            continue; // unparseable XML is already its own finding
+        const preSnap = await fs
+            .readFile(path.join(preDir, entry.file), "utf8")
+            .then((t) => JSON.parse(t))
+            .catch(() => null);
+        // A full-file replace keeps exactly what the file carries, so the authored intent IS the
+        // post-image for this purpose.
+        const wouldDrop = findRemovals(preSnap?.state.metadata ?? null, intent, intent).filter((r) => !isSourceFormatArtifact(r));
+        if (wouldDrop.length === 0)
+            continue;
+        const unstated = wouldDrop.filter((r) => !r.stated);
+        const rule = unstated.length > 0 ? "PREFLIGHT_REPLACE_DROPS_UNSTATED" : "PREFLIGHT_REPLACE_DROPS_STATED";
+        const acked = opts.acks.includes(rule);
+        const proven = PROVEN_REPLACE_TYPES.has(edit.typeName);
+        // Blocking only where the loss is MEASURED. On a proven type an unstated drop is a certainty,
+        // not a risk, so refusing is the accurate response; on a suspected one it is still a guess.
+        const blocks = proven && unstated.length > 0 && !acked;
+        lint.findings.push({
+            rule,
+            severity: blocks ? "error" : "warning",
+            component: `${edit.typeName}:${edit.fullName}`,
+            message: 
+            // TWO WORDINGS, ONE CHECK. The prose below was written for an EDIT — "already exists" is
+            // news to nobody who meant to change it, and "anything you did not mean to lose" assumes the
+            // author knew there was something there. Neither sentence fits a file whose plan entry says
+            // this component is being brought into being: that author believes the org has nothing, so
+            // the finding has to lead with the fact that it does, and the fix is a different one (declare
+            // the entry an update and author the complete desired state, rather than carry facets
+            // forward into a create that should not be a create).
+            (declaredCreate
+                ? `This wave declares ${edit.typeName}:${edit.fullName} as NEW, but the org ALREADY HAS it — and ` +
+                    `${edit.typeName} ${proven ? "IS full-file replace (MEASURED on a live org, not inferred)" : "may be full-file replace (SUSPECTED — never probed)"}, ` +
+                    "so this deploys over what is there rather than beside it. The org keeps only what this file carries, and it does not carry " +
+                    `${wouldDrop.length} thing(s)${unstated.length > 0 ? `, ${unstated.length} of them never mentioned in your file` : ""}:\n`
+                : `${edit.typeName} ${proven ? "IS full-file replace (MEASURED on a live org, not inferred)" : "may be full-file replace (SUSPECTED — never probed)"} and already exists: the org keeps only what this file carries. ` +
+                    `This deploy would drop ${wouldDrop.length} thing(s)${unstated.length > 0 ? `, ${unstated.length} of them never mentioned in your file` : ""}:\n`) +
+                renderRemovals(`${edit.typeName}:${edit.fullName}`, wouldDrop) +
+                `\n${proven ? "These WILL be gone." : "If the type does replace wholesale, these are gone."} ` +
+                (declaredCreate
+                    ? "Decide which is stale first: if the component is genuinely meant to CHANGE, give its plan.json entry " +
+                        'intent "update" and author its complete desired state; if the org copy is the stale one, this file has to ' +
+                        "carry everything worth keeping. "
+                    : "") +
+                `Re-read the pre-image under ${preDir} — ` +
+                `a DEPLOYABLE source-XML copy of the current component is under ${path.join(preDir, "source")} when the retrieve succeeded; edit that rather than transcribing JSON — ` +
+                `and carry forward anything you did not mean to lose. Ack ${rule} once you have checked.`,
+            ackable: true
+        });
+        if (blocks)
+            lint.blocked = true;
+    }
+    await writeJson(opts.bundleDir, "lint.json", lint);
+    if (lint.blocked) {
+        const result = { verdict: "LINT_BLOCKED", bundleDir: opts.bundleDir, lint, notes };
+        result.operatorSummary = operatorSummaryFor(result);
+        await writeJson(opts.bundleDir, "verdict.json", result);
+        return result;
+    }
+    // 3. Temp SFDX project
+    const projectDir = await stageDeployProject(opts.edits, opts.apiVersion);
+    try {
+        // 3b. Keep the EXACT tree that is about to be submitted. The temp project is deleted in the
+        // `finally` below, so until now the deployed bytes survived only inside request.json's `xml`
+        // strings — recoverable in principle, but not as files, and not at the paths Salesforce saw.
+        // The mirror overlays this directory as `source/` (plan 2026-08-02-002 U2), and a rollback
+        // redeploys from it. Written BEFORE the deploy so a rejected wave still shows what was sent.
+        // Bookkeeping: a failure here costs a note and never a deploy.
+        const deployTree = path.join(projectDir, "force-app", "main", "default");
+        try {
+            // CLEARED first, not merged into. A retry re-uses the same bundle directory (that is what
+            // makes `direct_lint {projection: "<label>"}` resolve), so a copy over the top would leave
+            // attempt 1's components sitting beside attempt 2's — and the mirror would then commit source
+            // XML for components this wave never deployed.
+            await fs.rm(path.join(opts.bundleDir, "deployed"), { recursive: true, force: true });
+            if (await fs.stat(deployTree).then((s) => s.isDirectory()).catch(() => false)) {
+                await fs.cp(deployTree, path.join(opts.bundleDir, "deployed"), { recursive: true });
+            }
+        }
+        catch (error) {
+            notes.push(`could not persist the deployed source tree into the bundle (${error instanceof Error ? error.message : String(error)}) — the deploy is unaffected; org history for this wave will carry no source XML`);
+        }
+        // 4. checkOnly — the authoritative rejection tier. Read-only server-side; retry once on timeout.
+        // Hoisted out of the block below so step 4c can report WHAT was validated: a wave with no file
+        // components reaches a dry-run result having had nothing checked at all, which is a different
+        // answer from a clean one.
+        //
+        // SKIPPABLE, OFF BY DEFAULT, AND ONLY FOR EDIT-ONLY WAVES — see checkOnlyIsSkippable. The
+        // corpus makes the safety case (0 real-deploy failures after a clean dry run in 121 applies,
+        // rollbackOnError:true on all 86) but says nothing about the case that has never been run, so
+        // this ships dark: `CC_MCP_SKIP_CHECKONLY=1` is the only way to take it, and a wave carrying
+        // deletes or facet updates keeps its checkOnly whatever the env says.
+        let validated;
+        const skipCheckOnly = checkOnlyIsSkippable(opts, process.env);
+        if (skipCheckOnly) {
+            notes.push("checkOnly SKIPPED (CC_MCP_SKIP_CHECKONLY=1, edit-only wave): the real deploy below is the only submission. Salesforce runs it with rollbackOnError, so a rejection is atomic — but its failures arrive from the deploy rather than from a practice run, and nothing validated this package before it was submitted for real.");
+        }
+        if (opts.edits.length > 0 && !skipCheckOnly) {
+            let dry = await orgCallPhase("checkOnly", () => sfDeploy(projectDir, opts.targetOrg, true, deployTimeout));
+            if (dry.timedOut) {
+                dry = await orgCallPhase("checkOnly", () => sfDeploy(projectDir, opts.targetOrg, true, deployTimeout));
+            }
+            await writeJson(opts.bundleDir, "dryrun.json", dry);
+            if (dry.status !== "Succeeded") {
+                const result = {
+                    verdict: "REJECTED_BY_ORG",
+                    bundleDir: opts.bundleDir,
+                    lint,
+                    dryRun: { status: dry.status, failures: dry.failures },
+                    notes
+                };
+                result.operatorSummary = operatorSummaryFor(result);
+                await writeJson(opts.bundleDir, "verdict.json", result);
+                return result;
+            }
+            validated = { status: dry.status, failures: [] };
+        }
+        // 4c. dryRunOnly stops HERE — outside the edits guard, which is where it belongs.
+        //
+        // It used to sit inside `if (opts.edits.length > 0)` above, so a wave carrying only deletes or
+        // only objectFacetUpdates fell straight past it and performed REAL WRITES on the option whose
+        // whole promise is "deploy nothing" (step 6b's comment said "skipped in dryRunOnly, which
+        // returned above" — true only when edits existed). Deletes are the worse half: a delete-only
+        // dry run destroyed components.
+        //
+        // The guard is structural rather than a condition repeated at each write site, because the next
+        // mutation step added to this loop would need the same one and the omission is silent.
+        if (opts.dryRunOnly) {
+            // DELETES ARE CHECKABLE. `--metadata-dir` accepts `--dry-run`, so the destructive package goes
+            // to the org as a real checkOnly and comes back with a per-member verdict: validated, blocked
+            // by a live reference (the org names the referrer), or not found. Nothing is destroyed — the
+            // measured proof is that a dry-run of a deletable field left the field in place, and that the
+            // same package with and without `--dry-run` produced identical failures.
+            //
+            // What is still unvalidatable is objectFacetUpdates, and only that: a CRUD read-modify-write
+            // has no practice mode at all. Those remain NOT VALIDATED, which is now a statement about one
+            // path rather than a blanket over two.
+            let destructiveRaw;
+            let destructive;
+            if (opts.deletes.length > 0) {
+                destructiveRaw = await orgCallPhase("destructiveCheckOnly", () => sfDestructiveDeploy(opts.deletes, opts.targetOrg, opts.apiVersion, true, deployTimeout, projectDir));
+                destructive = parseDestructiveResult(destructiveRaw, opts.deletes, "dry-run");
+                await writeJson(opts.bundleDir, "deletes.json", {
+                    mode: "dry-run",
+                    status: destructive.status,
+                    failed: destructive.failed,
+                    outcomes: destructive.outcomes,
+                    unattributed: destructive.unattributed,
+                    raw: destructiveRaw
+                });
+            }
+            const unvalidatedFacets = opts.facetUpdates.map((fu) => ({
+                object: fu.objectApiName,
+                status: "NOT VALIDATED — dryRunOnly. objectFacetUpdates go through a CRUD read-modify-write, which " +
+                    "Salesforce offers no validation step for, so nothing was submitted for this object and nothing " +
+                    "here says whether it would work. Drop dryRunOnly to apply it for real; the post-deploy read-back " +
+                    "is what verifies this path."
+            }));
+            // One status over both halves. A destructive package can come back `Succeeded` while a member
+            // inside it warned (that is what `--ignore-warnings` would produce, and the reason the warning
+            // is read directly), so this is derived from the per-member verdicts, never copied from either
+            // package's status field.
+            const deletesOk = !destructive || !destructive.failed;
+            const filesOk = !validated || validated.status === "Succeeded";
+            const dryRun = validated || destructiveRaw
+                ? {
+                    status: filesOk && deletesOk ? "Succeeded" : "Failed",
+                    failures: [...(validated?.failures ?? []), ...(destructiveRaw?.failures ?? [])],
+                    checked: [
+                        ...(validated ? ["files"] : []),
+                        ...(destructiveRaw ? ["deletes"] : [])
+                    ]
+                }
+                : undefined;
+            // A delete the org would refuse is a rejection, not a clean practice run — the same answer a
+            // refused file deploy gets. Returning VALIDATED here would put the word an operator quotes on
+            // top of a deletion Salesforce has already said it will not perform.
+            const result = {
+                verdict: destructive?.failed ? "REJECTED_BY_ORG" : "VALIDATED",
+                bundleDir: opts.bundleDir,
+                lint,
+                ...(dryRun ? { dryRun } : {}),
+                ...(destructive ? { deletes: destructive.outcomes } : {}),
+                ...(unvalidatedFacets.length ? { facetUpdates: unvalidatedFacets } : {}),
+                notes: [
+                    ...notes,
+                    "dryRunOnly — nothing deployed, nothing deleted",
+                    ...(destructive
+                        ? [
+                            `${destructive.outcomes.length} delete(s) submitted to Salesforce as a destructive checkOnly ` +
+                                `(package status ${destructive.status}); per-component verdicts are in the result and in ` +
+                                `deletes.json.`
+                        ]
+                        : []),
+                    ...(destructive?.packageNote ? [destructive.packageNote] : []),
+                    ...(unvalidatedFacets.length
+                        ? [
+                            `${unvalidatedFacets.length} object facet update(s) were NOT submitted anywhere: a CRUD ` +
+                                `read-modify-write has no validation step, so a clean result here proves nothing about them. ` +
+                                `They were also not applied — re-run without dryRunOnly and read the post-deploy verification.`
+                        ]
+                        : [])
+                ]
+            };
+            result.operatorSummary = operatorSummaryFor(result);
+            await writeJson(opts.bundleDir, "verdict.json", result);
+            return result;
+        }
+        // 4b. History-tracking BEFORE image. trackHistory is invisible to the Metadata API, so the
+        // pre-projection on disk cannot carry it and the pre/post comparison below cannot see it move.
+        // The Tooling API is the only surface that reports it, which makes this the one facet needing
+        // its own reading on each side of the deploy. Taken here, after the dry-run-only path has
+        // returned, so a validation costs nothing — and before the mutation window opens, so it is
+        // unambiguously the pre-image.
+        const preTrackedHistory = await orgCallPhase("historyProbe", () => probeFieldHistoryTracking(opts.reader, opts.edits));
+        // 5. Real deploy — never auto-retried, but no longer abandoned either.
+        //
+        // A timeout used to be the end of the story: `runProcess` SIGKILLs at `deployTimeoutMs` and we
+        // returned TIMED_OUT, which is AMBIGUOUS_DELIVERY and a re-projection by hand. The kill only ever
+        // destroyed OUR WATCHER — the Salesforce job kept running — and the CLI had already written that
+        // job's id to `~/.sf/deploy-cache.json` before it began polling. `sfDeploy(..., {notes})` now
+        // recovers it: report on the job, and cancel it if it is still writing. See sfDeploy and
+        // recoverTimedOutDeploy.
+        //
+        // The MUTATION WINDOW opens here. Everything before this point is read-only (the projection and
+        // the checkOnly validation), so this is the earliest instant at which the org can have changed
+        // because of us. It closes after the facet updates below — the last write this call makes.
+        // Recorded to the second and persisted, because the change scan (plan -002) asks the org "what
+        // moved between these two timestamps", and a window that is guessed after the fact is a window
+        // that either misses real changes or blames us for someone else's. That window is precisely what
+        // an ABANDONED deploy corrupts, which is why the recovery path cancels rather than merely
+        // reporting.
+        const mutationWindow = { start: new Date().toISOString(), end: "" };
+        let deploy;
+        if (opts.edits.length > 0) {
+            deploy = await orgCallPhase("deploy", () => sfDeploy(projectDir, opts.targetOrg, false, deployTimeout, { notes }));
+            await writeJson(opts.bundleDir, "deploy.json", deploy);
+            if (!deploy.timedOut && deploy.status !== "Succeeded") {
+                const result = {
+                    verdict: "REJECTED_BY_ORG",
+                    bundleDir: opts.bundleDir,
+                    lint,
+                    deploy: { status: deploy.status, id: deploy.id, failures: deploy.failures },
+                    notes: [
+                        ...notes,
+                        skipCheckOnly
+                            ? "deploy REJECTED, and this wave skipped its checkOnly (CC_MCP_SKIP_CHECKONLY=1) — so this rejection arrives from the real submission rather than from a practice run. Salesforce deployed with rollbackOnError, so nothing partial landed; the failures above are the org's, in the same shape a dry run would have given them."
+                            : "real deploy failed after a clean dry-run — org state may have moved between stages"
+                    ]
+                };
+                result.operatorSummary = operatorSummaryFor(result);
+                await writeJson(opts.bundleDir, "verdict.json", result);
+                return result;
+            }
+            // The recovery path already pushed the note that says WHICH kind of timeout this was — the job
+            // was cancelled, or it could not be identified, or it could not be reported on. A blanket line
+            // here would talk over the specific one.
+        }
+        // 6. Destructive deletes via an mdapi destructive deploy (no CRUD connection needed).
+        const deleteOutcomes = [];
+        if (opts.deletes.length > 0) {
+            const raw = await orgCallPhase("destructive", () => sfDestructiveDeploy(opts.deletes, opts.targetOrg, opts.apiVersion, false, deployTimeout, projectDir));
+            const status = raw.timedOut ? "TIMED_OUT (AMBIGUOUS — post-projection is the authority)" : raw.status;
+            for (const d of opts.deletes)
+                deleteOutcomes.push({ component: `${d.typeName}:${d.fullName}`, status });
+            await writeJson(opts.bundleDir, "deletes.json", { mode: "real", status, outcomes: deleteOutcomes, raw });
+        }
+        // 6b. Parent-object facet updates via CRUD read-modify-write (skipped in dryRunOnly,
+        // which returned above). Each is read-back verified by the post-projection intent stage.
+        const facetOutcomes = [];
+        if (opts.facetUpdates.length > 0) {
+            const { updateObjectFacets } = await import("./crud.js");
+            for (const fu of opts.facetUpdates) {
+                try {
+                    await orgCallPhase("facetUpdate", () => updateObjectFacets(opts.targetOrg, opts.apiVersion, fu.objectApiName, fu.facets));
+                    // SUBMITTED, not "updated". All that is known here is that the CRUD Metadata API answered
+                    // success:true, which acknowledges the REQUEST — Salesforce returns it for facets it
+                    // silently ignores. Live-caught CF63 w1: sharingModel reported success TWICE while
+                    // EntityDefinition.InternalSharingModel stayed ReadWrite. The read-back caught it, but the
+                    // response also carried `status: "updated"` next to that mismatch, so one payload made
+                    // two contradictory claims and the operator had to notice the disagreement.
+                    //
+                    // The verified word is written below, after the post-projection has actually looked.
+                    facetOutcomes.push({ object: fu.objectApiName, status: "submitted" });
+                }
+                catch (error) {
+                    facetOutcomes.push({ object: fu.objectApiName, status: `FAILED: ${error instanceof Error ? error.message : String(error)}` });
+                }
+            }
+            await writeJson(opts.bundleDir, "facet-updates.json", facetOutcomes);
+        }
+        // The mutation window closes: every write this call makes has now been issued. Padded by a
+        // second on each side because Salesforce stamps LastModifiedDate to the second, so a change
+        // made in the same second as the boundary would otherwise fall outside a strict comparison.
+        mutationWindow.end = new Date(Date.now() + 1000).toISOString();
+        mutationWindow.start = new Date(Date.parse(mutationWindow.start) - 1000).toISOString();
+        await writeJson(opts.bundleDir, "mutation-window.json", mutationWindow);
+        // 7. Post-projection + three-way diff. The mutations above (deploy/deletes/facets) have
+        // ALREADY landed; a network failure in this READ-BACK phase must not crash the call and
+        // throw them away. On any error here we return AMBIGUOUS_DELIVERY (deploy id preserved) —
+        // the operator re-projects to confirm. (6.5.1 run: a `fetch failed` here discarded a
+        // QuickAction deploy that had actually succeeded.)
+        try {
+            const postDir = path.join(opts.bundleDir, "post");
+            // Its own phase rather than sharing the pre-projection's, because the two are not the same
+            // cost on the same scope: post is measured at 3.8x pre across the corpus (identical scope, zero
+            // sleeps), and a meter that merged them would hide precisely that asymmetry. A read-back retry
+            // re-enters this, so the phase accumulates across attempts — which is the honest total.
+            const projectPost = async () => {
+                await orgCallPhase("postProjection", () => runProjection(opts.reader, {
+                    scope,
+                    outDir: postDir,
+                    orgAlias: opts.targetOrg,
+                    apiVersion: opts.apiVersion,
+                    label: "post",
+                    // The SAME decision the pre-projection made, and it has to be — an asymmetric skip would
+                    // manufacture a side change on every wave (see the pre-projection comment).
+                    skipPrecedent
+                }));
+            };
+            await projectPost();
+            // WHAT THE FIRST READ DISAGREED ABOUT — and it is the only read there is. There used to be a
+            // backoff here that re-projected up to five times over 9.5s; it is gone (see the note where
+            // READBACK_RETRY_DELAYS_MS used to live), and this predicate now decides the WORDING of a note
+            // rather than whether to sleep.
+            //
+            // Kept, rather than folded into step 8's intent check, because the two ask different questions:
+            // step 8 reports every mismatch, this one asks whether a mismatch is the org's final answer.
+            // "Unsettled" is deliberately the FULL intent check, not merely "is the component there".
+            //
+            // CF74 produced three distinct shapes of DELIVERED_WITH_DRIFT and only one was absence:
+            //   w1  CustomObject read back (absent)          — the component itself had not propagated
+            //   w4b compactLayoutAssignment read back SYSTEM — component present, facet still the old value
+            //   w7  sharingOwnerRules read back []           — present, and recalculating asynchronously
+            // The operator confirmed all three had landed correctly by re-reading moments later. A predicate
+            // that only counted missing components would name w1 and stay silent on the other two, which is
+            // most of the noise the verdict was suffering from.
+            //
+            // Readable only because the permanently-benign class is canonicalized first
+            // (PLATFORM_DEFAULT_WHEN_OMITTED): otherwise a mismatch that can NEVER resolve — an element the
+            // org always omits — would be advertised as worth re-reading on every single apply.
+            const unsettled = async () => {
+                const manifest = JSON.parse(await fs.readFile(path.join(postDir, "projection.json"), "utf8"));
+                const byKey = new Map(manifest.components.map((c) => [`${c.typeName}:${c.fullName}`, c]));
+                const out = [];
+                for (const edit of opts.edits) {
+                    const key = `${edit.typeName}:${edit.fullName}`;
+                    const entry = byKey.get(key);
+                    if (!entry?.found) {
+                        out.push({ component: key, absent: true, paths: [] });
+                        continue;
+                    }
+                    const intent = normalizeIntent(edit.typeName, edit.xml);
+                    if (!intent)
+                        continue; // unparseable intent is a real finding, not something waiting settles
+                    const snap = JSON.parse(await fs.readFile(path.join(postDir, entry.file), "utf8"));
+                    const observed = snap.state.metadata;
+                    const cmp = compareIntent(coerceLeaf(intent), observed ? coerceLeaf(observed) : null);
+                    if (cmp.mismatches.length > 0) {
+                        out.push({ component: key, absent: false, paths: cmp.mismatches.map((m) => m.path) });
+                    }
+                }
+                // Facet updates settle like everything else — and until the EV-31…40 run this loop could not
+                // see them, because it walked `edits` only. A facet-only apply therefore never waited for
+                // anything, whatever ASYNC_SETTLING_LEAVES said, and step 8 below scored the FIRST read as
+                // final: a sharingModel change came back "NOT APPLIED — the org accepted the request but
+                // still reads ReadWrite" while the org was mid-recalculation and Private moments later. The
+                // wait and the verdict have to look at the same set of writes.
+                for (const fu of opts.facetUpdates) {
+                    const key = `CustomObject:${fu.objectApiName}`;
+                    const entry = byKey.get(key);
+                    if (!entry?.found) {
+                        out.push({ component: `${key} (facets)`, absent: true, paths: [] });
+                        continue;
+                    }
+                    const snap = JSON.parse(await fs.readFile(path.join(postDir, entry.file), "utf8"));
+                    const observed = snap.state.metadata;
+                    const cmp = compareIntent(coerceLeaf(fu.facets), observed ? coerceLeaf(observed) : null);
+                    if (cmp.mismatches.length > 0) {
+                        out.push({ component: `${key} (facets)`, absent: false, paths: cmp.mismatches.map((m) => m.path) });
+                    }
+                }
+                return out;
+            };
+            // THE READ-BACK IS ONE READ. Nothing below sleeps or re-projects; `pending` is the first and
+            // only answer, and the two branches differ only in what the operator is told to do with it.
+            const pending = await unsettled();
+            if (pending.length > 0) {
+                const components = pending.map((p) => p.component).join(", ");
+                const paths = [...new Set(pending.flatMap((p) => p.paths))].slice(0, 6).join(", ");
+                notes.push(settlingIsPlausible(pending)
+                    ? `read-back differed on something Salesforce may still be settling: ${components}` +
+                        `${paths ? ` (${paths})` : " (read back absent)"}. The verdict below reports it as drift ` +
+                        `immediately rather than sleeping on it — the backoff that used to wait here settled ZERO of the 17 ` +
+                        `waves it ever fired on. Re-project the scope (project_org) to see whether it has caught up.`
+                    : `read-back concluded immediately: ${components} differed on ${paths}, none of which Salesforce settles ` +
+                        `asynchronously — this is the org's answer, not a work in progress. If one of these IS ` +
+                        `eventually-consistent, add its leaf name to ASYNC_SETTLING_LEAVES so the note above says so.`);
+            }
+            // Still reported, still always 0. The ledger has 28 waves of `readbackWaitMs` and every one is
+            // zero; emitting the field keeps that series continuous across this build rather than leaving a
+            // hole that reads as "older installs did not send it". `readbackSettled` is deliberately NOT set
+            // — it answered "did waiting help", and nothing waits.
+            const waited = 0;
+            const diff = await diffProjections(preDir, postDir);
+            await writeJson(opts.bundleDir, "diff.json", diff);
+            // 8. Intent check per edited component; deletes must be absent post.
+            const postManifest = JSON.parse(await fs.readFile(path.join(postDir, "projection.json"), "utf8"));
+            const postByKey = new Map(postManifest.components.map((c) => [`${c.typeName}:${c.fullName}`, c]));
+            const preByKey = new Map(pre.manifest.components.map((c) => [`${c.typeName}:${c.fullName}`, c]));
+            const intentReports = [];
+            const removalReports = [];
+            const unstatedChangeReports = [];
+            // trackHistory is INVISIBLE to the Metadata API read-back — omitted whatever its value, so a
+            // field deployed with history tracking ON reads back with the facet simply missing. The
+            // comparator (correctly) treats an intended TRUE that comes back absent as drift, which made
+            // every history-tracked field a false DELIVERED_WITH_DRIFT: 5 of them across the local runs.
+            //
+            // Cataloguing it in PLATFORM_DEFAULT_WHEN_OMITTED would silence the alarm by auto-matching any
+            // stated `true` — including when tracking genuinely failed to enable, which is exactly the
+            // masking this verdict exists to prevent. So the value is fetched from the one place the org
+            // does expose it, the Tooling API's FieldDefinition.IsFieldHistoryTracked, and compared for
+            // real. Fail-open: if the probe cannot run, the facet is left as the projection saw it and the
+            // old (noisy but honest) behaviour returns.
+            const trackedHistory = await orgCallPhase("historyProbe", () => probeFieldHistoryTracking(opts.reader, opts.edits));
+            for (const edit of opts.edits) {
+                const key = `${edit.typeName}:${edit.fullName}`;
+                const intent = normalizeIntent(edit.typeName, edit.xml);
+                const entry = postByKey.get(key);
+                let observed = null;
+                // The org's post-image UNTOUCHED. `observed` below gains the probed trackHistory, which the
+                // Metadata API never returns on either side — comparing that against a pre-image that
+                // structurally cannot carry it would manufacture a change on every history-tracked field.
+                let readBack = null;
+                if (entry?.found) {
+                    const snap = JSON.parse(await fs.readFile(path.join(postDir, entry.file), "utf8"));
+                    observed = snap.state.metadata;
+                    readBack = observed;
+                    const tracked = trackedHistory.get(edit.fullName);
+                    if (edit.typeName === "CustomField" && observed && tracked !== undefined) {
+                        observed = { ...observed, trackHistory: tracked };
+                    }
+                }
+                // Both pre/post comparisons below need the pre-image, and both are only possible when the
+                // component already existed — a create has no pre-image, which keeps them quiet and targeted.
+                const preEntry = preByKey.get(key);
+                const unstated = [];
+                if (preEntry?.found && observed) {
+                    const preSnap = JSON.parse(await fs.readFile(path.join(preDir, preEntry.file), "utf8"));
+                    // Full-file-replace collateral: what did this component LOSE?
+                    const lost = findRemovals(preSnap.state.metadata, observed, intent);
+                    if (lost.length > 0)
+                        removalReports.push({ component: key, removals: lost });
+                    // ...and what did it CHANGE that nobody asked for? The other half of the same question, and
+                    // the half that shipped green on the EV-31…40 run.
+                    unstated.push(...findUnstatedChanges(edit.typeName, preSnap.state.metadata, readBack, intent));
+                }
+                const trackingChange = unstatedTrackingChange(edit, intent, preTrackedHistory, trackedHistory);
+                if (trackingChange)
+                    unstated.push(trackingChange);
+                if (unstated.length > 0)
+                    unstatedChangeReports.push({ component: key, changes: unstated });
+                if (!intent) {
+                    intentReports.push({ component: key, matched: 0, mismatches: [{ path: "xml", intended: "(parseable)", observed: "(unparseable)" }], orderOnly: 0, found: Boolean(entry?.found) });
+                    continue;
+                }
+                const cmp = compareIntent(coerceLeaf(intent), observed ? coerceLeaf(observed) : null);
+                intentReports.push({ component: key, ...cmp, found: Boolean(entry?.found) });
+            }
+            for (const fu of opts.facetUpdates) {
+                const key = `CustomObject:${fu.objectApiName}`;
+                const entry = postByKey.get(key);
+                let observed = null;
+                if (entry?.found) {
+                    const snap = JSON.parse(await fs.readFile(path.join(postDir, entry.file), "utf8"));
+                    observed = snap.state.metadata;
+                }
+                const cmp = compareIntent(coerceLeaf(fu.facets), observed ? coerceLeaf(observed) : null);
+                intentReports.push({ component: `${key} (facets)`, ...cmp, found: Boolean(entry?.found) });
+                // Promote "submitted" to what the org ACTUALLY shows, so `facetUpdates` and `intent` cannot
+                // tell the reader two different stories about the same write (CF63 w1: `status: "updated"`
+                // sitting beside a mismatch proving nothing had changed). The mismatch is named here too —
+                // this line is the one a summary is most likely to quote.
+                const outcome = facetOutcomes.find((f) => f.object === fu.objectApiName);
+                if (outcome && outcome.status === "submitted")
+                    outcome.status = facetVerifiedStatus(cmp.mismatches);
+            }
+            if (facetOutcomes.length)
+                await writeJson(opts.bundleDir, "facet-updates.json", facetOutcomes);
+            for (const d of opts.deletes) {
+                const key = `${d.typeName}:${d.fullName}`;
+                const entry = postByKey.get(key);
+                const gone = !entry || !entry.found;
+                intentReports.push({
+                    component: key,
+                    matched: gone ? 1 : 0,
+                    mismatches: gone ? [] : [{ path: "metadata", intended: "(deleted)", observed: "(still present)" }],
+                    orderOnly: 0,
+                    found: Boolean(entry?.found)
+                });
+            }
+            await writeJson(opts.bundleDir, "intent.json", intentReports);
+            // Side changes: anything that moved outside the edit/delete set (real changes only).
+            //
+            // Two sources now. The projection diff still catches anything IN scope — which, since the scope
+            // narrowed (plan -002), is essentially the touched set, so it mostly catches added/removed
+            // collateral. The window scan supplies what the wide projection used to: components that moved
+            // during the deploy but were never projected, including on objects nobody put in scope.
+            const facetKeys = new Set(opts.facetUpdates.map((f) => `CustomObject:${f.objectApiName}`));
+            const sideChanges = diff.changed
+                .filter((c) => !editKeys.has(c.key) && !deleteKeys.has(c.key) && !facetKeys.has(c.key))
+                .filter((c) => c.changes.some((ch) => !ch.orderOnly))
+                .map((c) => c.key)
+                .concat(diff.added.filter((k) => !editKeys.has(k)), diff.removed.filter((k) => !deleteKeys.has(k)));
+            const ours = new Set([...editKeys, ...deleteKeys, ...facetKeys]);
+            // Witnesses exclude deletes: a removed component leaves no row to carry a LastModifiedDate, so
+            // counting it would make every delete-only wave report a suspect window.
+            const witnesses = new Set([...editKeys, ...facetKeys]);
+            const scan = await orgCallPhase("changeScan", () => scanChangedInWindow(opts.reader, mutationWindow, ours, witnesses));
+            await writeJson(opts.bundleDir, "change-scan.json", scan);
+            for (const c of scan.candidates)
+                if (!sideChanges.includes(c))
+                    sideChanges.push(c);
+            notes.push(...scan.notes);
+            // The scan catches per-type query errors and keeps going, so "found nothing" and "could not
+            // look" produce the same empty candidate list. typesCovered is the only thing that separates
+            // them, and it reached change-scan.json and nowhere else — not the verdict, not the operator
+            // sentence, not the ledger. A scan that queried no types would report DIFF_VERIFIED and say
+            // "every setting matches the specification".
+            const missingTypes = CHANGE_SCAN_TYPES.filter((t) => !scan.typesCovered.includes(t.type)).map((t) => t.type);
+            // Two ways the scan can fail to prove anything, and they must be treated identically: it could
+            // not QUERY some types (missingTypes), or it queried them over the WRONG INTERVAL and so cannot
+            // have seen a concurrent change either (windowSuspect — see ChangeScanResult). Both produce an
+            // empty candidate list that looks exactly like a clean org.
+            const scanIncomplete = missingTypes.length > 0 || scan.windowSuspect;
+            // Guarded on missingTypes, not on scanIncomplete: the window-suspect case has already pushed
+            // its own note (with the far more useful explanation), and this one would otherwise render
+            // "could not query: " with an empty list beside it.
+            if (missingTypes.length > 0) {
+                notes.push(`The org-wide change scan covered ${scan.typesCovered.length} of ${CHANGE_SCAN_TYPES.length} types (could not query: ${missingTypes.join(", ")}). ` +
+                    `Nothing here rules out a concurrent change to those types — the check did not complete, which is not the same as finding nothing.`);
+            }
+            if (scan.candidates.length > 0) {
+                notes.push(`${scan.candidates.length} component(s) changed in the org DURING this deploy window that this wave did not deploy ` +
+                    `(${scan.candidates.slice(0, 8).join(", ")}${scan.candidates.length > 8 ? ", …" : ""}). ` +
+                    `This is "moved while you were deploying", NOT "your deploy moved it" — a concurrent admin or a parallel run looks identical here. ` +
+                    `Re-read them before assuming either.`);
+            }
+            await writeJson(opts.bundleDir, "removals.json", removalReports);
+            for (const r of removalReports) {
+                notes.push(`CONTENT REMOVED by this edit — ${renderRemovals(r.component, r.removals)}. A full-file replace deletes whatever the file omits; confirm each loss was intended (re-read the pre-image in ${path.join(opts.bundleDir, "pre")} and restore anything you did not mean to drop).`);
+            }
+            await writeJson(opts.bundleDir, "unstated-changes.json", unstatedChangeReports);
+            for (const u of unstatedChangeReports) {
+                notes.push(`SETTING CHANGED WITHOUT BEING ASKED FOR — ${renderUnstatedChanges(u.component, u.changes)}. ` +
+                    `This component moved on a facet your file never states, so nothing verified it: the intent check only reads what you wrote. ` +
+                    `Compare the pre- and post-images in ${opts.bundleDir} and confirm each one, then either state the value you want in the file or restore it — ` +
+                    `an unstated change is how history tracking and a validation rule's error message were silently altered under a "verified" verdict.`);
+            }
+            // "NOT APPLIED" as well as "FAILED": the first is a facet the org ACCEPTED and then ignored,
+            // which is the quieter and more dangerous of the two. Its mismatch already fails intentClean on
+            // its own; naming it here keeps the verdict from depending on that coincidence.
+            const facetFailed = facetOutcomes.some((f) => f.status.startsWith("FAILED") || f.status.startsWith("NOT APPLIED"));
+            const intentClean = intentReports.every((r) => r.mismatches.length === 0) && !facetFailed;
+            // Removals never qualify as DIFF_VERIFIED: the shape the author stated may be perfectly
+            // matched while the component silently lost content it used to have (live-caught 6.5.4).
+            // Unstated changes block for the same reason from the other direction — the stated shape matches
+            // while a facet nobody wrote about moved (live-caught EV-31…40, under a DIFF_VERIFIED banner).
+            // scanIncomplete blocks DIFF_VERIFIED for the same reason removals do: the components may match
+            // the spec perfectly while something the run cannot see has moved. Verified means verified.
+            const verdict = deploy?.timedOut
+                ? "AMBIGUOUS_DELIVERY"
+                : intentClean &&
+                    sideChanges.length === 0 &&
+                    removalReports.length === 0 &&
+                    unstatedChangeReports.length === 0 &&
+                    !scanIncomplete
+                    ? "DIFF_VERIFIED"
+                    : "DELIVERED_WITH_DRIFT";
+            const result = {
+                verdict,
+                bundleDir: opts.bundleDir,
+                lint,
+                ...(opts.edits.length > 0
+                    ? {
+                        dryRun: { status: "Succeeded", failures: [] },
+                        deploy: deploy ? { status: deploy.status, id: deploy.id, failures: deploy.failures, timedOut: deploy.timedOut } : undefined
+                    }
+                    : {}),
+                ...(deleteOutcomes.length ? { deletes: deleteOutcomes } : {}),
+                ...(facetOutcomes.length ? { facetUpdates: facetOutcomes } : {}),
+                diff,
+                intent: intentReports,
+                sideChanges,
+                ...(removalReports.length ? { removals: removalReports } : {}),
+                ...(unstatedChangeReports.length ? { unstatedChanges: unstatedChangeReports } : {}),
+                ...(scanIncomplete ? { scanIncomplete: true } : {}),
+                readbackWaitMs: waited,
+                notes
+            };
+            return await recordInMirror(result, opts);
+        }
+        catch (readbackError) {
+            // Only the READ-BACK phase throws here. If nothing was mutated (no deploy/delete/facet),
+            // the error is real — surface it. Otherwise the mutation may have landed → AMBIGUOUS.
+            const mutated = opts.edits.length > 0 || opts.deletes.length > 0 || opts.facetUpdates.length > 0;
+            if (!mutated)
+                throw readbackError;
+            const result = ambiguousReadbackResult({
+                bundleDir: opts.bundleDir,
+                lint,
+                deploy: deploy ? { status: deploy.status, id: deploy.id, failures: deploy.failures, timedOut: deploy.timedOut } : undefined,
+                deletes: deleteOutcomes.length ? deleteOutcomes : undefined,
+                facetUpdates: facetOutcomes.length ? facetOutcomes : undefined,
+                priorNotes: notes,
+                error: readbackError
+            });
+            // An ambiguous read-back has no post-image, so the overlay has only the wave's deletes to
+            // stage and usually commits nothing. That is the honest outcome: R2 says an ambiguous wave
+            // records the components it OBSERVED, and here it observed none.
+            return await recordInMirror(result, opts);
+        }
+    }
+    finally {
+        await fs.rm(projectDir, { recursive: true, force: true });
+    }
+}