@hominis/fireforge 0.50.0 → 0.51.0

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

@@ -25,6 +25,15 @@ export interface TestRunHooks {
     coveragePaths?: string[];
     /** Runs after every preflight gate and the pre-test build, right before dispatch. */
     beforeDispatch?: () => Promise<void>;
+    /**
+     * Runs right before the pre-test build: a negative control on compiled
+     * source, which only reaches the binary when the build compiles it.
+     */
+    beforeBuild?: () => Promise<void>;
+    /** `--repeat` run this sub-run is (1-based), for `--results`. */
+    repetition?: number;
+    /** Where dispatches write their mozlog raw logs (`--results`, `--shard-size`). */
+    rawLogDir?: string;
 }
 /** The single-run body (`runTestCommandBody`), injected to avoid an import cycle. */
 export type TestRunBody = (paths: string[], options: TestOptions, hooks: TestRunHooks) => Promise<void>;

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

@@ -17,15 +17,16 @@
  */
 import { getProjectPaths } from '../core/config.js';
 import { applyNegativeControl, planNegativeControl, recoverPendingNegativeControl, restoreNegativeControl, } from '../core/negative-control.js';
+import { formatCompiledControlRefusal } from '../core/negative-control-compiled.js';
 import { getActiveRunLogPath, writeToActiveRunLog } from '../core/run-log.js';
-import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { GeneralError, InvalidArgumentError, PreflightRefusalError } from '../errors/base.js';
 import { TestFailureError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { info, notice, success } from '../utils/logger.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { classifyTestHarnesses } from './test-modes.js';
 import { deriveControlOutcome, describeControlOutcome, formatAggregateBody, formatRunLine, parseCapturedVerdict, worstRun, } from './test-multi-verdict.js';
-import { emitAggregateVerdict, emitFailVerdict, setVerdictCapture, verdictEmitted, } from './test-verdict.js';
+import { emitAggregateVerdict, emitFailVerdict, setVerdictCapture, setVerdictRunAttribute, verdictEmitted, } from './test-verdict.js';
 function assertMultiRunUsage(testPaths, options) {
     const flag = options.negativeControl !== undefined ? '--negative-control' : '--repeat';
     if (testPaths.length === 0) {
@@ -84,7 +85,10 @@ async function planRuns(engineDir, testPaths, options) {
                 ...(group.harness === undefined ? {} : { harness: group.harness }),
                 paths: group.paths,
                 options: first ? options : laterRunOptions(options),
-                hooks: first && union !== undefined ? { coveragePaths: union } : {},
+                hooks: {
+                    repetition,
+                    ...(first && union !== undefined ? { coveragePaths: union } : {}),
+                },
             });
         }
     }
@@ -158,6 +162,16 @@ export async function orchestrateTestRuns(projectRoot, testPaths, options, body,
         : await planNegativeControl(projectRoot, projectPaths.engine, options.negativeControl, {
             deferApplyCheck: options.build === true,
         });
+    // A compiled target only reaches the binary through a build, so its
+    // control goes in before the first run's pre-test build.
+    const compiled = plan?.compiled;
+    const compiledControl = compiled !== undefined;
+    if (compiledControl) {
+        if (options.build !== true) {
+            throw new PreflightRefusalError(formatCompiledControlRefusal(compiled), 'negative-control');
+        }
+        setVerdictRunAttribute('control-build', 'compiled');
+    }
     const results = [];
     let restoreError;
     for (const [index, run] of runs.entries()) {
@@ -170,7 +184,11 @@ export async function orchestrateTestRuns(projectRoot, testPaths, options, body,
         try {
             await body(run.paths, run.options, {
                 ...run.hooks,
-                ...(plan === undefined ? {} : { beforeDispatch: controlHook(controlPaths, plan, slot) }),
+                ...(plan === undefined
+                    ? {}
+                    : compiledControl && index === 0
+                        ? { beforeBuild: controlHook(controlPaths, plan, slot) }
+                        : { beforeDispatch: controlHook(controlPaths, plan, slot) }),
             });
         }
         catch (caught) {

package/dist/src/commands/test-perf-scope.d.ts

@@ -27,3 +27,24 @@ export declare function describePerfStaleImpact(engineDir: string, stalePaths: r
  * @param engineDir - Absolute engine directory
  */
 export declare function perfGenerationTolerance(engineDir: string): (before: string, after: string) => Promise<boolean>;
+/**
+ * Tolerance for `assertEngineGenerationUnchanged` on an ordinary run: true
+ * (with a warning, and `drift-tolerated=<n>` on the verdict) when HEAD did
+ * not move and every changed path is one the running browser cannot see.
+ *
+ * A peer deleting an unrelated chrome script used to make a whole run
+ * inconclusive. What a running browser can see mid-run is narrower than
+ * "anything under engine/": a file the objdir links to its source (`live`),
+ * one the harness stages at dispatch (`at-dispatch`), and the run's own
+ * test files and the staging inputs their manifests name. A compiled
+ * source, or a file the build copied into the package, is already fixed in
+ * the running binary or package; the next run's stale-build gate judges it.
+ *
+ * Perf runs keep {@link perfGenerationTolerance}: a sample is also void
+ * when a packaged path changes.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param requested - Normalized request paths of the run
+ * @param onTolerated - Receives the tolerated path count
+ */
+export declare function runGenerationTolerance(engineDir: string, requested: readonly string[], onTolerated: (count: number) => void): (before: string, after: string) => Promise<boolean>;

package/dist/src/commands/test-perf-scope.js

@@ -81,3 +81,58 @@ export function perfGenerationTolerance(engineDir) {
         return true;
     };
 }
+/**
+ * Tolerance for `assertEngineGenerationUnchanged` on an ordinary run: true
+ * (with a warning, and `drift-tolerated=<n>` on the verdict) when HEAD did
+ * not move and every changed path is one the running browser cannot see.
+ *
+ * A peer deleting an unrelated chrome script used to make a whole run
+ * inconclusive. What a running browser can see mid-run is narrower than
+ * "anything under engine/": a file the objdir links to its source (`live`),
+ * one the harness stages at dispatch (`at-dispatch`), and the run's own
+ * test files and the staging inputs their manifests name. A compiled
+ * source, or a file the build copied into the package, is already fixed in
+ * the running binary or package; the next run's stale-build gate judges it.
+ *
+ * Perf runs keep {@link perfGenerationTolerance}: a sample is also void
+ * when a packaged path changes.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param requested - Normalized request paths of the run
+ * @param onTolerated - Receives the tolerated path count
+ */
+export function runGenerationTolerance(engineDir, requested, onTolerated) {
+    return async (before, after) => {
+        const delta = generationDeltaPaths(before, after);
+        if (delta.headMoved || delta.paths.length === 0)
+            return false;
+        const index = await loadEngineInstallIndex(engineDir);
+        if (index === undefined)
+            return false;
+        const inputs = [...requested];
+        for (const path of requested)
+            inputs.push(...(await collectStagingInputs(engineDir, path)));
+        for (const path of delta.paths) {
+            const bare = path.endsWith('/') ? path.slice(0, -1) : path;
+            if (inputs.some((input) => isUnderPath(bare, input) || isUnderPath(input, bare))) {
+                return false;
+            }
+            // A path-less run requests every test, so any test file is its own.
+            if (requested.length === 0 && isTestPath(path))
+                return false;
+            if (path.endsWith('/')) {
+                if (installsFromDirectory(index, path))
+                    return false;
+                continue;
+            }
+            const delivery = await classifyRuntimeDelivery(index, engineDir, path);
+            if (delivery === 'live' || delivery === 'at-dispatch')
+                return false;
+        }
+        warn(`engine/ changed while this run was in flight, but only in files the running browser ` +
+            `cannot see (${capList(delta.paths)}); the verdict stands. The next run's stale-build ` +
+            'gate judges whether they need a rebuild.');
+        onTolerated(delta.paths.length);
+        return true;
+    };
+}

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

@@ -22,10 +22,13 @@ import { join } from 'node:path';
 import { describeBuildRunState, readBuildRunState } from '../core/build-run-record.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineExists } from '../core/engine-precondition.js';
+import { autoPortsRequested } from '../core/harness-port-fallback.js';
 import { hasBuildArtifacts, hasRunnableBundle } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { assertMarionettePortAvailable, ensureLaunchableBrowserNotRunning, extractForwardedMarionettePort, } from '../core/marionette-port.js';
 import { ensureMochitestServerPortAvailable } from '../core/mochitest-server-port.js';
+import { planNegativeControl } from '../core/negative-control.js';
+import { formatCompiledControlRefusal } from '../core/negative-control-compiled.js';
 import { waitBeforeLock } from '../core/preflight-wait.js';
 import { PreflightRefusalError } from '../errors/base.js';
 import { info } from '../utils/logger.js';
@@ -33,6 +36,7 @@ import { resolveWaitLockSeconds } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { checkRequestedTestTypes } from './test-checkjs.js';
 import { assertPathlessTestMode, classifyBeforeDispatch, resolveCanaryPath } from './test-modes.js';
+import { enforceStaleBuildGate } from './test-stale-gate.js';
 /**
  * Resolves the launchable binary a test run needs, or refuses naming why
  * it is missing. The cause comes from the build run record, which any
@@ -95,10 +99,11 @@ async function loadPreLockContext(projectRoot, testPaths, options) {
  * @param options - Parsed test options
  */
 export async function runTestPreLockPreflight(projectRoot, testPaths, options) {
-    const context = await loadPreLockContext(projectRoot, testPaths, options);
-    if (context === undefined)
-        return options;
-    const { paths, config, objDir } = context;
+    const loaded = await loadPreLockContext(projectRoot, testPaths, options);
+    if (loaded === undefined)
+        return withLockMode(options, 'exclusive');
+    const { paths, config, objDir } = loaded;
+    options = withLockMode(options, resolveTestLockMode(options, config));
     let launchablePath;
     try {
         launchablePath = await resolveLaunchablePathForTests(projectRoot, paths.engine, config.binaryName, objDir);
@@ -115,11 +120,102 @@ export async function runTestPreLockPreflight(projectRoot, testPaths, options) {
     if (options.build === true || options.buildOnly === true) {
         await checkRequestedTestTypes(paths, config, normalizedPaths);
     }
+    else {
+        await refuseCompiledControlBeforeLock(projectRoot, paths.engine, options);
+        await refuseStalePackagingBeforeLock(projectRoot, paths.engine, options, normalizedPaths);
+    }
     return waitForResourcesBeforeLock(paths.engine, config, options, {
         launchablePath,
         normalizedPaths,
     });
 }
+/** `options` with `sharedLock` set to the resolved decision. */
+function withLockMode(options, mode) {
+    if (mode === 'exclusive' && options.sharedLock === undefined)
+        return options;
+    const rest = { ...options };
+    delete rest.sharedLock;
+    return mode === 'shared' ? { ...rest, sharedLock: true } : rest;
+}
+/**
+ * How this run holds the engine session lock. Shared only on request
+ * (`--shared-lock` or `test.lockMode: "shared"`), and only for a run that
+ * writes nothing into engine/ or the objdir and can move its ports: no
+ * build, no negative control, auto ports. Every other run stays exclusive,
+ * so a shared holder can never overlap a build or a re-export.
+ */
+function resolveTestLockMode(options, config) {
+    const requested = options.sharedLock === true || config.test?.lockMode === 'shared';
+    if (!requested)
+        return 'exclusive';
+    const writes = options.build === true ||
+        options.buildOnly === true ||
+        options.negativeControl !== undefined ||
+        options.canary !== undefined ||
+        options.doctor === true;
+    if (writes || !autoPortsRequested(options, config)) {
+        info('Shared test lock requested, but this run ' +
+            (writes
+                ? 'builds, applies a negative control, or runs a canary/doctor preflight'
+                : 'does not use auto ports (--auto-ports or test.mochitestPorts: "auto")') +
+            ', so it holds the engine lock exclusively.');
+        return 'exclusive';
+    }
+    return 'shared';
+}
+/**
+ * Refuses a build-less `--negative-control` on compiled source before the
+ * lock: applied after the build it is never compiled, so the run could only
+ * report `control=missed` against the unmutated binary.
+ */
+async function refuseCompiledControlBeforeLock(projectRoot, engineDir, options) {
+    if (options.negativeControl === undefined)
+        return;
+    let plan;
+    try {
+        plan = await planNegativeControl(projectRoot, engineDir, options.negativeControl);
+    }
+    catch {
+        // Any other refusal (including a control a killed run left applied,
+        // which only the in-lock recovery may undo) is the in-lock pass's.
+        return;
+    }
+    if (plan.compiled === undefined)
+        return;
+    throw new PreflightRefusalError(formatCompiledControlRefusal(plan.compiled), 'negative-control');
+}
+/**
+ * Runs the build-less run's packaging gates (coverage, stale content,
+ * StaticComponents) before the lock, so a refusal surfaces before the run
+ * queues instead of after it reached the head of the queue. The same gate
+ * runs again under the lock, where a peer's build may since have changed
+ * the answer; this pass only refuses early what would refuse anyway.
+ *
+ * Skipped while a build runs (it will rewrite the record this reads) and
+ * under `--allow-stale-build`/`--allow-stale-components`, whose warnings
+ * belong to the in-lock pass alone. A `--negative-control` refusal says to
+ * add `--build`: without it the control has nothing current to run on, and
+ * the invocation used to end `control=inconclusive` after a full queue.
+ */
+async function refuseStalePackagingBeforeLock(projectRoot, engineDir, options, normalizedPaths) {
+    if (options.allowStaleBuild === true || options.allowStaleComponents === true)
+        return;
+    if ((await readBuildRunState(projectRoot)).kind === 'running')
+        return;
+    try {
+        await enforceStaleBuildGate(projectRoot, engineDir, options, normalizedPaths, {
+            quiet: true,
+        });
+    }
+    catch (error) {
+        if (options.negativeControl === undefined || !(error instanceof PreflightRefusalError)) {
+            throw error;
+        }
+        throw new PreflightRefusalError(`${error.message}\n\nThis --negative-control run has no --build, so its control would ` +
+            'run on this packaging and end inconclusive. Add --build: the control is then planned ' +
+            'against a fresh build of the requested paths.', error.note);
+    }
+}
 /** `options` without one wait budget, which this pass already spent. */
 function withoutOption(options, key) {
     const rest = { ...options };

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

@@ -106,7 +106,21 @@ function registerTestSharingOptions(test) {
 function registerTestBuildOptions(test) {
     return test
         .option('--extend-coverage', 'With --build/--build-only and explicit paths, refuse instead of dropping any earlier packaging claim. Scoped builds keep each earlier path by default while its own staging inputs (manifest directory and the fixtures its manifest names) and engine/mozconfig are unchanged; this flag turns a drop into a refusal before the build.')
-        .option('--no-furnace-apply', 'With --build/--build-only, skip the Furnace apply so the build packages engine/ as it stands; names the components whose undeployed components/ edits it leaves out');
+        .option('--furnace-apply <mode>', 'With --build/--build-only: all (default; deploy every component with undeployed edits), reached (only components a requested test names; the rest are reported as furnace-skipped=<names>), or none. Same as test.furnaceApply.', commanderArgParser((raw) => {
+        if (raw !== 'all' && raw !== 'reached' && raw !== 'none') {
+            throw new GeneralError(`--furnace-apply must be all, reached or none (got "${raw}")`);
+        }
+        return raw;
+    }))
+        .option('--no-furnace-apply', 'With --build/--build-only, skip the Furnace apply so the build packages engine/ as it stands; names the components whose undeployed components/ edits it leaves out (same as --furnace-apply none)');
+}
+/** Options that run a request on several harness instances, or judge it per file. */
+function registerTestParallelOptions(test) {
+    return test
+        .option('--jobs <n>', 'Run shards on n harness instances at once inside one lock hold, each with its own profile, Marionette port and (via auto ports) server ports. With --no-shard, or one directory argument, the files are split in order into n contiguous chunks. Prints a FIREFORGE-SHARD line per shard and one aggregate verdict. Requires --auto-ports or test.mochitestPorts: "auto".', commanderArgParser((raw) => parsePositiveIntegerFlag('--jobs', raw)))
+        .option('--shard-size <n>', 'Dispatch n files per mach invocation (mochitest restarts the browser between files) and judge each file from the structured log: shards= then counts files and failed-shards= names failed files. Combines with --jobs.', commanderArgParser((raw) => parsePositiveIntegerFlag('--shard-size', raw)))
+        .option('--results <path>', 'Write a JSON record per test file and --repeat run (status, expected, duration, run-log line) from the mozlog structured log, and name it on the verdict as results=<path>')
+        .option('--shared-lock', 'Hold the engine session lock shared when this run is build-less, applies no negative control and uses auto ports, so peers\' build-less runs on this objdir overlap; builds and re-exports still wait. Same as test.lockMode: "shared".');
 }
 /** Registers the test command on the CLI program. */
 export function registerTest(program, { getProjectRoot, withErrorHandling }) {
@@ -146,13 +160,14 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         return n;
     }))
         .addHelpText('after', TEST_HELP_TEXT);
-    addWaitLockOption(registerTestBuildOptions(registerTestMultiRunOptions(registerTestSharingOptions(test)))).action(withErrorHandling(async (paths, options) => {
+    addWaitLockOption(registerTestParallelOptions(registerTestBuildOptions(registerTestMultiRunOptions(registerTestSharingOptions(test))))).action(withErrorHandling(async (paths, options) => {
         const projectRoot = getProjectRoot();
         // Fallback for a verdict testCommand did not emit (it takes the lock).
         resetVerdictEmission();
         try {
-            await testCommand(projectRoot, paths, pickDefined(options), (body) => withEngineSessionLock(projectRoot, 'test', body, {
+            await testCommand(projectRoot, paths, pickDefined(options), (body, mode) => withEngineSessionLock(projectRoot, 'test', body, {
                 waitLockSeconds: resolveWaitLockSeconds(options.waitLock),
+                ...(mode === 'shared' ? { mode } : {}),
             }));
         }
         catch (error) {

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

@@ -0,0 +1,62 @@
+/**
+ * `fireforge test --results <path>`: one record per test file and per
+ * `--repeat` run, from the mozlog raw log each dispatch writes.
+ *
+ * Gates and retry wrappers downstream named a run's failing files by
+ * reading `TEST_START`/`TEST_END` lines and the prose of the "sharded test
+ * run(s) did not pass" error out of the human log, which nothing promised
+ * to keep stable. The results file is the stable form: JSON with a
+ * `schemaVersion`, written once the invocation has finished, and named on
+ * the verdict line as `results=<path>`.
+ */
+import type { RawTestResult } from '../core/test-raw-log.js';
+/** One file's result in one dispatch. */
+export interface TestFileResult extends RawTestResult {
+    /** `--repeat` run (1-based); 1 for a single run. */
+    run: number;
+    /** The shard (path argument or `--shard-size` chunk) the file ran in. */
+    shard: string;
+    /** Line of the run log where this file's dispatch began (1-based). */
+    logLine: number;
+}
+/** The document `--results` writes. */
+export interface TestResultsDocument {
+    schemaVersion: 1;
+    /** Files in dispatch-completion order. */
+    files: TestFileResult[];
+    /** Started files that never ended, per dispatch. */
+    unfinished: Array<{
+        test: string;
+        run: number;
+        shard: string;
+    }>;
+}
+/** Clears the collector at the start of an invocation. */
+export declare function resetTestResults(): void;
+/**
+ * Adds one dispatch's parsed raw log to the invocation's results.
+ *
+ * @param results - The dispatch's finished files
+ * @param unfinished - Its started-but-unfinished files
+ * @param context - Run, shard and run-log line of the dispatch
+ */
+export declare function recordTestResults(results: readonly RawTestResult[], unfinished: readonly string[], context: {
+    run: number;
+    shard: string;
+    logLine: number;
+}): void;
+/** The results collected so far (for tests and the shard summary). */
+export declare function collectedTestResults(): TestResultsDocument;
+/**
+ * Writes the collected results.
+ *
+ * @param path - Destination of `--results`
+ */
+export declare function writeTestResults(path: string): Promise<void>;
+/**
+ * Creates the scratch directory the dispatches' raw logs go to, runs
+ * `body`, and removes it afterwards.
+ *
+ * @param body - Receives the directory
+ */
+export declare function withRawLogDir<T>(body: (dir: string) => Promise<T>): Promise<T>;

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

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge test --results <path>`: one record per test file and per
+ * `--repeat` run, from the mozlog raw log each dispatch writes.
+ *
+ * Gates and retry wrappers downstream named a run's failing files by
+ * reading `TEST_START`/`TEST_END` lines and the prose of the "sharded test
+ * run(s) did not pass" error out of the human log, which nothing promised
+ * to keep stable. The results file is the stable form: JSON with a
+ * `schemaVersion`, written once the invocation has finished, and named on
+ * the verdict line as `results=<path>`.
+ */
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { writeJson } from '../utils/fs.js';
+let collected = { schemaVersion: 1, files: [], unfinished: [] };
+/** Clears the collector at the start of an invocation. */
+export function resetTestResults() {
+    collected = { schemaVersion: 1, files: [], unfinished: [] };
+}
+/**
+ * Adds one dispatch's parsed raw log to the invocation's results.
+ *
+ * @param results - The dispatch's finished files
+ * @param unfinished - Its started-but-unfinished files
+ * @param context - Run, shard and run-log line of the dispatch
+ */
+export function recordTestResults(results, unfinished, context) {
+    for (const result of results)
+        collected.files.push({ ...result, ...context });
+    for (const test of unfinished) {
+        collected.unfinished.push({ test, run: context.run, shard: context.shard });
+    }
+}
+/** The results collected so far (for tests and the shard summary). */
+export function collectedTestResults() {
+    return collected;
+}
+/**
+ * Writes the collected results.
+ *
+ * @param path - Destination of `--results`
+ */
+export async function writeTestResults(path) {
+    await writeJson(path, collectedTestResults());
+}
+/**
+ * Creates the scratch directory the dispatches' raw logs go to, runs
+ * `body`, and removes it afterwards.
+ *
+ * @param body - Receives the directory
+ */
+export async function withRawLogDir(body) {
+    const dir = await mkdtemp(join(tmpdir(), 'fireforge-raw-log-'));
+    try {
+        return await body(dir);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}

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

@@ -12,6 +12,7 @@
 import { type DisplaySleepState } from '../core/display-state.js';
 import { type MachCommandResult } from '../core/mach.js';
 import { type HarnessRunVerdict } from '../core/test-harness-crash.js';
+import { type RawTestResult } from '../core/test-raw-log.js';
 /** Default bounded retry budget for recognized harness crashes. */
 export declare const DEFAULT_HARNESS_RETRIES = 2;
 /**
@@ -49,6 +50,15 @@ export interface TestRunContext {
     fullOutput?: boolean;
     /** `--pgid-file`: where each dispatch publishes its harness process group id. */
     pgidFile?: string | undefined;
+    /**
+     * Where each dispatch writes its mozlog raw log (`--results`,
+     * `--shard-size`). Unset: no `--log-raw` is added and nothing is parsed.
+     */
+    rawLogDir?: string | undefined;
+    /** `--repeat` run this dispatch belongs to (1-based), for `--results`. */
+    repetition?: number | undefined;
+    /** Prefix for every echoed and logged output line (`--jobs` instances). */
+    outputPrefix?: string | undefined;
 }
 /** Outcome of one (possibly retried) harness invocation. */
 export interface TestRunOutcome {
@@ -62,64 +72,12 @@ export interface TestRunOutcome {
      * when the shape did not apply and no probe ran.
      */
     displayState?: DisplaySleepState | undefined;
+    /** Per-file results from the raw log, when the run wrote one. */
+    fileResults?: RawTestResult[] | undefined;
 }
 /**
  * Runs one mach test invocation for `paths`, retrying recognized harness
  * crashes up to the configured budget. Every attempt goes through the
  * stale-xpcshell-symlink repair path the single-run flow already used.
  */
-export declare function runTestsWithRetries(ctx: TestRunContext, paths: string[]): Promise<TestRunOutcome>;
-/**
- * One sequential harness invocation of a sharded run: a requested path
- * argument and the mach paths dispatched for it. A file argument is a group
- * of one. A directory argument groups its enumerated test files so the whole
- * directory still runs in ONE browser instance, keeping cross-file state
- * behaviour within a directory run.
- */
-export interface ShardGroup {
-    /** The path argument as the operator passed it (display label). */
-    label: string;
-    /** The mach dispatch paths for this argument. */
-    paths: string[];
-}
-/** Per-shard summary entry. */
-export interface ShardOutcome {
-    label: string;
-    outcome: TestRunOutcome;
-}
-/** Aggregate result of a sharded run, verdict emission deferred to the caller. */
-export interface ShardedRunSummary {
-    shards: ShardOutcome[];
-    passed: number;
-    total: number;
-    /** Aggregate classifier verdict. See {@link deriveAggregateShardVerdict}. */
-    aggregate: HarnessRunVerdict;
-}
-/**
- * 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`.
- */
-export declare function deriveAggregateShardVerdict(shards: ShardOutcome[]): HarnessRunVerdict;
-/**
- * Runs each requested path argument as its own sequential harness
- * invocation (a directory argument's enumerated files stay together in
- * one invocation, see {@link ShardGroup}) and prints an aggregate
- * report. Per-shard failures are diagnosed via `diagnoseShardFailure`
- * (which receives the throwing diagnosis chain from the command layer)
- * but downgraded to warnings so every shard runs. The aggregate verdict
- * line and the aggregate error are not produced here: the caller runs
- * the engine-generation integrity check first and then calls
- * {@link finalizeShardedOutcome}, so a run invalidated by a concurrent
- * `engine/` mutation can never print `PASS` before the check fails.
- */
-export declare function runShardedTests(ctx: TestRunContext, groups: ShardGroup[], diagnoseShardFailure: (outcome: TestRunOutcome, label: string) => string | undefined): Promise<ShardedRunSummary>;
-/**
- * Emits the aggregate FIREFORGE-VERDICT line for a sharded run, then
- * throws the aggregate error when any shard did not pass, the same
- * emit-then-throw shape as `finalizeSingleRunOutcome`. Called only after
- * the engine-generation check succeeded.
- */
-export declare function finalizeShardedOutcome(summary: ShardedRunSummary): void;
+export declare function runTestsWithRetries(ctx: TestRunContext, paths: string[], label?: string): Promise<TestRunOutcome>;