@hominis/fireforge 0.50.0 → 0.51.0

package/dist/src/core/patch-manifest-validate.js

@@ -5,6 +5,7 @@
 import { parseObject } from '../utils/parse.js';
 import { isArray, isObject, isValidFirefoxProduct, isValidFirefoxVersion, PATCH_CATEGORIES, } from '../utils/validation.js';
 import { parseLintIgnoreEntries } from './patch-lint-ignore.js';
+import { canonicalizePatchRow } from './patch-manifest-key-order.js';
 import { checkDocumentVersion, describeNewerDocument } from './state-file.js';
 function parseForwardImports(data, label) {
     if (!isArray(data)) {
@@ -134,7 +135,7 @@ function validatePatchMetadata(data, index) {
     if (rawStagedDependencies !== undefined) {
         result.stagedDependencies = parseStagedDependencies(rawStagedDependencies, `patches[${index}].stagedDependencies`);
     }
-    return result;
+    return canonicalizePatchRow(result);
 }
 /**
  * Validates the `retired` placeholders `patch retire` leaves behind. Kept on
@@ -160,6 +161,29 @@ function parseRetiredSlots(data) {
         return slot;
     });
 }
+/**
+ * Validates the `reserved` placeholders `patch reserve` writes. Same
+ * survival rule as {@link parseRetiredSlots}: dropping one on a round trip
+ * would reopen the gap a peer reserved the order to close.
+ */
+function parseReservedSlots(data) {
+    if (!isArray(data)) {
+        throw new Error('patches.json field "reserved" must be an array');
+    }
+    return data.map((entry, index) => {
+        const rec = parseObject(entry, `reserved[${index}]`);
+        const slot = {
+            order: rec.nonNegativeInteger('order'),
+            category: rec.validatedString('category', (value) => /^[a-z][a-z0-9-]*$/.test(value), 'a lowercase category identifier (letters, numbers, hyphens)'),
+            owner: rec.validatedString('owner', (value) => value.trim() !== '', 'a non-empty label'),
+            reservedAt: rec.string('reservedAt'),
+        };
+        const reason = rec.optionalString('reason');
+        if (reason !== undefined)
+            slot.reason = reason;
+        return slot;
+    });
+}
 /** Manifest schema version this build writes and understands. */
 const PATCHES_MANIFEST_VERSION = 1;
 /**
@@ -191,6 +215,8 @@ export function validatePatchesManifest(data) {
     };
     if (data['retired'] !== undefined)
         manifest.retired = parseRetiredSlots(data['retired']);
+    if (data['reserved'] !== undefined)
+        manifest.reserved = parseReservedSlots(data['reserved']);
     return manifest;
 }
 /**

package/dist/src/core/patch-order-legal.d.ts

@@ -14,7 +14,8 @@ import type { FireForgeConfig } from '../types/config.js';
  * Smallest order strictly greater than `after` that no patch occupies and
  * that adds no order-related `patchPolicy` finding (collision, category
  * range, reserved range, numeric gap) for a `category` patch. A retired
- * slot counts as free, since a patch may fill it. Returns null when no such
+ * slot counts as free, since a patch may fill it; a reservation does not,
+ * since it is held for its owner's export. Returns null when no such
  * order exists inside the category's configured ranges.
  *
  * @param config - Project config (only `patchPolicy` is read)

package/dist/src/core/patch-order-legal.js

@@ -11,6 +11,7 @@
  */
 import { formatPatchOrder } from './patch-parse.js';
 import { evaluatePatchPolicy } from './patch-policy.js';
+import { reservedOrderSet } from './patch-retired.js';
 /** Policy codes an order choice alone can trip. */
 const ORDER_CODES = new Set([
     'order-collision',
@@ -46,7 +47,8 @@ function orderIssueKeys(config, manifest) {
  * Smallest order strictly greater than `after` that no patch occupies and
  * that adds no order-related `patchPolicy` finding (collision, category
  * range, reserved range, numeric gap) for a `category` patch. A retired
- * slot counts as free, since a patch may fill it. Returns null when no such
+ * slot counts as free, since a patch may fill it; a reservation does not,
+ * since it is held for its owner's export. Returns null when no such
  * order exists inside the category's configured ranges.
  *
  * @param config - Project config (only `patchPolicy` is read)
@@ -55,7 +57,10 @@ function orderIssueKeys(config, manifest) {
  * @param after - The order the new patch must come after
  */
 export function earliestLegalOrderAfter(config, manifest, category, after) {
-    const occupied = new Set(manifest.patches.map((patch) => patch.order));
+    const occupied = new Set([
+        ...manifest.patches.map((patch) => patch.order),
+        ...reservedOrderSet(manifest),
+    ]);
     const ranges = config.patchPolicy?.ranges.filter((range) => range.category === category) ?? [];
     const limit = ranges.length > 0 ? Math.max(...ranges.map((range) => range.to)) : after + UNBOUNDED_SEARCH;
     const baseline = config.patchPolicy ? orderIssueKeys(config, manifest) : new Set();

package/dist/src/core/patch-policy.d.ts

@@ -72,5 +72,9 @@ export declare function applyRenameMapToManifest(manifest: PatchesManifest, rena
 }>): PatchesManifest;
 /** Enforces patch policy according to the configured mutation mode. */
 export declare function enforcePatchPolicy(input: PatchPolicyEnforcementInput): void;
-/** Allocates the next available order inside the configured ranges for a category. */
-export declare function allocatePolicyOrder(config: FireForgeConfig, patches: readonly PatchMetadata[], category: string): number | null;
+/**
+ * Allocates the next available order inside the configured ranges for a
+ * category. Orders in `reserved` (`patch reserve`) are skipped: they are
+ * held for their owner's export.
+ */
+export declare function allocatePolicyOrder(config: FireForgeConfig, patches: readonly PatchMetadata[], category: string, reserved?: ReadonlySet<number>): number | null;

package/dist/src/core/patch-policy.js

@@ -12,7 +12,7 @@ import { warn } from '../utils/logger.js';
 import { PATCH_CATEGORIES } from '../utils/validation.js';
 import { rewriteStagedDependencyOwners } from './patch-manifest-io.js';
 import { formatOrderRange, formatPatchOrder } from './patch-parse.js';
-import { manifestWithRetiredSlots, retiredOrderSet } from './patch-retired.js';
+import { manifestWithRetiredSlots, reservedOrderSet, retiredOrderSet } from './patch-retired.js';
 /** Default patch filename contract used when a policy omits `filenamePattern`. */
 const DEFAULT_PATCH_POLICY_FILENAME_PATTERN = '^(?<order>\\d{3})-(?<category>[a-z][a-z0-9-]*)-(?<slug>[a-z0-9-]+)\\.patch$';
 function policy(config) {
@@ -244,8 +244,8 @@ function evaluateGaps(cfg, patches, severity, retiredOrders = new Set()) {
         const last = occupied[occupied.length - 1];
         const missing = [];
         for (let order = first; order <= last; order++) {
-            // A retired slot (`patch retire`) is an occupied order with no
-            // patch behind it: the number stays spent, so it is not a gap.
+            // A retired slot (`patch retire`) or a reservation (`patch reserve`)
+            // is an occupied order with no patch behind it, so it is not a gap.
             if (!occupiedSet.has(order) &&
                 !retiredOrders.has(order) &&
                 reservedRangeForOrder(cfg, order) === null) {
@@ -295,7 +295,10 @@ export function evaluatePatchPolicy(config, manifest) {
     const severity = mutationMode(config) === 'warn' ? 'warning' : 'error';
     const issues = manifest.patches.flatMap((patch) => evaluatePatchMetadata(cfg, patch, severity));
     issues.push(...evaluateOrderCollisions(manifest.patches, severity));
-    issues.push(...evaluateGaps(cfg, manifest.patches, severity, retiredOrderSet(manifest)));
+    // Retired and reserved slots are both spent orders with no patch behind
+    // them: neither is a gap.
+    const placeholders = new Set([...retiredOrderSet(manifest), ...reservedOrderSet(manifest)]);
+    issues.push(...evaluateGaps(cfg, manifest.patches, severity, placeholders));
     return issues;
 }
 /**
@@ -357,8 +360,12 @@ export function enforcePatchPolicy(input) {
         : '';
     throw new InvalidArgumentError(`${input.command} would violate patchPolicy:\n${details.join('\n')}${suffix}`, mode === 'force' ? '--force-unsafe' : 'patchPolicy');
 }
-/** Allocates the next available order inside the configured ranges for a category. */
-export function allocatePolicyOrder(config, patches, category) {
+/**
+ * Allocates the next available order inside the configured ranges for a
+ * category. Orders in `reserved` (`patch reserve`) are skipped: they are
+ * held for their owner's export.
+ */
+export function allocatePolicyOrder(config, patches, category, reserved = new Set()) {
     const cfg = policy(config);
     if (!cfg)
         return null;
@@ -367,7 +374,7 @@ export function allocatePolicyOrder(config, patches, category) {
         .sort((a, b) => a.from - b.from || a.to - b.to);
     if (ranges.length === 0)
         return null;
-    const occupied = new Set(patches.map((patch) => patch.order));
+    const occupied = new Set([...patches.map((patch) => patch.order), ...reserved]);
     const highestInRanges = patches.reduce((highest, patch) => {
         if (!ranges.some((range) => patch.order >= range.from && patch.order <= range.to)) {
             return highest;

package/dist/src/core/patch-retired.d.ts

@@ -10,8 +10,12 @@
  * occupied. A patch that later takes the same order fills the slot, and
  * {@link carryRetiredSlots} drops it on that write, so the manifest never
  * holds a slot and a patch at one order.
+ *
+ * Reserved slots (`patch reserve`) follow the same rules: a placeholder for
+ * an order a session has claimed but not exported yet, counted as occupied
+ * by the gap check and filled (and dropped) by the export that lands on it.
  */
-import type { PatchesManifest, PatchMetadata, PatchRetiredSlot } from '../types/commands/index.js';
+import type { PatchesManifest, PatchMetadata, PatchReservedSlot, PatchRetiredSlot } from '../types/commands/index.js';
 /**
  * The retired slots of `current` that no patch in `patches` occupies, or
  * undefined when none remain. Every manifest write that rebuilds the
@@ -22,14 +26,32 @@ import type { PatchesManifest, PatchMetadata, PatchRetiredSlot } from '../types/
  * @param patches - The rows the written manifest will hold
  */
 export declare function carryRetiredSlots(current: Pick<PatchesManifest, 'retired'> | null | undefined, patches: readonly Pick<PatchMetadata, 'order'>[]): PatchRetiredSlot[] | undefined;
+/**
+ * Reserved twin of {@link carryRetiredSlots}: the reservations of `current`
+ * that no patch in `patches` has filled yet.
+ *
+ * @param current - Manifest the slots come from
+ * @param patches - The rows the written manifest will hold
+ */
+export declare function carryReservedSlots(current: Pick<PatchesManifest, 'reserved'> | null | undefined, patches: readonly Pick<PatchMetadata, 'order'>[]): PatchReservedSlot[] | undefined;
 /**
  * Builds a manifest from `patches` that keeps `current`'s unfilled retired
- * slots. The `retired` key is omitted entirely when no slot remains, so a
- * queue that never retired anything writes the same JSON as before.
+ * and reserved slots. Each key is omitted entirely when no slot remains, so
+ * a queue that never retired or reserved anything writes the same JSON as
+ * before.
  *
  * @param current - Manifest the slots come from
  * @param patches - The rows the written manifest will hold
  */
-export declare function manifestWithRetiredSlots(current: Pick<PatchesManifest, 'retired'> | null | undefined, patches: PatchMetadata[]): PatchesManifest;
+export declare function manifestWithRetiredSlots(current: Pick<PatchesManifest, 'retired' | 'reserved'> | null | undefined, patches: PatchMetadata[]): PatchesManifest;
 /** The set of order numbers held by retired slots. */
 export declare function retiredOrderSet(manifest: Pick<PatchesManifest, 'retired'>): Set<number>;
+/** The set of order numbers held by reserved slots. */
+export declare function reservedOrderSet(manifest: Pick<PatchesManifest, 'reserved'>): Set<number>;
+/**
+ * The reservation at `order`, if any.
+ *
+ * @param manifest - Manifest to search (null: none)
+ * @param order - Order number
+ */
+export declare function reservationAt(manifest: Pick<PatchesManifest, 'reserved'> | null | undefined, order: number): PatchReservedSlot | undefined;

package/dist/src/core/patch-retired.js

@@ -11,6 +11,10 @@
  * occupied. A patch that later takes the same order fills the slot, and
  * {@link carryRetiredSlots} drops it on that write, so the manifest never
  * holds a slot and a patch at one order.
+ *
+ * Reserved slots (`patch reserve`) follow the same rules: a placeholder for
+ * an order a session has claimed but not exported yet, counted as occupied
+ * by the gap check and filled (and dropped) by the export that lands on it.
  */
 /**
  * The retired slots of `current` that no patch in `patches` occupies, or
@@ -32,23 +36,57 @@ export function carryRetiredSlots(current, patches) {
         .sort((a, b) => a.order - b.order);
     return kept.length > 0 ? kept : undefined;
 }
+/**
+ * Reserved twin of {@link carryRetiredSlots}: the reservations of `current`
+ * that no patch in `patches` has filled yet.
+ *
+ * @param current - Manifest the slots come from
+ * @param patches - The rows the written manifest will hold
+ */
+export function carryReservedSlots(current, patches) {
+    const slots = current?.reserved;
+    if (slots === undefined || slots.length === 0)
+        return undefined;
+    const occupied = new Set(patches.map((patch) => patch.order));
+    const kept = slots
+        .filter((slot) => !occupied.has(slot.order))
+        .map((slot) => ({ ...slot }))
+        .sort((a, b) => a.order - b.order);
+    return kept.length > 0 ? kept : undefined;
+}
 /**
  * Builds a manifest from `patches` that keeps `current`'s unfilled retired
- * slots. The `retired` key is omitted entirely when no slot remains, so a
- * queue that never retired anything writes the same JSON as before.
+ * and reserved slots. Each key is omitted entirely when no slot remains, so
+ * a queue that never retired or reserved anything writes the same JSON as
+ * before.
  *
  * @param current - Manifest the slots come from
  * @param patches - The rows the written manifest will hold
  */
 export function manifestWithRetiredSlots(current, patches) {
     const retired = carryRetiredSlots(current, patches);
+    const reserved = carryReservedSlots(current, patches);
     return {
         version: 1,
         patches,
         ...(retired !== undefined ? { retired } : {}),
+        ...(reserved !== undefined ? { reserved } : {}),
     };
 }
 /** The set of order numbers held by retired slots. */
 export function retiredOrderSet(manifest) {
     return new Set((manifest.retired ?? []).map((slot) => slot.order));
 }
+/** The set of order numbers held by reserved slots. */
+export function reservedOrderSet(manifest) {
+    return new Set((manifest.reserved ?? []).map((slot) => slot.order));
+}
+/**
+ * The reservation at `order`, if any.
+ *
+ * @param manifest - Manifest to search (null: none)
+ * @param order - Order number
+ */
+export function reservationAt(manifest, order) {
+    return manifest?.reserved?.find((slot) => slot.order === order);
+}

package/dist/src/core/run-log.d.ts

@@ -65,6 +65,12 @@ export declare function openRunLog(projectRoot: string, command: string, now?: D
 export declare function keepRunLogCopy(log: RunLog | undefined, flag: string | undefined, command: string): Promise<RunLog | undefined>;
 /** Installs (or clears, with `undefined`) the run log for this process. */
 export declare function setActiveRunLog(log: RunLog | undefined): void;
+/**
+ * The 1-based line of the active run log the next write starts on.
+ * Redaction rewrites within a line and never adds or drops one, so the
+ * number holds for the file on disk.
+ */
+export declare function activeRunLogLine(): number;
 /** Absolute path of the active run log, or undefined when none is open. */
 export declare function getActiveRunLogPath(): string | undefined;
 /** Appends to the active run log. A no-op when none is open. */

package/dist/src/core/run-log.js

@@ -271,9 +271,20 @@ export async function keepRunLogCopy(log, flag, command) {
  * One command runs per process, so a single slot is the whole lifetime.
  */
 let activeRunLog;
+/** Newlines written to the active log so far, for line references into it. */
+let activeRunLogNewlines = 0;
 /** Installs (or clears, with `undefined`) the run log for this process. */
 export function setActiveRunLog(log) {
     activeRunLog = log;
+    activeRunLogNewlines = 0;
+}
+/**
+ * The 1-based line of the active run log the next write starts on.
+ * Redaction rewrites within a line and never adds or drops one, so the
+ * number holds for the file on disk.
+ */
+export function activeRunLogLine() {
+    return activeRunLogNewlines + 1;
 }
 /** Absolute path of the active run log, or undefined when none is open. */
 export function getActiveRunLogPath() {
@@ -281,7 +292,12 @@ export function getActiveRunLogPath() {
 }
 /** Appends to the active run log. A no-op when none is open. */
 export function writeToActiveRunLog(chunk) {
-    activeRunLog?.write(chunk);
+    if (activeRunLog === undefined)
+        return;
+    for (let index = chunk.indexOf('\n'); index !== -1; index = chunk.indexOf('\n', index + 1)) {
+        activeRunLogNewlines += 1;
+    }
+    activeRunLog.write(chunk);
 }
 /**
  * Closes and clears the active run log. Resolves even when none is open.

package/dist/src/core/test-harness-crash.d.ts

@@ -22,7 +22,7 @@
  * reporting phantom test failures (or phantom passes).
  */
 export type { HarnessCrashSignature } from './test-harness-signature.js';
-import type { HarnessCrashSignature, IncompleteRunEvidence } from './test-harness-signature.js';
+import { type HarnessCrashSignature, type IncompleteRunEvidence } from './test-harness-signature.js';
 export { headedDisplayAsleepVerdictNote, headedNoOutputTimeoutHint } from './test-stall-triage.js';
 /** How a completed harness run should be interpreted. */
 export type HarnessRunClassification = 'tests-ran-ok' | 'test-failures' | 'harness-crash' | 'harness-arguments' | 'no-tests';
@@ -198,6 +198,7 @@ export declare function extractSummaryCounts(output: string): HarnessSummaryCoun
 export declare function formatFireforgeVerdictLine(verdict: HarnessRunVerdict, shards?: {
     passed: number;
     total: number;
+    failed?: readonly string[];
 }): string;
 /**
  * Builds the operator-facing failure message for a green-looking summary

package/dist/src/core/test-harness-crash.js

@@ -25,6 +25,7 @@
 import { hasKnownTeardownNoise } from './mach-known-noise-filter.js';
 import { truncateEvidence, unmarkedFailureEvidenceNote, } from './test-harness-verdict-notes.js';
 import { classifyProfileArgumentFailure } from './test-profile-files.js';
+import { formatIncompleteSuffix, formatShardsSuffix, } from './test-harness-signature.js';
 // The no-output-stall triage text lives in `test-stall-triage.ts` (it is
 // operator advice, not classification) and is re-exported here so the
 // command layer keeps importing its harness diagnostics from one module.
@@ -659,15 +660,11 @@ function lastCapturedCount(output, pattern) {
 export function formatFireforgeVerdictLine(verdict, shards) {
     const counts = (verdict.checks !== undefined ? ` checks=${verdict.checks}` : '') +
         (verdict.unexpected !== undefined ? ` unexpected=${verdict.unexpected}` : '');
-    const shardSuffix = shards ? ` shards=${shards.passed}/${shards.total}` : '';
-    const { started: n, requested: m, firstUnstarted: first } = verdict.incomplete ?? {};
-    const truncation = first === undefined ? '' : ` started=${n}/${m} first-unstarted=${first}`;
-    const note = verdict.note !== undefined ? ` (${verdict.note})` : '';
-    if (verdict.kind === 'tests-ran-ok') {
-        return `FIREFORGE-VERDICT: PASS${counts}${shardSuffix}${note}`;
-    }
+    const tail = `${formatShardsSuffix(shards)}${verdict.note !== undefined ? ` (${verdict.note})` : ''}`;
+    if (verdict.kind === 'tests-ran-ok')
+        return `FIREFORGE-VERDICT: PASS${counts}${tail}`;
     const reason = verdict.kind === 'harness-crash' ? 'crash' : verdict.kind;
-    return `FIREFORGE-VERDICT: FAIL reason=${reason}${counts}${truncation}${shardSuffix}${note}`;
+    return `FIREFORGE-VERDICT: FAIL reason=${reason}${counts}${formatIncompleteSuffix(verdict.incomplete)}${tail}`;
 }
 /**
  * Builds the operator-facing failure message for a green-looking summary

package/dist/src/core/test-harness-signature.d.ts

@@ -20,6 +20,17 @@ export interface HarnessCrashSignature {
     /** The concrete output line the recognition was based on. */
     line: string;
 }
+/**
+ * The verdict line's `started=<n>/<m> first-unstarted=<path>
+ * [started-source=<src>]` keys, or nothing when every file started.
+ */
+export declare function formatIncompleteSuffix(evidence: IncompleteRunEvidence | undefined): string;
+/** The verdict line's `shards=<p>/<t> [failed-shards=<labels>]` keys of a sharded run. */
+export declare function formatShardsSuffix(shards: {
+    passed: number;
+    total: number;
+    failed?: readonly string[];
+} | undefined): string;
 /** Why an exit-0 run that would have read as a pass was failed instead. */
 export interface IncompleteRunEvidence {
     /** Requested test files that produced a start (or skip) marker. */
@@ -28,6 +39,11 @@ export interface IncompleteRunEvidence {
     requested: number;
     /** First requested file, in dispatch order, that never started. */
     firstUnstarted?: string;
+    /**
+     * Which evidence the start count came from, stamped with a short count:
+     * the structured raw log, the streamed output, or the capped capture.
+     */
+    startedSource?: 'raw' | 'stream' | 'capture';
     /** The harness's "shut down in the middle of a test" line, when present. */
     shutdownLine?: string;
     /** The summary's non-zero `Unexpected results:` count, when it printed one. */

package/dist/src/core/test-harness-signature.js

@@ -14,4 +14,22 @@
  * `test-run-completeness.ts` produces it from helpers in
  * `test-harness-crash.ts`, whose verdict type carries it.
  */
-export {};
+/**
+ * The verdict line's `started=<n>/<m> first-unstarted=<path>
+ * [started-source=<src>]` keys, or nothing when every file started.
+ */
+export function formatIncompleteSuffix(evidence) {
+    if (evidence?.firstUnstarted === undefined)
+        return '';
+    const source = evidence.startedSource === undefined ? '' : ` started-source=${evidence.startedSource}`;
+    return ` started=${evidence.started}/${evidence.requested} first-unstarted=${evidence.firstUnstarted}${source}`;
+}
+/** The verdict line's `shards=<p>/<t> [failed-shards=<labels>]` keys of a sharded run. */
+export function formatShardsSuffix(shards) {
+    if (shards === undefined)
+        return '';
+    const failed = shards.failed !== undefined && shards.failed.length > 0
+        ? ` failed-shards=${shards.failed.join(',')}`
+        : '';
+    return ` shards=${shards.passed}/${shards.total}${failed}`;
+}

package/dist/src/core/test-raw-log.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The mozlog structured ("raw") log of one mach test dispatch.
+ *
+ * Everything else FireForge reads from a run is human text: the
+ * `TEST_START`/`TEST_END` lines and the `Unexpected results:` summary, in two
+ * dialects, out of a capture that keeps only its last 2 MB. A gate that
+ * wants to name the files a run failed had to regex that text, and agent-
+ * quiet mozbuild drops `TEST_START` from it altogether. The raw log is the
+ * record the summary itself is computed from: one JSON object per line,
+ * with `test_start`, `test_status` and `test_end` actions naming each test
+ * by its manifest id.
+ *
+ * It is requested per dispatch with mozlog's `--log-raw=<path>`, which
+ * `mach test`, `mach mochitest` and `mach xpcshell-test` all accept, only
+ * when a run asks for per-file results (`--results`, `--shard-size`).
+ */
+import type { StartMarkers } from './test-run-completeness.js';
+/** One test file's outcome, from its `test_end` and failing `test_status` records. */
+export interface RawTestResult {
+    /** The test id mozlog reports (a manifest-relative path). */
+    test: string;
+    /** `test_end` status (`OK`, `PASS`, `FAIL`, `ERROR`, `TIMEOUT`, `CRASH`, `SKIP`). */
+    status: string;
+    /** Expected status; equal to `status` when mozlog omitted it. */
+    expected: string;
+    /** True when the file ended unexpectedly or any subtest did. */
+    unexpected: boolean;
+    /** Subtests that reported an unexpected status. */
+    unexpectedSubtests: number;
+    /** Wall time between `test_start` and `test_end`, when both carried a time. */
+    durationMs?: number;
+}
+/** Everything one raw log says about the run. */
+export interface RawTestLog {
+    /** Files in `test_end` order. A started file with no end is not listed. */
+    results: RawTestResult[];
+    /** Start markers for the completeness veto: every `test_start` id. */
+    markers: StartMarkers;
+    /** Started tests that never ended (a crash or a cut-off run). */
+    unfinished: string[];
+}
+/**
+ * Parses a mozlog raw log. Unknown actions and malformed lines are skipped,
+ * so a log truncated by a crash still yields the files that finished.
+ *
+ * @param text - The raw log's contents
+ */
+export declare function parseRawTestLog(text: string): RawTestLog;
+/**
+ * Reads and parses a raw log. Returns undefined when the file is missing or
+ * unreadable (the harness never started, or the engine's mach ignored the
+ * flag), so callers fall back to the streamed text.
+ *
+ * @param path - The `--log-raw` destination
+ */
+export declare function readRawTestLog(path: string): Promise<RawTestLog | undefined>;
+/**
+ * The `--log-raw` destination the operator already forwarded with
+ * `--mach-arg`, when it names a file. FireForge then reads that file instead
+ * of adding its own flag, so the operator's log is not replaced.
+ *
+ * @param args - The dispatch's extra mach arguments
+ */
+export declare function forwardedRawLogPath(args: readonly string[]): string | undefined;
+/** True when the dispatch arguments already carry any `--log-raw`. */
+export declare function hasForwardedRawLog(args: readonly string[]): boolean;

package/dist/src/core/test-raw-log.js

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The mozlog structured ("raw") log of one mach test dispatch.
+ *
+ * Everything else FireForge reads from a run is human text: the
+ * `TEST_START`/`TEST_END` lines and the `Unexpected results:` summary, in two
+ * dialects, out of a capture that keeps only its last 2 MB. A gate that
+ * wants to name the files a run failed had to regex that text, and agent-
+ * quiet mozbuild drops `TEST_START` from it altogether. The raw log is the
+ * record the summary itself is computed from: one JSON object per line,
+ * with `test_start`, `test_status` and `test_end` actions naming each test
+ * by its manifest id.
+ *
+ * It is requested per dispatch with mozlog's `--log-raw=<path>`, which
+ * `mach test`, `mach mochitest` and `mach xpcshell-test` all accept, only
+ * when a run asks for per-file results (`--results`, `--shard-size`).
+ */
+import { readFile } from 'node:fs/promises';
+function parseRecord(line) {
+    if (!line.startsWith('{'))
+        return undefined;
+    try {
+        const parsed = JSON.parse(line);
+        return typeof parsed === 'object' && parsed !== null ? parsed : undefined;
+    }
+    catch {
+        // A line cut off by a killed harness is not a record.
+        return undefined;
+    }
+}
+/**
+ * Parses a mozlog raw log. Unknown actions and malformed lines are skipped,
+ * so a log truncated by a crash still yields the files that finished.
+ *
+ * @param text - The raw log's contents
+ */
+export function parseRawTestLog(text) {
+    const results = [];
+    const started = [];
+    const startTimes = new Map();
+    const subtestFailures = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const record = parseRecord(line.trim());
+        if (record === undefined || typeof record.test !== 'string')
+            continue;
+        const test = record.test;
+        if (record.action === 'test_start') {
+            started.push(test);
+            if (typeof record.time === 'number')
+                startTimes.set(test, record.time);
+            continue;
+        }
+        if (record.action === 'test_status' && typeof record.expected === 'string') {
+            // mozlog sets `expected` on a status record only when it differs.
+            subtestFailures.set(test, (subtestFailures.get(test) ?? 0) + 1);
+            continue;
+        }
+        if (record.action !== 'test_end' || typeof record.status !== 'string')
+            continue;
+        const expected = typeof record.expected === 'string' ? record.expected : record.status;
+        const unexpectedSubtests = subtestFailures.get(test) ?? 0;
+        const start = startTimes.get(test);
+        results.push({
+            test,
+            status: record.status,
+            expected,
+            unexpected: expected !== record.status || unexpectedSubtests > 0,
+            unexpectedSubtests,
+            ...(start !== undefined && typeof record.time === 'number'
+                ? { durationMs: record.time - start }
+                : {}),
+        });
+    }
+    const ended = new Set(results.map((result) => result.test));
+    return {
+        results,
+        markers: {
+            started,
+            skipped: results.filter((r) => r.status === 'SKIP').map((r) => r.test),
+        },
+        unfinished: started.filter((test) => !ended.has(test)),
+    };
+}
+/**
+ * Reads and parses a raw log. Returns undefined when the file is missing or
+ * unreadable (the harness never started, or the engine's mach ignored the
+ * flag), so callers fall back to the streamed text.
+ *
+ * @param path - The `--log-raw` destination
+ */
+export async function readRawTestLog(path) {
+    try {
+        return parseRawTestLog(await readFile(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The `--log-raw` destination the operator already forwarded with
+ * `--mach-arg`, when it names a file. FireForge then reads that file instead
+ * of adding its own flag, so the operator's log is not replaced.
+ *
+ * @param args - The dispatch's extra mach arguments
+ */
+export function forwardedRawLogPath(args) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index] ?? '';
+        const value = arg.startsWith('--log-raw=')
+            ? arg.slice('--log-raw='.length)
+            : arg === '--log-raw'
+                ? args[index + 1]
+                : undefined;
+        if (value !== undefined)
+            return value === '-' ? undefined : value;
+    }
+    return undefined;
+}
+/** True when the dispatch arguments already carry any `--log-raw`. */
+export function hasForwardedRawLog(args) {
+    return args.some((arg) => arg === '--log-raw' || arg.startsWith('--log-raw='));
+}