in2-agent-server 0.20260821.185429

package/dist/direct/batchReport.js

@@ -0,0 +1,510 @@
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { sessionDir } from "../core/workspace.js";
+import { computeContamination, renderContamination } from "./contamination.js";
+import { historyLog } from "./orgRepo.js";
+import { preImageTargets } from "./preImageTargets.js";
+import { archivedContributingAttempts } from "./rollback.js";
+import { resolveRollbackBaseline } from "./rollbackRun.js";
+import { gradeWaves, readWaveBundles } from "./waveGrade.js";
+import { plannedKey, readPlannedScope } from "./plannedScope.js";
+import { expandComponent } from "./containers.js";
+/** How much of the org's history the report SHOWS; the requirement join reads far deeper. */
+const DISPLAYED_DELIVERIES = 50;
+/**
+ * Decorate the graded bundles with the two facts only this report asks for.
+ *
+ * The scan and the GRADE both come from `waveGrade.ts`, which `finalizeBatch` also calls. That is
+ * the whole point: the report and the terminal event cannot disagree about how many waves delivered
+ * or what the batch's result is, because neither of them decides it.
+ */
+async function readWaves(sessionId, graded, deliveries) {
+    const dir = path.join(sessionDir(sessionId), "direct");
+    // Requirement ids live on the mirror's commit trailers, not in the bundle — the bundle records
+    // what was deployed, the commit records what it was for. Joined by (session, wave) rather than
+    // by wave alone, since one org's history holds every session's waves.
+    const requirementsByWave = new Map();
+    for (const entry of deliveries) {
+        if (entry.sessionId === sessionId && entry.wave && !requirementsByWave.has(entry.wave)) {
+            requirementsByWave.set(entry.wave, entry.requirementIds);
+        }
+    }
+    return Promise.all(graded.map(async (wave) => {
+        const bundle = path.join(dir, wave.wave);
+        // Resolved ONCE and fed to both answers below — the image attestation and the
+        // touched-existing-state grade are two halves of one claim about one wave, and resolving
+        // the baseline separately is how they got to disagree.
+        const baseline = await resolveRollbackBaseline(bundle);
+        return {
+            wave: wave.wave,
+            verdict: wave.verdict,
+            dryRunOnly: wave.dryRunOnly,
+            classification: wave.classification,
+            resolvedBy: wave.resolvedBy,
+            rollbackImage: hasRollbackImage(baseline),
+            touchedExistingState: await touchedExistingState(bundle, baseline),
+            requirementIds: requirementsByWave.get(wave.wave) ?? []
+        };
+    }));
+}
+/**
+ * Whether the bundle holds a deployable rollback image AT AN ADDRESS `direct_rollback` would
+ * actually use.
+ *
+ * WHY: checking `<bundle>/pre/source` directly (as this used to) overclaims for a retried wave.
+ * `direct_rollback` resolves its pre-image root through `resolveRollbackBaseline` before it reads
+ * anything under `pre/source` — a legacy bundle retried before per-attempt archiving existed has no
+ * honest baseline and the tool REFUSES it outright (this report must then say NO, not YES), and an
+ * archived retry's honest baseline lives under `attempts/1/`, not the bundle's own attempt-N-
+ * overwritten `pre/` (this report must check THAT tree, not the top-level one). This report must
+ * never attest an image the rollback tool itself would not use.
+ */
+function hasRollbackImage(baseline) {
+    if (!baseline.ok)
+        return false;
+    // `retrievePreImageSource` writes to `<preRoot>/pre/source`. Reading `<bundle>/source` instead
+    // found nothing on any bundle ever written, so every wave read as having no rollback image.
+    return existsSync(path.join(baseline.preRoot, "pre", "source"));
+}
+/**
+ * Did this wave touch anything that already existed?
+ *
+ * Asked of the REQUESTS and the PRE-PROJECTION — the same inputs, through the same
+ * `preImageTargets`, that the apply loop used to decide what to retrieve an image FOR. The report
+ * and the retrieve therefore cannot disagree about which components had prior state, which is the
+ * only way "this wave is missing its rollback image" means anything. For a retried wave that means
+ * every attempt that may have landed (`archivedContributingAttempts`), measured against the
+ * RESOLVED baseline's manifest — the final attempt's request alone erases whatever an earlier
+ * landed attempt destroyed.
+ *
+ * It is NOT asked of the three-way diff, which was the live-caught defect. The diff is a comparison
+ * of two projections and has no concept of intent: it files a CREATE as a `changed` entry whose
+ * `before` is the string `"null"` and a DELETE as one whose `after` is `"null"`, while `added` and
+ * `removed` sat empty on all four waves of the run that caught this. Counting `changed` entries
+ * therefore graded two brand-new fields as edits of existing state. Nor can the diff answer at all
+ * for a dryRunOnly bundle, which never reaches it and has no `diff` key — those defaulted to
+ * "added only", printing a false n/a over practice bundles that target live components.
+ *
+ * FAILS LOUD, not quiet. A bundle whose request or manifest cannot be read cannot establish that it
+ * added only, and the two directions of that guess are not symmetric: a wrong `false` hides a
+ * missing rollback image, which is the failure this finding exists to catch, while a wrong `true`
+ * costs one over-reported wave that a reader can check against the bundle. Every bundle that
+ * reaches a verdict has both files — `request.json` is written before the org is read at all — so
+ * this is reachable only on a corrupt bundle.
+ */
+async function touchedExistingState(bundle, baseline) {
+    // A bundle the rollback tool refuses cannot establish that it added only — fail loud.
+    if (!baseline.ok)
+        return true;
+    try {
+        const request = JSON.parse(await fs.readFile(path.join(bundle, "request.json"), "utf8"));
+        // The manifest comes from the RESOLVED baseline, and the requests from every attempt that may
+        // have landed — a retried wave whose final attempt named only brand-new components still
+        // destroyed whatever an earlier landed attempt deleted, and grading it off the final request
+        // against the final pre/ read exactly that wave as "added only".
+        const manifest = JSON.parse(await fs.readFile(path.join(baseline.preRoot, "pre", "projection.json"), "utf8"));
+        if (!manifest.components)
+            return true;
+        const requests = [request, ...(await archivedContributingAttempts(bundle)).map((a) => a.request)];
+        return requests.some((r) => preImageTargets(r.edits ?? [], r.deletes ?? [], (r.facetUpdates ?? []).map((f) => f.objectApiName), { components: manifest.components }).length > 0);
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * The configurations a DELIVERING wave actually put in the org, at Configuration Item grain.
+ *
+ * Read from each delivered bundle's own `request.json` and expanded through the SAME
+ * `expandComponent` the planned scope and `campfire_config_item_plan` use. That shared expansion is
+ * the whole contract: a numerator counting deployed FILES against a denominator counting
+ * configurable COMPONENTS is QA round 1 item 24, and it would report a rate no evidence supports.
+ *
+ * A SET, not a sum. One component deployed twice — the revision model's ordinary create-then-update
+ * across two waves — is one configuration, and summing wave membership would produce rates above
+ * 100% on runs that did more work, not less.
+ *
+ * Practice runs are excluded by construction: only `delivered` bundles are read, and a dry run
+ * changed nothing by contract.
+ */
+async function deliveredConfigurations(sessionId, waves) {
+    const dir = path.join(sessionDir(sessionId), "direct");
+    const out = new Set();
+    for (const wave of waves) {
+        if (wave.classification !== "delivered")
+            continue;
+        try {
+            const request = JSON.parse(await fs.readFile(path.join(dir, wave.wave, "request.json"), "utf8"));
+            for (const edit of request.edits ?? []) {
+                // The submitted XML is on the request, so a container expands here exactly as it did at
+                // planning. An edit with no XML counts once at its own grain, matching the planned side's
+                // treatment of an entry with no authored file.
+                for (const c of expandComponent(edit.typeName, edit.fullName, edit.xml)) {
+                    out.add(plannedKey(c));
+                }
+            }
+            // A verified REMOVAL is a completed configuration — operator-voice.md is explicit that a
+            // removal counts as completed. It has no submitted XML to expand, so it counts at its own key.
+            for (const del of request.deletes ?? [])
+                out.add(plannedKey(del));
+            // A FACET UPDATE is a CRUD read-modify-write of the object itself, and
+            // `campfire_config_item_plan` derives a `CustomObject` Configuration Item from it
+            // (`deriveFromBundle.ts`, the `facetUpdates` loop). Omitting it here would make a batch whose
+            // only change to an object was its sharing model count that object as planned-but-not-
+            // automated, while Campfire records a CI for it — the two rows of the panel disagreeing,
+            // which is the failure this whole grain discipline exists to prevent.
+            for (const facet of request.facetUpdates ?? []) {
+                out.add(plannedKey({ typeName: "CustomObject", fullName: facet.objectApiName }));
+            }
+        }
+        catch {
+            // An unreadable bundle contributes nothing rather than failing the report. The consequence is
+            // a LOW numerator — a conservative rate, never an inflated one.
+        }
+    }
+    return out;
+}
+/**
+ * The four counts, or null when nothing recorded what this batch was asked for.
+ *
+ * The intersection is the point. `automated` counts only planned configurations the delivery
+ * proved, so the numerator can never exceed the denominator, and anything delivered that no plan
+ * owned lands in `outsideScope` — reported, and in neither half of the rate.
+ */
+function computeScope(planned, delivered) {
+    const plannedKeys = new Set(planned.components.map(plannedKey));
+    const manualKeys = new Set(planned.manual.map(plannedKey));
+    // NOT in the denominator: no metadata deploy could ever satisfy these, so counting them
+    // against the rate measures the requirement mix, not the tool. Reported as their own count.
+    // Absent on scope files written before the field existed — reads as empty, the old math.
+    const unautomatableKeys = new Set((planned.unautomatable ?? []).map(plannedKey));
+    // A DELIVERY IS EVIDENCE, AND EVIDENCE OUTRANKS A PLAN-TIME ROUTE.
+    //
+    // The loops below dedup only OUTWARD FROM `plannedKeys`, so a component the plan routed to a
+    // person and a later wave then delivered was matched by no case: uncredited in the numerator,
+    // still counted as manual, AND flagged outsideScope — three wrong statements about one
+    // component, and the middle one is an actionable falsehood that sends a consultant into Setup to
+    // redo work the org already holds. Promoting the key here is the whole fix; the existing loops
+    // do the removals. For a manual key the denominator is unchanged (one gained on the left, one
+    // lost on the right). For an unautomatable key it GROWS by one, deliberately: those are excluded
+    // on the premise that no metadata deploy could ever satisfy them, and an observed delivery
+    // disproves the premise for that key.
+    for (const key of delivered) {
+        if (manualKeys.has(key) || unautomatableKeys.has(key))
+            plannedKeys.add(key);
+    }
+    // A component both deployed and routed is counted once, on the deployed side: the route was the
+    // fallback, and the deploy is what the org read-back can prove.
+    for (const key of plannedKeys) {
+        manualKeys.delete(key);
+        unautomatableKeys.delete(key);
+    }
+    // A key both ordinarily-manual and unautomatable (two plans, two causes) counts once, on the
+    // manual side — the fail-closed direction: against the rate rather than out of it.
+    for (const key of manualKeys)
+        unautomatableKeys.delete(key);
+    const denominator = plannedKeys.size + manualKeys.size;
+    const automated = [...plannedKeys].filter((key) => delivered.has(key)).length;
+    return {
+        planned: denominator,
+        automated,
+        manual: manualKeys.size,
+        unautomatable: unautomatableKeys.size,
+        // A zero denominator would make this 0/0. It cannot arise with a scope on disk that holds any
+        // component, and a scope holding none is not a batch anyone measured — report 0 rather than NaN.
+        automationRate: denominator === 0 ? 0 : Math.round((automated / denominator) * 100),
+        outsideScope: [...delivered].filter((key) => !plannedKeys.has(key)).length
+    };
+}
+/**
+ * Findings true of the BATCH.
+ *
+ * Deliberately conservative: each one is computed from evidence on disk and says what is missing
+ * rather than what it implies. "No wave in this batch has a deployable rollback image" is a fact;
+ * "this batch is unsafe" would be an opinion the evidence does not carry.
+ */
+function batchFindings(waves, contamination) {
+    const findings = [];
+    // Only waves that changed or removed something that already existed can HAVE a rollback image;
+    // see WaveOutcome.touchedExistingState for why pure additions are excluded rather than graded.
+    const atRisk = waves.filter((w) => w.classification === "delivered" && w.touchedExistingState);
+    const withoutImage = atRisk.filter((w) => !w.rollbackImage);
+    if (atRisk.length > 0 && withoutImage.length === atRisk.length) {
+        findings.push(`NO ROLLBACK IMAGE FOR ANY WAVE THAT CHANGED EXISTING STATE — all ${atRisk.length} such wave(s) (${atRisk.map((w) => w.wave).join(", ")}) delivered without retrieving a deployable pre-image. ` +
+            `Undoing any of them means re-authoring the prior state by hand: the JSON snapshots under each bundle's pre/ verify the diff but cannot be redeployed. ` +
+            `Waves that only ADDED components are excluded — undoing an add is a deletion, so their missing pre-image is correct, not a gap.`);
+    }
+    else if (withoutImage.length > 0) {
+        findings.push(`${withoutImage.length} of ${atRisk.length} wave(s) that changed existing state have NO deployable rollback image: ${withoutImage.map((w) => w.wave).join(", ")}. The rest can be redeployed from their bundle's source/.`);
+    }
+    // Requirement attribution is mandatory per the playbook ("Pass `requirementIds` on every
+    // direct_apply"), and it is the ONLY thing that survives into the org's own history to answer
+    // "why does this field exist?" months later. A wave that delivered without it is a permanent gap
+    // rather than a formatting one, so the batch says so while the run is still in living memory.
+    const unattributed = waves.filter((w) => w.classification === "delivered" && w.requirementIds.length === 0);
+    if (unattributed.length > 0) {
+        findings.push(`${unattributed.length} delivering wave(s) recorded NO requirement ids (${unattributed.map((w) => w.wave).join(", ")}) — ` +
+            `the org's history will not say what those components were for. Pass \`requirementIds\` on every direct_apply; it cannot be added after the fact.`);
+    }
+    // A PRACTICE RUN THE ORG OR THE LINT REFUSED. Reported in EVERY case, whether or not it counted
+    // against the grade — the grade decides how loud this is, never whether the operator hears it.
+    // Its two halves are separate findings because they ask the reader for different things.
+    const blocked = waves.filter((w) => w.classification === "practice-blocked");
+    const unanswered = blocked.filter((w) => w.resolvedBy === null);
+    if (unanswered.length > 0) {
+        findings.push(`${unanswered.length} practice run(s) were REFUSED and nothing in this batch went on to do it (${unanswered.map((w) => `${w.wave} — ${w.verdict}`).join("; ")}). ` +
+            `A dry run exists to find this before the real wave, so it did its job — but the work it was checking has not been delivered here. ` +
+            `Check whether it was resolved elsewhere, abandoned on purpose, or is still outstanding.`);
+    }
+    const answered = blocked.filter((w) => w.resolvedBy !== null);
+    if (answered.length > 0) {
+        findings.push(`${answered.length} practice run(s) were refused and then delivered anyway by a later wave (${answered.map((w) => `${w.wave} → ${(w.resolvedBy ?? []).join(", ")}`).join("; ")}) — ` +
+            `not counted against this batch. That is a SCOPE match (same components, same operation, verified delivery), not proof the reason for the refusal was understood; the delivery log above shows both.`);
+    }
+    const ambiguous = waves.filter((w) => w.verdict === "AMBIGUOUS_DELIVERY" && !w.dryRunOnly);
+    if (ambiguous.length > 0) {
+        findings.push(`${ambiguous.length} wave(s) recorded an AMBIGUOUS_DELIVERY (${ambiguous.map((w) => w.wave).join(", ")}) — the post-image is partial, so what reached the org is not fully established from this machine's evidence.`);
+    }
+    if (contamination && contamination.readSet.opaqueReads > 0) {
+        findings.push(`${contamination.readSet.opaqueReads} org read(s) named no component, so the contamination result below is a floor and not a clean bill of health.`);
+    }
+    return findings;
+}
+/**
+ * Was this batch's work ALREADY DONE before it started?
+ *
+ * THE DEFECT (QA round 2, Matt Nelson): when every requested configuration already existed, the
+ * analyzers authored nothing to deploy, no bundle was written, and `gradeWaves` returned NO_WAVES —
+ * whose rendering is one sentence written for a different situation: "A run that only read has no
+ * batch result to state." The operator read a successful outcome as a dead end. His words: "here's
+ * what you asked for. It already existed in the org. Like duplicate verified."
+ *
+ * THE DISTINGUISHING EVIDENCE is the planned scope, and it is why this could not be decided from
+ * bundles alone. A read-only run and an already-satisfied run leave the SAME empty `direct/`
+ * directory; what separates them is that one of them planned N configurations and the other planned
+ * nothing. That fact now survives to close, so the two stop collapsing.
+ *
+ * NARROW ON PURPOSE — four conditions, each closing a way this could overclaim:
+ *   - `NO_WAVES` only. A batch that graded COMPLETE, FAILED or NEEDS_ATTENTION has a delivery
+ *     result of its own and this must never overwrite it.
+ *   - NO WAVE BUNDLES AT ALL. `gradeResult` returns NO_WAVES for two different runs: one with no
+ *     bundles, and one whose bundles were all accepted PRACTICE runs. Only the first is evidence
+ *     that the analyzers found nothing to author. A batch that dry-ran three configurations and
+ *     stopped there touched the org with nothing and verified the presence of nothing — declaring
+ *     it "already configured, all 3 were already in place" invents a projection result out of a
+ *     rehearsal. `core/telemetry.ts`'s `finalizeBatch` already classifies that run correctly ("a
+ *     run that only read **or only practiced**"); this condition is what stops the two subsystems
+ *     from contradicting each other on the same evidence.
+ *   - A scope with at least one PLANNED component. Zero planned is a run that asked for nothing.
+ *   - No MANUAL routes outstanding. A batch that still owes a person work is not satisfied, and
+ *     saying so would be the flattering error §4 of the handoff forbids.
+ *
+ * What it does NOT establish: that anything was re-verified just now. The claim is "this batch
+ * deployed nothing and everything it planned was already present at planning time", grounded in
+ * the projection the scope records. The rendering says exactly that and no more.
+ */
+function alreadySatisfied(result, waveCount, scope) {
+    return (result === "NO_WAVES" &&
+        waveCount === 0 &&
+        scope !== null &&
+        scope.components.length > 0 &&
+        scope.manual.length === 0);
+}
+/** Compute the batch's closing report. Reads only — no org contact, no writes. */
+export async function composeBatchReport(input) {
+    // Each source is independently guarded: this runs at batch close, and one unavailable input must
+    // degrade its own section rather than cost the whole report.
+    // Reads DEEP, displays shallow. The join needs this session's own entries, and a busy org buries
+    // them: on the dev install this session's four waves sat at positions 51-64, so a 50-entry window
+    // attributed none of them. The requirement ids are the only record of what a wave was FOR, so the
+    // window that finds them is not the window a reader wants to scroll.
+    let history = [];
+    try {
+        history = await historyLog({
+            orgId: input.orgId,
+            limit: 500,
+            ...(input.root ? { root: input.root } : {})
+        });
+    }
+    catch {
+        history = [];
+    }
+    const deliveries = history.slice(0, DISPLAYED_DELIVERIES);
+    // Reads the log first: the bundles carry the verdicts, the log carries the requirement ids.
+    // The GRADE is not computed here — `gradeWaves` owns it, and `finalizeBatch` calls the same
+    // function on the same bundles, so the local report and the ledger's terminal event state one
+    // result rather than two that happen to agree.
+    const grade = gradeWaves(readWaveBundles(path.join(sessionDir(input.sessionId), "direct")));
+    const waves = await readWaves(input.sessionId, grade.waves, history);
+    let contamination = null;
+    try {
+        contamination = await computeContamination({
+            sessionId: input.sessionId,
+            orgId: input.orgId,
+            ...(input.orgAlias ? { orgAlias: input.orgAlias } : {}),
+            ...(input.root ? { root: input.root } : {})
+        });
+    }
+    catch {
+        contamination = null;
+    }
+    // The denominator, and the two counts taken over it. Independently guarded like every other
+    // source here: a session with no recorded scope reports no rate rather than failing the close.
+    const plannedScope = await readPlannedScope(input.sessionId);
+    // Resolved ONCE and used for both the counts and the page. Awaited unconditionally rather than
+    // inside the ternary so the page can still enumerate what the org proved on a batch that
+    // recorded no denominator.
+    const delivered = await deliveredConfigurations(input.sessionId, waves);
+    const scope = plannedScope ? computeScope(plannedScope, delivered) : null;
+    return {
+        sessionId: input.sessionId,
+        orgId: input.orgId,
+        generatedAt: new Date().toISOString(),
+        // ALREADY_SATISFIED is decided HERE rather than in `waveGrade`, and deliberately so. That
+        // module is synchronous and dependency-free because `finalizeBatch` may run inside a signal
+        // handler; the planned scope is an async read it must not take. So the grade stays the one
+        // rule about BUNDLES, and this narrows its NO_WAVES using evidence bundles cannot carry.
+        result: alreadySatisfied(grade.result, grade.waves.length, plannedScope) ? "ALREADY_SATISFIED" : grade.result,
+        scope,
+        plannedScope,
+        deliveredKeys: [...delivered],
+        waves,
+        deliveredWaves: grade.deliveredWaves,
+        problemWaves: grade.problemWaves,
+        practiceRuns: grade.practiceRuns,
+        findings: batchFindings(waves, contamination),
+        deliveries,
+        contamination
+    };
+}
+/** Render the report as the markdown the artifact holds and `close_batch` returns. */
+export function renderBatchReport(report) {
+    const lines = [
+        `# Batch close — session ${report.sessionId}`,
+        ``,
+        `Org ${report.orgId} · generated ${report.generatedAt}`,
+        ``,
+        `## Result: ${report.result}`,
+        ``
+    ];
+    // THE DENOMINATOR, FIRST. The operator's complaint was not that the numbers were wrong but that
+    // the page never stated what was ASKED, so a 19-of-20 run read as unremarkable. The rate leads
+    // because it is the one line that carries the run's whole shape; the four counts follow it,
+    // because they are what makes it checkable rather than a slogan.
+    if (report.scope) {
+        lines.push(`${report.scope.automated} of ${report.scope.planned} planned configuration(s) automated (${report.scope.automationRate}%).`, ...(report.scope.manual > 0 ? [`${report.scope.manual} planned configuration(s) still need a person.`] : []), 
+        // Stated beside the rate and in neither half of it — the mirror image of outsideScope.
+        // Silent exclusion would be the flattering-direction lie; the count and the reason travel
+        // with every rate this page states.
+        ...(report.scope.unautomatable > 0
+            ? [
+                `${report.scope.unautomatable} configuration(s) cannot be satisfied by any metadata deploy (data rows or no API) — excluded from the rate's denominator and listed as their own count.`
+            ]
+            : []), 
+        // Stated, and in NEITHER half of the rate above. A rate that could absorb unrequested work
+        // is a lie in the flattering direction (QA round 1: a COMPLETE batch reported as 82%).
+        ...(report.scope.outsideScope > 0
+            ? [`${report.scope.outsideScope} delivered configuration(s) were outside the approved scope — counted in neither half of that rate.`]
+            : []), ``);
+    }
+    if (report.result === "ALREADY_SATISFIED") {
+        // NOT the read-only sentence. This batch asked for specific configurations and every one of
+        // them was already in the org, which is an outcome rather than an absence of one.
+        lines.push(`${report.scope?.planned ?? 0} planned configuration(s) were already present in this org, so no step needed to change anything.`, `Nothing was deployed and nothing was altered — the batch's configurations were verified as already in place.`, ``);
+    }
+    else if (report.waves.length === 0) {
+        lines.push(`No wave changed this org. A run that only read has no batch result to state.`, ``);
+    }
+    else {
+        // Practice runs get their OWN line rather than being folded into either count. A dry run that
+        // passed is the practice succeeding, and a scoreboard that buried three of them inside "need
+        // review" is what this report used to print over a run where every real wave delivered.
+        const practice = report.waves.filter((w) => w.dryRunOnly);
+        const accepted = practice.filter((w) => w.classification === "practice-accepted").length;
+        const cleared = practice.filter((w) => w.resolvedBy !== null).length;
+        const outstanding = practice.length - accepted - cleared;
+        lines.push(report.deliveredWaves === 0 && report.problemWaves === 0
+            ? `No wave changed this org — ${practice.length} practice run(s) only.`
+            : `${report.deliveredWaves} of ${report.waves.length - practice.length} real wave(s) delivered; ${report.problemWaves} need review.`, ...(practice.length > 0
+            ? [
+                `${practice.length} practice run(s) (dry runs, which change nothing): ${accepted} accepted` +
+                    `${cleared > 0 ? `, ${cleared} refused but delivered later by a real wave` : ""}` +
+                    `${outstanding > 0 ? `, ${outstanding} REFUSED with nothing in this batch delivering it` : ""}.`
+            ]
+            : []), ``, `| Wave | Verdict | Deployable rollback image | Requirements |`, `| --- | --- | --- | --- |`, ...report.waves.map((w) => `| ${w.wave}${w.dryRunOnly ? " (practice)" : ""} | ${w.verdict} | ${w.rollbackImage ? "yes" : w.touchedExistingState ? "NO" : "n/a (added only)"} | ${w.requirementIds.join(", ") || "—"} |`), ``);
+    }
+    if (report.findings.length > 0) {
+        lines.push(`## Batch-level findings`, ``, ...report.findings.map((f) => `- ${f}`), ``);
+    }
+    // The delivery log sits BESIDE contamination on purpose — see the module header. The
+    // driftExplained edges are what let a stale-parent classification explain itself.
+    lines.push(`## Delivery log`, ``);
+    if (report.deliveries.length === 0) {
+        lines.push(`No deliveries recorded for this org yet.`, ``);
+    }
+    else {
+        for (const e of report.deliveries) {
+            const staleParents = [...new Set(e.driftExplained.map((pair) => pair.split(" <- ")[0]))];
+            const flags = [
+                ...(e.ambiguous ? ["DELIVERY AMBIGUOUS — the post-image is partial"] : []),
+                ...(e.orderingUnreliable ? ["position in this list is not evidence of when it happened"] : []),
+                ...(e.revertOf ? [`rollback of ${e.revertOf}`] : []),
+                ...(e.drifted.length ? [`changed outside this machine's history first: ${e.drifted.join(", ")}`] : []),
+                ...(staleParents.length
+                    ? [
+                        `recorded shape of ${staleParents.join(", ")} was stale here — accounted for by this history's own delivery of ${e.driftExplained.length} child component(s), not an outside change`
+                    ]
+                    : []),
+                // A gap in the record, printed as one. Sits with the other flags rather than in a footnote
+                // because "could not check" belongs next to "checked and found nothing", never below it.
+                ...e.notComparable.map((entry) => `NOT COMPARABLE (no claim either way, not a clean result) — ${entry.split(" <> ")[0]}: ${entry.split(" <> ").slice(1).join("; ") || "reader changed"}`),
+                // What this entry's post-image does NOT contain. Sits with the flags for the same reason
+                // the line above does: a bound on the record belongs beside the record, never in a
+                // footnote — and this one is invisible in the tree, because the reader drops the facet it
+                // could not verify rather than storing a value it does not trust.
+                ...e.incompleteFacets.map((entry) => `INCOMPLETE RECORD (never read, not empty) — ${entry.split(" <> ")[0]}: ${(entry.split(" <> ")[1] ?? "?")
+                    .split(",")
+                    .map((f) => `${f.trim()}: NOT READ at capture`)
+                    .join("; ")}`)
+            ];
+            lines.push(`- ${e.date}  ${e.wave ?? "?"}${e.attempt && e.attempt > 1 ? ` (attempt ${e.attempt})` : ""}  ${e.verdict ?? "?"}` +
+                `${e.sessionId ? `  session ${e.sessionId}` : ""}${e.requirementIds.length ? `  [${e.requirementIds.join(", ")}]` : ""}` +
+                `${flags.length ? `\n  - ${flags.join("\n  - ")}` : ""}`);
+        }
+        lines.push(``);
+    }
+    lines.push(`## Contamination (measurement validity)`, ``);
+    lines.push(report.contamination
+        ? renderContamination(report.contamination)
+        : `Not computed for this session. Absence of a report is NOT a clean result — nothing was measured.`);
+    return `${lines.join("\n")}\n`;
+}
+/** Where the report lands in the session's evidence. */
+export function batchReportArtifacts(sessionId) {
+    const dir = sessionDir(sessionId);
+    return { json: path.join(dir, "batch-report.json"), markdown: path.join(dir, "BATCH-REPORT.md") };
+}
+/**
+ * Write the report beside the session's other evidence.
+ *
+ * FAIL-OPEN: this runs at batch close, after the work is done, so an unwritable session directory
+ * costs the artifact and nothing else. The contamination artifacts are written too, so the U5
+ * output keeps its own stable path for anything that already reads it.
+ */
+export async function writeBatchReportArtifacts(report, rendered) {
+    try {
+        const files = batchReportArtifacts(report.sessionId);
+        await fs.mkdir(path.dirname(files.json), { recursive: true });
+        await fs.writeFile(files.json, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+        await fs.writeFile(files.markdown, rendered ?? renderBatchReport(report), "utf8");
+        if (report.contamination) {
+            const { writeContaminationArtifacts } = await import("./contamination.js");
+            await writeContaminationArtifacts(report.contamination);
+        }
+        return files;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/direct/comparatorNoise.js

@@ -0,0 +1,75 @@
+// THE NOISE BUDGET — the canonicalizations that keep the delivery comparators quiet.
+//
+// Every entry here is a live-caught class of Salesforce read-back behaviour that made a CORRECT
+// deploy report drift. They were written for the intent check (compareIntent), but the unstated-change
+// check compares a pre-image against a post-image over the same metadata and is exposed to the same
+// classes — so they live in one module rather than being copied. A suppression that exists on one
+// side and not the other is how two subsystems end up disagreeing about the same facet, which the
+// removals module already paid for once (see its CF63 w4 note).
+//
+// The bar for adding an entry is a MEASURED org behaviour, not a plausible one: each of these
+// silences a real alarm, and a guessed entry silences a real finding just as effectively.
+// Elements the org OMITS from a read-back when their value equals the platform default. Stating
+// one explicitly is correct authoring, so intent-says-default vs observed-absent is AGREEMENT.
+// Keyed by leaf element name; extend as each is live-caught rather than guessed at.
+export const PLATFORM_DEFAULT_WHEN_OMITTED = {
+    formulaTreatBlanksAs: "BlankAsBlank",
+    // CF77 w4-retry, both live-confirmed against the org read-back: the author states these on an
+    // approval step, the org stores them as the default and omits them entirely on read. Absent
+    // means "the value you asked for", so reporting drift here is a false alarm on a correct deploy.
+    whenMultipleApprovers: "FirstResponse",
+    rejectBehavior: { type: "RejectRequest" }
+};
+// A currency criterion is echoed back FORMATTED for the org's locale and currency:
+// `10000` is stored, `"USD 10,000"` is what a read returns. Same number, different rendering, so
+// comparing the strings reported drift on an approval process that deployed exactly as authored.
+export function canonicalizeCurrencyish(v) {
+    if (typeof v !== "string")
+        return v;
+    const bare = v.replace(/^"|"$/g, "").trim();
+    const m = /^(?:[A-Z]{3}\s*)?(-?[\d,]+(?:\.\d+)?)$/.exec(bare);
+    if (!m)
+        return v;
+    const n = Number(m[1].replace(/,/g, ""));
+    return Number.isFinite(n) ? String(n) : v;
+}
+export const isPlainObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/**
+ * Is this value "nothing", whatever shape it arrived in?
+ *
+ * An empty XML element parses to `""`; the org read-back returns the fully materialized skeleton.
+ * CF77 w5: the author wrote three empty `<layoutColumns/>` on the Custom Links section and the org
+ * returned `[{layoutItems: []}, …]` — identical meaning, reported as drift on a Layout that
+ * deployed exactly as written.
+ */
+export function isEmptyish(v) {
+    if (v === "" || v === null || v === undefined)
+        return true;
+    if (Array.isArray(v))
+        return v.every(isEmptyish);
+    if (isPlainObj(v))
+        return Object.values(v).every(isEmptyish);
+    return false;
+}
+// XML parse yields strings for scalars; org read-back yields typed values. Compare
+// on canonical string forms for scalar leaves (the projection normalizers already
+// coerce the load-bearing booleans/numbers on the observed side).
+export function coerceLeaf(v) {
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    if (typeof v === "string")
+        return v;
+    if (Array.isArray(v))
+        return v.map(coerceLeaf);
+    if (v && typeof v === "object") {
+        // Text-node-with-attributes shape (live-caught on CustomMetadata `<value xsi:type=…>text`):
+        // the org read-back returns {_: "5", $: {xsi:type}} while author XML (attrs ignored) yields
+        // the plain scalar "5". Collapse to the text so intent compares like-with-like — the xsi:type
+        // is a derivable type hint, not semantic content for delivery verification.
+        const rec = v;
+        if ("_" in rec && "$" in rec && Object.keys(rec).length === 2)
+            return coerceLeaf(rec._);
+        return Object.fromEntries(Object.entries(rec).map(([k, x]) => [k, coerceLeaf(x)]));
+    }
+    return v;
+}