@flighthq/tool-capture 0.3.0 → 0.3.1-next.1041.35b950c

package/dist/captureValidation.js

@@ -22,12 +22,17 @@ import { resolve } from 'node:path';
 import { CAPTURE_PARITY_TOLERANCE, CAPTURE_REGRESSION_TOLERANCE, compareCaptureFingerprints, evaluateCaptureParity, evaluateCaptureRegression, } from '@flighthq/capture/contract';
 import pc from 'picocolors';
 import { getBaselineField, setBaselineField } from './baselineStore.js';
+import { diffCaptureBaselineCoverage, formatCaptureBaselineCoverageIdentity, isCaptureBaselineCoverageFailure, readCaptureBaselineCoverageManifest, writeCaptureBaselineCoverageManifest, } from './captureBaselineCoverageManifest.js';
+import { isUniformCaptureFingerprint } from './captureBaselineSanity.js';
 import { launchBrowser } from './captureBrowser.js';
+import { provideCaptureDomRenderPixels } from './captureDomReadback.js';
 import { BACKEND_UNAVAILABLE, getCaptureEntryRoute, rendererMatchesFilter } from './captureEntries.js';
+import { selectCaptureEntriesByName } from './captureEntryFilter.js';
 import { formatDetailLine, formatStatusLine, formatSummaryCount, formatSummaryLine } from './captureFormat.js';
 import { installAbortHandler, isBrowserClosedError } from './captureInterrupt.js';
 import { CAPTURE_PROTOCOL_VERSION } from './captureProtocol.js';
 import { writeCaptureReport } from './captureReport.js';
+import { formatCaptureConsoleMessage, listenForCaptureResourceFailures } from './captureResourceFailure.js';
 import { getCaptureSceneSourceHash } from './captureSourceHash.js';
 import { getCaptureTimeoutMs } from './captureTimeout.js';
 function fingerprintKey(entry, renderer) {
@@ -53,12 +58,19 @@ function addPair(pairs, fingerprints, a, b, group, tolerance) {
 // Why an entry produced no parity pair. Each case has a different remedy, and a bare "0 comparisons"
 // sends a reader to the wrong one: an ineligible backend needs a parity group or a committed baseline,
 // while a single eligible backend has nothing to disagree with and needs a second one in scope.
-export function explainCaptureParityUncovered(eligibleCount, hasGroups) {
+export function explainCaptureParityUncovered(eligibleCount, hasGroups, unavailableReferences = []) {
     if (eligibleCount === 0) {
         return hasGroups
             ? 'no renderer in any parity group is eligible'
             : 'no renderer is parity-eligible — declare a parity group, or commit a fingerprint baseline';
     }
+    // Checked before the counts because it is a DIFFERENT remedy: with a reference missing, adding an
+    // eligible backend or shortening the skip list changes nothing until the reference itself is back.
+    // Collapsing it into the skip message would send the reader to the wrong list, and the reference can
+    // be absent for a reason that has nothing to do with skips (never parity-eligible).
+    if (unavailableReferences.length > 0) {
+        return `parity group reference not present (${unavailableReferences.join(', ')}) — a reference group compares against that backend only, so it yields NO pairs rather than falling back to all-pairs`;
+    }
     if (eligibleCount === 1)
         return 'only one parity-eligible renderer — nothing to compare it against';
     return 'every eligible pair is excluded by a parity skip';
@@ -71,6 +83,7 @@ async function loadFingerprint(context, baseUrl, entry, renderer, subject) {
     // collect those too. Without this, a thrown verifier or a renamed/missing export reads as the
     // uninformative "verifier did not run" instead of the actual message.
     let pageError = '';
+    let resourceError = '';
     let page = null;
     try {
         // newPage is inside the try: once an interrupt has closed the browser it throws, and that must read
@@ -79,8 +92,9 @@ async function loadFingerprint(context, baseUrl, entry, renderer, subject) {
         page.on('pageerror', (e) => (pageError ||= e.message));
         page.on('console', (m) => {
             if (m.type() === 'error')
-                pageError ||= m.text();
+                pageError ||= formatCaptureConsoleMessage(m);
         });
+        listenForCaptureResourceFailures(page, (message) => (resourceError ||= message));
         const route = getCaptureEntryRoute(entry, renderer, subject);
         await page.goto(`${baseUrl}/${route}`, {
             waitUntil: 'domcontentloaded',
@@ -93,12 +107,27 @@ async function loadFingerprint(context, baseUrl, entry, renderer, subject) {
         // race because their readback is synchronous). So wait until the fingerprint is populated OR an error
         // overlay appears, then read the result. Poll on a timer (the capture harness halts rAF).
         const waitStartedAt = performance.now();
-        await page
+        const reachedReadbackOrTerminal = await page
             .waitForFunction(() => {
-            const v = window.__ftVerification;
-            return v?.state === 'passed' || v?.state === 'failed' || document.getElementById('ft-error') !== null;
+            const w = window;
+            const verification = w.__ftVerification;
+            return (verification?.state === 'passed' ||
+                verification?.state === 'failed' ||
+                (verification?.render === 'dom' && typeof w.__ftProvideDomRenderPixels === 'function') ||
+                document.getElementById('ft-error') !== null);
         }, null, { timeout: getCaptureTimeoutMs(), polling: 100 })
-            .catch(() => { });
+            .then(() => true)
+            .catch(() => false);
+        if (reachedReadbackOrTerminal && (await provideCaptureDomRenderPixels(page))) {
+            await page
+                .waitForFunction(() => {
+                const verification = window.__ftVerification;
+                return (verification?.state === 'passed' ||
+                    verification?.state === 'failed' ||
+                    document.getElementById('ft-error') !== null);
+            }, null, { timeout: getCaptureTimeoutMs(), polling: 100 })
+                .catch(() => { });
+        }
         const waitedMs = Math.round(performance.now() - waitStartedAt);
         const verification = await page
             .evaluate(() => window.__ftVerification ?? null)
@@ -122,7 +151,7 @@ async function loadFingerprint(context, baseUrl, entry, renderer, subject) {
         // The functional entry paints any error into #ft-error (covering window.error AND unhandledrejection);
         // read it as the most reliable real reason when neither a fingerprint nor a pageerror surfaced.
         const overlay = await page.$eval('#ft-error', (el) => el.textContent ?? '').catch(() => '');
-        const detail = verification?.error || pageError || overlay;
+        const detail = verification?.error || resourceError || pageError || overlay;
         if (BACKEND_UNAVAILABLE.test(detail))
             return { fingerprint: null, reason: `backend unavailable (${detail})`, unavailable: true, aborted: false };
         return {
@@ -234,11 +263,35 @@ export function explainCaptureVerificationStall(verification, waitedMs) {
     }
     // Registered and still non-terminal: it started and never finished, which is a stall rather than a
     // scene that is merely expensive. The STAGE is the actionable half — 'awaitingFrame' means a presented
-    // frame never arrived (page/scheduler), 'readingBack' means the GPU readback never resolved (driver).
+    // frame never arrived (page/scheduler), while 'readingBack' means a GPU readback or the DOM runner bridge
+    // never resolved.
     const stage = verification.stage;
     const where = stage === undefined ? '' : ` at stage "${stage}"`;
     return `verifier registered but stalled${where} in state "${verification.state}" (${budget}); it started and never reached a terminal state`;
 }
+/**
+ * Ranks measured parity distances, widest disagreement first.
+ *
+ * Returns null when nothing was compared, so a run that measured nothing prints no ranking rather
+ * than an empty one that would read as agreement.
+ */
+export function formatCaptureParityRanking(checks, limit = 10) {
+    const measured = checks
+        .filter((check) => check.kind === 'parity' && typeof check.distance === 'number')
+        .map((check) => ({ distance: check.distance, entry: check.entry, renderers: check.renderers ?? [] }))
+        .sort((a, b) => b.distance - a.distance || a.entry.localeCompare(b.entry));
+    if (measured.length === 0)
+        return null;
+    const shown = measured.slice(0, limit);
+    const median = measured[measured.length >> 1].distance;
+    const lines = shown.map((row) => `  ${row.distance.toFixed(2)}  ${row.entry}  ${row.renderers.join('·')}`);
+    const omitted = measured.length - shown.length;
+    return [
+        `  widest parity distances (${measured.length} compared, median ${median.toFixed(2)}):`,
+        ...lines,
+        ...(omitted > 0 ? [`  … ${omitted} more not shown`] : []),
+    ].join('\n');
+}
 export function isCaptureParityCoverageFailure(run) {
     if (!run.gateParity || run.interrupted)
         return false;
@@ -259,29 +312,11 @@ export function isCaptureRegressionCoverageFailure(run) {
         return false;
     return run.regressionComparisons === 0 && run.regressionUncovered > 0;
 }
-// Loads a single test/renderer page and returns its render fingerprint, or null with a reason and a
-// flag marking whether the cause is a genuinely-unavailable backend (skippable) versus a real error.
-// True when every cell of a coarse fingerprint carries the same value — a blank or flat-filled frame.
-//
-// This is a WRITE-SIDE gate, not a render check: a uniform frame may be a legitimate render (a solid
-// background scene), but it is never worth BLESSING as a regression baseline, because it cannot
-// distinguish a working scene from a broken one. Refusing it costs a real flat scene its regression
-// coverage and costs a broken one nothing — the asymmetry is the point.
-//
-// Format: "<cellSize>:<hex cells>", so the payload after the colon is split into fixed-width cells.
-export function isUniformCaptureFingerprint(fingerprint) {
-    const payload = fingerprint.slice(fingerprint.indexOf(':') + 1);
-    if (payload.length <= CAPTURE_FINGERPRINT_CELL_CHARS)
-        return true;
-    const first = payload.slice(0, CAPTURE_FINGERPRINT_CELL_CHARS);
-    for (let i = CAPTURE_FINGERPRINT_CELL_CHARS; i < payload.length; i += CAPTURE_FINGERPRINT_CELL_CHARS) {
-        if (payload.slice(i, i + CAPTURE_FINGERPRINT_CELL_CHARS) !== first)
-            return false;
-    }
-    return true;
-}
 async function processEntry(entry, entryIndex, totalEntries, isAborted, options, samples) {
     const result = {
+        visited: [],
+        undetermined: [],
+        covered: [],
         regressionFailures: 0,
         regressionUncovered: 0,
         parityFailures: 0,
@@ -313,6 +348,7 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
     const statusLine = (tone, label, message) => formatStatusLine(tone, label, labelWidth, message);
     const detailLine = (glyph, label, message, paint) => formatDetailLine(glyph, label, labelWidth, message, paint);
     if (options.fingerprintSkip.has(entry.name)) {
+        result.undetermined.push(...renderers.map((renderer) => formatCaptureBaselineCoverageIdentity(entry.name, renderer)));
         result.skipped += renderers.length;
         result.checks.push({
             entry: entry.name,
@@ -358,9 +394,16 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
                     message: first.reason,
                 });
             }
+            // A renderer that never produced a fingerprint tells us NOTHING about its coverage. Recording it as
+            // visited-but-uncovered would report a load failure a second time as a coverage loss; recording it
+            // as never-visited would report it as vanished. It is neither — it is unknown, and an unknown is
+            // carried forward on acceptance rather than retired.
+            result.undetermined.push(formatCaptureBaselineCoverageIdentity(entry.name, renderer));
             continue;
         }
         const fingerprint = first.fingerprint;
+        // Coverage for this identity is now DETERMINABLE: the baseline lookup below settles it either way.
+        result.visited.push(formatCaptureBaselineCoverageIdentity(entry.name, renderer));
         // Explicit groups are same-run comparisons and do not require a committed regression baseline.
         // Legacy all-pairs parity retains its prior proven-stable/baselined eligibility policy.
         if (Object.keys(options.parityGroups).length > 0)
@@ -405,7 +448,13 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
                 });
                 continue;
             }
-            setBaselineField(options.root, options.subject, entry.name, renderer, 'fingerprint', fingerprint);
+            // ★ STAMP ONLY WHAT THIS PASS PRODUCED. The provenance is looked up by the SAME (entry, renderer)
+            // key the fingerprint came from, and is passed only when this pass actually captured that
+            // fingerprint. A fingerprint supplied from elsewhere, or already on disk, gets NO provenance:
+            // attaching today's conditions to a value produced by an earlier capture would manufacture an
+            // agreement nobody observed, and a wrong provenance is worse than the absent one it replaces.
+            const provenance = options.fingerprintProvenance[entry.name]?.[renderer];
+            setBaselineField(options.root, options.subject, entry.name, renderer, 'fingerprint', fingerprint, provenance);
             const sourceHash = getCaptureSceneSourceHash(options.root, options.subject, entry, renderer);
             if (sourceHash !== null) {
                 setBaselineField(options.root, options.subject, entry.name, renderer, 'sourceHash', sourceHash);
@@ -419,6 +468,7 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
                 status: 'passed',
                 message: 'baseline written',
             });
+            result.covered.push(formatCaptureBaselineCoverageIdentity(entry.name, renderer));
             eligible.set(renderer, fingerprint);
             continue;
         }
@@ -436,6 +486,10 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
             });
             continue;
         }
+        // Coverage is recorded HERE, where it is a fact, not inferred later from the shape of the checks:
+        // a smoke leg gates neither regression nor report and so emits no regression check at all, and
+        // deriving coverage by subtracting skips would call every one of those targets lost.
+        result.covered.push(formatCaptureBaselineCoverageIdentity(entry.name, renderer));
         const dist = distance(fingerprint, committed);
         eligible.set(renderer, fingerprint);
         if (dist === null) {
@@ -506,6 +560,9 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
     const allowed = (renderer) => skip !== 'all' && !skip?.includes(renderer);
     const pairs = [];
     const groups = Object.entries(options.parityGroups);
+    // Groups whose declared reference is not present, as "<group> → <reference>". Carried to the uncovered
+    // explanation so the reason names the missing reference instead of collapsing into the skip message.
+    const unavailableReferences = [];
     if (groups.length === 0) {
         const present = [...eligible.keys()].filter(allowed);
         for (let i = 0; i < present.length; i++) {
@@ -517,18 +574,48 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
     else {
         for (const [groupName, group] of groups) {
             const present = group.targets.filter((renderer) => eligible.has(renderer) && allowed(renderer));
-            if (group.reference !== undefined && present.includes(group.reference)) {
+            // A group that DECLARES a reference is claiming agreement WITH THAT BACKEND. If the reference is
+            // not present — removed by a skip, or never parity-eligible — that claim cannot be checked, and
+            // comparing the remaining targets to each other substitutes a DIFFERENT, weaker claim under the
+            // same group name. Yield no pairs instead, so the scene reports itself uncovered by name.
+            if (group.reference !== undefined) {
+                // Only a SKIP-removed reference kills the group. A skip is a deliberate statement that this
+                // backend is not to be trusted for this scene, so comparing the survivors to each other
+                // substitutes a different, weaker claim under the same group name — yield nothing and let the
+                // scene report itself uncovered.
+                //
+                // A reference that was never there is NOT the same thing and must keep the all-pairs branch:
+                // the built-in group declares `reference: 'canvas'` once for every scene, and 83 scenes have no
+                // canvas column at all. Treating those as reference-removed silently deletes 85 real
+                // cross-backend comparisons — measured, not estimated: 253 → 168 on the functional suite.
+                if (eligible.has(group.reference) && !allowed(group.reference)) {
+                    unavailableReferences.push(`${groupName} → ${group.reference}`);
+                    continue;
+                }
+                if (!present.includes(group.reference)) {
+                    // The comparison is FINE here and the CLAIM was false: nobody asked for the reference to go,
+                    // it simply is not a column for this scene, and all-pairs among the columns that DO exist is
+                    // real coverage worth keeping. What was wrong is reporting it under a group that asserts a
+                    // reference it never used, so the label says so rather than the pairs disappearing.
+                    const label = `${groupName} (all-pairs, no ${group.reference} column)`;
+                    for (let i = 0; i < present.length; i++) {
+                        for (let j = i + 1; j < present.length; j++) {
+                            addPair(pairs, eligible, present[i], present[j], label, group.tolerance ?? options.parityTolerance);
+                        }
+                    }
+                    continue;
+                }
                 for (const renderer of present) {
                     if (renderer !== group.reference) {
                         addPair(pairs, eligible, group.reference, renderer, groupName, group.tolerance ?? options.parityTolerance);
                     }
                 }
+                continue;
             }
-            else {
-                for (let i = 0; i < present.length; i++) {
-                    for (let j = i + 1; j < present.length; j++) {
-                        addPair(pairs, eligible, present[i], present[j], groupName, group.tolerance ?? options.parityTolerance);
-                    }
+            // No reference declared at all: all-pairs is what this group means, not a fallback for a lost one.
+            for (let i = 0; i < present.length; i++) {
+                for (let j = i + 1; j < present.length; j++) {
+                    addPair(pairs, eligible, present[i], present[j], groupName, group.tolerance ?? options.parityTolerance);
                 }
             }
         }
@@ -544,7 +631,7 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
             renderers: [...eligible.keys()],
             kind: 'parity',
             status: 'skipped',
-            message: explainCaptureParityUncovered(eligible.size, groups.length > 0),
+            message: explainCaptureParityUncovered(eligible.size, groups.length > 0, unavailableReferences),
         });
     }
     if (pairs.length > 0) {
@@ -557,7 +644,7 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
                     renderers: [pair.a, pair.b],
                     kind: 'parity',
                     status: 'reported',
-                    message: `parity distance ${pair.dist.toFixed(2)}`,
+                    message: `parity ${pair.label} distance ${pair.dist.toFixed(2)}`,
                     distance: pair.dist,
                     threshold: pair.tolerance,
                 });
@@ -576,7 +663,7 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
                         renderers: [p.a, p.b],
                         kind: 'parity',
                         status: 'failed',
-                        message: `parity ${p.dist.toFixed(2)} > ${p.tolerance}`,
+                        message: `parity ${p.label} ${p.dist.toFixed(2)} > ${p.tolerance}`,
                         distance: p.dist,
                         threshold: p.tolerance,
                     });
@@ -588,7 +675,7 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
                     renderers: [p.a, p.b],
                     kind: 'parity',
                     status: 'passed',
-                    message: `parity ${p.dist.toFixed(2)} ≤ ${p.tolerance}`,
+                    message: `parity ${p.label} ${p.dist.toFixed(2)} ≤ ${p.tolerance}`,
                     distance: p.dist,
                     threshold: p.tolerance,
                 });
@@ -602,13 +689,41 @@ async function processEntry(entry, entryIndex, totalEntries, isAborted, options,
     }
     return result;
 }
+// Loads a single test/renderer page and returns its render fingerprint, or null with a reason and a
+// flag marking whether the cause is a genuinely-unavailable backend (skippable) versus a real error.
+export { isUniformCaptureFingerprint } from './captureBaselineSanity.js';
+function classifyCaptureBaselineFreshness(recordedSourceHash, currentSourceHash) {
+    if (recordedSourceHash === null) {
+        return {
+            message: 'scene-source freshness unavailable (baseline has no recorded source hash)',
+            status: 'unavailable',
+        };
+    }
+    if (currentSourceHash === null) {
+        return {
+            message: 'scene-source freshness unavailable (current scene source could not be read)',
+            status: 'unavailable',
+        };
+    }
+    if (recordedSourceHash !== currentSourceHash) {
+        return {
+            message: 'scene source changed since baseline — recapture owed by the scene owner',
+            status: 'changed',
+        };
+    }
+    return {
+        message: 'scene source unchanged since baseline — environment drift; never rebaseline',
+        status: 'unchanged',
+    };
+}
 export async function runCaptureValidation(input) {
     const startedAt = performance.now();
-    const entries = input.filter
-        ? input.entries.filter((entry) => entry.name.includes(input.filter))
-        : [...input.entries];
+    const entries = selectCaptureEntriesByName(input.entries, input.filter, input.filterExact);
     if (entries.length === 0)
         throw new Error(`No validation entries found subject=${input.subject}`);
+    // A filtered run cannot tell "this pinned target vanished" from "I excluded it", so it must not claim
+    // an absence. It can still report a LOSS, because that is about a target it actually ran.
+    const entryFiltered = (input.filter !== undefined && input.filter !== '') || input.filterExact !== undefined;
     const options = {
         subject: input.subject,
         root: resolve(input.root ?? process.cwd()),
@@ -617,6 +732,7 @@ export async function runCaptureValidation(input) {
         report: input.report ?? false,
         quiet: input.quiet ?? false,
         updateFingerprints: input.updateFingerprints ?? false,
+        updateCoverage: input.updateCoverage ?? false,
         gateRegression: input.gateRegression ?? true,
         gateParity: input.gateParity ?? true,
         stabilityEpsilon: input.stabilityEpsilon ?? 4,
@@ -626,6 +742,7 @@ export async function runCaptureValidation(input) {
         paritySkip: input.paritySkip ?? {},
         parityGroups: input.parityGroups ?? {},
         fingerprints: input.fingerprints ?? {},
+        fingerprintProvenance: input.fingerprintProvenance ?? {},
     };
     const ownsBrowser = input.browserSession === undefined;
     const launched = input.browserSession ??
@@ -645,6 +762,9 @@ export async function runCaptureValidation(input) {
     let updated = 0;
     let skipped = 0;
     const checks = [];
+    const coveredIdentities = [];
+    const visitedIdentities = [];
+    const undeterminedIdentities = [];
     try {
         // Balance pages, not entries: a four-renderer entry must not monopolize one worker while another
         // worker gets a one-renderer entry. The same flattened queue also makes capture-provided
@@ -696,6 +816,12 @@ export async function runCaptureValidation(input) {
                     updated += result.updated;
                     skipped += result.skipped;
                     checks.push(...result.checks);
+                    coveredIdentities.push(...result.covered);
+                    visitedIdentities.push(...result.visited);
+                    undeterminedIdentities.push(...result.undetermined);
+                    undeterminedIdentities.push(...result.undetermined);
+                    coveredIdentities.push(...result.covered);
+                    visitedIdentities.push(...result.visited);
                     if (!options.quiet)
                         for (const line of result.output)
                             console.log(line);
@@ -772,7 +898,41 @@ export async function runCaptureValidation(input) {
         parityUncovered,
         rendererFilterCount: options.rendererFilter.length,
     });
-    const failed = regressionFailures > 0 ||
+    // The zero-floor above asks only whether ANY comparison ran. This asks WHICH ones did: a pinned
+    // identity that ran and no longer has a baseline is named individually, instead of being absorbed into
+    // an "uncovered" count that still satisfies the floor as long as one other target compared.
+    const coverageDiff = options.gateRegression && !options.updateCoverage
+        ? diffCaptureBaselineCoverage(readCaptureBaselineCoverageManifest(options.root), options.subject, Object.fromEntries([...new Set(coveredIdentities)].map((identity) => [identity, ['fingerprint']])), [...new Set(visitedIdentities)], {
+            entryFiltered,
+            activeRenderers: options.rendererFilter.length > 0 ? [...options.rendererFilter] : null,
+            undetermined: [...new Set(undeterminedIdentities)],
+            // Validation observes the FINGERPRINT column and nothing else. Without this the screenshot
+            // and oracle pins would read as lost on every validate run — absence of observation reported
+            // as absence of evidence, which is the defect this manifest exists to prevent.
+            kinds: ['fingerprint'],
+        })
+        : { gained: [], lost: [], absent: [] };
+    const coverageFailed = isCaptureBaselineCoverageFailure(coverageDiff);
+    // ★ Accepting new coverage does NOT excuse the run's own verdict. Writing the manifest from a branch
+    // that returned early would report exit 0 over a leg with real regression failures — an acceptance path
+    // that reports green is the same defect class this manifest exists to close, one level up. So the write
+    // happens here, after the verdict is computed, and only the COVERAGE component of that verdict is
+    // suppressed: a target with a failing comparison still has baseline evidence, so it is still covered.
+    if (options.updateCoverage) {
+        // An interrupted run's own summary is not trustworthy, so it never writes. A run with load failures
+        // does write: the write retires only identities this run positively determined to be uncovered, so a
+        // target that never loaded keeps its pin instead of being silently retired by its own flakiness.
+        if (interrupted) {
+            console.error(pc.red('\nRefusing to update the capture baseline coverage manifest from an interrupted run.'));
+            return createResult(true);
+        }
+        const identities = [...new Set(coveredIdentities)];
+        writeCaptureBaselineCoverageManifest(options.root, options.subject, Object.fromEntries(identities.map((identity) => [identity, ['fingerprint']])), options.rendererFilter.length > 0 ? [...options.rendererFilter] : null, [...new Set(visitedIdentities)], ['fingerprint']);
+        if (!options.quiet)
+            console.log(`\ncapture baseline coverage manifest updated — ${identities.length} identit${identities.length === 1 ? 'y' : 'ies'} pinned for ${options.subject}`);
+    }
+    const failed = coverageFailed ||
+        regressionFailures > 0 ||
         parityFailures > 0 ||
         loadFailures > 0 ||
         parityCoverageFailed ||
@@ -790,6 +950,24 @@ export async function runCaptureValidation(input) {
                 formatSummaryCount(loadFailures, 'load failures', 'fail'),
             ]) +
             note);
+    // A parity PASS spans zero to the tolerance, so the verdict alone cannot distinguish a scene that
+    // matched exactly from one that came within a hair of failing. Rank the measured distances so the
+    // reader sees what the comparison actually found rather than only that nothing crossed the line.
+    const ranking = formatCaptureParityRanking(checks);
+    if (ranking !== null && !options.quiet)
+        console.log(ranking);
+    for (const identity of coverageDiff.lost) {
+        console.error(pc.red(`  - ${identity}  (pinned, ran, no comparable baseline)`));
+    }
+    for (const identity of coverageDiff.absent) {
+        console.error(pc.red(`  - ${identity}  (pinned, never reached by this run)`));
+    }
+    for (const identity of coverageDiff.gained) {
+        console.error(pc.red(`  + ${identity}  (newly covered, not yet pinned)`));
+    }
+    if (coverageFailed) {
+        console.error(pc.red(`\nCapture baseline coverage does not match scripts/capture-baseline-coverage-manifest.json — the manifest is an exact set, so a gain counts too. Repair a missing baseline, or accept the change deliberately with --update-coverage (no --filter).`));
+    }
     // Name the entries behind an "N uncovered" count: a bare number tells a reader something is missing but
     // not what to go look at, and the entries differ in why.
     for (const [label, uncovered, failedTier] of [
@@ -844,30 +1022,4 @@ export async function runCaptureValidation(input) {
         return result;
     }
 }
-function classifyCaptureBaselineFreshness(recordedSourceHash, currentSourceHash) {
-    if (recordedSourceHash === null) {
-        return {
-            message: 'scene-source freshness unavailable (baseline has no recorded source hash)',
-            status: 'unavailable',
-        };
-    }
-    if (currentSourceHash === null) {
-        return {
-            message: 'scene-source freshness unavailable (current scene source could not be read)',
-            status: 'unavailable',
-        };
-    }
-    if (recordedSourceHash !== currentSourceHash) {
-        return {
-            message: 'scene source changed since baseline — recapture owed by the scene owner',
-            status: 'changed',
-        };
-    }
-    return {
-        message: 'scene source unchanged since baseline — environment drift; never rebaseline',
-        status: 'unchanged',
-    };
-}
-// Hex characters per fingerprint cell (one RGB triplet).
-const CAPTURE_FINGERPRINT_CELL_CHARS = 6;
 //# sourceMappingURL=captureValidation.js.map