@hominis/fireforge 0.51.0 → 0.53.0

package/dist/src/commands/test-shards.js

@@ -13,6 +13,7 @@
  * judged per file from each dispatch's raw log: `shards=` then counts files
  * and `failed-shards=` names the files that failed.
  */
+import { formatHarnessServerPorts } from '../core/harness-port-reservation.js';
 import { getActiveRunLogPath, writeToActiveRunLog } from '../core/run-log.js';
 import { buildHarnessCrashMessage, formatFireforgeVerdictLine, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
 import { TestFailureError } from '../errors/build.js';
@@ -27,19 +28,32 @@ const SHARD_STATUS_LABEL = {
     'no-tests': 'NO-TESTS',
     'harness-arguments': 'ARGUMENTS',
 };
+/** The summary box's status word; a server that never started is not a crash. */
+function shardStatusLabel(verdict) {
+    return verdict.signature?.verdictReason === 'server-startup'
+        ? 'SERVER'
+        : SHARD_STATUS_LABEL[verdict.kind];
+}
 /**
  * Derives the aggregate classification for a sharded run: all-green is
  * `tests-ran-ok`. Otherwise the most structural failure wins. A crashed
  * shard makes the whole run `harness-crash`, then `no-tests`, then plain
  * `test-failures`, so the aggregate `reason=` keeps the classifier-driven
- * contract instead of collapsing every failure to `test-failures`.
+ * contract instead of collapsing every failure to `test-failures`. When
+ * every crashed shard is a server that never started, the aggregate keeps
+ * that signature, so its line says `reason=server-startup` too.
  */
 export function deriveAggregateShardVerdict(shards) {
     const kinds = new Set(shards.map(({ outcome }) => outcome.verdict.kind));
     if (kinds.has('harness-arguments'))
         return { kind: 'harness-arguments' };
-    if (kinds.has('harness-crash'))
-        return { kind: 'harness-crash' };
+    if (kinds.has('harness-crash')) {
+        const crashes = shards.filter(({ outcome }) => outcome.verdict.kind === 'harness-crash');
+        const signature = crashes[0]?.outcome.verdict.signature;
+        return crashes.every(({ outcome }) => outcome.verdict.signature?.verdictReason === 'server-startup') && signature !== undefined
+            ? { kind: 'harness-crash', signature }
+            : { kind: 'harness-crash' };
+    }
     if (kinds.has('no-tests'))
         return { kind: 'no-tests' };
     if (kinds.has('test-failures'))
@@ -48,15 +62,18 @@ export function deriveAggregateShardVerdict(shards) {
 }
 /**
  * The `FIREFORGE-SHARD:` line for one finished shard: the verdict it would
- * have printed alone, plus `shard=<i>/<n>` and `path=<label>`. Never a
- * `FIREFORGE-VERDICT:` line, so the run keeps exactly one.
+ * have printed alone, plus `shard=<i>/<n>` and `path=<label>`, and
+ * `ports=http:N,ssl:N,ws:N` when the harness reported the mochitest server
+ * ports it took. Never a `FIREFORGE-VERDICT:` line, so the run keeps
+ * exactly one.
  */
 export function formatShardLine(shard, index, total, failedFiles) {
     const body = formatFireforgeVerdictLine(shard.outcome.verdict).slice('FIREFORGE-VERDICT: '.length);
     const files = failedFiles !== undefined && failedFiles.length > 0
         ? ` failed-files=${failedFiles.join(',')}`
         : '';
-    return `FIREFORGE-SHARD: ${body} shard=${index + 1}/${total} path=${shard.label.replace(/\s+/g, '_')}${files}`;
+    const ports = formatHarnessServerPorts(shard.outcome.serverPorts);
+    return `FIREFORGE-SHARD: ${body} shard=${index + 1}/${total} path=${shard.label.replace(/\s+/g, '_')}${files}${ports === undefined ? '' : ` ports=${ports}`}`;
 }
 function writeShardLine(line) {
     process.stdout.write(`${line}\n`);
@@ -163,7 +180,7 @@ function reportProgress(finished, total, jobs) {
  * counts as a whole.
  */
 function summarizeShards(shards, perFile) {
-    const lines = shards.map(({ label, outcome }) => `${SHARD_STATUS_LABEL[outcome.verdict.kind].padEnd(8)} ${label}` +
+    const lines = shards.map(({ label, outcome }) => `${shardStatusLabel(outcome.verdict).padEnd(8)} ${label}` +
         (outcome.attempts > 1 ? `  (${outcome.attempts} attempts)` : ''));
     const failingShards = shards.filter(({ outcome }) => outcome.verdict.kind !== 'tests-ran-ok');
     let passed = shards.length - failingShards.length;

package/dist/src/commands/test-stale-gate.d.ts

@@ -29,9 +29,14 @@ import type { TestOptions } from '../types/commands/index.js';
  * stale-content refusal still applies to it unchanged.
  */
 export declare function enforceStaleBuildGate(projectRoot: string, engineDir: string, options: TestOptions, normalizedPaths: readonly string[], 
-/** `quiet`: refuse only, without the exemption note (the pre-lock pass). */
+/**
+ * `quiet`: refuse only, without the exemption note (the pre-lock pass).
+ * `launchablePath`: the engine-relative binary the run launches, which
+ * anchors the stale-compiled check (skipped without one).
+ */
 gate?: {
     quiet?: boolean;
+    launchablePath?: string | undefined;
 }): Promise<void>;
 /**
  * Compiled-StaticComponents gate: refuses runs whose child process would

package/dist/src/commands/test-stale-gate.js

@@ -8,9 +8,10 @@
  * `src/core/test-stale-check.ts`.
  */
 import { filterByCarriedFullCoverage } from '../core/coverage-dispatch.js';
-import { checkStaleBuildForTest, checkStaticComponentsStale, findChangedTestManifestsForPaths, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, FULL_SUITE_REQUEST, } from '../core/test-stale-check.js';
+import { checkStaleBuildForTest, checkStaticComponentsStale, findChangedTestManifestsForPaths, findCompiledSourcesNewerThanBinary, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaleCompiledRefusal, formatStaticComponentsRefusal, formatTestCoverageRefusal, FULL_SUITE_REQUEST, } from '../core/test-stale-check.js';
 import { formatStaleExemptions } from '../core/test-stale-exempt.js';
 import { PreflightRefusalError } from '../errors/base.js';
+import { isProcessAlive } from '../utils/errors.js';
 import { info, warn } from '../utils/logger.js';
 import { describePerfStaleImpact } from './test-perf-scope.js';
 /**
@@ -34,14 +35,20 @@ import { describePerfStaleImpact } from './test-perf-scope.js';
  * stale-content refusal still applies to it unchanged.
  */
 export async function enforceStaleBuildGate(projectRoot, engineDir, options, normalizedPaths, 
-/** `quiet`: refuse only, without the exemption note (the pre-lock pass). */
+/**
+ * `quiet`: refuse only, without the exemption note (the pre-lock pass).
+ * `launchablePath`: the engine-relative binary the run launches, which
+ * anchors the stale-compiled check (skipped without one).
+ */
 gate = {}) {
     const stale = await checkStaleBuildForTest(projectRoot, engineDir);
+    enforceControlBuiltGate(stale.baseline);
     const dispatchesNoTests = options.doctor === true && normalizedPaths.length === 0;
     if (!dispatchesNoTests) {
         await enforceCoverageGate(engineDir, stale.baseline, normalizedPaths);
     }
     await enforceStaticComponentsGate(engineDir, stale.baseline, options);
+    await enforceStaleCompiledGate(engineDir, stale.baseline, options, gate.launchablePath);
     const exempt = stale.exempt ?? [];
     if (!stale.stale && exempt.length > 0 && gate.quiet !== true) {
         info(`Stale-build preflight: ${exempt.length} edit(s) since the last build need no rebuild: ${formatStaleExemptions(exempt)}.`);
@@ -72,6 +79,38 @@ gate = {}) {
         throw new PreflightRefusalError(staleMessage, 'stale-build');
     }
 }
+/**
+ * Control-built refusal: the recorded build compiled a negative control
+ * into the binary, and no build since has recompiled the restored source
+ * (the run was killed, or its restore build failed). Every test against
+ * that binary tests the mutation. Not bypassable: `--allow-stale-build`
+ * accepts old content, not a deliberately broken binary.
+ */
+function enforceControlBuiltGate(baseline) {
+    const stamp = baseline?.controlBuild;
+    if (stamp === undefined)
+        return;
+    throw new PreflightRefusalError(`The binary under test was built with the negative control ${stamp.diffFile} applied ` +
+        `(${stamp.targets.map((target) => `engine/${target}`).join(', ')}, applied ${stamp.appliedAt}), ` +
+        'and no build has recompiled the restored source since. Run "fireforge build" to ' +
+        'rebuild the binary without the control, then rerun.', 'control-built');
+}
+/**
+ * Stale-compiled refusal: compiled sources modified after the binary under
+ * test was linked. `--allow-stale-build` downgrades it to a warning, as it
+ * does the stale-build refusal.
+ */
+async function enforceStaleCompiledGate(engineDir, baseline, options, launchablePath) {
+    const result = await findCompiledSourcesNewerThanBinary(engineDir, baseline, launchablePath);
+    if (result === undefined || result.paths.length === 0)
+        return;
+    const message = formatStaleCompiledRefusal(result);
+    if (options.allowStaleBuild === true) {
+        warn(message);
+        return;
+    }
+    throw new PreflightRefusalError(message, 'stale-compiled');
+}
 /**
  * Packaging-coverage refusal. A path outside the recorded scoped list is
  * still covered while its own staging inputs are unchanged against a
@@ -93,6 +132,12 @@ async function enforceCoverageGate(engineDir, baseline, normalizedPaths) {
     throw new PreflightRefusalError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : [], changedManifests, {
         changedInputs: Object.fromEntries(remaining.map((request) => [request.path, request.changed])),
         carriesFullAnchor: baseline?.fullCoverageAnchor !== undefined,
+        recordedBy: baseline?.recordedBy,
+        builtAt: baseline?.builtAt,
+        recorder: baseline?.recorder,
+        recorderAlive: baseline?.recorder !== undefined &&
+            baseline.recorder.pid !== process.pid &&
+            isProcessAlive(baseline.recorder.pid),
     }), 'coverage-replaced');
 }
 /**

package/dist/src/commands/test-verdict.d.ts

@@ -1,7 +1,9 @@
 import type { HarnessRunVerdict } from '../core/test-harness-crash.js';
 /**
  * Reason codes the emission layer can put on a `FIREFORGE-VERDICT: FAIL`
- * line. The first three mirror the harness classifier. `preflight` covers
+ * line. The first three mirror the harness classifier, as does
+ * `server-startup`: a harness-crash-class infrastructure failure where a
+ * mochitest server never came up, so no test ran. `preflight` covers
  * every failure before harness classification (missing/stale builds,
  * invalid paths, port conflicts, config errors, spawn failures),
  * `inconclusive` marks a run whose harness result exists but cannot be
@@ -11,9 +13,9 @@ import type { HarnessRunVerdict } from '../core/test-harness-crash.js';
  * and `killed` marks a run terminated by a signal before it could reach any
  * of the others.
  */
-export type FireforgeVerdictReason = 'crash' | 'harness-arguments' | 'no-tests' | 'test-failures' | 'preflight' | 'inconclusive' | 'lock-timeout' | 'killed';
+export type FireforgeVerdictReason = 'crash' | 'harness-arguments' | 'no-tests' | 'test-failures' | 'server-startup' | 'preflight' | 'inconclusive' | 'lock-timeout' | 'killed';
 /** Additive keys a run can stamp on its verdict line. */
-export type VerdictRunAttributeKey = 'shuffle' | 'orphans-reaped' | 'host-load' | 'host-cpu-warning' | 'power-source' | 'power-changed' | 'furnace-applied' | 'furnace-apply' | 'furnace-skipped' | 'control-build' | 'drift-tolerated' | 'lock' | 'jobs' | 'results';
+export type VerdictRunAttributeKey = 'shuffle' | 'orphans-reaped' | 'host-load' | 'host-cpu-warning' | 'power-source' | 'power-changed' | 'furnace-applied' | 'furnace-apply' | 'furnace-skipped' | 'control-build' | 'control-restore-build' | 'build-id' | 'drift-tolerated' | 'lock' | 'jobs' | 'upload-dirs' | 'results';
 /** Records an additive attribute for this run's verdict line. */
 export declare function setVerdictRunAttribute(key: VerdictRunAttributeKey, value: string): void;
 /**

package/dist/src/commands/test.js

@@ -2,6 +2,7 @@
 import { join, resolve } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineExists } from '../core/engine-precondition.js';
+import { readBuildId } from '../core/launchable-build.js';
 import { hasBuildArtifacts } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { ensureLaunchableBrowserNotRunning } from '../core/marionette-port.js';
@@ -142,7 +143,9 @@ export async function testCommand(projectRoot, testPaths, options = {}, underLoc
             renderPreflightRefusal(error);
             emitFailVerdict('preflight', refusalNote(error));
         });
-        const collectsResults = options.results !== undefined || options.shardSize !== undefined;
+        // `--jobs` always reads each dispatch's raw log, so a shard that ran
+        // files other than its own fails instead of passing on their results.
+        const collectsResults = options.results !== undefined || options.shardSize !== undefined || (options.jobs ?? 1) > 1;
         try {
             await underLock(() => (collectsResults ? withRawLogDir((dir) => orchestrate(dir)) : orchestrate()), lockMode);
         }
@@ -346,9 +349,19 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
     if (await runTestBuildPhase(projectRoot, paths, projectConfig, harnessRetries, options, {
         classification,
         normalizedPaths: hooks.coveragePaths ?? normalizedPaths,
+        ...(hooks.fullBuildReason === undefined ? {} : { fullBuildReason: hooks.fullBuildReason }),
+        ...(hooks.controlBuild === undefined ? {} : { controlBuild: hooks.controlBuild }),
+        launchablePath,
     })) {
         return;
     }
+    // Which binary this run exercises, read after the pre-test build so it
+    // names the build the tests actually ran against (`moz:buildID`).
+    if (launchablePath !== undefined) {
+        const buildId = await readBuildId(paths.engine, launchablePath);
+        if (buildId !== undefined)
+            setVerdictRunAttribute('build-id', buildId);
+    }
     const { forwardedPort, effectivePort } = await ensureTestBrowserEnvironment(paths.engine, launchablePath, xpcshellOnly, projectConfig, options, buildCheck.objDir);
     if (options.doctor) {
         const doctorOutcome = await runDoctorPreflight({

package/dist/src/commands/token.js

@@ -42,8 +42,8 @@ async function normalizeTokenNameForProject(projectRoot, rawTokenName) {
  *
  * A variant skip has no category to name, because the declaration lives in
  * a `:root<selector>` block, so the location reads as that block. The
- * variant path used to report no location at all, so a re-run meant to
- * change a value exited 0 having silently changed nothing.
+ * location matters: without it a re-run meant to change a value exits 0
+ * having silently changed nothing.
  *
  * @param tokenName - Full token name including prefix
  * @param result - Result carrying the skip location, when known

package/dist/src/commands/verify.js

@@ -328,7 +328,7 @@ export function registerVerify(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('verify')
         .description('Read-only fsck for the patch queue (manifest + cross-patch lint)')
-        .option('--patches <names...>', 'Judge only findings that name these patches (filename, stem, order number, manifest name, or slug; repeat or comma-separate). Queue-wide findings stay; unowned worktree changes drop out')
+        .option('--patches <names...>', 'Judge only findings that name these patches (filename, stem, order number, manifest name, or slug; repeat, or separate with commas or whitespace). Queue-wide findings stay; unowned worktree changes drop out')
         .action(withErrorHandling(async (options) => {
         await verifyCommand(getProjectRoot(), options);
     }));

package/dist/src/commands/watch.js

@@ -195,7 +195,7 @@ export async function watchCommand(projectRoot) {
     catch (error) {
         throw new BuildError('Watch process failed to start', 'mach watch', error instanceof Error ? error : undefined);
     }
-    // On Ctrl+C the bin signal handler now waits for the mach child to shut
+    // On Ctrl+C the bin signal handler waits for the mach child to shut
     // down (waitForActiveChildShutdown) before exiting, so this continuation
     // can run and whitelist the SIGINT exit code, though the bin may still
     // win the race and terminate first. Both outcomes are acceptable.

package/dist/src/commands/wire.js

@@ -208,7 +208,7 @@ function buildWireSubscriptOptions(options, domFilePath, domTargetPath, subscrip
     };
 }
 /**
- * Surfaces any legacy parser fallbacks the wiring run consumed, so the
+ * Surfaces any regex parser fallbacks the wiring run consumed, so the
  * operator knows which files were mutated by the regex path rather than
  * the AST path.
  */

package/dist/src/core/build-audit-resolve.d.ts

@@ -29,11 +29,10 @@ export declare function countTrailingSegmentMatches(a: string, b: string): numbe
  *
  * Shared on purpose: this set governs two halves of one decision,
  * `scoreCandidate` (selection) and `isConfidentMatch` (confirmation, in
- * `build-audit.ts`). When the halves kept separate copies they disagreed,
- * so a source path could earn a selection bonus for a segment that
- * confirmation then rejected as meaningless, leaving the chosen artifact
- * unconfirmable. Any addition must apply to both halves, which is now
- * automatic.
+ * `build-audit.ts`). Separate copies would disagree, so a source path
+ * could earn a selection bonus for a segment that confirmation then
+ * rejected as meaningless, leaving the chosen artifact unconfirmable. One
+ * set makes every addition apply to both halves.
  */
 export declare const GENERIC_PATH_SEGMENTS: ReadonlySet<string>;
 /**

package/dist/src/core/build-audit-resolve.js

@@ -96,11 +96,10 @@ export function countTrailingSegmentMatches(a, b) {
  *
  * Shared on purpose: this set governs two halves of one decision,
  * `scoreCandidate` (selection) and `isConfidentMatch` (confirmation, in
- * `build-audit.ts`). When the halves kept separate copies they disagreed,
- * so a source path could earn a selection bonus for a segment that
- * confirmation then rejected as meaningless, leaving the chosen artifact
- * unconfirmable. Any addition must apply to both halves, which is now
- * automatic.
+ * `build-audit.ts`). Separate copies would disagree, so a source path
+ * could earn a selection bonus for a segment that confirmation then
+ * rejected as meaningless, leaving the chosen artifact unconfirmable. One
+ * set makes every addition apply to both halves.
  */
 export const GENERIC_PATH_SEGMENTS = new Set([
     'content',

package/dist/src/core/build-audit-skip.d.ts

@@ -1,8 +1,8 @@
 /**
  * Why a changed engine path was not audited.
  *
- * The first four name skips that already existed as unstructured
- * `verbose()` strings. The last four are the 0.46.0 classifiers.
+ * Each reason is structured so summaries and machine output can count
+ * skips by cause instead of reading verbose log strings.
  */
 export type AuditSkipReason = 'not-packageable' | 'platform-gated' | 'platform-gated-ancestor' | 'tests-not-packaged' | 'source-unreadable' | 'branding-not-selected' | 'storybook-story' | 'declared-unpackaged';
 /** Render order for the `Packaged:` summary's per-class breakdown. */

package/dist/src/core/build-audit.d.ts

@@ -40,10 +40,9 @@ export interface AuditEntry {
     status: 'updated' | 'stale' | 'missing' | 'skipped';
     /**
      * Why a `skipped` entry was skipped. Present only for `skipped`. The
-     * reasons used to exist only as verbose log strings, so the summary line
-     * could report `4 missing` on a run with zero real misses and nothing in
-     * the counts distinguished a structural non-input from an unregistered
-     * file an operator must act on.
+     * reason lets the counts distinguish a structural non-input from an
+     * unregistered file an operator must act on, so the summary line never
+     * reports skips as misses.
      */
     skipReason?: AuditSkipReason;
 }

package/dist/src/core/build-baseline-types.d.ts

@@ -93,10 +93,11 @@ export interface BuildBaseline {
      * mozconfig and complete testInputFingerprints outside the rebuilt scope
      * remain anchored. Explicitly rebuilt paths may change. A failed anchor
      * replaces coverage with a dropped-path notice, or refuses when the caller
-     * required --extend-coverage. Legacy packageable-only anchors cannot retain
-     * coverage because they cannot prove test scripts and fixtures unchanged.
+     * required --extend-coverage. Anchors that fingerprint only packageable
+     * inputs cannot retain coverage because they cannot prove test scripts and
+     * fixtures unchanged.
      *
-     * Since 0.50.0 retention is decided per staged path: see
+     * Retention is decided per staged path: see
      * {@link BuildBaseline.testCoverageRecords} and
      * {@link BuildBaseline.fullCoverageAnchor}.
      */
@@ -144,6 +145,39 @@ export interface BuildBaseline {
      * as "unknown" when absent.
      */
     recordedBy?: string;
+    /**
+     * The process that wrote this baseline: its pid, its invocation id (the
+     * one its history records carry) and the caller's `FIREFORGE_SESSION_ID`
+     * when set. A coverage refusal names it, so a run whose claim another
+     * session's scoped build replaced can tell whose build that was.
+     */
+    recorder?: BaselineRecorder;
+    /**
+     * Set when this build compiled a negative control into the binary
+     * (`test --negative-control --build` on compiled source). The source is
+     * restored byte-exact after the run, but the objdir binary keeps the
+     * mutation until a build recompiles it. FireForge runs that restore build
+     * itself, inside the same lock hold, and its baseline drops the stamp.
+     * A stamp still present (the run was killed, or the restore build
+     * failed) makes the next `fireforge test` refuse with `control-built`
+     * until `fireforge build` replaces the baseline.
+     */
+    controlBuild?: ControlBuildStamp;
+}
+/** See {@link BuildBaseline.controlBuild}. */
+export interface ControlBuildStamp {
+    /** The `--negative-control` diff file, as given. */
+    diffFile: string;
+    /** Engine-relative compiled targets the control edited. */
+    targets: string[];
+    /** ISO-8601 time the control was applied. */
+    appliedAt: string;
+}
+/** See {@link BuildBaseline.recorder}. */
+export interface BaselineRecorder {
+    pid: number;
+    invocationId: string;
+    sessionId?: string;
 }
 /**
  * State of the engine at the last full build, as far as compiled-in XPCOM

package/dist/src/core/build-baseline-validate.d.ts

@@ -1,3 +1,32 @@
 import { type BuildBaseline } from './build-baseline-types.js';
-/** Validates persisted fields without converting malformed coverage into a full claim. */
+/**
+ * The first field of a persisted baseline that fails validation, and the
+ * offending value: what a refusal names so the operator can tell a scoped
+ * coverage claim from a corrupt marker.
+ */
+export interface BuildBaselineProblem {
+    /** Field path, e.g. `testPackagingCoverage[2]` or `testCoverageRecords["a/"]`. */
+    field: string;
+    /** The offending value, as found (may be any JSON value). */
+    value: unknown;
+}
+/** True when the problem sits in a packaging-coverage field. */
+export declare function isCoverageProblem(problem: BuildBaselineProblem): boolean;
+/** Renders a problem for a refusal: the field and a bounded JSON rendering of its value. */
+export declare function describeBuildBaselineProblem(problem: BuildBaselineProblem): string;
+/**
+ * Validates persisted fields without converting malformed coverage into a
+ * full claim, and returns the first failing field with its value, or
+ * undefined when the baseline is valid.
+ *
+ * @param value - The parsed `last-build.json`
+ */
+export declare function findBuildBaselineProblem(value: unknown): BuildBaselineProblem | undefined;
+/**
+ * Validates persisted fields without converting malformed coverage into a
+ * full claim. The boolean form of {@link findBuildBaselineProblem}.
+ *
+ * @internal Exported only so tests can reach it. Production reads go
+ * through `findBuildBaselineProblem`, which names the failing field.
+ */
 export declare function isBuildBaseline(value: unknown): value is BuildBaseline;

package/dist/src/core/build-baseline-validate.js

@@ -24,49 +24,150 @@ function isCoverageAnchor(value) {
         isFingerprint(value['mozconfigHash']) &&
         isFingerprintMap(value['fingerprints']));
 }
-function isCoverageRecordMap(value) {
+/** A `controlBuild` stamp: the control's diff file, its targets and when it went in. */
+function isControlBuildStamp(value) {
     return (isObject(value) &&
-        Object.entries(value).every(([path, record]) => isBaselinePath(path) &&
-            isCoverageAnchor(record) &&
-            isObject(record) &&
-            Array.isArray(record['inputs']) &&
-            record['inputs'].every(isBaselinePath)));
+        typeof value['diffFile'] === 'string' &&
+        Array.isArray(value['targets']) &&
+        value['targets'].every(isBaselinePath) &&
+        typeof value['appliedAt'] === 'string' &&
+        Number.isFinite(Date.parse(value['appliedAt'])));
 }
-/** Validates persisted fields without converting malformed coverage into a full claim. */
-export function isBuildBaseline(value) {
+/** A `recorder` stamp: an integer pid, an invocation id and an optional session id. */
+function isBaselineRecorder(value) {
+    return (isObject(value) &&
+        Number.isInteger(value['pid']) &&
+        typeof value['invocationId'] === 'string' &&
+        (value['sessionId'] === undefined || typeof value['sessionId'] === 'string'));
+}
+/** Fields whose problem a scoped `test --build` can leave and a fresh one replaces. */
+const COVERAGE_FIELDS = ['testPackagingCoverage', 'testCoverageRecords', 'fullCoverageAnchor'];
+/** True when the problem sits in a packaging-coverage field. */
+export function isCoverageProblem(problem) {
+    return COVERAGE_FIELDS.some((field) => problem.field === field ||
+        problem.field.startsWith(`${field}[`) ||
+        problem.field.startsWith(`${field}.`));
+}
+/** Renders a problem for a refusal: the field and a bounded JSON rendering of its value. */
+export function describeBuildBaselineProblem(problem) {
+    let rendered;
+    try {
+        // JSON.stringify(undefined) returns undefined at runtime despite its type.
+        const json = JSON.stringify(problem.value);
+        rendered = json ?? 'undefined';
+    }
+    catch {
+        rendered = String(problem.value);
+    }
+    if (rendered.length > 120)
+        rendered = `${rendered.slice(0, 117)}...`;
+    return `${problem.field} = ${rendered}`;
+}
+function findFingerprintMapProblem(field, value) {
+    if (!isObject(value))
+        return { field, value };
+    for (const [path, fingerprint] of Object.entries(value)) {
+        if (!isBaselinePath(path))
+            return { field: `${field}[${JSON.stringify(path)}]`, value: path };
+        if (!isFingerprint(fingerprint)) {
+            return { field: `${field}[${JSON.stringify(path)}]`, value: fingerprint };
+        }
+    }
+    return undefined;
+}
+function findCoverageRecordProblem(value) {
+    const field = 'testCoverageRecords';
+    if (!isObject(value))
+        return { field, value };
+    for (const [path, record] of Object.entries(value)) {
+        const entry = `${field}[${JSON.stringify(path)}]`;
+        if (!isBaselinePath(path))
+            return { field: entry, value: path };
+        if (!isCoverageAnchor(record) || !isObject(record) || !Array.isArray(record['inputs'])) {
+            return { field: entry, value: record };
+        }
+        const inputs = record['inputs'];
+        const input = inputs.find((item) => !isBaselinePath(item));
+        if (input !== undefined)
+            return { field: `${entry}.inputs`, value: input };
+    }
+    return undefined;
+}
+/**
+ * Validates persisted fields without converting malformed coverage into a
+ * full claim, and returns the first failing field with its value, or
+ * undefined when the baseline is valid.
+ *
+ * @param value - The parsed `last-build.json`
+ */
+export function findBuildBaselineProblem(value) {
     if (!isObject(value))
-        return false;
-    if (typeof value['engineHeadSha'] !== 'string' ||
-        typeof value['builtAt'] !== 'string' ||
-        !Number.isFinite(Date.parse(value['builtAt'])) ||
-        typeof value['binaryName'] !== 'string' ||
-        !/^[a-z][a-z0-9-]*$/.test(value['binaryName']))
-        return false;
+        return { field: '(root)', value };
+    if (typeof value['engineHeadSha'] !== 'string') {
+        return { field: 'engineHeadSha', value: value['engineHeadSha'] };
+    }
+    if (typeof value['builtAt'] !== 'string' || !Number.isFinite(Date.parse(value['builtAt']))) {
+        return { field: 'builtAt', value: value['builtAt'] };
+    }
+    if (typeof value['binaryName'] !== 'string' || !/^[a-z][a-z0-9-]*$/.test(value['binaryName'])) {
+        return { field: 'binaryName', value: value['binaryName'] };
+    }
     for (const field of [
         'packageableFingerprints',
         'testInputFingerprints',
         'buildInputFingerprints',
     ]) {
-        if (value[field] !== undefined && !isFingerprintMap(value[field]))
-            return false;
+        if (value[field] === undefined)
+            continue;
+        const problem = findFingerprintMapProblem(field, value[field]);
+        if (problem !== undefined)
+            return problem;
     }
     const coverage = value['testPackagingCoverage'];
-    if (coverage !== undefined &&
-        coverage !== 'full' &&
-        !(Array.isArray(coverage) && coverage.every(isBaselinePath)))
-        return false;
-    if (value['mozconfigHash'] !== undefined && !isFingerprint(value['mozconfigHash']))
-        return false;
-    if (value['recordedBy'] !== undefined && typeof value['recordedBy'] !== 'string')
-        return false;
-    if (value['testCoverageRecords'] !== undefined &&
-        !isCoverageRecordMap(value['testCoverageRecords']))
-        return false;
-    if (value['fullCoverageAnchor'] !== undefined && !isCoverageAnchor(value['fullCoverageAnchor']))
-        return false;
+    if (coverage !== undefined && coverage !== 'full') {
+        if (!Array.isArray(coverage))
+            return { field: 'testPackagingCoverage', value: coverage };
+        const index = coverage.findIndex((path) => !isBaselinePath(path));
+        if (index >= 0) {
+            return { field: `testPackagingCoverage[${index}]`, value: coverage[index] };
+        }
+    }
+    if (value['mozconfigHash'] !== undefined && !isFingerprint(value['mozconfigHash'])) {
+        return { field: 'mozconfigHash', value: value['mozconfigHash'] };
+    }
+    if (value['recordedBy'] !== undefined && typeof value['recordedBy'] !== 'string') {
+        return { field: 'recordedBy', value: value['recordedBy'] };
+    }
+    if (value['recorder'] !== undefined && !isBaselineRecorder(value['recorder'])) {
+        return { field: 'recorder', value: value['recorder'] };
+    }
+    if (value['testCoverageRecords'] !== undefined) {
+        const problem = findCoverageRecordProblem(value['testCoverageRecords']);
+        if (problem !== undefined)
+            return problem;
+    }
+    if (value['fullCoverageAnchor'] !== undefined && !isCoverageAnchor(value['fullCoverageAnchor'])) {
+        return { field: 'fullCoverageAnchor', value: value['fullCoverageAnchor'] };
+    }
     const components = value['staticComponentsBaseline'];
-    return (components === undefined ||
-        (isObject(components) &&
+    if (components !== undefined &&
+        !(isObject(components) &&
             typeof components['engineHeadSha'] === 'string' &&
-            isFingerprintMap(components['fingerprints'])));
+            isFingerprintMap(components['fingerprints']))) {
+        return { field: 'staticComponentsBaseline', value: components };
+    }
+    if (value['controlBuild'] !== undefined && !isControlBuildStamp(value['controlBuild'])) {
+        return { field: 'controlBuild', value: value['controlBuild'] };
+    }
+    return undefined;
+}
+/**
+ * Validates persisted fields without converting malformed coverage into a
+ * full claim. The boolean form of {@link findBuildBaselineProblem}.
+ *
+ * @internal Exported only so tests can reach it. Production reads go
+ * through `findBuildBaselineProblem`, which names the failing field.
+ */
+export function isBuildBaseline(value) {
+    return findBuildBaselineProblem(value) === undefined;
 }