@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -25,17 +25,7 @@ import { explainMachError } from './mach-error-hints.js';
 /** Path fragments of files whose edits invalidate the recursive-make backend. */
 const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.in'];
 /**
- * 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 function requiresFullBuildForIncrementalTest(path) {
-    return isJarManifestPath(path);
-}
-/**
- * Build-input manifests changed since the last SUCCESSFUL build — not
+ * Build-input manifests changed since the last successful build, not
  * merely dirty against HEAD. `collectChangedEnginePaths` unions the
  * baseline-to-HEAD diff with every worktree modification, and a fork's
  * worktree is permanently dirty (imported patches, Furnace-applied
@@ -43,8 +33,8 @@ export function requiresFullBuildForIncrementalTest(path) {
  * `moz.build` as changed on every run: `mach configure` re-ran and the
  * pre-test build escalated to a full `mach build` after each full build
  * that had already consumed exactly this content. The baseline's
- * `buildInputFingerprints` say what the last successful build saw;
- * anything byte-identical to that is dropped here. A baseline without the
+ * `buildInputFingerprints` say what the last successful build saw.
+ * Anything byte-identical to that is dropped here. A baseline without the
  * field (written before it existed) keeps every dirty input, which is the
  * old behaviour.
  *
@@ -66,8 +56,9 @@ async function collectChangedBuildInputs(engineDir, baseline) {
  * Extracts the tail of captured `mach configure` output so the underlying
  * mozbuild failure (e.g. `mozbuild.util.UnsortedError: ... is not in sorted
  * order`) is carried into the thrown `BuildError` instead of being reduced to
- * a bare exit code. mozbuild writes the error and its traceback to stderr;
- * stdout is included as a fallback for shells that interleave the streams.
+ * a bare exit code. mozbuild writes the error and its traceback to stderr,
+ * and stdout is included as a fallback for shells that interleave the
+ * streams.
  * Returns an empty string when nothing useful was captured.
  */
 function extractMachConfigureError(result) {
@@ -79,7 +70,7 @@ function extractMachConfigureError(result) {
 /**
  * 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.
@@ -101,7 +92,7 @@ export function describeSignalShapedExit(exitCode) {
  * Builds the `BuildError` for a non-zero auto-configure exit: the output
  * tail (so the underlying mozbuild failure survives), any matched
  * mach-error hints (so e.g. a toolchain minimum that moved with a source
- * hop names `fireforge bootstrap` on this path too, exactly like the
+ * hop names `fireforge bootstrap` on this path too, just like the
  * protected build dispatch), and the stop rationale.
  */
 function buildConfigureFailureError(captured) {
@@ -126,9 +117,14 @@ function buildConfigureFailureError(captured) {
  * @param baseline - Last successful build's baseline
  */
 async function decideJarEscalation(engineDir, changed, baseline) {
-    const decision = await evaluateJarManifestEscalation(engineDir, changed.filter(requiresFullBuildForIncrementalTest), baseline);
+    // Packaging manifests whose graph/destination directories may need a full
+    // build. Path-shape only: `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.
+    const decision = await evaluateJarManifestEscalation(engineDir, changed.filter(isJarManifestPath), baseline);
     if (decision.cleared.length > 0) {
-        verbose(`jar escalation: ${String(decision.cleared.length)} changed jar.mn add entries to an existing dist/bin manifest; not escalating for ${decision.cleared.join(', ')}.`);
+        verbose(`jar escalation: ${decision.cleared.length} changed jar.mn add entries to an existing dist/bin manifest; not escalating for ${decision.cleared.join(', ')}.`);
     }
     return decision.escalate ? formatJarEscalationNotice(decision) : undefined;
 }
@@ -144,10 +140,10 @@ export function isBackendInvalidatingFile(path) {
     return false;
 }
 /**
- * Loud before the overwrite, not silent after it.
+ * Warns before the overwrite rather than after it.
  *
- * Every write `prepareBuildEnvironment` performs — branding, Furnace
- * components, `mozconfig` — rewrites engine files from a FireForge-owned
+ * Every write `prepareBuildEnvironment` performs (branding, Furnace
+ * components, `mozconfig`) rewrites engine files from a FireForge-owned
  * source. Content recorded in neither a patch body nor the pristine baseline
  * is destroyed by that, and on a multi-session checkout the destruction is
  * what lets a later re-export capture a half-reverted hybrid that every gate
@@ -220,9 +216,9 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
                 const exitCode = captured.exitCode;
                 if (exitCode !== 0) {
                     configureSpinner.error(`mach configure failed with exit code ${exitCode}`);
-                    // Surface the underlying mozbuild error (e.g. UnsortedError) instead
-                    // of a bare exit code — the generic message hid the actual cause —
-                    // plus any matched mach-error hints (see the helper).
+                    // Surface the underlying mozbuild error (e.g. UnsortedError)
+                    // instead of a bare exit code, since the generic message hid the
+                    // actual cause, plus any matched mach-error hints (see the helper).
                     throw buildConfigureFailureError(captured);
                 }
                 else {
@@ -246,7 +242,7 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
     // Set up custom branding directory and patch moz.configure. Thread the
     // project license through so `buildConfigureScriptContent` /
     // `buildBrandPropertiesContent` / `buildBrandFtlContent` stamp the
-    // generated files with a matching SPDX header — otherwise `patch-lint`
+    // generated files with a matching SPDX header. Otherwise `patch-lint`
     // flags them with `missing-license-header` on every subsequent export when
     // the project is not MPL-2.0.
     const brandingConfig = {

package/dist/src/core/config-mutate.js

@@ -18,10 +18,10 @@ function cloneConfigDocument(config) {
     return cloned;
 }
 /**
- * The error every sentinel-segment refusal raises. Only the MESSAGE lives
+ * The error every sentinel-segment refusal raises. Only the message lives
  * here: the comparison itself is spelled inline at each write site, because
  * that is what both a reader and CodeQL's `js/prototype-pollution-utility`
- * barrier detection need — the latter is not interprocedural, so a check
+ * barrier detection need. That detection is not interprocedural, so a check
  * hidden behind a helper leaves the descent below looking unguarded.
  */
 function sentinelSegmentError(key, part) {
@@ -41,8 +41,8 @@ function getOrCreateChildRecord(parent, key) {
 export function mutateConfig(config, key, value, skipValidation = false) {
     const parts = key.split('.');
     const raw = cloneConfigDocument(config);
-    // Every segment is checked at the point it is USED as a property name —
-    // the descent below and the leaf assignment — rather than once up front,
+    // Every segment is checked at the point it is used as a property name
+    // (the descent below and the leaf assignment) rather than once up front,
     // so `--force` cannot be used to mutate Object.prototype and neither write
     // can drift out from behind the guard. `raw` is a private clone, so a
     // refusal here has mutated nothing the caller can observe.

package/dist/src/core/config-paths.d.ts

@@ -2,16 +2,12 @@
  * Project path derivation from a root directory.
  */
 import type { ProjectPaths } from '../types/config.js';
-/** Name of the configuration file */
-export declare const CONFIG_FILENAME = "fireforge.json";
 /** Name of the fireforge data directory */
 export declare const FIREFORGE_DIR = ".fireforge";
-/** Name of the state file */
-export declare const STATE_FILENAME = "state.json";
 /** Supported top-level fireforge.json keys backed by the current schema. */
-export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "test", "externalToolchains", "license", "wire", "patchLint", "patchPolicy", "typecheck", "markerComment"];
+export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "buildAudit", "test", "externalToolchains", "license", "wire", "patchLint", "patchPolicy", "typecheck", "markerComment"];
 /** Supported config paths that can be read or set without --force. */
-export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "firefox.candidate", "build", "build.jobs", "test", "test.canaryPath", "test.canaryTimeoutSeconds", "externalToolchains", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.checkJsTestFiles", "patchLint.checkJsTestShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "patchPolicy", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
+export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "firefox.candidate", "firefox.allowUnverifiedDownload", "build", "build.jobs", "test", "test.canaryPath", "test.canaryTimeoutSeconds", "externalToolchains", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.checkJsTestFiles", "patchLint.checkJsTestShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "patchPolicy", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
 /**
  * Gets all project paths based on a root directory.
  * @param root - Root directory of the project

package/dist/src/core/config-paths.js

@@ -4,11 +4,11 @@
  */
 import { join } from 'node:path';
 /** Name of the configuration file */
-export const CONFIG_FILENAME = 'fireforge.json';
+const CONFIG_FILENAME = 'fireforge.json';
 /** Name of the fireforge data directory */
 export const FIREFORGE_DIR = '.fireforge';
 /** Name of the state file */
-export const STATE_FILENAME = 'state.json';
+const STATE_FILENAME = 'state.json';
 /** Name of the engine directory */
 const ENGINE_DIR = 'engine';
 /** Name of the patches directory */
@@ -25,6 +25,7 @@ export const SUPPORTED_CONFIG_ROOT_KEYS = [
     'binaryName',
     'firefox',
     'build',
+    'buildAudit',
     'test',
     'externalToolchains',
     'license',
@@ -46,6 +47,7 @@ export const SUPPORTED_CONFIG_PATHS = [
     'firefox.product',
     'firefox.sha256',
     'firefox.candidate',
+    'firefox.allowUnverifiedDownload',
     'build',
     'build.jobs',
     'test',

package/dist/src/core/config-state.d.ts

@@ -8,12 +8,6 @@ import type { FireForgeState } from '../types/config.js';
  * @returns FireForge state
  */
 export declare function loadState(root: string): Promise<FireForgeState>;
-/**
- * Saves the fireforge state.
- * @param root - Root directory of the project
- * @param state - State to save
- */
-export declare function saveState(root: string, state: FireForgeState): Promise<void>;
 /**
  * Updates specific fields in the fireforge state.
  * @param root - Root directory of the project

package/dist/src/core/config-state.js

@@ -24,13 +24,7 @@ function sanitizeProjectState(data) {
     const state = {};
     const issues = [];
     const recoveredFields = [];
-    const stringFields = [
-        'brand',
-        'buildMode',
-        'lastBuild',
-        'downloadedVersion',
-        'baseCommit',
-    ];
+    const stringFields = ['brand', 'buildMode', 'downloadedVersion', 'baseCommit'];
     for (const key of stringFields) {
         const value = data[key];
         if (value === undefined) {
@@ -41,9 +35,9 @@ function sanitizeProjectState(data) {
             continue;
         }
         if (key === 'buildMode') {
-            // Validate and assign in ONE block so the predicate's narrowing reaches
+            // Validate and assign in one block so the predicate's narrowing reaches
             // the assignment. Split across two `key === 'buildMode'` guards,
-            // TypeScript cannot correlate them and the assignment needed a cast —
+            // TypeScript cannot correlate them and the assignment needed a cast,
             // which is what let the untyped allowlist drift from the union.
             if (!isBuildMode(value)) {
                 issues.push(`field "buildMode" must be one of: ${BUILD_MODES.join(', ')}`);
@@ -132,18 +126,6 @@ export async function loadState(root) {
     const paths = getProjectPaths(root);
     return loadStateFromPath(paths.state);
 }
-/**
- * Saves the fireforge state.
- * @param root - Root directory of the project
- * @param state - State to save
- */
-export async function saveState(root, state) {
-    const paths = getProjectPaths(root);
-    const validatedState = validateFireForgeState(state);
-    await withStateFileLock(paths.state, async () => {
-        await writeJson(paths.state, validatedState);
-    });
-}
 /**
  * Updates specific fields in the fireforge state.
  * @param root - Root directory of the project

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

@@ -0,0 +1,8 @@
+import type { BuildAuditConfig } from '../types/config.js';
+/**
+ * Parses the `buildAudit` block.
+ *
+ * @param raw - The raw `buildAudit` value from fireforge.json
+ * @returns The validated block
+ */
+export declare function parseBuildAuditConfig(raw: unknown): BuildAuditConfig;

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

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Validation for the `buildAudit` block.
+ *
+ * Split out of `config-validate.ts`, which is at its per-file line budget,
+ * following the `config-validate-file-size.ts` precedent.
+ *
+ * The rules here are stricter than the schema strictly needs, on purpose:
+ * every entry is a standing suppression of a warning the
+ * audit would otherwise raise. A malformed one must fail loudly at config
+ * load rather than quietly admit nothing (leaving the operator believing a
+ * path is carved out) or quietly admit everything.
+ */
+import { ConfigError } from '../errors/config.js';
+import { isContainedRelativePath } from '../utils/paths.js';
+import { isObject } from '../utils/validation.js';
+/** Parses one `buildAudit.unpackaged[]` entry. */
+function parseUnpackagedEntry(raw, field) {
+    if (!isObject(raw)) {
+        throw new ConfigError(`Config field "${field}" must be a plain object with "path" and "reason"`);
+    }
+    for (const key of Object.keys(raw)) {
+        if (key !== 'path' && key !== 'reason') {
+            throw new ConfigError(`Config field "${field}" has unknown key "${key}"`);
+        }
+    }
+    const path = raw['path'];
+    if (typeof path !== 'string' || path.trim().length === 0) {
+        throw new ConfigError(`Config field "${field}.path" must be a non-empty string`);
+    }
+    if (!isContainedRelativePath(path)) {
+        throw new ConfigError(`Config field "${field}.path" must be an engine-relative path`);
+    }
+    if (path.includes('**')) {
+        // A `**` carve-out admits an entire subtree, which is how a reviewed
+        // exception quietly becomes a blanket one. `*` inside a single segment
+        // is enough for the shapes this exists for.
+        throw new ConfigError(`Config field "${field}.path" must not use "**" — a carve-out may glob within one path segment only`);
+    }
+    const reason = raw['reason'];
+    if (typeof reason !== 'string' || reason.trim().length === 0) {
+        // Required on purpose: this is the one audit class FireForge cannot
+        // derive from the tree, so the declaration is the evidence.
+        throw new ConfigError(`Config field "${field}.reason" must be a non-empty string explaining why the file is never packaged`);
+    }
+    return { path, reason };
+}
+/**
+ * Parses the `buildAudit` block.
+ *
+ * @param raw - The raw `buildAudit` value from fireforge.json
+ * @returns The validated block
+ */
+export function parseBuildAuditConfig(raw) {
+    if (!isObject(raw)) {
+        throw new ConfigError('Config field "buildAudit" must be a plain object');
+    }
+    for (const key of Object.keys(raw)) {
+        if (key !== 'unpackaged') {
+            throw new ConfigError(`Config field "buildAudit" has unknown key "${key}"`);
+        }
+    }
+    const unpackaged = raw['unpackaged'];
+    if (unpackaged === undefined)
+        return {};
+    if (!Array.isArray(unpackaged)) {
+        throw new ConfigError('Config field "buildAudit.unpackaged" must be an array');
+    }
+    const entries = unpackaged.map((entry, index) => parseUnpackagedEntry(entry, `buildAudit.unpackaged[${String(index)}]`));
+    const seen = new Set();
+    for (const entry of entries) {
+        if (seen.has(entry.path)) {
+            // Two rows for one path means one of the two reasons is not the
+            // operative one, and nothing says which.
+            throw new ConfigError(`Config field "buildAudit.unpackaged" declares "${entry.path}" more than once`);
+        }
+        seen.add(entry.path);
+    }
+    return { unpackaged: entries };
+}

package/dist/src/core/config-validate-file-size.d.ts

@@ -6,7 +6,7 @@
 import type { PatchLintFileSizeThresholds } from '../types/config.js';
 /**
  * Parses the `patchLint.fileSizeThresholds` block. Ordering is validated
- * against the MERGED triple (overrides on top of the defaults), so setting
+ * against the merged triple (overrides on top of the defaults), so setting
  * only `warning` cannot land below the default `notice`.
  */
 export declare function parsePatchLintFileSizeThresholds(raw: unknown): PatchLintFileSizeThresholds;

package/dist/src/core/config-validate-file-size.js

@@ -9,7 +9,7 @@ import { isObject } from '../utils/validation.js';
 import { DEFAULT_FILE_SIZE_THRESHOLDS } from './patch-lint-file-size.js';
 /**
  * Parses one `patchLint.fileSizeThresholds.<tier>` triple. Every field is
- * optional and merges over the built-in default; values must be positive
+ * optional and merges over the built-in default. Values must be positive
  * integers and stay ordered `notice <= warning <= error`, because an
  * out-of-order triple would silently disable a band instead of failing.
  */
@@ -36,7 +36,7 @@ function parseFileSizeTier(raw, field) {
 }
 /**
  * Parses the `patchLint.fileSizeThresholds` block. Ordering is validated
- * against the MERGED triple (overrides on top of the defaults), so setting
+ * against the merged triple (overrides on top of the defaults), so setting
  * only `warning` cannot land below the default `notice`.
  */
 export function parsePatchLintFileSizeThresholds(raw) {
@@ -52,7 +52,7 @@ export function parsePatchLintFileSizeThresholds(raw) {
         const merged = { ...DEFAULT_FILE_SIZE_THRESHOLDS[tier], ...parsed };
         if (merged.notice > merged.warning || merged.warning > merged.error) {
             throw new ConfigError(`Config field "patchLint.fileSizeThresholds.${tier}" must satisfy notice <= warning <= error ` +
-                `(resolved: ${String(merged.notice)}/${String(merged.warning)}/${String(merged.error)})`);
+                `(resolved: ${merged.notice}/${merged.warning}/${merged.error})`);
         }
         out[tier] = parsed;
     }

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

@@ -2,6 +2,6 @@
  * Validation helpers for `fireforge.json#patchPolicy`.
  */
 import type { PatchPolicyConfig } from '../types/config.js';
-import { parseObject } from '../utils/parse.js';
+import { type ParsedRecord } from '../utils/parse.js';
 /** Parses and validates the optional patch policy config block. */
-export declare function parsePatchPolicyBlock(rec: ReturnType<typeof parseObject>): PatchPolicyConfig;
+export declare function parsePatchPolicyBlock(rec: ParsedRecord): PatchPolicyConfig;

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

@@ -108,7 +108,7 @@ function parsePatchPolicyReservedRange(raw, label) {
     return {
         from,
         to,
-        allowed: allowedRaw.map((entry, index) => parseReservedAllowedPatch(entry, `${label}.allowed[${String(index)}]`)),
+        allowed: allowedRaw.map((entry, index) => parseReservedAllowedPatch(entry, `${label}.allowed[${index}]`)),
     };
 }
 function assertPolicyRangesDoNotOverlap(ranges, label) {
@@ -160,14 +160,14 @@ export function parsePatchPolicyBlock(rec) {
     if (!Array.isArray(rangesRaw) || rangesRaw.length === 0) {
         throw new ConfigError('Config field "patchPolicy.ranges" must be a non-empty array');
     }
-    out.ranges = rangesRaw.map((entry, index) => parsePatchPolicyRange(entry, `patchPolicy.ranges[${String(index)}]`));
+    out.ranges = rangesRaw.map((entry, index) => parsePatchPolicyRange(entry, `patchPolicy.ranges[${index}]`));
     assertPolicyRangesDoNotOverlap(out.ranges, 'patchPolicy.ranges');
     const reservedRangesRaw = rec.raw('reservedRanges');
     if (reservedRangesRaw !== undefined) {
         if (!Array.isArray(reservedRangesRaw)) {
             throw new ConfigError('Config field "patchPolicy.reservedRanges" must be an array');
         }
-        out.reservedRanges = reservedRangesRaw.map((entry, index) => parsePatchPolicyReservedRange(entry, `patchPolicy.reservedRanges[${String(index)}]`));
+        out.reservedRanges = reservedRangesRaw.map((entry, index) => parsePatchPolicyReservedRange(entry, `patchPolicy.reservedRanges[${index}]`));
         assertPolicyRangesDoNotOverlap(out.reservedRanges, 'patchPolicy.reservedRanges');
     }
     return out;

package/dist/src/core/config-validate-test-toolchains.d.ts

@@ -1,6 +1,6 @@
 import type { FireForgeConfig } from '../types/config.js';
-import { parseObject } from '../utils/parse.js';
-type ConfigRecord = ReturnType<typeof parseObject>;
+import type { ParsedRecord } from '../utils/parse.js';
+type ConfigRecord = ParsedRecord;
 /** Parses the optional `test` block. */
 export declare function parseTestBlock(rec: ConfigRecord, config: FireForgeConfig): void;
 /** Parses optional project-specific external toolchain doctor probes. */

package/dist/src/core/config-validate-test-toolchains.js

@@ -1,6 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { ConfigError } from '../errors/config.js';
-import { parseObject } from '../utils/parse.js';
 import { isContainedRelativePath } from '../utils/paths.js';
 import { isObject } from '../utils/validation.js';
 function optionalConfigString(rec, key, label) {
@@ -58,16 +57,16 @@ export function parseExternalToolchainsBlock(rec, config) {
     }
     config.externalToolchains = raw.map((entry, index) => {
         if (!isObject(entry)) {
-            throw new ConfigError(`Config field "externalToolchains[${String(index)}]" must be an object`);
+            throw new ConfigError(`Config field "externalToolchains[${index}]" must be an object`);
         }
         const item = entry;
         const name = item['name'];
         if (typeof name !== 'string' || name.trim() === '') {
-            throw new ConfigError(`Config field "externalToolchains[${String(index)}].name" must be a non-empty string`);
+            throw new ConfigError(`Config field "externalToolchains[${index}].name" must be a non-empty string`);
         }
         const tools = item['tools'];
         if (!Array.isArray(tools) || tools.length === 0) {
-            throw new ConfigError(`Config field "externalToolchains[${String(index)}].tools" must be a non-empty array`);
+            throw new ConfigError(`Config field "externalToolchains[${index}].tools" must be a non-empty array`);
         }
         return {
             name,
@@ -76,7 +75,7 @@ export function parseExternalToolchainsBlock(rec, config) {
     });
 }
 function parseExternalToolRequirement(tool, index, toolIndex) {
-    const label = `externalToolchains[${String(index)}].tools[${String(toolIndex)}]`;
+    const label = `externalToolchains[${index}].tools[${toolIndex}]`;
     if (!isObject(tool)) {
         throw new ConfigError(`Config field "${label}" must be an object`);
     }

package/dist/src/core/config-validate.js

@@ -8,6 +8,7 @@ import { parseObject } from '../utils/parse.js';
 import { isContainedRelativePath, isExplicitAbsolutePath } from '../utils/paths.js';
 import { describeProductVersionIncompatibility, FIREFOX_PRODUCTS, isObject, isValidAppId, isValidFirefoxCandidate, isValidFirefoxProduct, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, } from '../utils/validation.js';
 import { SUPPORTED_CONFIG_ROOT_KEYS } from './config-paths.js';
+import { parseBuildAuditConfig } from './config-validate-build-audit.js';
 import { parsePatchLintFileSizeThresholds } from './config-validate-file-size.js';
 import { parsePatchPolicyBlock } from './config-validate-patch-policy.js';
 import { parseExternalToolchainsBlock, parseTestBlock } from './config-validate-test-toolchains.js';
@@ -20,7 +21,7 @@ import { parseExternalToolchainsBlock, parseTestBlock } from './config-validate-
 function parseIdentityFields(rec) {
     // Empty strings would technically pass the
     // typeof-check below but are never valid for any of these identifier
-    // fields — rejecting them here prevents downstream code (Firefox build,
+    // fields. Rejecting them here prevents downstream code (Firefox build,
     // launcher binary lookup, AppID assertions) from failing with confusing
     // errors much later.
     const name = requireConfigString(rec, 'name');
@@ -54,7 +55,8 @@ function parseIdentityFields(rec) {
 /**
  * Parses and validates the required `firefox` block: version shape,
  * product allowlist, product/version cross-compatibility, and the
- * optional sha256 digest (normalized to lowercase).
+ * optional sha256 digest (normalized to lowercase), optional
+ * `allowUnverifiedDownload` opt-out, optional candidate directory.
  */
 function parseFirefoxBlock(rec) {
     let firefoxRec;
@@ -70,7 +72,7 @@ function parseFirefoxBlock(rec) {
     }
     const firefoxProduct = requireConfigString(firefoxRec, 'product', 'firefox.product');
     // Uses the shared guard rather than a fourth copy of the member list. This
-    // is the fireforge.json READ path: a product added to the union but not to
+    // is the fireforge.json read path: a product added to the union but not to
     // the copy that used to live here would have been silently rejected from
     // every project config.
     if (!isValidFirefoxProduct(firefoxProduct)) {
@@ -85,6 +87,10 @@ function parseFirefoxBlock(rec) {
     if (firefoxSha256 !== undefined && !/^[a-f0-9]{64}$/i.test(firefoxSha256)) {
         throw new ConfigError('Config field "firefox.sha256" must be a 64-character SHA-256 hex digest');
     }
+    const allowUnverifiedDownload = firefoxRec.raw('allowUnverifiedDownload');
+    if (allowUnverifiedDownload !== undefined && typeof allowUnverifiedDownload !== 'boolean') {
+        throw new ConfigError('Config field "firefox.allowUnverifiedDownload" must be a boolean');
+    }
     const firefoxCandidate = optionalConfigString(firefoxRec, 'candidate', 'firefox.candidate');
     if (firefoxCandidate !== undefined && !isValidFirefoxCandidate(firefoxCandidate)) {
         throw new ConfigError('Config field "firefox.candidate" must look like "buildN" (e.g. "build2")');
@@ -93,6 +99,7 @@ function parseFirefoxBlock(rec) {
         version: firefoxVersion,
         product: firefoxProduct,
         ...(firefoxSha256 !== undefined ? { sha256: firefoxSha256.toLowerCase() } : {}),
+        ...(allowUnverifiedDownload !== undefined ? { allowUnverifiedDownload } : {}),
         ...(firefoxCandidate !== undefined ? { candidate: firefoxCandidate } : {}),
     };
 }
@@ -155,11 +162,15 @@ export function validateConfig(data) {
     const firefox = parseFirefoxBlock(rec);
     const config = { ...identity, firefox };
     parseBuildBlock(rec, config);
+    const buildAuditRaw = rec.raw('buildAudit');
+    if (buildAuditRaw !== undefined) {
+        config.buildAudit = parseBuildAuditConfig(buildAuditRaw);
+    }
     parseTestBlock(rec, config);
     parseExternalToolchainsBlock(rec, config);
     parseWireBlock(rec, config);
     parseLicenseField(rec, config);
-    // Marker comment — appended to lines FireForge writes into upstream files.
+    // Marker comment, appended to lines FireForge writes into upstream files.
     const markerComment = parseMarkerComment(rec.raw('markerComment'));
     if (markerComment !== undefined) {
         config.markerComment = markerComment;
@@ -174,7 +185,7 @@ export function validateConfig(data) {
     if (patchPolicyRec) {
         config.patchPolicy = parsePatchPolicyBlock(patchPolicyRec);
     }
-    // Typecheck (top-level, distinct from patchLint — see TypecheckConfig docs).
+    // Typecheck (top-level, distinct from patchLint). See TypecheckConfig docs.
     const typecheckRec = optionalConfigObject(rec, 'typecheck');
     if (typecheckRec) {
         config.typecheck = parseTypecheckBlock(typecheckRec);
@@ -389,10 +400,9 @@ function parsePatchLintBlock(rec) {
  * file. Shared between `patchLint.checkJsExtraShim` and
  * `typecheck.extraShim` so both fields reject the same absolute-path /
  * traversal / empty-string inputs with consistent error messages. The
- * file's existence is intentionally not checked here — that lives at
- * the engine layer where a missing file produces a typed runtime error
- * pointing at the actual command, rather than blocking config reads
- * for unrelated commands.
+ * file's existence is not checked here. That lives at the engine layer,
+ * where a missing file produces a typed runtime error pointing at the
+ * actual command, rather than blocking config reads for unrelated commands.
  */
 function parseShimPath(raw, label) {
     if (typeof raw !== 'string' || raw.trim() === '') {
@@ -406,7 +416,7 @@ function parseShimPath(raw, label) {
 /**
  * Validates the optional top-level `typecheck` block. Empty `projects`
  * is rejected because a silent no-op for `fireforge typecheck` is a
- * footgun — operators set the block expecting it to do something. Each
+ * footgun, since operators set the block expecting it to do something. Each
  * project path must be a contained relative path so `--project` / CLI
  * scripts can't escape the project root.
  */
@@ -425,10 +435,10 @@ function parseTypecheckBlock(rec) {
     for (let i = 0; i < projectsRaw.length; i++) {
         const entry = projectsRaw[i];
         if (typeof entry !== 'string' || entry.trim() === '') {
-            throw new ConfigError(`Config field "typecheck.projects[${String(i)}]" must be a non-empty string`);
+            throw new ConfigError(`Config field "typecheck.projects[${i}]" must be a non-empty string`);
         }
         if (!isContainedRelativePath(entry)) {
-            throw new ConfigError(`Config field "typecheck.projects[${String(i)}]" must be a project-relative path`);
+            throw new ConfigError(`Config field "typecheck.projects[${i}]" must be a project-relative path`);
         }
         projects.push(entry);
     }

package/dist/src/core/config.d.ts

@@ -1,17 +1,17 @@
 /**
- * Project configuration — barrel module.
+ * Project configuration barrel module.
  *
  * Re-exports from focused sub-modules:
- *   config-paths.ts    — constants and project path derivation
- *   config-validate.ts — fireforge.json schema validation
- *   config-mutate.ts   — immutable config mutation
- *   config-state.ts    — state file management
+ *   config-paths.ts:    constants and project path derivation
+ *   config-validate.ts: fireforge.json schema validation
+ *   config-mutate.ts:   immutable config mutation
+ *   config-state.ts:    state file management
  */
 import type { FireForgeConfig } from '../types/config.js';
 import type { JsonObject } from '../types/json.js';
 export { mutateConfig } from './config-mutate.js';
-export { CONFIG_FILENAME, FIREFORGE_DIR, getProjectPaths, STATE_FILENAME, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
-export { loadState, saveState, updateState } from './config-state.js';
+export { FIREFORGE_DIR, getProjectPaths, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
+export { loadState, updateState } from './config-state.js';
 export { validateConfig } from './config-validate.js';
 /**
  * Checks if a fireforge.json exists in the given directory.
@@ -28,12 +28,12 @@ export declare function configExists(root: string): Promise<boolean>;
 export declare function loadConfig(root: string): Promise<FireForgeConfig>;
 /**
  * Reads the raw `fireforge.json` document without running it through
- * {@link validateConfig}. Returns every persisted key — including keys
+ * {@link validateConfig}. Returns every persisted key, including keys
  * written via `fireforge config <key> --force` that `validateConfig`
  * would strip from the typed result.
  *
  * Callers that need the validated, typed shape must still use
- * {@link loadConfig}; this helper exists specifically for the `config`
+ * {@link loadConfig}. This helper exists specifically for the `config`
  * read path so `fireforge config <key>` can surface keys the write path
  * accepted under `--force`.
  *
@@ -67,9 +67,9 @@ export declare function writeConfigDocument(root: string, config: FireForgeConfi
  * Runs an operation while holding a sidecar lock on `fireforge.json`.
  *
  * Two concurrent `fireforge config <key> <value>` invocations each run
- * load → mutate → writeJson against the same document; without this lock the
- * second rename lands after the first and silently drops the first writer's
- * key, with both commands exiting 0.
+ * load → mutate → writeJson against the same document. Without this lock
+ * the second rename lands after the first and silently drops the first
+ * writer's key, with both commands exiting 0.
  *
  * Reads (`loadConfig`, `loadRawConfigDocument`) stay lock-free: writers
  * always use `writeJson`'s atomic temp-file + rename, so a reader observes