@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -1,7 +1,7 @@
 /**
  * Type of the last-build baseline marker, split out of `build-baseline.ts`
  * so its consumers (`build-audit`, `build-prepare`, `test-stale-check`) can
- * import the shape without importing the I/O module — `build-baseline.ts`
+ * import the shape without importing the I/O module. `build-baseline.ts`
  * itself depends on `build-audit.ts` at runtime, and a type import back
  * into it would make the dependency graph cyclic.
  */
@@ -11,7 +11,7 @@ export interface BuildBaseline {
     /** SHA of engine HEAD at the time the build succeeded. */
     engineHeadSha: string;
     /**
-     * ISO-8601 timestamp of when the baseline was recorded. Informational —
+     * ISO-8601 timestamp of when the baseline was recorded. Informational:
      * downstream code keys off `engineHeadSha` for diffs, but the timestamp
      * helps operators reason about stale markers.
      */
@@ -46,19 +46,20 @@ export interface BuildBaseline {
      * neither re-runs `mach configure` nor escalates a pre-test build to a
      * full `mach build`. Without this the persistent worktree diff every
      * fork carries (imported patches + Furnace-applied components) made a
-     * patch-touched `jar.mn` "changed" on EVERY run, and each `test --build`
+     * patch-touched `jar.mn` "changed" on every run, and each `test --build`
      * after a full build paid the full build again.
      *
      * Refresh rules, per entry kind:
      * - backend inputs (`moz.build` & co) are refreshed on every successful
-     *   write — every baseline-writing path ran the auto-configure preflight
-     *   against the previous baseline, so a changed one was reconfigured;
-     * - `jar.mn` entries are refreshed only by a FULL build and carried
+     *   write, because every baseline-writing path ran the auto-configure
+     *   preflight against the previous baseline, so a changed one was
+     *   reconfigured.
+     * - `jar.mn` entries are refreshed only by a full build and carried
      *   forward verbatim from the previous record on a `faster` write, since
      *   `fireforge build --ui` never escalates and recording a `jar.mn` no
      *   full build has installed would hide the next escalation.
      *
-     * Absent on baselines written before the field existed; `build-prepare`
+     * Absent on baselines written before the field existed. `build-prepare`
      * then falls back to the path-only comparison (every dirty build input
      * counts as changed).
      */
@@ -66,7 +67,7 @@ export interface BuildBaseline {
     /**
      * What the packaged test runtime produced by the recorded build covers.
      *
-     * - `'full'`: the build packaged the full test set — written by
+     * - `'full'`: the build packaged the full test set, written by
      *   `fireforge build` / `build --ui` and by a path-less
      *   `fireforge test --build` (full-suite run).
      * - `string[]`: engine-relative POSIX request paths of the file/directory-
@@ -83,15 +84,15 @@ export interface BuildBaseline {
      * most one obj dir exists per project.
      *
      * Union/"shared coverage" across successive scoped builds is unsound in
-     * general — every baseline write refreshes `packageableFingerprints` for
-     * ALL dirty packageable paths, so a blind union would whitewash an
+     * general: every baseline write refreshes `packageableFingerprints` for
+     * all dirty packageable paths, so a blind union would whitewash an
      * earlier scope's edited fixtures while `obj-*`/`_tests/` still holds its
-     * stale staging. Coverage therefore REPLACES by default.
+     * stale staging. Coverage therefore replaces by default.
      *
      * The one exception is `test --build --extend-coverage`, which unions only
      * after proving the previous record's anchor still holds: same engine
      * HEAD, same {@link BuildBaseline.mozconfigHash}, and every previously
-     * fingerprinted path byte-identical — i.e. the wholesale fingerprint
+     * fingerprinted path byte-identical, i.e. the wholesale fingerprint
      * refresh is a no-op for everything the earlier scope's staging depended
      * on. Any divergence refuses fail-closed. See `src/core/coverage-extend.ts`
      * for the one boundary that guard does not cover (dirty non-packageable
@@ -100,7 +101,7 @@ export interface BuildBaseline {
     testPackagingCoverage?: TestPackagingCoverage;
     /**
      * Hex-encoded SHA-256 of `engine/mozconfig` as it stood for this build.
-     * Recorded because the mozconfig is REGENERATED from project-side
+     * Recorded because the mozconfig is regenerated from project-side
      * `configs/*.mozconfig` templates plus `fireforge.json` on every build, so
      * `engineHeadSha` does not cover it: two builds at the same engine SHA can
      * configure differently. Consumed by the `--extend-coverage` anchor, which
@@ -109,10 +110,10 @@ export interface BuildBaseline {
     mozconfigHash?: string;
     /**
      * Anchor for the compiled StaticComponents table: the engine HEAD SHA of
-     * the last FULL-coverage build plus content fingerprints of the
+     * the last full-coverage build plus content fingerprints of the
      * `components.conf` manifests that were dirty at that moment. Written
-     * fresh only on FULL-coverage baseline writes (`fireforge build`,
-     * `build --ui`, path-less `test --build`); a scoped `test --build` carries
+     * fresh only on full-coverage baseline writes (`fireforge build`,
+     * `build --ui`, path-less `test --build`). A scoped `test --build` carries
      * the previous record forward verbatim, because `mach build faster` does
      * not rebake `components.conf` registrations into the compiled table. When
      * absent, the static-components stale check degrades to "fresh".
@@ -121,13 +122,13 @@ export interface BuildBaseline {
     /**
      * Invocation shape that recorded this baseline (`'fireforge build'`,
      * `'fireforge build --ui'`, `'fireforge test --build [paths]'`).
-     * Informational — surfaced by `fireforge status --test-coverage`. Render
+     * Informational, surfaced by `fireforge status --test-coverage`. Render
      * as "unknown" when absent.
      */
     recordedBy?: string;
 }
 /**
- * State of the engine at the last FULL build, as far as compiled-in XPCOM
+ * State of the engine at the last full build, as far as compiled-in XPCOM
  * component registration is concerned. See
  * {@link BuildBaseline.staticComponentsBaseline}.
  */

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

@@ -2,7 +2,7 @@
 /**
  * Type of the last-build baseline marker, split out of `build-baseline.ts`
  * so its consumers (`build-audit`, `build-prepare`, `test-stale-check`) can
- * import the shape without importing the I/O module — `build-baseline.ts`
+ * import the shape without importing the I/O module. `build-baseline.ts`
  * itself depends on `build-audit.ts` at runtime, and a type import back
  * into it would make the dependency graph cyclic.
  */

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

@@ -12,7 +12,7 @@
  *     recursive-make backend isn't stale.
  *
  * The marker lives under `.fireforge/last-build.json`. It is written only
- * on successful build completion; a failed build does not update it, so a
+ * on successful build completion. A failed build does not update it, so a
  * subsequent run still audits against the last known-good tree.
  */
 import { type BuildBaseline, type TestPackagingCoverage } from './build-baseline-types.js';
@@ -21,12 +21,10 @@ import { type BuildBaseline, type TestPackagingCoverage } from './build-baseline
  * the `jar.mn` half of {@link BuildBaseline.buildInputFingerprints} is
  * refreshed (`'full'`) or carried forward from the previous record
  * (`'faster'`). `fireforge build --ui` and a non-escalated `test --build`
- * are `'faster'`; `fireforge build` and an escalated `test --build` are
+ * are `'faster'`. `fireforge build` and an escalated `test --build` are
  * `'full'`.
  */
 export type BaselineBuildKind = 'full' | 'faster';
-/** Name of the last-build marker file under `.fireforge/`. */
-export declare const BUILD_BASELINE_FILENAME = "last-build.json";
 /**
  * Resolves the on-disk path of the build baseline marker.
  * @param projectRoot - Root directory of the project
@@ -35,41 +33,60 @@ export declare const BUILD_BASELINE_FILENAME = "last-build.json";
 export declare function getBuildBaselinePath(projectRoot: string): string;
 /**
  * Reads the last-build baseline if present. Returns undefined when no
- * previous successful build has been recorded — callers must tolerate that
+ * previous successful build has been recorded. Callers must tolerate that
  * path (first build, cleaned workspace).
  * @param projectRoot - Root directory of the project
  */
 export declare function readBuildBaseline(projectRoot: string): Promise<BuildBaseline | undefined>;
+export interface WriteBuildBaselineOptions {
+    /** Root directory of the project. */
+    projectRoot: string;
+    /** Path to the engine directory. */
+    engineDir: string;
+    /** Current `binaryName` from fireforge.json. */
+    binaryName: string;
+    /**
+     * Coverage claim of the packaged test runtime this build produced
+     * (`'full'`, or the scoped request paths of a `test --build` invocation).
+     * Omitted → field left off the marker.
+     */
+    testPackagingCoverage?: TestPackagingCoverage | undefined;
+    /**
+     * The baseline this write replaces, when the caller has it. A scoped
+     * (non-`'full'`) write carries its `staticComponentsBaseline` forward
+     * verbatim, because `mach build faster` does not rebake `components.conf`
+     * registrations, so the last full build stays the anchor for the
+     * compiled StaticComponents table.
+     */
+    previousBaseline?: BuildBaseline | undefined;
+    /** Invocation shape that produced this baseline. */
+    recordedBy?: string | undefined;
+    /**
+     * `'auto'` (default) refreshes the static-components anchor whenever the
+     * coverage claim is `'full'` or absent. `'refresh'` records it even for a
+     * scoped coverage claim whose implementation escalated to a full build.
+     * `'carry-forward'` always keeps the previous anchor: needed by
+     * `--extend-coverage`, whose union can evaluate to `'full'` while the
+     * build that produced it was still a scoped `mach build faster` that did
+     * not rebake the compiled table.
+     */
+    staticComponentsHandling?: 'auto' | 'refresh' | 'carry-forward' | undefined;
+    /**
+     * Which mach build produced this baseline (default `'full'`). A
+     * `'faster'` write carries the previous record's `jar.mn` fingerprints
+     * forward instead of refreshing them. See
+     * {@link BuildBaseline.buildInputFingerprints}. Every caller that ran
+     * `mach build faster` must say so, or the next pre-test build skips an
+     * escalation no full build has honoured.
+     */
+    buildKind?: BaselineBuildKind | undefined;
+}
 /**
  * Records a successful build by writing a fresh baseline marker. Captures
  * engine HEAD SHA (or an empty string when the engine has no HEAD yet) and
  * the current binaryName. Caller is responsible for only invoking this
  * after the build exit code was zero.
  *
- * @param projectRoot - Root directory of the project
- * @param engineDir - Path to the engine directory
- * @param binaryName - Current `binaryName` from fireforge.json
- * @param testPackagingCoverage - Coverage claim of the packaged test
- *   runtime this build produced (`'full'`, or the scoped request paths of
- *   a `test --build` invocation). Omitted → field left off the marker.
- * @param previousBaseline - The baseline this write replaces, when the
- *   caller has it. A scoped (non-`'full'`) write carries its
- *   `staticComponentsBaseline` forward verbatim — `mach build faster`
- *   does not rebake `components.conf` registrations, so the last FULL
- *   build stays the honest anchor for the compiled StaticComponents table.
- * @param recordedBy - Invocation shape that produced this baseline.
- * @param staticComponentsHandling - `'auto'` (default) refreshes the
- *   static-components anchor whenever the coverage claim is `'full'` or
- *   absent. `'refresh'` records it even for a scoped coverage claim whose
- *   implementation escalated to a full build. `'carry-forward'` always
- *   keeps the previous anchor: needed by `--extend-coverage`, whose union
- *   can EVALUATE to `'full'` while the build that produced it was still a
- *   scoped `mach build faster` that did not rebake the compiled table.
- * @param buildKind - Which mach build produced this baseline (default
- *   `'full'`). A `'faster'` write carries the previous record's `jar.mn`
- *   fingerprints forward instead of refreshing them — see
- *   {@link BuildBaseline.buildInputFingerprints}. Every caller that ran
- *   `mach build faster` MUST say so, or the next pre-test build skips an
- *   escalation no full build has honoured.
+ * @param options - See {@link WriteBuildBaselineOptions}
  */
-export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string, testPackagingCoverage?: TestPackagingCoverage, previousBaseline?: BuildBaseline, recordedBy?: string, staticComponentsHandling?: 'auto' | 'refresh' | 'carry-forward', buildKind?: BaselineBuildKind): Promise<void>;
+export declare function writeBuildBaseline(options: WriteBuildBaselineOptions): Promise<void>;

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

@@ -13,15 +13,15 @@
  *     recursive-make backend isn't stale.
  *
  * The marker lives under `.fireforge/last-build.json`. It is written only
- * on successful build completion; a failed build does not update it, so a
+ * on successful build completion. A failed build does not update it, so a
  * subsequent run still audits against the last known-good tree.
  */
-import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { mapWithConcurrency } from '../utils/concurrency.js';
 import { getNodeErrorCode, toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { sha256Hex } from '../utils/hash.js';
 import { verbose } from '../utils/logger.js';
 import { isBuildInputPath, isJarManifestPath, isPackageablePath, isXpcomManifestPath, } from './build-audit.js';
 import { DELETED_FILE_FINGERPRINT, } from './build-baseline-types.js';
@@ -36,7 +36,7 @@ import { getUntrackedFiles } from './git-status.js';
  */
 const FINGERPRINT_IO_CONCURRENCY = 16;
 /** Name of the last-build marker file under `.fireforge/`. */
-export const BUILD_BASELINE_FILENAME = 'last-build.json';
+const BUILD_BASELINE_FILENAME = 'last-build.json';
 /**
  * Resolves the on-disk path of the build baseline marker.
  * @param projectRoot - Root directory of the project
@@ -47,7 +47,7 @@ export function getBuildBaselinePath(projectRoot) {
 }
 /**
  * Reads the last-build baseline if present. Returns undefined when no
- * previous successful build has been recorded — callers must tolerate that
+ * previous successful build has been recorded. Callers must tolerate that
  * path (first build, cleaned workspace).
  * @param projectRoot - Root directory of the project
  */
@@ -60,7 +60,7 @@ export async function readBuildBaseline(projectRoot) {
         return await readJson(path);
     }
     catch {
-        // A corrupt marker is equivalent to no marker — the audit/auto-configure
+        // A corrupt marker is equivalent to no marker: the audit/auto-configure
         // will treat it as "first build" rather than block on the inconsistency.
         return undefined;
     }
@@ -71,42 +71,19 @@ export async function readBuildBaseline(projectRoot) {
  * the current binaryName. Caller is responsible for only invoking this
  * after the build exit code was zero.
  *
- * @param projectRoot - Root directory of the project
- * @param engineDir - Path to the engine directory
- * @param binaryName - Current `binaryName` from fireforge.json
- * @param testPackagingCoverage - Coverage claim of the packaged test
- *   runtime this build produced (`'full'`, or the scoped request paths of
- *   a `test --build` invocation). Omitted → field left off the marker.
- * @param previousBaseline - The baseline this write replaces, when the
- *   caller has it. A scoped (non-`'full'`) write carries its
- *   `staticComponentsBaseline` forward verbatim — `mach build faster`
- *   does not rebake `components.conf` registrations, so the last FULL
- *   build stays the honest anchor for the compiled StaticComponents table.
- * @param recordedBy - Invocation shape that produced this baseline.
- * @param staticComponentsHandling - `'auto'` (default) refreshes the
- *   static-components anchor whenever the coverage claim is `'full'` or
- *   absent. `'refresh'` records it even for a scoped coverage claim whose
- *   implementation escalated to a full build. `'carry-forward'` always
- *   keeps the previous anchor: needed by `--extend-coverage`, whose union
- *   can EVALUATE to `'full'` while the build that produced it was still a
- *   scoped `mach build faster` that did not rebake the compiled table.
- * @param buildKind - Which mach build produced this baseline (default
- *   `'full'`). A `'faster'` write carries the previous record's `jar.mn`
- *   fingerprints forward instead of refreshing them — see
- *   {@link BuildBaseline.buildInputFingerprints}. Every caller that ran
- *   `mach build faster` MUST say so, or the next pre-test build skips an
- *   escalation no full build has honoured.
+ * @param options - See {@link WriteBuildBaselineOptions}
  */
-export async function writeBuildBaseline(projectRoot, engineDir, binaryName, testPackagingCoverage, previousBaseline, recordedBy, staticComponentsHandling = 'auto', buildKind = 'full') {
+export async function writeBuildBaseline(options) {
+    const { projectRoot, engineDir, binaryName, testPackagingCoverage, previousBaseline, recordedBy, staticComponentsHandling = 'auto', buildKind = 'full', } = options;
     let engineHeadSha = '';
     try {
         engineHeadSha = await getHead(engineDir);
     }
     catch (error) {
-        // Engine may be an unborn branch (freshly cloned + reset, or mid-import)
-        // — record an empty SHA and let downstream fall back to "no prior state"
-        // behavior. Any other git failure is bubbled up; we don't want to
-        // silently write a garbage marker.
+        // Engine may be an unborn branch (freshly cloned + reset, or
+        // mid-import). Record an empty SHA and let downstream fall back to "no
+        // prior state" behavior. Any other git failure is bubbled up, because
+        // we don't want to silently write a garbage marker.
         if (!isMissingHeadError(error)) {
             throw error;
         }
@@ -115,7 +92,7 @@ export async function writeBuildBaseline(projectRoot, engineDir, binaryName, tes
     const buildInputFingerprints = await collectBuildInputFingerprints(engineDir, previousBaseline, buildKind);
     // A full-coverage write (and the legacy no-claim `fireforge build` shape)
     // just recompiled the StaticComponents table, so it anchors the table to
-    // the current engine state. A scoped write did not — carry the previous
+    // the current engine state. A scoped write did not, so carry the previous
     // anchor forward verbatim.
     const staticComponentsBaseline = staticComponentsHandling === 'refresh' ||
         (staticComponentsHandling === 'auto' &&
@@ -145,7 +122,7 @@ export async function writeBuildBaseline(projectRoot, engineDir, binaryName, tes
  * or new one means the file is genuinely stale.
  *
  * Returns `undefined` on any git failure so a broken probe never corrupts
- * the on-disk baseline with `{}`; the stale-check then falls back to a
+ * the on-disk baseline with `{}`. The stale-check then falls back to a
  * path-only comparison.
  */
 async function collectPackageableFingerprints(engineDir) {
@@ -156,9 +133,9 @@ async function collectPackageableFingerprints(engineDir) {
  * ({@link isBuildInputPath}) this build consumed. Backend inputs
  * (`moz.build` & co) are always taken from the live tree: the
  * auto-configure preflight reconfigured against them before this build
- * ran. `jar.mn` entries are taken from the live tree only after a FULL
- * build; a `faster` write carries the previous record's `jar.mn` entries
- * forward verbatim, because `mach build faster` is exactly the build the
+ * ran. `jar.mn` entries are taken from the live tree only after a full
+ * build. A `faster` write carries the previous record's `jar.mn` entries
+ * forward verbatim, because `mach build faster` is the build the
  * `jar.mn` escalation exists to bypass, and recording a `jar.mn` it did
  * not install would silence the next escalation. Returns `undefined` on
  * probe failure so the field is omitted rather than written as `{}`.
@@ -182,7 +159,7 @@ async function collectBuildInputFingerprints(engineDir, previousBaseline, buildK
 /**
  * Anchor for the compiled StaticComponents table: the engine HEAD SHA of
  * this (full) build plus content fingerprints of the `components.conf`
- * manifests dirty right now — the same dirty-path probe family as
+ * manifests dirty right now, using the same dirty-path probe family as
  * {@link collectPackageableFingerprints}, filtered to XPCOM manifests.
  * Returns `undefined` on probe failure so a broken probe omits the field
  * (the static-components stale check then degrades to "fresh") rather than
@@ -224,7 +201,7 @@ async function collectDirtyFingerprints(engineDir, includePath, contextLabel) {
         const entries = await mapWithConcurrency(included, FINGERPRINT_IO_CONCURRENCY, async (relPath) => {
             try {
                 const buffer = await readFile(join(engineDir, relPath));
-                return [relPath, createHash('sha256').update(buffer).digest('hex')];
+                return [relPath, sha256Hex(buffer)];
             }
             catch (fileError) {
                 if (getNodeErrorCode(fileError) === 'ENOENT') {
@@ -234,7 +211,7 @@ async function collectDirtyFingerprints(engineDir, includePath, contextLabel) {
                     return [relPath, DELETED_FILE_FINGERPRINT];
                 }
                 // A file that disappeared between status probe and hash is
-                // expected in concurrent scenarios; non-ENOENT failures remain
+                // expected in concurrent scenarios. Non-ENOENT failures remain
                 // untrusted and are skipped without failing the whole baseline write.
                 verbose(`Build baseline: skipping ${contextLabel} for ${relPath} — ${toError(fileError).message}`);
                 return undefined;

package/dist/src/core/build-jar-escalation.d.ts

@@ -3,19 +3,19 @@
  * escalate from `mach build faster` to a full `mach build`.
  *
  * The 0.41.0 rule was `any changed jar.mn ⇒ full build`, which costs ~10
- * minutes against ~20 s for a chrome-only slice and is paid TWICE per
+ * minutes against ~20 s for a chrome-only slice and is paid twice per
  * green/no-change pair on a Furnace-touching slice. A downstream experiment
  * (two clean runs, 2026-08-29, against 0.44.4) showed the rule is over-broad
- * for the common case: a jar-only registration of a NEW content file added
- * to an EXISTING `dist/bin` manifest was installed by a plain
- * `fireforge build --ui` both times — `faster/install_dist_bin_browser` named
+ * for the common case: a jar-only registration of a new content file added
+ * to an existing `dist/bin` manifest was installed by a plain
+ * `fireforge build --ui` both times: `faster/install_dist_bin_browser` named
  * the destination, the file landed in `dist/bin/…/content/browser/` and in
  * the `.app` bundle, and a plain `fireforge test` fetched it over
  * `chrome://` at runtime. Neither run escalated, and neither needed to.
  *
- * What the experiment did NOT exercise, and what therefore still escalates:
+ * What the experiment did not exercise, and what therefore still escalates:
  *
- *  - a NEW `jar.mn` file. The install manifest for a manifest the backend
+ *  - a new `jar.mn` file. The install manifest for a manifest the backend
  *    has never seen does not exist yet, and `mach build faster` consumes
  *    install manifests rather than regenerating the backend that writes
  *    them.
@@ -42,7 +42,7 @@ export interface JarEscalationDecision {
     escalate: boolean;
     /** One entry per manifest that forces the escalation. */
     causes: JarEscalationCause[];
-    /** Manifests the narrowing cleared; kept for the verbose explanation. */
+    /** Manifests the narrowing cleared. Kept for the verbose explanation. */
     cleared: string[];
 }
 /**
@@ -57,7 +57,7 @@ export interface JarEscalationDecision {
  */
 export declare function evaluateJarManifestEscalation(engineDir: string, changedPaths: readonly string[], baseline: BuildBaseline | undefined): Promise<JarEscalationDecision>;
 /**
- * Renders the operator-facing escalation notice. Names the manifest AND the
+ * Renders the operator-facing escalation notice. Names the manifest and the
  * reason: "a jar.mn changed" is the sentence that made the previous rule
  * impossible to argue with from outside.
  */

package/dist/src/core/build-jar-escalation.js

@@ -4,19 +4,19 @@
  * escalate from `mach build faster` to a full `mach build`.
  *
  * The 0.41.0 rule was `any changed jar.mn ⇒ full build`, which costs ~10
- * minutes against ~20 s for a chrome-only slice and is paid TWICE per
+ * minutes against ~20 s for a chrome-only slice and is paid twice per
  * green/no-change pair on a Furnace-touching slice. A downstream experiment
  * (two clean runs, 2026-08-29, against 0.44.4) showed the rule is over-broad
- * for the common case: a jar-only registration of a NEW content file added
- * to an EXISTING `dist/bin` manifest was installed by a plain
- * `fireforge build --ui` both times — `faster/install_dist_bin_browser` named
+ * for the common case: a jar-only registration of a new content file added
+ * to an existing `dist/bin` manifest was installed by a plain
+ * `fireforge build --ui` both times: `faster/install_dist_bin_browser` named
  * the destination, the file landed in `dist/bin/…/content/browser/` and in
  * the `.app` bundle, and a plain `fireforge test` fetched it over
  * `chrome://` at runtime. Neither run escalated, and neither needed to.
  *
- * What the experiment did NOT exercise, and what therefore still escalates:
+ * What the experiment did not exercise, and what therefore still escalates:
  *
- *  - a NEW `jar.mn` file. The install manifest for a manifest the backend
+ *  - a new `jar.mn` file. The install manifest for a manifest the backend
  *    has never seen does not exist yet, and `mach build faster` consumes
  *    install manifests rather than regenerating the backend that writes
  *    them.
@@ -30,6 +30,7 @@
  * error direction stays the slow-but-correct one.
  */
 import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
 import { readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { isJarManifestPath } from './build-audit.js';
@@ -37,7 +38,7 @@ import { getUntrackedFilesInDir } from './git-status.js';
 /**
  * A jar declaration line: an optional bracketed base-directory prefix, then
  * the jar name. Matched at column zero because entry lines inside a section
- * are indented — an indented `foo.jar:` is content, not a declaration.
+ * are indented. An indented `foo.jar:` is content, not a declaration.
  */
 const JAR_DECLARATION_PATTERN = /^(\[[^\]]*\]\s*)?[^\s[\]]+\.jar:\s*$/;
 /** True when the jar declaration redirects the install base directory. */
@@ -48,14 +49,14 @@ function declaresNonDefaultBase(line) {
     return match[1] !== undefined;
 }
 /**
- * True when a changed `jar.mn` is NEW to the last successful build.
+ * True when a changed `jar.mn` is new to the last successful build.
  *
- * Untracked in the engine repo is the reliable tell: a fork's engine tree is
- * a checkout of upstream with patches applied to the WORKTREE, so a manifest
- * a patch created is untracked and one that shipped upstream is tracked. The
- * baseline's fingerprints cannot answer this on their own — they record only
- * the paths that were DIRTY at the last build, so a clean pre-existing
- * manifest has no entry either.
+ * Untracked in the engine repo is the reliable signal: a fork's engine tree
+ * is a checkout of upstream with patches applied to the worktree, so a
+ * manifest a patch created is untracked and one that shipped upstream is
+ * tracked. The baseline's fingerprints cannot answer this on their own: they
+ * record only the paths that were dirty at the last build, so a clean
+ * pre-existing manifest has no entry either.
  */
 async function isNewJarManifest(engineDir, path) {
     const untracked = await getUntrackedFilesInDir(engineDir, path);
@@ -82,7 +83,7 @@ export async function evaluateJarManifestEscalation(engineDir, changedPaths, bas
         }
         catch (error) {
             // Fail closed: an unanswerable "is this new?" keeps the old rule.
-            verbose(`jar escalation: could not classify engine/${path} (${String(error)}); escalating.`);
+            verbose(`jar escalation: could not classify engine/${path} (${toError(error).message}); escalating.`);
             causes.push({ path, reason: 'could not determine whether the manifest is new' });
             continue;
         }
@@ -95,7 +96,7 @@ export async function evaluateJarManifestEscalation(engineDir, changedPaths, bas
             body = await readText(join(engineDir, path));
         }
         catch (error) {
-            verbose(`jar escalation: could not read engine/${path} (${String(error)}); escalating.`);
+            verbose(`jar escalation: could not read engine/${path} (${toError(error).message}); escalating.`);
             causes.push({ path, reason: 'manifest could not be read' });
             continue;
         }
@@ -115,7 +116,7 @@ export async function evaluateJarManifestEscalation(engineDir, changedPaths, bas
     return { escalate: causes.length > 0, causes, cleared };
 }
 /**
- * Renders the operator-facing escalation notice. Names the manifest AND the
+ * Renders the operator-facing escalation notice. Names the manifest and the
  * reason: "a jar.mn changed" is the sentence that made the previous rule
  * impossible to argue with from outside.
  */

package/dist/src/core/build-overwrite-guard.d.ts

@@ -1,15 +1,15 @@
 /**
- * Loud guard against silently reverting UNEXPORTED engine drift.
+ * Loud guard against silently reverting unexported engine drift.
  *
  * `build-prepare` rewrites engine files from FireForge-owned sources before
  * every build: the branding tree, every Furnace-managed component, and
  * `mozconfig`. On a multi-session checkout that is a silent destructive
- * write — one session edits a file in `engine/` while another holds the
+ * write: one session edits a file in `engine/` while another holds the
  * engine lock, the lock-holder's build rewrites it back to its patch
  * baseline, and the editing session's later `re-export --wait-lock`
- * captures a HYBRID file that every gate then passes.
+ * captures a hybrid file that every gate then passes.
  *
- * This guard runs BEFORE the writes, classifies the engine's dirty files
+ * This guard runs before the writes, classifies the engine's dirty files
  * with the same classifier `fireforge status` uses, and reports the ones
  * whose content is explained by neither a patch body nor the pristine
  * baseline. Advisory by default (a warning naming every file), refusing

package/dist/src/core/build-overwrite-guard.js

@@ -1,16 +1,16 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Loud guard against silently reverting UNEXPORTED engine drift.
+ * Loud guard against silently reverting unexported engine drift.
  *
  * `build-prepare` rewrites engine files from FireForge-owned sources before
  * every build: the branding tree, every Furnace-managed component, and
  * `mozconfig`. On a multi-session checkout that is a silent destructive
- * write — one session edits a file in `engine/` while another holds the
+ * write: one session edits a file in `engine/` while another holds the
  * engine lock, the lock-holder's build rewrites it back to its patch
  * baseline, and the editing session's later `re-export --wait-lock`
- * captures a HYBRID file that every gate then passes.
+ * captures a hybrid file that every gate then passes.
  *
- * This guard runs BEFORE the writes, classifies the engine's dirty files
+ * This guard runs before the writes, classifies the engine's dirty files
  * with the same classifier `fireforge status` uses, and reports the ones
  * whose content is explained by neither a patch body nor the pristine
  * baseline. Advisory by default (a warning naming every file), refusing
@@ -23,12 +23,12 @@ import { collectFurnaceManagedPrefixes } from './furnace-config.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from './git-status.js';
 import { classifyFiles } from './status-classify.js';
 /**
- * Classifications whose on-disk content is explained by NEITHER a patch
- * body nor the pristine baseline — exactly the content a build-prepare
+ * Classifications whose on-disk content is explained by neither a patch
+ * body nor the pristine baseline, which is the content a build-prepare
  * overwrite would destroy without a record anywhere.
  *
- * `patch-backed` and `furnace` are excluded because their content IS the
- * recorded state; `branding` is excluded because the branding writer
+ * `patch-backed` and `furnace` are excluded because their content is the
+ * recorded state. `branding` is excluded because the branding writer
  * preserves unmanaged lines rather than overwriting them.
  */
 const AT_RISK_CLASSIFICATIONS = new Set(['unmanaged', 'patch-owned-drift', 'conflict']);
@@ -58,15 +58,15 @@ function isOverwrittenByBuildPrepare(file, binaryName, furnacePrefixes) {
  * Narrows the status entries to the ones build-prepare can overwrite,
  * expanding collapsed untracked directories on the way.
  *
- * Git reports a WHOLLY untracked directory as a single `?? dir/` entry
+ * Git reports a wholly untracked directory as a single `?? dir/` entry
  * rather than listing the files under it. A directory entry has no content
  * to compare, so `classifyFiles` matches it against neither a patch body nor
- * the pristine baseline and buckets it `unmanaged` — an at-risk
- * classification. Expanding here is what keeps this guard and
- * `status --unmanaged`, which expands, agreeing by construction.
+ * the pristine baseline and buckets it `unmanaged`, an at-risk
+ * classification. Expanding here keeps this guard in agreement with
+ * `status --unmanaged`, which also expands.
  *
  * Expansion is scoped to build-prepare-owned prefixes on both sides of the
- * walk: a collapsed directory that merely CONTAINS an owned prefix
+ * walk: a collapsed directory that merely contains an owned prefix
  * (`components/` when `components/custom/` is Furnace-managed) is rewritten
  * to the owned prefixes beneath it, so the enumeration never walks an
  * unrelated subtree and never trips the per-directory expansion cap.
@@ -143,7 +143,7 @@ export function formatUnexportedDriftWarning(files) {
         const owner = entry.owner !== undefined ? ` (owned by ${entry.owner})` : '';
         return `  ${entry.file} [${entry.classification}]${owner}`;
     });
-    return (`This build is about to rewrite ${String(files.length)} engine file(s) from FireForge-owned ` +
+    return (`This build is about to rewrite ${files.length} engine file(s) from FireForge-owned ` +
         'sources, and their current content matches NEITHER a patch body NOR the pristine ' +
         'baseline — so the edits below are recorded nowhere and the build will destroy them:\n' +
         `${rows.join('\n')}\n\n` +

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

@@ -26,28 +26,20 @@ export interface PrepareBuildOptions {
      * Previous successful-build baseline, used to detect `moz.build` /
      * `moz.configure` / `Makefile.in` changes that require a fresh
      * `mach configure` before the build. When undefined, the auto-configure
-     * step is skipped — there's no reference point for what "changed since"
-     * means.
+     * step is skipped, since there's no reference point for what "changed
+     * since" means.
      */
     previousBaseline?: BuildBaseline | undefined;
     /**
      * Turn the unexported-drift warning into a hard refusal.
-     * Scripted gates want the stop; an interactive build wants the warning.
+     * Scripted gates want the stop. An interactive build wants the warning.
      */
     refuseUnexportedDrift?: boolean | undefined;
 }
-/**
- * Packaging manifests whose graph/destination directories MAY need a full
- * build. Path-shape only: {@link evaluateJarManifestEscalation} decides
- * whether a given changed manifest actually forces one (a new manifest, or
- * one that redirects its install base directory), so an entry added to an
- * existing `dist/bin` manifest no longer costs a ~10-minute build.
- */
-export declare function requiresFullBuildForIncrementalTest(path: string): boolean;
 /**
  * Describes an exit code in the shell's 128+N signal convention. Truncated
  * configure/build logs with a signal-shaped exit (e.g. 144 = 128+16, SIGURG
- * on macOS) are environmental interruptions, not compiler failures — naming
+ * on macOS) are environmental interruptions, not compiler failures. Naming
  * that in the failure text saves the operator a fruitless log hunt.
  * Returns undefined for codes <= 128 (regular failures) and
  * for codes past the conventional signal range, so callers append nothing.