in2-agent-server 0.20260821.185429

package/dist/direct/rollback.js

@@ -0,0 +1,1513 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { sortKeysDeep } from "../projection/diff.js";
+import { incompleteFacetsOf } from "../orgread/layoutSnapshot.js";
+import { assessComparability } from "./snapshotComparability.js";
+import { deliveredComponents, mirrorPath } from "./orgRepo.js";
+import { resolveComponentFromRelPath } from "./sourceTree.js";
+/**
+ * ORIGIN R18, VERBATIM IN STRUCTURE — every class this module can return, and nothing else.
+ *
+ * Exported as data rather than left implicit in branches because R18 is a CONTRACT: the tool's
+ * card text, this module's classification and the plan document all have to say the same thing,
+ * and a table nobody can read is a table that drifts.
+ *
+ * ONE ROW IS AN AMENDMENT, not a transcription: `ALREADY_LIVE` has no counterpart in
+ * 2026-07-31-001 §2, which never asks what happens when the deleted component is back. It is
+ * recorded as an amendment at R18 in 2026-08-02-001 (2026-08-03) rather than smuggled in here.
+ */
+export const REVERSIBILITY_TABLE = [
+    {
+        class: "CLEAN_DELETE",
+        change: "Component created",
+        rollbackPath: "Delete it",
+        risk: "Clean, if nothing came to depend on it"
+    },
+    {
+        class: "CLEAN_REDEPLOY",
+        change: "Component modified",
+        rollbackPath: "Deploy the bundle's pre/source/ image",
+        risk: "Clean while the pre-image is COMPLETE; an incomplete one drops content on a replace type, so an image whose projection declared an unread facet is gated for ack rather than called clean"
+    },
+    {
+        class: "UNDELETE_WINDOW",
+        change: "Field deleted, under 15 days ago",
+        rollbackPath: "Undelete in Setup — never a metadata re-create",
+        risk: "Data intact. Restoring by deploy instead would throw it away while appearing to succeed"
+    },
+    {
+        class: "ALREADY_LIVE",
+        change: "Field deleted, and the component is LIVE in the org again",
+        rollbackPath: "Nothing to roll back for the definition — verify the live state is what you want",
+        risk: "No loss to accept. Carding this as lossy would claim data loss that did not happen, and re-creating a component that already exists is a deploy against live state"
+    },
+    {
+        class: "LOSSY_RECREATE",
+        change: "Field deleted, window lapsed",
+        rollbackPath: "Re-create from the pre-image",
+        risk: "Metadata returns, DATA IS GONE FOREVER — an explicit operator decision, never a default"
+    },
+    {
+        class: "IRREVERSIBLE",
+        change: "Picklist value set moved, record type created, CMT access granted",
+        rollbackPath: "None — the Metadata API cannot perform the removal, or no deploy restores the data",
+        risk: "Refused, naming the limitation; the rest of a partial selection is unaffected"
+    }
+];
+/**
+ * Mark a RESOLVED `EntityDefinition.DurableId` as addressable. The only way to make a
+ * `TableEnumOrId`, so every one of them is traceable to a resolution the caller actually performed —
+ * U10's probe does it in `rollbackRun.ts`.
+ */
+export const tableEnumOrId = (durableId) => durableId;
+/**
+ * The Tooling query, with the column that makes the difference correct.
+ *
+ * `NamespacePrefix` is not optional. Omitting it turns a 34-row deleted set into a 226-row one made
+ * almost entirely of managed-package fields whose `DeveloperName` does not carry their namespace
+ * (measured, T-Pinto, 2026-08-03). `FullName` is included because Tooling's own answer beats a
+ * reconstruction, and it is free HERE — the single-row restriction that makes `Metadata`/`FullName`
+ * expensive applies to the qualification, not the column list. If an org rejects it, drop the column
+ * and `toolingFullName` reconstructs.
+ *
+ * The parameter is a `TableEnumOrId` and not an object name — see that type.
+ */
+export const TOOLING_CUSTOM_FIELD_SOQL = (table) => `SELECT Id, DeveloperName, NamespacePrefix FROM CustomField WHERE TableEnumOrId = '${table}'`;
+/**
+ * The audit query. `Action` differs by object kind and `Display` cannot appear in a WHERE clause
+ * (probe §4, traps 1 and 2), so the object filter is `Section` server-side plus label matching
+ * client-side — which is what makes every window fact this contributes INFERRED.
+ */
+export const SETUP_AUDIT_TRAIL_SOQL = (standardObject) => `SELECT CreatedDate, Action, Section, Display FROM SetupAuditTrail ` +
+    `WHERE Action = '${standardObject ? "deletedCF" : "deletedCFCustom"}' ORDER BY CreatedDate DESC`;
+/** Salesforce's Deleted Fields retention. 15 days, then field and data are erased. */
+export const UNDELETE_WINDOW_DAYS = 15;
+const DAY_MS = 24 * 60 * 60 * 1000;
+export class RollbackError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "RollbackError";
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// the deleted-set detector
+// ---------------------------------------------------------------------------------------------
+/**
+ * A Tooling row's qualified name, the way `listMetadata` would report it.
+ *
+ * Tooling's own `FullName` when the caller asked for it; otherwise reconstructed as
+ * `<object>.<ns>__<developerName>__c`. The namespace segment is the whole point — see the module
+ * header's refinement 1.
+ */
+export function toolingFullName(objectName, row) {
+    if (row.fullName)
+        return row.fullName;
+    const ns = row.namespacePrefix ? `${row.namespacePrefix}__` : "";
+    return `${objectName}.${ns}${row.developerName}__c`;
+}
+/**
+ * `Tooling CustomField ∖ listMetadata CustomField` — the deleted-but-recoverable set (probe §3).
+ *
+ * Name-independent by construction, which is what makes it survive the re-delete collision that a
+ * `_del`-suffix scan cannot: the SET is decided by absence from `listMetadata`, and only the join
+ * back to a specific field (`matchDeletedField`) touches names at all.
+ *
+ * The reverse difference is expected to be empty and is returned rather than asserted: a non-empty
+ * `onlyLive` means Tooling did not see something `listMetadata` did, which is a fact about the read
+ * (paging, a scope mismatch) and a caller deciding how much to trust the answer wants to see it.
+ */
+export function deletedFieldSet(args) {
+    const liveSet = new Set(args.live);
+    const toolingNames = args.tooling.map((row) => toolingFullName(args.objectName, row));
+    const toolingSet = new Set(toolingNames);
+    return {
+        deleted: toolingNames.filter((name) => !liveSet.has(name)).sort(),
+        onlyLive: args.live.filter((name) => !toolingSet.has(name)).sort()
+    };
+}
+// Salesforce's delete rename: `TEST_Region__c` -> `TEST_Region_del__c`, and a SECOND deleted
+// generation of the same base name -> `TEST_Region_del1__c` (measured 2026-08-03; the probe had
+// flagged this as unprobeable without a write). Anchored at both ends so `Foo_del` cannot match
+// `Foo_delta`.
+const deletedNameRe = (base) => new RegExp(`^${base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}_del\\d*__c$`);
+/**
+ * The deleted-set members that are this field, post-rename.
+ *
+ * More than one is the re-delete collision and is RETURNED rather than resolved: two generations of
+ * one API name are two different fields with two different data sets, and picking one silently
+ * would card the operator with a Setup path that might restore the wrong one.
+ */
+export function matchDeletedField(deleted, fullName) {
+    const dot = fullName.indexOf(".");
+    if (dot < 0)
+        return [];
+    const object = fullName.slice(0, dot);
+    const leaf = fullName.slice(dot + 1);
+    if (!leaf.endsWith("__c"))
+        return [];
+    const base = leaf.slice(0, -"__c".length);
+    const re = deletedNameRe(base);
+    return deleted.filter((name) => name.slice(0, dot) === object && re.test(name.slice(dot + 1))).sort();
+}
+// ---------------------------------------------------------------------------------------------
+// the window
+// ---------------------------------------------------------------------------------------------
+const iso = (ms) => new Date(ms).toISOString();
+const AUDIT_DISPLAY_PREFIX = "deleted custom field ";
+const AUDIT_DISPLAY_OBJECT_SEP = " from ";
+/**
+ * The LABEL an audit row names, lower-cased — or null when the row is not a field deletion.
+ *
+ * WHY NOT A SUBSTRING SEARCH. The join needle is a field label and `Display` is a whole sentence,
+ * so `display.includes(label)` matches any row whose label merely CONTAINS the needle: the label
+ * "Region" joins "Deleted custom field Sales Region Code" and dates one field's window from a
+ * different field's deletion. The rendering is fixed and documented (probe §4, trap 2), so the
+ * label is extracted from it and compared whole. Two shapes, because the action name differs by
+ * object kind: `deletedCF` ends at the label, `deletedCFCustom` appends ` from <Object Label>`.
+ * `lastIndexOf` on the separator, so a label that itself contains " from " keeps its tail.
+ *
+ * A row that does not carry the prefix contributes nothing rather than something plausible. The
+ * audit trail is corroboration only, and losing it costs an INFERRED term, not a class.
+ */
+export function auditDisplayLabel(display) {
+    const text = display.trim().toLowerCase();
+    if (!text.startsWith(AUDIT_DISPLAY_PREFIX))
+        return null;
+    const rest = text.slice(AUDIT_DISPLAY_PREFIX.length).trim();
+    const sep = rest.lastIndexOf(AUDIT_DISPLAY_OBJECT_SEP);
+    const label = (sep < 0 ? rest : rest.slice(0, sep)).trim();
+    return label || null;
+}
+/**
+ * The audit row for this field, joined by LABEL and picked by NEARNESS to the wave's own clock.
+ *
+ * The probe had to take "the most recent row" because it had no bundle. A rollback usually does:
+ * the wave that issued the delete recorded when, so the right row is the one closest to that
+ * instant rather than the newest — which is what keeps an EARLIER deletion of a same-labelled field
+ * from claiming this field's window. Still inferred, because the join is still a label. When the
+ * bundle recorded NO instant (`bundleMs` NaN) there is nothing to be near, and this falls back to
+ * the probe's own heuristic: the first row, which the query orders newest-first.
+ */
+function joinAuditRow(rows, label, bundleMs) {
+    if (!label)
+        return { matched: 0 };
+    const needle = label.trim().toLowerCase();
+    if (!needle)
+        return { matched: 0 };
+    const matches = rows.filter((row) => auditDisplayLabel(row.display) === needle);
+    if (matches.length === 0)
+        return { matched: 0 };
+    let best = matches[0];
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const row of matches) {
+        const at = Date.parse(row.createdDate);
+        const distance = Number.isNaN(at) ? Number.POSITIVE_INFINITY : Math.abs(at - bundleMs);
+        if (distance < bestDistance) {
+            best = row;
+            bestDistance = distance;
+        }
+    }
+    return { row: best, matched: matches.length };
+}
+/**
+ * The window for one deleted field: when it lapses, how much is left, and on whose word.
+ *
+ * The BUNDLE's mutation window is the primary term and the audit trail corroborates it, which
+ * inverts the probe's ranking for the one case the probe could not cover. When the two disagree by
+ * more than a day the audit row wins — Salesforce's own clock beats ours for a purge Salesforce
+ * performs — and the disagreement is reported so a reader can see which one moved the date.
+ *
+ * AND WITH NEITHER TERM THERE IS NO WINDOW. `basis: "UNVERIFIED"`, `lapsesAt` and `daysRemaining`
+ * withheld. The alternative — anchoring on `asOf` — manufactures a FULL 15-day window out of the
+ * moment this code happened to run and labels it `BUNDLE_WINDOW`, i.e. states as measured the one
+ * thing the bundle failed to record. That is the same error the probe's presence rule forbids on
+ * the other axis (a failed probe leaves presence UNVERIFIED, never absent), and it fails in the
+ * dangerous direction: a fabricated window is at its most generous exactly when the delete is
+ * oldest and least likely to still be recoverable.
+ */
+export function undeleteWindowFor(args) {
+    const bundleMs = args.deletedAtBundle ? Date.parse(args.deletedAtBundle) : Number.NaN;
+    const auditMs = args.audit?.row ? Date.parse(args.audit.row.createdDate) : Number.NaN;
+    const usable = (value) => !Number.isNaN(value);
+    // The bundle's own clock unless the audit row disagrees materially. "Materially" is a day,
+    // because sub-day drift between an org's stamp and a laptop's is not a finding.
+    const preferAudit = usable(auditMs) && (!usable(bundleMs) || Math.abs(auditMs - bundleMs) > DAY_MS);
+    const anchor = preferAudit ? auditMs : bundleMs;
+    const base = {
+        ...(args.candidates[0] ? { toolingFullName: args.candidates[0] } : {}),
+        candidates: args.candidates,
+        ...(args.deletedAtBundle ? { deletedAtBundle: args.deletedAtBundle } : {}),
+        ...(args.audit?.row ? { deletedAtAudit: args.audit.row.createdDate } : {}),
+        auditRowsMatched: args.audit?.matched ?? 0,
+        presenceVerified: args.presenceVerified
+    };
+    if (!usable(anchor))
+        return { ...base, basis: "UNVERIFIED", daysRemaining: null };
+    const lapsesMs = anchor + UNDELETE_WINDOW_DAYS * DAY_MS;
+    return {
+        ...base,
+        lapsesAt: iso(lapsesMs),
+        basis: preferAudit ? "AUDIT_TRAIL_INFERRED" : "BUNDLE_WINDOW",
+        daysRemaining: Math.floor((lapsesMs - Date.parse(args.asOf)) / DAY_MS)
+    };
+}
+async function readJson(file) {
+    try {
+        return JSON.parse(await fs.readFile(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A relative path from a manifest, or null if it could escape the directory it is joined against.
+ *
+ * `orgRepo.ts`'s `safeRelPath` is the rule ("Manifest paths are org-derived — check them") and this
+ * is the same check: manifest `file` entries are written from ORG-SUPPLIED component names, so a
+ * bundle produced against a hostile or merely strange org must not be able to steer a read outside
+ * its own tree. Replicated rather than imported because `safeRelPath` is not exported and U9 does
+ * not edit `orgRepo.ts` — the same bounded duplication `canonicalizeSnapshot` documents.
+ *
+ * NULL RATHER THAN A THROW, because both callers here are reads whose failure already has a
+ * meaning: no snapshot, and no mirror match. Refusing a path degrades a comparison; it must not
+ * take down the classification of every other component in the wave.
+ */
+function safeRelPath(rel) {
+    const normalized = path.normalize(rel).replace(/^[/\\]+/, "");
+    if (!normalized || normalized === "." || normalized.split(/[/\\]/).includes("..") || path.isAbsolute(normalized)) {
+        return null;
+    }
+    return normalized;
+}
+/**
+ * The bytes a component contributes to the mirror — orgRepo's `canonicalSnapshot`, mirrored here.
+ *
+ * NOT IMPORTED because it is not exported, and U9 does not edit `orgRepo.ts`. The duplication is
+ * deliberate and bounded by two things: `rollback.test.ts` commits a wave through the real
+ * `overlayAndCommit` and asserts this function reproduces the committed bytes, so a divergence
+ * fails a test rather than quietly mis-reporting drift; and every comparison below runs BOTH sides
+ * through this function, so agreement only requires the two to be semantically equal, not for this
+ * to match orgRepo byte for byte.
+ *
+ * `observedAt` goes because it is when we looked, not what we found; `errors` goes because it
+ * describes the read — except for an `INCOMPLETE_FACET` declaration, which is a fact about the
+ * DOCUMENT ("the facet named here is not in the state below") and must survive.
+ */
+export function canonicalizeSnapshot(snapshot) {
+    const source = (snapshot ?? {});
+    const { observedAt: _observedAt, errors, ...rest } = source;
+    const declared = [...new Set(incompleteFacetsOf(Array.isArray(errors) ? errors : undefined))].sort();
+    const withMarker = declared.length > 0 ? { ...rest, incompleteFacets: declared } : rest;
+    return `${JSON.stringify(sortKeysDeep(withMarker), null, 2)}\n`;
+}
+/**
+ * The facets a snapshot's own `errors` array declares it could not read, deduped and sorted.
+ *
+ * The DOCUMENT's declaration, not a guess about it: a projection that hit a partial read says so
+ * (`layoutSnapshot.ts`'s `INCOMPLETE_FACET` prefix), and that declaration is what makes "the
+ * pre-image is complete" checkable instead of assumed. Silence is not a completeness claim — a
+ * facet nobody declared can still be missing — so an empty result means "nothing declared", which
+ * is why the gate it feeds is an ack rather than a promise.
+ */
+function declaredIncompleteFacets(snapshot) {
+    const errors = snapshot?.errors;
+    if (!Array.isArray(errors))
+        return [];
+    return [...new Set(incompleteFacetsOf(errors))].sort();
+}
+const componentKey = (c) => `${c.typeName}:${c.fullName}`;
+async function readSide(dir) {
+    const manifest = await readJson(path.join(dir, "projection.json"));
+    if (!manifest?.components)
+        return null;
+    const components = new Map();
+    for (const entry of manifest.components) {
+        if (typeof entry?.typeName !== "string" || typeof entry?.fullName !== "string")
+            continue;
+        const rel = typeof entry.file === "string" ? safeRelPath(entry.file) : null;
+        const snapshot = entry.found && rel ? await readJson(path.join(dir, rel)) : null;
+        components.set(componentKey(entry), { entry, snapshot });
+    }
+    return { ...(manifest.orgId ? { orgId: manifest.orgId } : {}), components };
+}
+/**
+ * Which components the bundle holds deployable bytes for, from `pre/source/`.
+ *
+ * Read by WALKING the tree and resolving each path back to its component
+ * (`resolveComponentFromRelPath`), never by predicting where the retrieve would have put a
+ * component. The retrieve is fail-open (U1) and can land partially, so the only honest answer to
+ * "is there an image" is "is there a file", and a forward prediction would answer a different
+ * question confidently.
+ *
+ * `preRoot` is the bundle dir for a single-attempt wave, or attempt 1's archive for a retried one —
+ * whichever `classifyRollback` resolved as the honest baseline. Never `bundleDir` unconditionally.
+ */
+async function readPreImageIndex(preRoot) {
+    const root = path.join(preRoot, "pre", "source");
+    const out = new Map();
+    const walk = async (dir, prefix) => {
+        const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                await walk(path.join(dir, entry.name), rel);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const resolved = resolveComponentFromRelPath(rel);
+            if (!resolved)
+                continue;
+            const key = `${resolved.typeName}:${resolved.fullName}`;
+            const image = out.get(key) ?? { relPaths: [] };
+            // Meta first: a content-file type deploys its `-meta.xml` alongside its payload, and the
+            // meta is what names the component.
+            if (resolved.role === "meta")
+                image.relPaths.unshift(rel);
+            else
+                image.relPaths.push(rel);
+            out.set(key, image);
+        }
+    };
+    await walk(root, "");
+    return out;
+}
+// ---------------------------------------------------------------------------------------------
+// irreversibility detection
+// ---------------------------------------------------------------------------------------------
+const metadataOf = (snapshot) => {
+    const state = snapshot?.state;
+    if (!state || typeof state !== "object")
+        return {};
+    const metadata = state.metadata;
+    return metadata && typeof metadata === "object" && !Array.isArray(metadata)
+        ? metadata
+        : state;
+};
+const namesOf = (value, field = "fullName") => {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((entry) => entry?.[field])
+        .filter((name) => typeof name === "string");
+};
+/**
+ * The picklist value names a snapshot declares, across the three shapes that carry them.
+ *
+ * `CustomField` nests them under `valueSet.valueSetDefinition.value[]` (live shape, transcribed
+ * from `Account.PV_Risk_Tier__c`); `GlobalValueSet` uses `customValue[]`; `StandardValueSet` uses
+ * `standardValue[]`. Null — not an empty array — when the snapshot carries NO value set at all, so
+ * "this component is not a picklist" and "this picklist has no values" stay different answers.
+ */
+export function picklistValues(snapshot) {
+    const metadata = metadataOf(snapshot);
+    const valueSet = metadata.valueSet;
+    if (valueSet && typeof valueSet === "object") {
+        const definition = valueSet.valueSetDefinition;
+        if (definition && typeof definition === "object")
+            return namesOf(definition.value).sort();
+        // A picklist inheriting a global value set names it rather than listing values; there is no
+        // per-field value set to compare and the global one is its own component.
+        if (typeof valueSet.valueSetName === "string")
+            return null;
+        if (Array.isArray(valueSet.values))
+            return [...valueSet.values].filter((v) => typeof v === "string").sort();
+    }
+    if (Array.isArray(metadata.customValue))
+        return namesOf(metadata.customValue).sort();
+    if (Array.isArray(metadata.standardValue))
+        return namesOf(metadata.standardValue).sort();
+    return null;
+}
+/** The custom-metadata-type accesses a Profile/PermissionSet snapshot grants. */
+export function customMetadataAccesses(snapshot) {
+    const metadata = metadataOf(snapshot);
+    const raw = metadata.customMetadataTypeAccesses;
+    if (!Array.isArray(raw))
+        return null;
+    return raw
+        .map((entry) => {
+        const record = entry;
+        return typeof record?.name === "string" && record.enabled !== false ? record.name : null;
+    })
+        .filter((name) => typeof name === "string")
+        .sort();
+}
+const sameSet = (a, b) => a.length === b.length && a.every((v, i) => v === b[i]);
+/**
+ * Would undoing this modify require a removal the Metadata API cannot perform?
+ *
+ * See the module header for how R18's three irreversible rows are read. Only asked of a MODIFY: a
+ * create's rollback is a delete of the whole component (allowed for a picklist field, which is why
+ * a wave that creates a picklist is clean), and a delete's rollback adds values back inside a
+ * component that has to be re-created anyway.
+ */
+export function irreversibleModify(pre, post) {
+    const preValues = picklistValues(pre);
+    const postValues = picklistValues(post);
+    if (preValues && postValues && !sameSet(preValues, postValues)) {
+        const removed = preValues.filter((v) => !postValues.includes(v));
+        const added = postValues.filter((v) => !preValues.includes(v));
+        if (added.length > 0 && removed.length > 0) {
+            return `this wave both added (${added.join(", ")}) and removed (${removed.join(", ")}) picklist values. Neither half is undoable: the Metadata API can only INACTIVATE a value, never remove one, and the records that carried a removed value lost it at removal — no deploy restores them.`;
+        }
+        if (added.length > 0) {
+            return `this wave added the picklist value(s) ${added.join(", ")}; undoing that means REMOVING them, and the Metadata API can only inactivate a picklist value, never remove it.`;
+        }
+        return `this wave removed the picklist value(s) ${removed.join(", ")}; re-adding the value is possible, but every record that carried it lost its value at removal and no deploy restores those.`;
+    }
+    const preAccess = customMetadataAccesses(pre);
+    const postAccess = customMetadataAccesses(post);
+    if (preAccess && postAccess) {
+        const granted = postAccess.filter((v) => !preAccess.includes(v));
+        if (granted.length > 0) {
+            return `this wave granted custom metadata type access (${granted.join(", ")}); undoing that means REMOVING the access, which the Metadata API cannot do — CMT access can be added to a profile, not removed.`;
+        }
+    }
+    return null;
+}
+/** Types whose rollback-of-a-create is a deletion the Metadata API refuses. */
+const UNDELETABLE_TYPES = new Set(["RecordType"]);
+/** The org-wide-default fields of a `CustomObject` — 2026-07-31-001 §2's last row. */
+const SHARING_MODEL_KEYS = ["sharingModel", "externalSharingModel"];
+/**
+ * Did this modify move an org-wide default, and what does undoing it set off?
+ *
+ * 2026-07-31-001 §2 CARRIES A ROW R18's four classes do not: *Org-wide defaults changed* → "Re-deploy
+ * prior sharing model" → "Slow recalculation; not atomic". Read only through the reversibility
+ * question that row is a plain CLEAN_REDEPLOY and disappears, which is the wrong answer to give an
+ * operator: the hazard is not that the rollback cannot be done, it is what the rollback DOES. Lowering
+ * an org-wide default makes Salesforce recalculate sharing for every affected record asynchronously,
+ * so the org sits partly on one model and partly on the other for as long as that takes — and the
+ * deploy reporting success is not the org having finished.
+ *
+ * A NOTE ON THE RESULT, NOT A CLASS OF ITS OWN — chosen deliberately. A class would say this change
+ * is a different KIND of reversible when it is not; what was missing is the ack, not the class.
+ */
+export function sharingModelChange(pre, post) {
+    const before = metadataOf(pre);
+    const after = metadataOf(post);
+    const moved = SHARING_MODEL_KEYS.filter((key) => {
+        const from = before[key];
+        const to = after[key];
+        return typeof from === "string" && typeof to === "string" && from !== to;
+    });
+    if (moved.length === 0)
+        return null;
+    const detail = moved.map((key) => `${key} ${String(before[key])} → ${String(after[key])}`).join(", ");
+    return `this wave changed an org-wide default (${detail}). Rolling that back re-deploys the prior sharing model, and Salesforce then recalculates sharing for every affected record ASYNCHRONOUSLY: the change is slow and NOT ATOMIC, so the org sits partly on the old model and partly on the new one until the recalculation finishes — which the deploy's own success does not report.`;
+}
+// ---------------------------------------------------------------------------------------------
+// the R16 preflight
+// ---------------------------------------------------------------------------------------------
+/**
+ * Does live state still match what this wave recorded, and if not, can this history explain it?
+ *
+ * ORDER MATTERS, and it is the order origin R16 states: the divergence is classified against MIRROR
+ * HISTORY FIRST. Live state matching this org's own later delivery is not an outside edit — it is
+ * the operator being about to revert past a wave, and the ack card has to name that wave rather
+ * than accuse a client admin of changing something.
+ *
+ * COMPARABILITY IS ASKED BEFORE EITHER (PV Arm B, `snapshotComparability.ts`). A months-old recorded
+ * post-image and a snapshot read today can be the work of two different readers, and their
+ * difference is then not evidence about the org in either direction. A rollback preflight is the
+ * worst possible place to learn that lesson twice: the finding there would be "someone changed this,
+ * ack before I overwrite it" about a component nobody touched.
+ *
+ * THE MIRROR IS CONSULTED AT ITS WORKING TREE, not commit by commit. The tree equals HEAD after
+ * every overlay, so `projection/<file>` IS the newest recorded state — one file read instead of a
+ * walk. The bound that buys, stated rather than hidden: live state matching an INTERMEDIATE recorded
+ * delivery (later than the target, older than HEAD) reads as an external change. That is the
+ * conservative direction — it asks for an ack instead of granting one — and it can only arise when
+ * something outside this history has already moved the component back. A second bound of the same
+ * kind and the same direction: naming the LATER waves reads only the newest
+ * `ATTRIBUTION_COMMIT_LIMIT` mirror commits, so in a history longer than that a divergence whose
+ * explanation lies further back is worded as an external change rather than attributed — and when
+ * the read reaches that bound, `classifyRollback` says so in the plan's notes.
+ */
+export async function preflightDivergence(args) {
+    const key = componentKey(args.component);
+    const recorded = args.recordedPost === null ? null : canonicalizeSnapshot(args.recordedPost);
+    const live = args.live === null ? null : canonicalizeSnapshot(args.live);
+    if (recorded === live)
+        return null;
+    if (recorded !== null && live !== null) {
+        const verdict = assessComparability({ recorded, observed: live });
+        if (verdict.kind !== "COMPARABLE") {
+            return {
+                kind: "NOT_COMPARABLE",
+                detail: verdict.kind === "READER_CHANGED"
+                    ? `${key}: the recorded post-image and today's read were produced by different readers, so their difference is not evidence about the org. Nothing here says whether ${key} changed.`
+                    : `${key}: every difference falls inside a facet one of the two reads declared it could not read (${verdict.facets.join(", ")}). Not evidence about the org.`,
+                ...(verdict.kind === "READER_CHANGED"
+                    ? { readers: { recorded: readerLabel(verdict.recorded), observed: readerLabel(verdict.observed) } }
+                    : {}),
+                differingKeys: verdict.differingKeys
+            };
+        }
+    }
+    const later = await laterWavesFor(args.orgId, key, args.target, args.root, args.notes);
+    const explained = await matchesMirrorHead(args.orgId, args.component, live, args.root);
+    if (explained && later.length > 0) {
+        return {
+            kind: "REVERTING_PAST_WAVE",
+            detail: `${key} no longer matches what wave ${args.target.wave} left, and this org's own history accounts for it: live state is what ${later[0]} delivered. Rolling this component back reverts past ${later.join(", ")}.`,
+            laterWaves: later
+        };
+    }
+    const present = live === null ? "is absent from the org" : "does not match the recorded post-image";
+    return {
+        kind: "EXTERNAL_CHANGE",
+        detail: `${key} ${present}, and nothing in this org's history accounts for the difference — it changed outside this history since wave ${args.target.wave} touched it. Rolling it back would overwrite that change.`
+    };
+}
+const readerLabel = (id) => `${id.family}|${id.source}`;
+/**
+ * How many mirror commits divergence attribution reads. A BOUND ON THE ANSWER, so it is named.
+ *
+ * `deliveredComponents` caps at `--max-count`, which counts COMMITS, not components — one busy
+ * wave can spend many rows of it. Past the cap the attribution simply does not see the delivery
+ * that explains a divergence, which is the conservative direction (an unnamed wave becomes an ack
+ * card, never a silent proceed) but is still an answer shaped by a limit rather than by the org.
+ */
+const ATTRIBUTION_COMMIT_LIMIT = 500;
+/**
+ * `<sessionId>/<wave>` for every commit that touched this component AFTER the target wave.
+ *
+ * `deliveredComponents` rather than `historyLog({component})`, and the difference is identity.
+ * `historyLog`'s component filter is a PATH GLOB, so it answers "which commits touched a file whose
+ * name looks like this" — on the live mirror it matches through the `source/` deploy log, which
+ * keeps a DELETED component's last bytes and would therefore report a delete as a later delivery.
+ * `deliveredComponents` reads each committed blob's own `typeName`/`fullName` and reports removals
+ * as removals, which is the question being asked here.
+ */
+async function laterWavesFor(orgId, component, target, root, notes) {
+    let delivered;
+    try {
+        delivered = await deliveredComponents({ orgId, limit: ATTRIBUTION_COMMIT_LIMIT, ...(root ? { root } : {}) });
+    }
+    catch {
+        // No history, or git could not answer. An unproven attribution is not an attribution, and the
+        // caller's fallback ("external change") is the conservative one.
+        return [];
+    }
+    if (notes && new Set(delivered.map((entry) => entry.sha)).size >= ATTRIBUTION_COMMIT_LIMIT) {
+        const note = `divergence attribution read the newest ${ATTRIBUTION_COMMIT_LIMIT} mirror commits and that bound was reached, so a divergence explained by a delivery older than those is worded as an external change rather than named.`;
+        if (!notes.includes(note))
+            notes.push(note);
+    }
+    // Newest commit first, so everything before the target's own entry is later than it.
+    const mine = delivered.filter((entry) => entry.key === component);
+    const index = mine.findIndex((entry) => entry.sessionId === target.sessionId && entry.wave === target.wave);
+    const later = index < 0 ? [] : mine.slice(0, index);
+    const seen = new Set();
+    return later
+        .map((entry) => `${entry.sessionId ?? "?"}/${entry.wave ?? "?"}`)
+        .filter((label) => (seen.has(label) ? false : (seen.add(label), true)));
+}
+/** Does live state equal the mirror's newest recorded state for this component? */
+async function matchesMirrorHead(orgId, component, live, root) {
+    if (!component.file)
+        return false;
+    const rel = safeRelPath(component.file);
+    // A manifest path that could escape the mirror is not read at all. `false` is the conservative
+    // answer: it costs an ack card, where a successful escape would read an arbitrary file.
+    if (!rel)
+        return false;
+    const file = path.join(mirrorPath(orgId, root), "projection", rel);
+    const recorded = await fs.readFile(file, "utf8").catch(() => null);
+    // A component the mirror removed has no file: its recorded state is ABSENCE, which live absence
+    // matches and live presence does not.
+    if (recorded === null)
+        return live === null;
+    if (live === null)
+        return false;
+    // Both sides re-canonicalized, so this survives a serialization change in the materializer.
+    try {
+        return canonicalizeSnapshot(JSON.parse(recorded)) === live;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Classify every rollback candidate in one wave.
+ *
+ * The wave is addressed by its BUNDLE, which is the rebuild-stable identity (R17): session id and
+ * wave label come from the directory, never from a commit SHA, because any rebuild rewrites those.
+ */
+export async function classifyRollback(input) {
+    const bundleDir = path.resolve(input.bundleDir);
+    // Only the pre-image moves. See the field doc on `ClassifyInput.preImageRoot` for why.
+    const preRoot = input.preImageRoot ? path.resolve(input.preImageRoot) : bundleDir;
+    const wave = path.basename(bundleDir);
+    const sessionId = path.basename(path.resolve(bundleDir, "..", ".."));
+    const asOf = input.asOf ?? new Date().toISOString();
+    const notes = [];
+    const verdictFile = await readJson(path.join(bundleDir, "verdict.json"));
+    const verdict = verdictFile?.verdict;
+    if (!verdict) {
+        throw new RollbackError("BUNDLE_UNREADABLE", `${bundleDir} has no readable verdict.json — nothing here says what this wave did, so nothing can be classified.`);
+    }
+    if (!STATE_CHANGING.has(verdict)) {
+        throw new RollbackError("NOT_STATE_CHANGING", `wave ${wave} ended ${verdict}, which changed nothing in the org. There is nothing to roll back, and rolling back a wave that did not land would be a change of its own.`);
+    }
+    if (verdict === "AMBIGUOUS_DELIVERY") {
+        notes.push(`wave ${wave} ended AMBIGUOUS_DELIVERY: its post-image covers only the components the run actually observed, so a component missing below is UNKNOWN rather than untouched.`);
+    }
+    const request = await readJson(path.join(bundleDir, "request.json"));
+    const pre = await readSide(path.join(preRoot, "pre"));
+    const post = await readSide(path.join(bundleDir, "post"));
+    if (!request || !pre) {
+        throw new RollbackError("BUNDLE_UNREADABLE", `${bundleDir} is missing request.json, or ${preRoot} is missing pre/projection.json. Both are written before the org is read at all, so their absence means a corrupt bundle and guessing at its scope would be guessing at what to change in a live org.`);
+    }
+    const window = await readJson(path.join(bundleDir, "mutation-window.json"));
+    const deletedAtBundle = window?.start;
+    if (!deletedAtBundle) {
+        notes.push(`wave ${wave} records no mutation window, so any undelete window below rests on the audit trail alone (inferred) or on nothing at all.`);
+    }
+    const images = await readPreImageIndex(preRoot);
+    let candidates = candidatesOf(request);
+    // A SHRINKING-SCOPE RETRY: attempt 1 delivered FieldA + FieldB, attempt 2 re-applied only FieldB.
+    // The rollback's pre-image comes from attempt 1 (preRoot !== bundleDir means the baseline was
+    // resolved to an archive), but candidates so far come from the LAST attempt's request.json alone
+    // — which no longer names FieldA. Left unfixed, FieldA is never classified and survives the
+    // rollback untouched, while the note this tool prints claims the org is restored to before the
+    // wave first changed it. So: union in every CONTRIBUTING archived attempt's own request.json
+    // too (see archivedContributingAttempts for which attempts qualify — one that landed nothing
+    // must not seed phantoms into an executable plan), and a component only an EARLIER attempt
+    // named is classified against the baseline pre-image exactly like any other candidate. The
+    // current request's declared operation wins on overlap (it is the most recent statement of
+    // intent for that component); earlier attempts only ever ADD candidates — and the plan says
+    // which ones they added, because a union row an operator cannot attribute is indistinguishable
+    // from this wave's own scope.
+    if (preRoot !== bundleDir) {
+        const earlier = [];
+        const sourceAttempt = new Map();
+        for (const { attempt, request: attemptRequest } of await archivedContributingAttempts(bundleDir)) {
+            for (const candidate of candidatesOf(attemptRequest)) {
+                earlier.push(candidate);
+                const key = `${candidate.typeName}:${candidate.fullName}`;
+                if (!sourceAttempt.has(key))
+                    sourceAttempt.set(key, attempt);
+            }
+        }
+        const ownScope = new Set(candidates.map((c) => `${c.typeName}:${c.fullName}`));
+        candidates = unionCandidates(candidates, earlier);
+        const added = candidates.filter((c) => !ownScope.has(`${c.typeName}:${c.fullName}`));
+        if (added.length > 0) {
+            notes.push(`in scope from an EARLIER attempt's request, not this bundle's own: ${added
+                .map((c) => `${componentKey(c)} (attempt ${sourceAttempt.get(`${c.typeName}:${c.fullName}`)})`)
+                .sort()
+                .join(", ")}.`);
+        }
+    }
+    if (candidates.length === 0) {
+        throw new RollbackError("NO_CANDIDATES", `wave ${wave}'s request names no components to roll back.`);
+    }
+    const selected = input.components ? new Set(input.components) : null;
+    const skipped = selected ? [...selected].filter((key) => !candidates.some((c) => componentKey(c) === key)) : [];
+    if (skipped.length > 0) {
+        notes.push(`not part of wave ${wave} and therefore not classified: ${skipped.sort().join(", ")}.`);
+    }
+    const probeLedger = newProbeLedger();
+    const components = [];
+    for (const candidate of candidates) {
+        const key = componentKey(candidate);
+        if (selected && !selected.has(key))
+            continue;
+        components.push(await classifyOne({
+            candidate,
+            key,
+            wave,
+            sessionId,
+            orgId: input.orgId,
+            asOf,
+            pre,
+            post,
+            images,
+            ...(deletedAtBundle ? { deletedAtBundle } : {}),
+            ...(input.probe ? { probe: input.probe } : {}),
+            probeLedger,
+            notes,
+            ...(input.live ? { live: input.live } : {}),
+            ...(input.root ? { root: input.root } : {})
+        }));
+    }
+    components.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    // ROLLING BACK A ROLLBACK IS A NAMED SITUATION, NEVER ONE SILENT STEP (G12). A rollback bundle
+    // is an ordinary bundle, so it classifies like any wave — and until this, nothing read the
+    // `revertOf` its request carries, so undoing `revert-w1` looked identical to undoing a delivery.
+    // It is not: its "pre-image" is the org mid-rollback, and executing against it re-applies the
+    // very state the first rollback was approved to remove — the operator is un-approving a decision,
+    // and the plan must say which one. The class stays whatever the evidence says; the GATE degrades
+    // to ACK_REQUIRED per component, because "proceed silently" is the one wrong answer. Semantics
+    // beyond the ack (a true un-revert) are deliberately not built here.
+    if (request.revertOf) {
+        const target = `${request.revertOf.sessionId}/${request.revertOf.wave}`;
+        notes.push(`wave ${wave} was itself a ROLLBACK — it reverted ${target}. Undoing it re-applies what that rollback was approved to remove, and its pre-image is the org as it stood mid-rollback, not a delivery baseline. Every component below requires an explicit ack for that reason.`);
+        const reason = `${wave} was a rollback of ${target}; undoing it re-applies what that rollback removed. Acknowledge only if un-doing the rollback is the intent.`;
+        for (let i = 0; i < components.length; i++) {
+            const component = components[i];
+            // The three terminal gates hold their ground for the same reasons `withDivergence` gives:
+            // REFUSED has nothing an ack could release, NO_ACTION nothing to execute, OPERATOR_ACTION's
+            // deploy is the harm. Everything else — including PROCEEDS — now needs the operator to say
+            // "yes, undo the rollback" with the target named.
+            if (component.gate === "REFUSED" || component.gate === "NO_ACTION" || component.gate === "OPERATOR_ACTION")
+                continue;
+            components[i] = { ...component, gate: "ACK_REQUIRED", ackReasons: [...component.ackReasons, reason] };
+        }
+    }
+    return { sessionId, wave, orgId: input.orgId, asOf, components, notes, probe: probeOutcome(probeLedger, Boolean(input.probe)) };
+}
+/** Mirrors orgRepo's own set — the verdicts that changed the org and can therefore be undone. */
+const STATE_CHANGING = new Set(["DIFF_VERIFIED", "DELIVERED_WITH_DRIFT", "AMBIGUOUS_DELIVERY"]);
+/**
+ * What the wave named, from its own request.
+ *
+ * The request's TOP-LEVEL entries, deliberately un-expanded. `orgRepo`'s `touchedKeys` expands a
+ * container into the children a deploy produced, because the mirror records component STATE; a
+ * rollback redeploys FILES, and the file is the container. Expanding here would offer the operator
+ * a child that cannot be deployed on its own.
+ */
+function candidatesOf(request) {
+    const out = [];
+    const seen = new Set();
+    const add = (typeName, fullName, deleted) => {
+        const key = `${typeName}:${fullName}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ typeName, fullName, deleted });
+    };
+    for (const item of request.deletes ?? []) {
+        if (typeof item?.typeName === "string" && typeof item?.fullName === "string")
+            add(item.typeName, item.fullName, true);
+    }
+    for (const item of request.edits ?? []) {
+        if (typeof item?.typeName === "string" && typeof item?.fullName === "string")
+            add(item.typeName, item.fullName, false);
+    }
+    for (const facet of request.facetUpdates ?? []) {
+        if (typeof facet?.objectApiName === "string")
+            add("CustomObject", facet.objectApiName, false);
+    }
+    return out;
+}
+/**
+ * The archived attempts whose requests can still bind components into this wave's blast radius.
+ *
+ * An archived attempt speaks for org state only if it may have LANDED something. The canonical
+ * same-label retry is attempt 1 `REJECTED_BY_ORG` — an attempt whose request names every component
+ * it meant to change and whose deploy changed none of them. Unioning that request into a rollback
+ * plan resurrects phantoms: a delete it tried and failed comes back through the deleted-candidate
+ * path as a re-create, one ack away from redeploying a stale image over a live component. So:
+ *
+ *   - an attempt whose archive manifest proves it never wrote pre/ never reached the deploy that
+ *     follows the pre-write — a proven no-op, skipped;
+ *   - an attempt with an explicit non-state-changing verdict landed nothing — skipped;
+ *   - an attempt with a pre-image but NO verdict died somewhere between deploy and verdict-write —
+ *     the same cannot-rule-it-out territory as AMBIGUOUS_DELIVERY, so it stays in.
+ *
+ * Ordered numerically, not lexicographically: attempts/10 sorts after attempts/2, and
+ * first-occurrence-wins downstream makes the order load-bearing.
+ *
+ * Shared with the batch report (`batchReport.ts`), which must answer "did any attempt of this wave
+ * touch existing state?" from the same set of requests this plan draws its scope from.
+ */
+export async function archivedContributingAttempts(bundleDir) {
+    const attemptsDir = path.join(bundleDir, "attempts");
+    const entries = await fs.readdir(attemptsDir, { withFileTypes: true }).catch(() => []);
+    const out = [];
+    const numbered = entries
+        .filter((e) => e.isDirectory() && /^\d+$/.test(e.name))
+        .sort((a, b) => Number(a.name) - Number(b.name));
+    for (const entry of numbered) {
+        const dir = path.join(attemptsDir, entry.name);
+        const archive = await readJson(path.join(dir, "archive.json"));
+        if (archive?.archived && archive.archived["pre"] === false)
+            continue;
+        const verdict = (await readJson(path.join(dir, "verdict.json")))?.verdict;
+        if (verdict && !STATE_CHANGING.has(verdict))
+            continue;
+        const request = await readJson(path.join(dir, "request.json"));
+        if (request)
+            out.push({ attempt: entry.name, request });
+    }
+    return out;
+}
+/**
+ * Merge candidate lists, first occurrence wins — the same identity `candidatesOf` dedupes on
+ * (`typeName:fullName`). Used to union a shrinking-scope retry's earlier-attempt candidates in
+ * behind the current request's: see the call site in `classifyRollback`.
+ */
+function unionCandidates(...lists) {
+    const out = [];
+    const seen = new Set();
+    for (const list of lists) {
+        for (const candidate of list) {
+            const key = `${candidate.typeName}:${candidate.fullName}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(candidate);
+        }
+    }
+    return out;
+}
+/**
+ * Did this component exist before the wave?
+ *
+ * Asked of the PRE-PROJECTION MANIFEST, not of the request's declared intent — the same measurement
+ * `preImageTargets` makes, and for the same reason `orgRepo`'s `touchedKeys` gives for ignoring
+ * `intent`: a mis-declared entry must not get to decide what happened, and the org's own answer is
+ * on disk.
+ *
+ * A component the manifest does not mention at all falls to MODIFY. The two wrong answers are not
+ * symmetric: a create mistaken for a modify offers a redeploy that is gated on an image and blocked
+ * without one, while a modify mistaken for a create offers to DELETE a component that predates the
+ * wave. Doubt fails towards the harmless one.
+ */
+function operationOf(candidate, pre) {
+    if (candidate.deleted)
+        return { operation: "delete", measured: true };
+    const entry = pre.get(componentKey(candidate));
+    if (!entry)
+        return { operation: "modify", measured: false };
+    return { operation: entry.entry.found ? "modify" : "create", measured: true };
+}
+async function probeObject(probe, objectName) {
+    try {
+        const [tooling, live, audit] = await Promise.all([
+            probe.toolingCustomFields(objectName),
+            probe.listCustomFields(objectName),
+            probe.fieldDeleteAudit(objectName).catch(() => [])
+        ]);
+        return { ...deletedFieldSet({ objectName, tooling, live }), live, audit };
+    }
+    catch (error) {
+        // A probe that could not run leaves presence UNVERIFIED — never "absent". The difference is the
+        // whole point: absence means the field was purged and the data is gone, and asserting that on a
+        // network error would tell an operator to accept data loss they do not have.
+        return { deleted: [], live: [], onlyLive: [], audit: [], failed: error instanceof Error ? error.message : String(error) };
+    }
+}
+const newProbeLedger = () => ({
+    cache: new Map(),
+    asked: new Set(),
+    failures: new Map(),
+    presence: new Map()
+});
+/**
+ * A re-check's ledger, pre-loaded with what the classification already answered.
+ *
+ * SEEDED RATHER THAN MERGED AFTERWARDS. The re-check visits only `UNDELETE_WINDOW` components, so
+ * the rest keep the classification's answer and there is nothing to recompute for them — and the
+ * "later pass wins" rule then lives in exactly one place (the ledger's own writes) instead of being
+ * restated by a merge function that has to re-derive it for four fields.
+ *
+ * `cache` is deliberately left EMPTY: the whole point of the re-check is to ask the org again.
+ */
+function seedProbeLedger(outcome) {
+    const ledger = newProbeLedger();
+    for (const objectName of outcome.objects)
+        ledger.asked.add(objectName);
+    for (const failure of outcome.failures)
+        ledger.failures.set(failure.objectName, failure.error);
+    for (const key of outcome.verified)
+        ledger.presence.set(key, null);
+    for (const entry of outcome.unverified)
+        ledger.presence.set(entry.key, entry.reason);
+    return ledger;
+}
+async function askProbe(ledger, probe, objectName) {
+    ledger.asked.add(objectName);
+    let pending = ledger.cache.get(objectName);
+    if (!pending) {
+        pending = probeObject(probe, objectName);
+        ledger.cache.set(objectName, pending);
+    }
+    const probed = await pending;
+    // LAST ANSWER WINS PER OBJECT, IN BOTH DIRECTIONS. The delete is what makes the seeded case sound:
+    // a failure this pass answered must not survive as a failure, or an execute whose token was
+    // refreshed since the plan would still report the plan's expired-token error.
+    if (probed.failed)
+        ledger.failures.set(objectName, probed.failed);
+    else
+        ledger.failures.delete(objectName);
+    return probed;
+}
+/** Why a component's presence went unanswered — the reason recorded against the component itself. */
+const unansweredBecause = (probe, probed) => probed?.failed ??
+    (probe
+        ? "the probe was never asked about it — this component's name carries no object to look a Deleted Fields list up by"
+        : "no live org probe was supplied");
+function probeOutcome(ledger, supplied) {
+    const verified = [];
+    const unverified = [];
+    for (const key of [...ledger.presence.keys()].sort()) {
+        const reason = ledger.presence.get(key);
+        if (reason === null || reason === undefined)
+            verified.push(key);
+        else
+            unverified.push({ key, reason });
+    }
+    const objects = [...ledger.asked].sort();
+    const failures = objects
+        .filter((objectName) => ledger.failures.has(objectName))
+        .map((objectName) => ({ objectName, error: ledger.failures.get(objectName) ?? "" }));
+    const status = !supplied
+        ? "NOT_ATTEMPTED"
+        : objects.length === 0
+            ? "NOT_NEEDED"
+            : verified.length === 0
+                ? "FAILED"
+                : unverified.length > 0 || failures.length > 0
+                    ? "PARTIAL"
+                    : "MEASURED";
+    return { status, objects, failures, verified, unverified };
+}
+async function classifyOne(args) {
+    const { candidate, key } = args;
+    const { operation, measured } = operationOf(candidate, args.pre.components);
+    const evidence = [
+        {
+            statement: measured
+                ? `wave ${args.wave} ${operation === "delete" ? "deleted" : operation === "create" ? "created" : "changed"} ${key}; the pre-projection ${operation === "create" ? "did not find it" : "found it"}.`
+                : `wave ${args.wave} edited ${key}, and its pre-projection does not mention the component. Treated as a MODIFY, which is the direction that cannot offer to delete something the wave did not create.`,
+            basis: measured ? "MEASURED" : "INFERRED"
+        }
+    ];
+    const image = args.images.get(key);
+    const preSnapshot = args.pre.components.get(key)?.snapshot ?? null;
+    const postSnapshot = args.post?.components.get(key)?.snapshot ?? null;
+    // R18's CLEAN_REDEPLOY row is conditioned on the pre-image being COMPLETE, and completeness is a
+    // SECOND question from existence. `readPreImageIndex` answers "is there a file", which the
+    // fail-open retrieve makes the only honest existence test — but a component whose projection
+    // declared `INCOMPLETE_FACET` was read partially, and on a REPLACE type deploying that image
+    // drops whatever the unread facet held while the deploy reports success. The class does not move
+    // (the CHANGE is still cleanly reversible); the GATE does, which is the distinction this module
+    // is built on.
+    const incompleteFacets = image ? declaredIncompleteFacets(preSnapshot) : [];
+    const incompleteAck = incompleteFacets.length > 0
+        ? `the pre-image for ${key} declares it could not read ${incompleteFacets.join(", ")}, so it is not a complete image of what was there. Redeploying it restores everything else and, on a replace type, DROPS what ${incompleteFacets.length > 1 ? "those facets" : "that facet"} held — while the deploy reports success.`
+        : null;
+    if (incompleteAck)
+        evidence.push({ statement: incompleteAck, basis: "MEASURED" });
+    const base = {
+        key,
+        typeName: candidate.typeName,
+        fullName: candidate.fullName,
+        operation,
+        ...(image ? { image } : {}),
+        ackReasons: [],
+        evidence
+    };
+    const divergence = await divergenceFor(args, operation);
+    if (divergence)
+        evidence.push({ statement: divergence.detail, basis: "MEASURED" });
+    const withDivergence = (component) => {
+        if (!divergence)
+            return component;
+        if (divergence.kind === "NOT_COMPARABLE")
+            return { ...component, divergence };
+        // R16: divergence blocks PER COMPONENT pending explicit ack, whatever the class says. THREE
+        // gates are already terminal and an ack cannot move them, so putting an approval in front of one
+        // would be theatre — or worse:
+        //
+        //   REFUSED          an irreversible component has no rollback for an ack to release.
+        //   NO_ACTION        a no-op has nothing to execute.
+        //   OPERATOR_ACTION  an in-window deleted field leaves through SETUP, not through a deploy. No
+        //                    ack can buy a deploy here, because the deploy is the harm (AE4).
+        //
+        // THE THIRD WAS MISSING, and its absence was not theatre — it broke AE4. Rewriting
+        // OPERATOR_ACTION to ACK_REQUIRED left `class` at UNDELETE_WINDOW while handing the component an
+        // ack token, and U10 dispatches on the GATE: once acked it reached the deploy and re-created the
+        // field from the pre-image — every value every record held destroyed, while the recoverable
+        // generation sat in Setup's Deleted Fields list and the deploy reported success.
+        //
+        // The trigger is ORDINARY, not exotic: the delete FREES the original API name (measured — see
+        // U10's POST_UNDELETE_CHECKLIST item 1), so a later wave or an admin re-creating a field under
+        // that name is live state disagreeing with a recorded post-image of ABSENCE, which is exactly
+        // what this preflight is built to find. `liveAgain` does not absorb it either, since that needs
+        // an EMPTY deleted set and this field is still in one.
+        const gate = component.gate === "REFUSED" || component.gate === "NO_ACTION" || component.gate === "OPERATOR_ACTION"
+            ? component.gate
+            : "ACK_REQUIRED";
+        return { ...component, divergence, gate, ackReasons: [...component.ackReasons, divergence.detail] };
+    };
+    if (operation === "create") {
+        if (UNDELETABLE_TYPES.has(candidate.typeName)) {
+            return withDivergence({
+                ...base,
+                class: "IRREVERSIBLE",
+                gate: "REFUSED",
+                action: `no rollback: undoing the creation of ${key} means deleting it.`,
+                limitation: `the Metadata API cannot delete a ${candidate.typeName} — "Cannot delete record type through API". Deactivating it in Setup is the nearest available action and is the operator's to take.`
+            });
+        }
+        return withDivergence({
+            ...base,
+            class: "CLEAN_DELETE",
+            gate: "PROCEEDS",
+            action: `delete ${key}, which wave ${args.wave} created.`
+        });
+    }
+    if (operation === "modify") {
+        const limitation = irreversibleModify(preSnapshot, postSnapshot);
+        if (limitation) {
+            return withDivergence({
+                ...base,
+                class: "IRREVERSIBLE",
+                gate: "REFUSED",
+                action: `no rollback for ${key}.`,
+                limitation
+            });
+        }
+        const sharing = sharingModelChange(preSnapshot, postSnapshot);
+        if (sharing)
+            evidence.push({ statement: sharing, basis: "MEASURED" });
+        // AN UNRUN CHECK IS A STATED BOUND, NOT SILENCE. Both detectors above compare pre against
+        // post, and `metadataOf(null)` is `{}` — so with no post snapshot every guard short-circuits
+        // and returns null, which the code below used to read as "nothing irreversible happened".
+        // That handed a picklist edit on an AMBIGUOUS_DELIVERY wave an unconditional PROCEEDS: the
+        // detectors go quiet in exactly the runs where org state is least certain (gap G1, confirmed
+        // by rollbackGaps.test.ts 2026-08-18). The class stays CLEAN_REDEPLOY — the pre-image and the
+        // redeploy are fine — but PROCEEDS is a certification this plan cannot issue, so the gate
+        // degrades to ACK_REQUIRED with the reason on the component, where its reader is. The
+        // plan-level AMBIGUOUS_DELIVERY note cannot carry this: it says a MISSING component is
+        // unknown, and this component is present and would otherwise read as measured-clean.
+        const unknownPost = postSnapshot === null
+            ? `no post-image exists for ${key}, so the irreversibility checks never ran: whether this edit added a picklist value (unremovable through the Metadata API), granted custom-metadata access, or moved an org-wide default was not established. Unknown is not clean — acknowledge to redeploy the pre-image anyway.`
+            : null;
+        const acks = [incompleteAck, sharing, unknownPost].filter((reason) => reason !== null);
+        return withDivergence({
+            ...base,
+            class: "CLEAN_REDEPLOY",
+            gate: image ? (acks.length > 0 ? "ACK_REQUIRED" : "PROCEEDS") : "BLOCKED_NO_IMAGE",
+            ackReasons: acks,
+            action: image
+                ? `redeploy ${key} from the wave's pre-image (${image.relPaths.join(", ")}).${incompleteAck ? " The image is INCOMPLETE — see the ack." : ""}${sharing ? " Re-deploying an org-wide default is slow and not atomic — see the ack." : ""}${unknownPost ? " Reversibility is UNKNOWN — see the ack." : ""}`
+                : `cannot redeploy ${key}: this bundle holds no pre/source image for it, so there are no bytes to restore. The change itself is cleanly reversible — the image is what is missing.`
+        });
+    }
+    // A delete. The undelete window applies to CUSTOM FIELDS ONLY: Salesforce's Deleted Fields list
+    // is a field feature, and no other type has one.
+    if (candidate.typeName === "CustomField") {
+        return withDivergence(await classifyDeletedField(args, base, image));
+    }
+    if (UNDELETABLE_TYPES.has(candidate.typeName)) {
+        // Reachable only from outside this tool — the API that refuses to delete a record type is the
+        // API a wave would have had to use. Classified rather than crashed, and lossy rather than clean,
+        // because re-creating one does not restore the records that were assigned to it.
+        evidence.push({
+            statement: `${candidate.typeName} cannot be deleted through the Metadata API, so this deletion did not come from a wave's own deploy.`,
+            basis: "MEASURED"
+        });
+        return withDivergence({
+            ...base,
+            class: "LOSSY_RECREATE",
+            gate: image ? "ACK_REQUIRED" : "BLOCKED_NO_IMAGE",
+            action: `re-create ${key} from the wave's pre-image.`,
+            ackReasons: [
+                `re-creating ${key} restores the definition only; every record assigned to it lost that assignment when it was deleted, and no deploy restores those.`
+            ]
+        });
+    }
+    return withDivergence({
+        ...base,
+        class: "CLEAN_REDEPLOY",
+        gate: image ? (incompleteAck ? "ACK_REQUIRED" : "PROCEEDS") : "BLOCKED_NO_IMAGE",
+        ackReasons: incompleteAck ? [incompleteAck] : [],
+        action: image
+            ? `re-create ${key} from the wave's pre-image (${image.relPaths.join(", ")}).${incompleteAck ? " The image is INCOMPLETE — see the ack." : ""}`
+            : `cannot re-create ${key}: this bundle holds no pre/source image, and after the delete that image was the only surviving definition of the component on this machine.`
+    });
+}
+/**
+ * A deleted custom field: in the window, or past it.
+ *
+ * PRESENCE IS THE AUTHORITY, the clock is the estimate. The probe verified 28/28 (and this
+ * implementation re-verified 34/34 on 2026-08-03) that the surviving Tooling set IS the in-window
+ * set, so when the two disagree — the derived lapse date has passed but Salesforce still lists the
+ * field — the derived date is what is wrong, and saying "lossy" over a field that is still sitting
+ * in Setup's Deleted Fields list would throw away recoverable DATA. The disagreement is reported.
+ */
+async function classifyDeletedField(args, base, image) {
+    const { key, candidate } = args;
+    const evidence = base.evidence;
+    const objectName = candidate.fullName.split(".")[0] ?? "";
+    const label = labelOf(args.pre.components.get(key)?.snapshot);
+    let probed = null;
+    if (args.probe && objectName)
+        probed = await askProbe(args.probeLedger, args.probe, objectName);
+    // The reverse difference `deletedFieldSet` returns "rather than asserts" so a caller can decide
+    // how much to trust the read — which no caller could, because `ObjectProbe` dropped it (G14).
+    // Non-empty means listMetadata saw fields Tooling did not: paging or scope trouble on the read,
+    // so the deleted set for this OBJECT may be missing members. Plan-level and once per object —
+    // it is a fact about the read, not about any one component.
+    if (probed && !probed.failed && probed.onlyLive.length > 0) {
+        const note = `the deleted-field probe's Tooling read for ${objectName} did not return ${probed.onlyLive.length} field(s) listMetadata sees (${probed.onlyLive.join(", ")}) — the read paged or scoped short, so the deleted set for this object may be incomplete and its answers deserve less trust.`;
+        if (!args.notes.includes(note))
+            args.notes.push(note);
+    }
+    const candidates = probed && !probed.failed ? matchDeletedField(probed.deleted, candidate.fullName) : [];
+    const presenceVerified = Boolean(probed && !probed.failed);
+    // The plan's own record of what the probe was worth for THIS component, so the summary header can
+    // state attempted-and-failed rather than inferring "ran" from the probe's mere existence.
+    args.probeLedger.presence.set(key, presenceVerified ? null : unansweredBecause(args.probe, probed));
+    // NO SUBSTITUTE CLOCK. `?? args.asOf` used to stand here, which turned a bundle with no
+    // `mutation-window.json` into a full 15-day window measured from the instant this ran, labelled
+    // `BUNDLE_WINDOW` as if the bundle had said so. See `undeleteWindowFor`.
+    const deletedAtBundle = args.deletedAtBundle;
+    const audit = probed
+        ? joinAuditRow(probed.audit, label, deletedAtBundle ? Date.parse(deletedAtBundle) : Number.NaN)
+        : { matched: 0 };
+    const window = undeleteWindowFor({
+        ...(deletedAtBundle ? { deletedAtBundle } : {}),
+        asOf: args.asOf,
+        candidates,
+        presenceVerified,
+        audit
+    });
+    if (!presenceVerified) {
+        evidence.push({
+            statement: probed?.failed
+                ? `the live deleted-field probe failed (${probed.failed}), so presence in Salesforce's Deleted Fields list is UNVERIFIED — not absent. The window below is the clock's answer alone.`
+                : `no live org probe was supplied, so presence in Salesforce's Deleted Fields list is UNVERIFIED — not absent. The window below rests on the recorded timestamps alone.`,
+            basis: "INFERRED"
+        });
+    }
+    else if (candidates.length > 0) {
+        evidence.push({
+            statement: `${key} is present in Tooling CustomField and absent from listMetadata as ${candidates.join(", ")} — the exact deleted-but-recoverable set. Presence implies it is still restorable.`,
+            basis: "MEASURED"
+        });
+        if (candidates.length > 1) {
+            evidence.push({
+                statement: `${candidates.length} deleted generations of this API name coexist (Salesforce suffixes a re-delete: _del, _del1, …). Setup's Deleted Fields list will show all of them and they hold different data; which one this wave deleted cannot be decided from the API.`,
+                basis: "INFERRED"
+            });
+        }
+    }
+    // Measured, and only decidable when the probe ran: the deleted set is empty for this field
+    // BECAUSE the field is back in `listMetadata`, not because Salesforce purged it.
+    const liveAgain = presenceVerified && candidates.length === 0 && (probed?.live.includes(candidate.fullName) ?? false);
+    if (presenceVerified && candidates.length === 0) {
+        evidence.push({
+            statement: liveAgain
+                ? `${key} is LIVE in the org again — it is in listMetadata, so it is not in the deleted set. Something restored or re-created it after this wave.`
+                : `${key} is in neither listMetadata nor the Tooling deleted set: the 15-day window has closed and Salesforce has erased the field and its data.`,
+            basis: "MEASURED"
+        });
+    }
+    if (window.deletedAtAudit) {
+        evidence.push({
+            statement: `SetupAuditTrail records a matching deletion at ${window.deletedAtAudit} (joined by field LABEL${window.auditRowsMatched > 1 ? `, ${window.auditRowsMatched} rows matched that label` : ""}) — inferred, not measured.`,
+            basis: "INFERRED"
+        });
+    }
+    if (window.basis === "UNVERIFIED") {
+        evidence.push({
+            statement: `wave ${args.wave} recorded no mutation window and no audit row joined this field's label, so WHEN it was deleted is not established from this bundle and no lapse date is derivable from it. A live probe of the deleted-field set is what resolves this.`,
+            basis: "INFERRED"
+        });
+    }
+    // A component that is back is not a loss and not a re-create. It is reported and left alone.
+    if (liveAgain) {
+        return {
+            ...base,
+            class: "ALREADY_LIVE",
+            gate: "NO_ACTION",
+            action: `nothing to roll back for the definition of ${key}: wave ${args.wave} deleted it, but it is live in the org again, so there is nothing for a rollback to re-create. Verify the live state matches what you want — the wave's pre-image is on this machine to compare against.`
+        };
+    }
+    // PRESENCE OUTRANKS THE CLOCK. Without presence the clock decides — and a clock that could not be
+    // read at all decides nothing, which leaves the non-lossy direction: "the data is permanently
+    // gone" is the one answer this module may never give without evidence, and Setup's Deleted Fields
+    // list is where an operator can see the truth for themselves.
+    const inWindow = presenceVerified
+        ? candidates.length > 0
+        : window.daysRemaining === null || window.daysRemaining >= 0;
+    if (inWindow) {
+        if (presenceVerified && window.daysRemaining !== null && window.daysRemaining < 0) {
+            evidence.push({
+                statement: `the derived lapse date (${window.lapsesAt}) has passed, yet Salesforce still lists the field as deleted-and-recoverable. Presence is measured and the date is derived, so the date is what is wrong; treated as in-window.`,
+                basis: "MEASURED"
+            });
+        }
+        const remaining = window.daysRemaining === null
+            ? ` This bundle establishes no delete timestamp, so how much of the 15-day window is left could not be computed here — a live probe of the deleted-field set, or Setup's own list, is what answers that.`
+            : window.daysRemaining >= 0
+                ? ` ${window.daysRemaining} day(s) left; lapses ${window.lapsesAt}.`
+                : "";
+        return {
+            ...base,
+            class: "UNDELETE_WINDOW",
+            gate: "OPERATOR_ACTION",
+            window,
+            action: `undelete ${key} in Setup (Object Manager → ${objectName} → Fields & Relationships → Deleted Fields → Undelete). Never re-created as metadata: the undelete restores the DATA, a re-create does not.${remaining}`
+        };
+    }
+    // A LAPSE NOTHING VERIFIED IS NOT A LAPSE AN ACK MAY SPEND. Presence outranks the clock above; it
+    // outranks it here too, and its ABSENCE is the whole question. What is left when the probe did not
+    // answer is `deletedAt + 15 days` — a derivation this module has already caught being wrong in the
+    // dangerous direction (see the `Presence is measured and the date is derived` branch above, where
+    // Salesforce still listed a field whose derived date had passed).
+    //
+    // The ONE remaining path where an unanswered check reached a destructive outcome. Everything else
+    // in this module withholds when a check does not answer — presence stays UNVERIFIED rather than
+    // absent, a missing timestamp leaves the window UNVERIFIED rather than borrowing `asOf`,
+    // NOT_COMPARABLE is carded as a check that did not run. This branch alone converted silence into a
+    // one-key release for a deploy that destroys data, which is that doctrine inverted.
+    //
+    // SO THE GATE MOVES AND THE CLASS DOES NOT. The belief is still lossy — that is what the clock
+    // says, and saying otherwise would promise an undelete nothing established either. What changes is
+    // what the tool may DO with the belief, which is exactly the split `RollbackGate` exists for: the
+    // operator opens Setup and looks, and the answer they bring back is a measurement rather than an
+    // inference. `isUnverifiedLapse` is how U10's chokepoint recognises this state.
+    //
+    // NO GRACE MARGIN, deliberately. "Far enough past the date that no probe is needed" was the
+    // alternative, and it requires a constant nobody measured, guarding the exact claim this module
+    // refuses to make on inference; at the margin's own boundary it would authorise a destructive
+    // re-create on the strength of a number we invented. The remedy for a check that did not answer is
+    // a check that answers — re-run with the org reachable — not a bigger clock.
+    if (!presenceVerified) {
+        const reason = unverifiedLapseReason({ key, window, probeReason: unansweredBecause(args.probe, probed) });
+        evidence.push({ statement: reason, basis: "INFERRED" });
+        return {
+            ...base,
+            class: "LOSSY_RECREATE",
+            gate: "OPERATOR_ACTION",
+            window,
+            action: unverifiedLapseAction({ key, objectName, ...(image ? { image } : {}) }),
+            ackReasons: [reason]
+        };
+    }
+    // The ack says what is KNOWN, term by term — a lapse date that has not arrived is not a closure
+    // date, and a window that was never established is not one either.
+    const deletedPhrase = window.deletedAtBundle ? `was deleted ${window.deletedAtBundle}` : `was deleted by wave ${args.wave}`;
+    const windowPhrase = window.lapsesAt === undefined
+        ? `its undelete window could not be established from this bundle, and Salesforce no longer lists it as deleted-and-recoverable`
+        : window.daysRemaining !== null && window.daysRemaining >= 0
+            ? `Salesforce no longer lists it as deleted-and-recoverable, ahead of the derived lapse date ${window.lapsesAt}`
+            : `its undelete window closed ${window.lapsesAt}`;
+    return {
+        ...base,
+        class: "LOSSY_RECREATE",
+        gate: image ? "ACK_REQUIRED" : "BLOCKED_NO_IMAGE",
+        window,
+        action: image
+            ? `re-create ${key} from the wave's pre-image (${image.relPaths.join(", ")}). The definition returns; the data does not.`
+            : `cannot re-create ${key}: the undelete window is gone AND this bundle holds no pre/source image, so neither the data nor the definition can be restored from this machine.`,
+        ackReasons: [
+            `${key} ${deletedPhrase} and ${windowPhrase}. Re-creating it returns the field DEFINITION only — every value every record held in it is permanently gone.`
+        ]
+    };
+}
+/**
+ * A lossy re-create whose ONLY evidence of lapse is a clock nobody checked against the org.
+ *
+ * THE ONE PREDICATE, ASKED IN THREE PLACES. `classifyDeletedField` and `recheckUndeleteWindow` gate
+ * on this state, and U10's chokepoint refuses to build a deploy containing one. Re-deriving the
+ * question at the chokepoint is how a guard comes to disagree with the rule it guards — the same
+ * shape as U9's divergence handling rewriting a gate the AE4 check was reading.
+ *
+ * EXACT BY CONSTRUCTION, not by luck: a deleted field whose window is `UNVERIFIED` has a null
+ * `daysRemaining`, which keeps it in `UNDELETE_WINDOW` rather than letting it reach lossy at all, and
+ * the only other producer of `LOSSY_RECREATE` (a delete of an undeletable type) carries no window. So
+ * `LOSSY_RECREATE` + a window + unverified presence is precisely "the clock said so and nothing else
+ * did".
+ */
+export const isUnverifiedLapse = (component) => component.class === "LOSSY_RECREATE" && component.window !== undefined && !component.window.presenceVerified;
+/**
+ * What a lapse nothing verified establishes — which is nothing about the org.
+ *
+ * WRITTEN ONCE because both ends of the wait say it: `classifyDeletedField` when the probe never
+ * answered in the first place, and `recheckUndeleteWindow` when the token that worked on Monday has
+ * expired by Thursday. Two texts drifting apart is how the header came to contradict the evidence.
+ *
+ * IT NAMES BOTH HALVES OF WHAT IS MISSING. The date can be inferred (an audit row joined by field
+ * LABEL, and labels repeat — 3 of 34 in-window labels collided in the live probe), and the check that
+ * would have settled it did not answer. An operator told only "the window closed" has been handed the
+ * conclusion without either premise.
+ */
+function unverifiedLapseReason(args) {
+    const closed = args.window.lapsesAt
+        ? `the ${UNDELETE_WINDOW_DAYS}-day undelete window derived for it ran out ${args.window.lapsesAt}`
+        : "its undelete window could not be established from this bundle";
+    const anchor = args.window.basis === "AUDIT_TRAIL_INFERRED"
+        ? ", and that date is itself INFERRED — derived from a SetupAuditTrail row joined by field LABEL, which is not an identity"
+        : "";
+    return (`${args.key}: ${closed}${anchor}. NOTHING VERIFIED IT — ${args.probeReason} — so presence in Salesforce's ` +
+        "Deleted Fields list is UNVERIFIED, not absent, and \"the data is gone\" is this clock's inference rather than the " +
+        "org's answer. No acknowledgement releases a re-create on that: if the field is still listed, an undelete restores " +
+        "it AND ITS DATA, and a re-create would destroy exactly what the undelete would have brought back.");
+}
+/** What the operator does about it — the only move that turns the inference into an answer. */
+function unverifiedLapseAction(args) {
+    return (`settle ${args.key} in Setup before anything re-creates it (Object Manager → ${args.objectName} → Fields & ` +
+        "Relationships → Deleted Fields). If it is listed, UNDELETE it — the data is intact and this plan's clock was " +
+        "wrong. If it is not listed, the field and its data are gone; re-run this rollback with the org reachable so the " +
+        "probe can measure that, and the re-create is offered for your acknowledgement then." +
+        (args.image ? "" : " This bundle holds no pre/source image either, so no re-create is available from this machine in any case."));
+}
+/** A component's label, for the audit-trail join. Never used as an identity. */
+function labelOf(snapshot) {
+    const label = metadataOf(snapshot).label;
+    return typeof label === "string" ? label : undefined;
+}
+async function divergenceFor(args, operation) {
+    if (!args.live || !args.live.has(args.key))
+        return null;
+    const entry = args.pre.components.get(args.key)?.entry ?? args.post?.components.get(args.key)?.entry;
+    return preflightDivergence({
+        orgId: args.orgId,
+        component: {
+            typeName: args.candidate.typeName,
+            fullName: args.candidate.fullName,
+            ...(entry?.file ? { file: entry.file } : {})
+        },
+        // A delete's recorded post-image is ABSENCE. Reading the post projection for it would find
+        // either nothing or a snapshot the deploy had already invalidated.
+        recordedPost: operation === "delete" ? null : (args.post?.components.get(args.key)?.snapshot ?? null),
+        live: args.live.get(args.key) ?? null,
+        target: { sessionId: args.sessionId, wave: args.wave },
+        notes: args.notes,
+        ...(args.root ? { root: args.root } : {})
+    });
+}
+/**
+ * Re-ask the undelete question at execution time, and downgrade whatever has lapsed.
+ *
+ * THE REASON THIS EXISTS AS ITS OWN STEP. A classification is a statement about an instant. An
+ * operator reads "11 days left, undelete in Setup", takes it to a change board, and comes back on
+ * day 16 — by which point Salesforce has erased the field and its data, and the plan in their hand
+ * still promises a clean recovery. A rollback that acts on that plan reports success while the data
+ * it claimed to protect is gone. The window is per FIELD, not per run (the probe measured two
+ * delete dates 8 days apart inside one cleanup), so this asks per component.
+ *
+ * ONE-DIRECTIONAL BY DESIGN: this can only take a component OUT of `UNDELETE_WINDOW` — to
+ * `LOSSY_RECREATE` when Salesforce purged it, or to `ALREADY_LIVE` when it left the deleted set by
+ * coming back. A lossy component does not become recoverable because a probe now succeeds — if the
+ * field reappeared in the deleted set, something deleted it again, and that is a different deletion
+ * with a different window and different data behind it.
+ *
+ * AND THE WITHDRAWAL IS NOT ITSELF A PROMISE. The probe that answered on Monday can fail on
+ * Thursday — a token expires exactly across that gap — and then the only thing saying the window ran
+ * out is the clock the plan already carried. That withdraws the undelete, because a promise nothing
+ * supports may not stand; it does not hand over a re-create, because nothing supports that either.
+ * The class moves and the GATE goes to the operator. See `isUnverifiedLapse`.
+ */
+export async function recheckUndeleteWindow(args) {
+    const reclassified = [];
+    // Seeded with the classification's answers, then overwritten by this pass for what it touches. The
+    // re-check asks a fresher org, so its answer supersedes — and a plan that carried the first pass's
+    // outcome unchanged would report a token that expired in between as a probe that measured.
+    //
+    // AND NOT SEEDED AT ALL WHEN THERE IS NO PROBE, which is the same rule read the other way. A pass
+    // that cannot ask has not asked, and republishing the earlier pass's objects and failures under
+    // this pass's outcome is how the header came to read `ATTEMPTED, FAILED — nothing answered` over
+    // components whose own recorded reason was that no probe was supplied. Unreachable through
+    // `runRollback` (one reader decides both passes), and this function is exported.
+    const ledger = args.probe ? seedProbeLedger(args.plan.probe) : newProbeLedger();
+    const components = [];
+    for (const component of args.plan.components) {
+        if (component.class !== "UNDELETE_WINDOW" || !component.window) {
+            components.push(component);
+            continue;
+        }
+        const objectName = component.fullName.split(".")[0] ?? "";
+        let probed = null;
+        if (args.probe && objectName)
+            probed = await askProbe(ledger, args.probe, objectName);
+        const presenceVerified = Boolean(probed && !probed.failed);
+        ledger.presence.set(component.key, presenceVerified ? null : unansweredBecause(args.probe, probed));
+        const candidates = presenceVerified ? matchDeletedField(probed?.deleted ?? [], component.fullName) : [];
+        const window = {
+            ...component.window,
+            candidates: presenceVerified ? candidates : component.window.candidates,
+            presenceVerified,
+            daysRemaining: component.window.lapsesAt
+                ? Math.floor((Date.parse(component.window.lapsesAt) - Date.parse(args.asOf)) / DAY_MS)
+                : null
+        };
+        // Presence still outranks the clock (see `classifyDeletedField`). Without a probe the clock is
+        // all there is, and a clock that says the window closed is enough to withdraw the promise — but
+        // a window that was never established says nothing, and silence does not withdraw anything.
+        const stillInWindow = presenceVerified
+            ? candidates.length > 0
+            : window.daysRemaining === null || window.daysRemaining >= 0;
+        if (stillInWindow) {
+            components.push({ ...component, window });
+            continue;
+        }
+        // The same question `classifyDeletedField` asks, at the other end of the wait: an empty deleted
+        // set means PURGED only if the component is not simply live again. Somebody restoring the field
+        // between classification and execution must not be reported as the data being destroyed.
+        if (presenceVerified && (probed?.live.includes(component.fullName) ?? false)) {
+            const reason = `${component.key} has left Salesforce's deleted-field set by coming BACK: it is in listMetadata again, so something restored or re-created it since this plan was made. There is nothing to re-create and nothing was lost.`;
+            reclassified.push({ key: component.key, from: "UNDELETE_WINDOW", to: "ALREADY_LIVE", reason });
+            components.push({
+                ...component,
+                class: "ALREADY_LIVE",
+                gate: "NO_ACTION",
+                window,
+                action: `nothing to roll back for the definition of ${component.key}: it is live in the org again. Verify the live state matches what you want.`,
+                evidence: [...component.evidence, { statement: reason, basis: "MEASURED" }]
+            });
+            continue;
+        }
+        // WITHDRAWN IS NOT INVERTED. The promise of a clean undelete goes the moment the clock says the
+        // window ran out — but when nothing checked the org, an ack that buys the re-create does not
+        // arrive in its place. That is `classifyDeletedField`'s rule at the other end of the wait, and
+        // it is worded there for both ends; see `unverifiedLapseReason` and `isUnverifiedLapse`.
+        if (!presenceVerified) {
+            const reason = unverifiedLapseReason({
+                key: component.key,
+                window,
+                probeReason: unansweredBecause(args.probe, probed)
+            });
+            reclassified.push({ key: component.key, from: "UNDELETE_WINDOW", to: "LOSSY_RECREATE", reason });
+            components.push({
+                ...component,
+                class: "LOSSY_RECREATE",
+                gate: "OPERATOR_ACTION",
+                window,
+                action: unverifiedLapseAction({
+                    key: component.key,
+                    objectName,
+                    ...(component.image ? { image: component.image } : {})
+                }),
+                ackReasons: [...component.ackReasons, reason],
+                evidence: [...component.evidence, { statement: reason, basis: "INFERRED" }]
+            });
+            continue;
+        }
+        const closedAt = window.lapsesAt ? ` at ${window.lapsesAt}` : "";
+        const reason = `${component.key} is no longer in Salesforce's deleted-field set: the ${UNDELETE_WINDOW_DAYS}-day window closed${closedAt} and the field and its data have been erased. The undelete this plan offered is no longer available.`;
+        reclassified.push({ key: component.key, from: "UNDELETE_WINDOW", to: "LOSSY_RECREATE", reason });
+        components.push({
+            ...component,
+            class: "LOSSY_RECREATE",
+            gate: component.image ? "ACK_REQUIRED" : "BLOCKED_NO_IMAGE",
+            window,
+            action: component.image
+                ? `re-create ${component.key} from the wave's pre-image (${component.image.relPaths.join(", ")}). The definition returns; the data does not.`
+                : `cannot re-create ${component.key}: the undelete window has closed AND this bundle holds no pre/source image.`,
+            ackReasons: [...component.ackReasons, reason],
+            evidence: [...component.evidence, { statement: reason, basis: "MEASURED" }]
+        });
+    }
+    return {
+        plan: {
+            ...args.plan,
+            asOf: args.asOf,
+            components,
+            probe: probeOutcome(ledger, Boolean(args.probe))
+        },
+        reclassified
+    };
+}