@hominis/fireforge 0.44.4 → 0.46.0

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

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Skip classification for the post-build packaging audit.
+ *
+ * The audit is warn-only, which makes a false positive cheap individually
+ * and expensive in aggregate: an operator who learns that `Audit:` lines are
+ * usually wrong stops reading the one that is right. Every classifier here
+ * exists to remove a warning whose "missing packaged artifact" claim is
+ * structurally impossible, and each carries its own reason so the
+ * `Packaged:` summary can say what it skipped and why — a run reporting
+ * `4 missing` with zero real misses is what this replaces.
+ */
+import { readText } from '../utils/fs.js';
+import { normalizePathSlashes } from '../utils/paths.js';
+import { escapeRegex } from '../utils/regex.js';
+import { extractWithBrandingPath } from './mach-mozconfig.js';
+/** Render order for the `Packaged:` summary's per-class breakdown. */
+export const AUDIT_SKIP_REASONS = [
+    'not-packageable',
+    'platform-gated',
+    'platform-gated-ancestor',
+    'tests-not-packaged',
+    'source-unreadable',
+    'branding-not-selected',
+    'storybook-story',
+    'declared-unpackaged',
+];
+/**
+ * Suffixes of Storybook story modules.
+ *
+ * Firefox's in-tree Storybook renders these through its own Vite config;
+ * no `jar.mn` or `moz.build` entry packages one, so "no packaged artifact"
+ * is the expected state rather than a missing registration. Kept as a
+ * CLOSED list on purpose: generalising to "anything with a dotted infix"
+ * would swallow `*.worker.js` and `*.sys.mjs`, which are packaged.
+ */
+const STORYBOOK_SUFFIXES = ['.stories.mjs', '.stories.js'];
+/** True for a Storybook story module. */
+export function isStorybookStoryPath(sourcePath) {
+    const normalised = normalizePathSlashes(sourcePath);
+    return STORYBOOK_SUFFIXES.some((suffix) => normalised.endsWith(suffix));
+}
+/** Prefix under which every branding tree lives. */
+const BRANDING_ROOT = 'browser/branding/';
+/**
+ * Reads the branding directory this objdir was configured with.
+ *
+ * FireForge generates `engine/mozconfig` and writes the
+ * `ac_add_options --with-branding=…` line into it, so the selected branding
+ * is knowable from the tree. Returns undefined when the mozconfig cannot be
+ * read or carries no directive — the caller must then keep warning, because
+ * a skip that cannot name its evidence is a masked warning.
+ *
+ * @param engineDir - Absolute path to the engine root
+ * @returns Engine-relative branding path, or undefined
+ */
+export async function resolveSelectedBranding(engineDir) {
+    try {
+        const content = await readText(`${engineDir.replace(/[/\\]+$/, '')}/mozconfig`);
+        const selected = extractWithBrandingPath(content);
+        return selected === undefined ? undefined : normalizePathSlashes(selected).replace(/\/+$/, '');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True when `sourcePath` lives under a branding tree that is NOT the one
+ * this objdir was configured with.
+ *
+ * An unselected branding directory is not an input to this build at all, so
+ * its files can never appear in `dist/`. Worse, the basename walker matched
+ * them against the SELECTED branding's same-named artifact and reported the
+ * unselected file as "newer than its packaged artifact" — a stale warning
+ * about a comparison that has no meaning.
+ *
+ * @param sourcePath - Engine-relative POSIX path
+ * @param selectedBranding - Engine-relative selected branding path
+ */
+export function isUnselectedBrandingPath(sourcePath, selectedBranding) {
+    if (selectedBranding === undefined)
+        return false;
+    const normalised = normalizePathSlashes(sourcePath);
+    if (!normalised.startsWith(BRANDING_ROOT))
+        return false;
+    const selected = `${selectedBranding}/`;
+    return !normalised.startsWith(selected);
+}
+/**
+ * Finds the declaration admitting `sourcePath`, if any.
+ *
+ * Exact match or a `*`-within-one-segment glob, matching the
+ * `support-files` matcher's deliberate narrowness: `**` and other
+ * cross-directory shapes are not accepted, because a carve-out that
+ * silently widens is exactly the failure this feature is warned against.
+ *
+ * @param sourcePath - Engine-relative POSIX path
+ * @param declarations - The project's `buildAudit.unpackaged` entries
+ */
+export function matchUnpackagedDeclaration(sourcePath, declarations) {
+    const normalised = normalizePathSlashes(sourcePath);
+    return declarations.find((declaration) => {
+        const pattern = normalizePathSlashes(declaration.path);
+        if (!pattern.includes('*'))
+            return pattern === normalised;
+        const regex = new RegExp(`^${pattern
+            .split('*')
+            .map((part) => escapeRegex(part))
+            .join('[^/]*')}$`);
+        return regex.test(normalised);
+    });
+}

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

@@ -1,3 +1,4 @@
+import { type AuditSkipReason, type UnpackagedDeclaration } from './build-audit-skip.js';
 import type { BuildBaseline } from './build-baseline-types.js';
 /**
  * True for the build-input manifests the build consumes but never packages
@@ -34,9 +35,17 @@ export interface AuditEntry {
      * updated: an artifact exists and is at least as new as the source.
      * stale:   artifact exists but is older than the source (probable packaging drop).
      * missing: no artifact with a matching basename was found anywhere under dist/.
-     * skipped: the file extension / path does not imply packaging; not counted.
+     * skipped: the file was not audited; `skipReason` says why.
      */
     status: 'updated' | 'stale' | 'missing' | 'skipped';
+    /**
+     * Why a `skipped` entry was skipped. Present only for `skipped`; the
+     * reasons used to exist only as verbose log strings, so the summary line
+     * could report `4 missing` on a run with zero real misses and nothing in
+     * the counts distinguished a structural non-input from an unregistered
+     * file an operator must act on.
+     */
+    skipReason?: AuditSkipReason;
 }
 /** Summary counts for the "Packaged:" end-of-build line. */
 export interface AuditSummary {
@@ -44,6 +53,8 @@ export interface AuditSummary {
     stale: number;
     missing: number;
     skipped: number;
+    /** Per-class skip counts, so the summary can name what it dismissed. */
+    skippedByReason: Record<AuditSkipReason, number>;
     entries: AuditEntry[];
 }
 /**
@@ -78,4 +89,6 @@ export declare function isXpcomManifestPath(sourcePath: string): boolean;
  * @param baseline Optional previous-build baseline marker.
  * @returns Summary of artifact status counts.
  */
-export declare function auditBuildArtifacts(projectRoot: string, engineDir: string, baseline: BuildBaseline | undefined): Promise<AuditSummary>;
+export declare function auditBuildArtifacts(projectRoot: string, engineDir: string, baseline: BuildBaseline | undefined, options?: {
+    unpackaged?: readonly UnpackagedDeclaration[];
+}): Promise<AuditSummary>;

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

@@ -35,14 +35,18 @@
  */
 import { readdir, stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, verbose, warn } from '../utils/logger.js';
 import { normalizePathSlashes } from '../utils/paths.js';
-import { detectPlatformGate } from './build-audit-platform.js';
+import { detectAncestorDirsGate, detectPlatformGate } from './build-audit-platform.js';
 import { collectSameBasenameCandidates, findRegisteredTarget, resolveArtifactByRegistration, } from './build-audit-registration.js';
 import { countTrailingSegmentMatches, GENERIC_PATH_SEGMENTS, isTestPath, resolveBestArtifact, } from './build-audit-resolve.js';
+import { AUDIT_SKIP_REASONS, isStorybookStoryPath, isUnselectedBrandingPath, matchUnpackagedDeclaration, resolveSelectedBranding, } from './build-audit-skip.js';
 import { resolveArtifactByKnownTransform } from './build-audit-transforms.js';
 import { collectChangedEnginePaths } from './engine-changes.js';
+import { loadPatchesManifest } from './patch-manifest-io.js';
+import { buildPatchClaims } from './status-classify.js';
 /** Path extensions that are conventionally packaged into the Firefox bundle. */
 const PACKAGEABLE_EXTENSIONS = [
     '.js',
@@ -98,6 +102,10 @@ export function isBuildInputPath(sourcePath) {
 export function isJarManifestPath(sourcePath) {
     return sourcePath === 'jar.mn' || sourcePath.endsWith('/jar.mn');
 }
+/** Zeroed per-class skip counters. */
+function emptySkipCounts() {
+    return Object.fromEntries(AUDIT_SKIP_REASONS.map((reason) => [reason, 0]));
+}
 /**
  * Decides whether a source path should be packaged. Returns true for paths
  * whose extension or directory fragment matches a known-packaged pattern,
@@ -144,7 +152,7 @@ export function isPackageablePath(sourcePath) {
  * @returns True when the path is a `components.conf` manifest.
  */
 export function isXpcomManifestPath(sourcePath) {
-    return basename(sourcePath.replace(/\\/g, '/')) === 'components.conf';
+    return basename(normalizePathSlashes(sourcePath)) === 'components.conf';
 }
 /*
  * Finds the unique obj-star directory with a dist subtree, or undefined
@@ -270,6 +278,55 @@ function isConfidentMatch(source, candidate) {
     }
     return false;
 }
+/**
+ * Applies a `buildAudit.unpackaged` carve-out to a classified result.
+ *
+ * Two behaviours, both mirroring the `--expect-unmanaged` model:
+ *
+ *  - An admitted path is LISTED, not silenced. A carve-out nobody can see
+ *    is how one quietly widens, so the run says which paths it admitted and
+ *    on what stated reason.
+ *  - An admitted path that DOES resolve to a packaged artifact is a STALE
+ *    carve-out: the declaration asserts a fact about the tree that is no
+ *    longer true, and suppressing on it would hide a real packaging change.
+ *    That is reported as a warning, not accepted.
+ *
+ * A declaration matching nothing that changed this run says nothing —
+ * unlike `--expect-unmanaged`, whose unseen entries are reported. The
+ * difference is deliberate: that is a per-invocation flag list, where an
+ * unmet entry is probably a typo in the command just typed. This is a
+ * standing config list checked against only the files that happened to
+ * change, so "not met" is the normal case and reporting it would put a
+ * warning on every build.
+ */
+function applyUnpackagedCarveOut(result, ctx) {
+    // Already skipped for a more specific structural reason — the carve-out
+    // is redundant there and reporting it would be noise.
+    if (result.status === 'skipped')
+        return result;
+    const declaration = matchUnpackagedDeclaration(result.source, ctx.unpackaged);
+    if (declaration === undefined)
+        return result;
+    if (result.artifact !== undefined) {
+        return {
+            source: result.source,
+            artifact: result.artifact,
+            status: 'skipped',
+            skipReason: 'declared-unpackaged',
+            warning: `Audit: engine/${result.source} is declared unpackaged in fireforge.json ` +
+                `("${declaration.reason}") but a packaged artifact exists at ${result.artifact}. ` +
+                'The declaration is stale — remove it, or correct its path.',
+        };
+    }
+    return {
+        source: result.source,
+        artifact: undefined,
+        status: 'skipped',
+        skipReason: 'declared-unpackaged',
+        notice: `Audit: engine/${result.source} admitted as unpackaged by ` +
+            `buildAudit.unpackaged "${declaration.path}" — ${declaration.reason}`,
+    };
+}
 /**
  * Audits one engine source path and returns its entry. Pure orchestration
  * helper kept separate so `auditBuildArtifacts` stays under the per-function
@@ -277,12 +334,30 @@ function isConfidentMatch(source, candidate) {
  */
 async function auditSinglePath(source, ctx) {
     if (!isPackageablePath(source)) {
-        return { source, artifact: undefined, status: 'skipped' };
+        return { source, artifact: undefined, status: 'skipped', skipReason: 'not-packageable' };
+    }
+    if (isStorybookStoryPath(source)) {
+        verbose(`Audit: skipping engine/${source} — Storybook story, never packaged.`);
+        return { source, artifact: undefined, status: 'skipped', skipReason: 'storybook-story' };
+    }
+    if (isUnselectedBrandingPath(source, ctx.selectedBranding)) {
+        verbose(`Audit: skipping engine/${source} — branding tree is not the selected ${ctx.selectedBranding ?? '?'}, so it is not an input to this objdir.`);
+        return { source, artifact: undefined, status: 'skipped', skipReason: 'branding-not-selected' };
     }
     const gate = await detectPlatformGate(ctx.engineDir, source);
     if (gate.gatedOff) {
         verbose(`Audit: skipping engine/${source} — gated off by "${gate.gateExpression ?? '?'}".`);
-        return { source, artifact: undefined, status: 'skipped' };
+        return { source, artifact: undefined, status: 'skipped', skipReason: 'platform-gated' };
+    }
+    const ancestorGate = await detectAncestorDirsGate(ctx.engineDir, source);
+    if (ancestorGate.gatedOff) {
+        verbose(`Audit: skipping engine/${source} — its directory is reached through a DIRS entry in engine/${ancestorGate.gateFile ?? '?'} gated by "${ancestorGate.gateExpression ?? '?'}".`);
+        return {
+            source,
+            artifact: undefined,
+            status: 'skipped',
+            skipReason: 'platform-gated-ancestor',
+        };
     }
     // Tests only end up under `_tests/` after `mach package-tests` (or a
     // test-run that invokes the target) has executed. A plain `mach build`
@@ -291,7 +366,7 @@ async function auditSinglePath(source, ctx) {
     // Skip audit for test sources when no packaged-tests marker is present.
     if (isTestPath(source) && !ctx.testsPackaged) {
         verbose(`Audit: skipping engine/${source} — _tests/${PACKAGED_TESTS_MARKER} not present; full test packaging has not run for this build.`);
-        return { source, artifact: undefined, status: 'skipped' };
+        return { source, artifact: undefined, status: 'skipped', skipReason: 'tests-not-packaged' };
     }
     const sourcePath = join(ctx.engineDir, source);
     let sourceMtime;
@@ -301,7 +376,7 @@ async function auditSinglePath(source, ctx) {
     }
     catch {
         // Deletion that didn't propagate — distinct class of bug, not audited yet.
-        return { source, artifact: undefined, status: 'skipped' };
+        return { source, artifact: undefined, status: 'skipped', skipReason: 'source-unreadable' };
     }
     const roots = searchRootsFor(source, ctx.distRoot, ctx.testsRoot);
     // Registration-aware resolution first: a `jar.mn` entry whose `(source)`
@@ -442,6 +517,39 @@ function relativeManifestPath(engineDir, manifest) {
     }
     return manifest;
 }
+/**
+ * Path → owning patch filenames, from the patches manifest's
+ * `filesAffected`. Best-effort: a project with no queue (or an unreadable
+ * manifest) yields an empty map and the notices render exactly as before.
+ */
+async function resolveAuditOwnership(projectRoot) {
+    try {
+        const patchesDir = join(projectRoot, 'patches');
+        const manifest = await loadPatchesManifest(patchesDir);
+        if (!manifest)
+            return new Map();
+        return buildPatchClaims(manifest.patches);
+    }
+    catch (error) {
+        verbose(`Audit: ownership lookup unavailable (${toError(error).message}).`);
+        return new Map();
+    }
+}
+/**
+ * Renders the ownership suffix for one audit notice: the owning patch, or
+ * an explicit `unmanaged` mark. An empty map (no queue, unreadable
+ * manifest) renders nothing rather than claiming everything is unmanaged —
+ * "unmanaged" must mean "checked and unowned", never "could not check".
+ */
+function describeOwnership(ownersByPath, source) {
+    if (ownersByPath.size === 0)
+        return '';
+    const owners = ownersByPath.get(source);
+    if (owners === undefined || owners.length === 0) {
+        return ' Ownership: unmanaged (no patch claims this path).';
+    }
+    return ` Ownership: ${owners.join(', ')}.`;
+}
 /**
  * Runs the post-build audit. Emits per-file warnings for missing or
  * stale artifacts and a summary info line at the end. Always returns
@@ -452,13 +560,13 @@ function relativeManifestPath(engineDir, manifest) {
  * @param baseline Optional previous-build baseline marker.
  * @returns Summary of artifact status counts.
  */
-export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
-    void projectRoot;
+export async function auditBuildArtifacts(projectRoot, engineDir, baseline, options = {}) {
     const summary = {
         updated: 0,
         stale: 0,
         missing: 0,
         skipped: 0,
+        skippedByReason: emptySkipCounts(),
         entries: [],
     };
     const distRoot = await resolveDistRoot(engineDir);
@@ -472,18 +580,52 @@ export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
     if (changed.length === 0) {
         return summary;
     }
-    const ctx = { engineDir, distRoot, testsRoot, testsPackaged };
+    // Ownership, resolved once for the whole audit. The notices key on "was
+    // touched", which on a shared checkout means any concurrent session's
+    // dirty files — so an operator gets a registration-shaped warning about a
+    // file they never edited and has to census ownership by hand to dismiss
+    // it. FireForge already resolves this for `status --ownership`; carrying
+    // it here turns a three-line mystery into three dismissible lines.
+    const ownersByPath = await resolveAuditOwnership(projectRoot);
+    const ctx = {
+        engineDir,
+        distRoot,
+        testsRoot,
+        testsPackaged,
+        selectedBranding: await resolveSelectedBranding(engineDir),
+        unpackaged: options.unpackaged ?? [],
+    };
     for (const source of changed) {
-        const result = await auditSinglePath(source, ctx);
+        const result = applyUnpackagedCarveOut(await auditSinglePath(source, ctx), ctx);
         summary[result.status] += 1;
+        if (result.status === 'skipped' && result.skipReason !== undefined) {
+            summary.skippedByReason[result.skipReason] += 1;
+        }
         summary.entries.push({
             source: result.source,
             artifact: result.artifact,
             status: result.status,
+            ...(result.skipReason === undefined ? {} : { skipReason: result.skipReason }),
         });
         if (result.warning)
-            warn(result.warning);
+            warn(`${result.warning}${describeOwnership(ownersByPath, result.source)}`);
+        if (result.notice)
+            info(result.notice);
     }
-    info(`Packaged: ${summary.updated} updated, ${summary.stale} stale, ${summary.missing} missing, ${summary.skipped} skipped`);
+    info(`Packaged: ${summary.updated} updated, ${summary.stale} stale, ${summary.missing} missing, ` +
+        `${summary.skipped} skipped${describeSkipBreakdown(summary)}`);
     return summary;
 }
+/**
+ * Renders the per-class skip breakdown appended to the `Packaged:` line.
+ *
+ * Without it the summary reported one undifferentiated `skipped` count, so
+ * a run that dismissed four unselected-branding files and one
+ * ancestor-gated directory looked identical to one that dismissed five
+ * unregistered sources — and the four false `missing` entries downstream
+ * reported had no counterpart in the counts an operator could check.
+ */
+function describeSkipBreakdown(summary) {
+    const parts = AUDIT_SKIP_REASONS.filter((reason) => summary.skippedByReason[reason] > 0).map((reason) => `${reason} ${String(summary.skippedByReason[reason])}`);
+    return parts.length === 0 ? '' : ` (${parts.join(', ')})`;
+}

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

@@ -25,8 +25,6 @@ import { type BuildBaseline, type TestPackagingCoverage } from './build-baseline
  * `'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
@@ -40,36 +38,55 @@ export declare function getBuildBaselinePath(projectRoot: string): string;
  * @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 — `mach build faster` does not rebake `components.conf`
+     * registrations, so the last FULL build stays the honest 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

@@ -16,12 +16,12 @@
  * 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
@@ -71,33 +71,10 @@ 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);
@@ -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') {

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

@@ -0,0 +1,64 @@
+/**
+ * Decides whether a changed `jar.mn` really forces the pre-test build to
+ * 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
+ * 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
+ * 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:
+ *
+ *  - 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.
+ *  - a manifest whose jar declaration carries a bracketed base-directory
+ *    prefix (`[some/dir] name.jar:`), which redirects the install
+ *    destination away from the default chrome root. That redirect is the
+ *    "non-dist/bin target" half nobody has run.
+ *
+ * Everything else about the rule is unchanged, and every failure to read or
+ * parse a manifest escalates: this narrows a conservative rule, so its
+ * error direction stays the slow-but-correct one.
+ */
+import type { BuildBaseline } from './build-baseline-types.js';
+/** Why one changed `jar.mn` still forces a full build. */
+export interface JarEscalationCause {
+    /** Engine-relative manifest path. */
+    path: string;
+    /** Operator-facing reason, printed with the escalation notice. */
+    reason: string;
+}
+/** Outcome of {@link evaluateJarManifestEscalation}. */
+export interface JarEscalationDecision {
+    /** True when at least one changed manifest still needs a full build. */
+    escalate: boolean;
+    /** One entry per manifest that forces the escalation. */
+    causes: JarEscalationCause[];
+    /** Manifests the narrowing cleared; kept for the verbose explanation. */
+    cleared: string[];
+}
+/**
+ * Evaluates every changed `jar.mn` against the narrowed rule.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param changedPaths - Engine-relative paths changed since the last
+ *   successful build (non-`jar.mn` entries are ignored)
+ * @param baseline - Last successful build's baseline (reserved: the
+ *   fingerprint map already gated which paths reach here)
+ * @returns The escalation decision with per-manifest causes
+ */
+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
+ * reason: "a jar.mn changed" is the sentence that made the previous rule
+ * impossible to argue with from outside.
+ */
+export declare function formatJarEscalationNotice(decision: JarEscalationDecision): string;