@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -121,6 +121,105 @@ function assertPolicyRangesDoNotOverlap(ranges, label) {
         }
     }
 }
+function parseNonEmptyString(raw, label) {
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        throw new ConfigError(`Config field "${label}" must be a non-empty string`);
+    }
+    return raw;
+}
+function parseGlobList(raw, label) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new ConfigError(`Config field "${label}" must be a non-empty array of path globs`);
+    }
+    return raw.map((entry, index) => parseNonEmptyString(entry, `${label}[${index}]`));
+}
+function parseUpstreamAllowEntry(raw, label, defaultMarker) {
+    if (typeof raw === 'string')
+        return parseNonEmptyString(raw, label);
+    let rec;
+    try {
+        rec = parseObject(raw, label);
+    }
+    catch {
+        throw new ConfigError(`Config field "${label}" must be a path glob or an object`);
+    }
+    const entry = {
+        path: parseNonEmptyString(rec.raw('path'), `${label}.path`),
+    };
+    const addOnly = rec.raw('addOnly');
+    if (addOnly !== undefined) {
+        if (typeof addOnly !== 'boolean') {
+            throw new ConfigError(`Config field "${label}.addOnly" must be a boolean`);
+        }
+        entry.addOnly = addOnly;
+    }
+    const marker = rec.raw('marker');
+    if (marker !== undefined)
+        entry.marker = parseNonEmptyString(marker, `${label}.marker`);
+    if (entry.addOnly === true && entry.marker === undefined && defaultMarker === undefined) {
+        throw new ConfigError(`Config field "${label}" sets addOnly but no marker: set "${label}.marker" or "patchPolicy.addOnlyMarker"`);
+    }
+    return entry;
+}
+function parseScopeRule(raw, label) {
+    let rec;
+    try {
+        rec = parseObject(raw, label);
+    }
+    catch {
+        throw new ConfigError(`Config field "${label}" must be an object`);
+    }
+    const rule = { files: parseGlobList(rec.raw('files'), `${label}.files`) };
+    const category = rec.raw('category');
+    if (category !== undefined) {
+        rule.category = parsePatchPolicyCategory(category, `${label}.category`);
+    }
+    const filenamePattern = optionalConfigString(rec, 'filenamePattern', `${label}.filenamePattern`);
+    if (filenamePattern !== undefined) {
+        try {
+            new RegExp(filenamePattern);
+        }
+        catch (error) {
+            throw new ConfigError(`Config field "${label}.filenamePattern" must be a valid regular expression: ${toError(error).message}`);
+        }
+        rule.filenamePattern = filenamePattern;
+    }
+    if (rule.category === undefined && rule.filenamePattern === undefined) {
+        throw new ConfigError(`Config field "${label}" must set "category" or "filenamePattern" to select the patches it scopes`);
+    }
+    return rule;
+}
+/**
+ * Parses the registration-only policy fields: `upstreamAllowlist`,
+ * `addOnlyMarker`, `scopeRules` and `verifyDocumentPaths`. All opt-in.
+ */
+function parsePatchPolicyContentRules(rec, out) {
+    const addOnlyMarker = rec.raw('addOnlyMarker');
+    if (addOnlyMarker !== undefined) {
+        out.addOnlyMarker = parseNonEmptyString(addOnlyMarker, 'patchPolicy.addOnlyMarker');
+    }
+    const allowlist = rec.raw('upstreamAllowlist');
+    if (allowlist !== undefined) {
+        if (!Array.isArray(allowlist)) {
+            throw new ConfigError('Config field "patchPolicy.upstreamAllowlist" must be an array');
+        }
+        out.upstreamAllowlist = allowlist.map((entry, index) => parseUpstreamAllowEntry(entry, `patchPolicy.upstreamAllowlist[${index}]`, out.addOnlyMarker));
+    }
+    const scopeRules = rec.raw('scopeRules');
+    if (scopeRules !== undefined) {
+        if (!Array.isArray(scopeRules)) {
+            throw new ConfigError('Config field "patchPolicy.scopeRules" must be an array');
+        }
+        out.scopeRules = scopeRules.map((entry, index) => parseScopeRule(entry, `patchPolicy.scopeRules[${index}]`));
+    }
+    const verifyDocumentPaths = rec.raw('verifyDocumentPaths');
+    if (verifyDocumentPaths !== undefined) {
+        if (typeof verifyDocumentPaths !== 'boolean') {
+            throw new ConfigError('Config field "patchPolicy.verifyDocumentPaths" must be a boolean');
+        }
+        out.verifyDocumentPaths = verifyDocumentPaths;
+    }
+}
 /** Parses and validates the optional patch policy config block. */
 export function parsePatchPolicyBlock(rec) {
     const out = { ranges: [] };
@@ -170,5 +269,6 @@ export function parsePatchPolicyBlock(rec) {
         out.reservedRanges = reservedRangesRaw.map((entry, index) => parsePatchPolicyReservedRange(entry, `patchPolicy.reservedRanges[${index}]`));
         assertPolicyRangesDoNotOverlap(out.reservedRanges, 'patchPolicy.reservedRanges');
     }
+    parsePatchPolicyContentRules(rec, out);
     return out;
 }

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

@@ -52,6 +52,27 @@ export function parseTestBlock(rec, config) {
         }
         out.reapOrphans = reapOrphans;
     }
+    const mochitestPorts = testRec.raw('mochitestPorts');
+    if (mochitestPorts !== undefined) {
+        if (mochitestPorts !== 'fixed' && mochitestPorts !== 'auto') {
+            throw new ConfigError('Config field "test.mochitestPorts" must be "fixed" or "auto"');
+        }
+        out.mochitestPorts = mochitestPorts;
+    }
+    const lockMode = testRec.raw('lockMode');
+    if (lockMode !== undefined) {
+        if (lockMode !== 'exclusive' && lockMode !== 'shared') {
+            throw new ConfigError('Config field "test.lockMode" must be "exclusive" or "shared"');
+        }
+        out.lockMode = lockMode;
+    }
+    const furnaceApply = testRec.raw('furnaceApply');
+    if (furnaceApply !== undefined) {
+        if (furnaceApply !== 'all' && furnaceApply !== 'reached' && furnaceApply !== 'none') {
+            throw new ConfigError('Config field "test.furnaceApply" must be "all", "reached" or "none"');
+        }
+        out.furnaceApply = furnaceApply;
+    }
     config.test = out;
 }
 /** Parses optional project-specific external toolchain doctor probes. */

package/dist/src/core/config-validate-token-scales.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Validation for `fireforge.json#patchLint.tokenScales`.
+ *
+ * Unknown keys are refused: a misspelt `allowInCalc` or `minFiles` would
+ * otherwise loosen or drop a scale without a word.
+ */
+import type { PatchLintTokenScale } from '../types/config.js';
+/** Parses and validates `patchLint.tokenScales`. */
+export declare function parsePatchLintTokenScales(raw: unknown): PatchLintTokenScale[];

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

@@ -0,0 +1,92 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Validation for `fireforge.json#patchLint.tokenScales`.
+ *
+ * Unknown keys are refused: a misspelt `allowInCalc` or `minFiles` would
+ * otherwise loosen or drop a scale without a word.
+ */
+import { ConfigError } from '../errors/config.js';
+import { parseObject } from '../utils/parse.js';
+const SCALE_KEYS = [
+    'properties',
+    'prefix',
+    'allowLiterals',
+    'allow',
+    'allowInCalc',
+    'offsetCap',
+    'exclude',
+    'minFiles',
+];
+const PREFIX_PATTERN = /^--[\w-]+$/;
+function parseNames(raw, label, required) {
+    if (raw === undefined && !required)
+        return undefined;
+    if (!Array.isArray(raw) ||
+        (required && raw.length === 0) ||
+        raw.some((value) => typeof value !== 'string' || value.trim() === '')) {
+        throw new ConfigError(`Config field "${label}" must be ${required ? 'a non-empty' : 'an'} array of non-empty strings`);
+    }
+    return raw;
+}
+function parsePrefix(raw, label) {
+    const prefixes = Array.isArray(raw) ? raw : [raw];
+    if (prefixes.length === 0 ||
+        prefixes.some((prefix) => typeof prefix !== 'string' || !PREFIX_PATTERN.test(prefix))) {
+        throw new ConfigError(`Config field "${label}.prefix" must be a custom-property prefix such as "--mybrowser-space-", or a non-empty list of them`);
+    }
+    return Array.isArray(raw) ? prefixes : raw;
+}
+function parseNumber(raw, label, integer) {
+    const valid = typeof raw === 'number' && Number.isFinite(raw) && (integer ? Number.isInteger(raw) : true);
+    if (!valid || raw < (integer ? 1 : 0)) {
+        throw new ConfigError(`Config field "${label}" must be ${integer ? 'a positive integer' : 'a non-negative number'}`);
+    }
+    return raw;
+}
+function parseTokenScale(raw, label) {
+    let rec;
+    try {
+        rec = parseObject(raw, label);
+    }
+    catch {
+        throw new ConfigError(`Config field "${label}" must be an object`);
+    }
+    for (const key of Object.keys(raw)) {
+        if (!SCALE_KEYS.includes(key)) {
+            throw new ConfigError(`Config field "${label}" has unknown key "${key}"`);
+        }
+    }
+    const properties = parseNames(rec.raw('properties'), `${label}.properties`, true) ?? [];
+    const scale = { properties, prefix: parsePrefix(rec.raw('prefix'), label) };
+    const allowLiterals = parseNames(rec.raw('allowLiterals'), `${label}.allowLiterals`, false);
+    if (allowLiterals !== undefined)
+        scale.allowLiterals = allowLiterals;
+    const allow = parseNames(rec.raw('allow'), `${label}.allow`, false);
+    if (allow !== undefined) {
+        const malformed = allow.find((name) => !name.startsWith('--'));
+        if (malformed !== undefined) {
+            throw new ConfigError(`Config field "${label}.allow" entries must be custom-property names starting with "--" (got "${malformed}")`);
+        }
+        scale.allow = allow;
+    }
+    const allowInCalc = parseNames(rec.raw('allowInCalc'), `${label}.allowInCalc`, false);
+    if (allowInCalc !== undefined)
+        scale.allowInCalc = allowInCalc;
+    const offsetCap = rec.raw('offsetCap');
+    if (offsetCap !== undefined)
+        scale.offsetCap = parseNumber(offsetCap, `${label}.offsetCap`, false);
+    const exclude = parseNames(rec.raw('exclude'), `${label}.exclude`, false);
+    if (exclude !== undefined)
+        scale.exclude = exclude;
+    const minFiles = rec.raw('minFiles');
+    if (minFiles !== undefined)
+        scale.minFiles = parseNumber(minFiles, `${label}.minFiles`, true);
+    return scale;
+}
+/** Parses and validates `patchLint.tokenScales`. */
+export function parsePatchLintTokenScales(raw) {
+    if (!Array.isArray(raw)) {
+        throw new ConfigError('Config field "patchLint.tokenScales" must be an array');
+    }
+    return raw.map((entry, index) => parseTokenScale(entry, `patchLint.tokenScales[${index}]`));
+}

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

@@ -9,9 +9,12 @@ import { isContainedRelativePath, isExplicitAbsolutePath } from '../utils/paths.
 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 { parseCheckConfig } from './config-validate-check.js';
+import { parsePatchLintSizeFields } from './config-validate-file-size.js';
+import { parseHistoryBlock } from './config-validate-history.js';
 import { parsePatchPolicyBlock } from './config-validate-patch-policy.js';
 import { parseExternalToolchainsBlock, parseTestBlock } from './config-validate-test-toolchains.js';
+import { parsePatchLintTokenScales } from './config-validate-token-scales.js';
 /**
  * Parses and validates the four required identity fields (`name`,
  * `vendor`, `appId`, `binaryName`): all non-empty strings, with
@@ -167,6 +170,7 @@ export function validateConfig(data) {
         config.buildAudit = parseBuildAuditConfig(buildAuditRaw);
     }
     parseTestBlock(rec, config);
+    parseHistoryBlock(rec, config);
     parseExternalToolchainsBlock(rec, config);
     parseWireBlock(rec, config);
     parseLicenseField(rec, config);
@@ -190,6 +194,11 @@ export function validateConfig(data) {
     if (typecheckRec) {
         config.typecheck = parseTypecheckBlock(typecheckRec);
     }
+    // `fireforge check` policy and project steps.
+    const checkRaw = rec.raw('check');
+    if (checkRaw !== undefined) {
+        config.check = parseCheckConfig(checkRaw);
+    }
     // Warn on unknown root keys
     const knownRootKeys = new Set(SUPPORTED_CONFIG_ROOT_KEYS);
     for (const key of rec.keys()) {
@@ -372,10 +381,7 @@ function parsePatchLintBlock(rec) {
         }
         out.rawColorAllowlist = rawColorAllowlist;
     }
-    const fileSizeThresholds = rec.raw('fileSizeThresholds');
-    if (fileSizeThresholds !== undefined) {
-        out.fileSizeThresholds = parsePatchLintFileSizeThresholds(fileSizeThresholds);
-    }
+    Object.assign(out, parsePatchLintSizeFields((key) => rec.raw(key)));
     const forwardRegistration = rec.raw('forwardRegistration');
     if (forwardRegistration !== undefined) {
         if (forwardRegistration !== 'support-files' && forwardRegistration !== 'extended') {
@@ -383,6 +389,9 @@ function parsePatchLintBlock(rec) {
         }
         out.forwardRegistration = forwardRegistration;
     }
+    const tokenScales = rec.raw('tokenScales');
+    if (tokenScales !== undefined)
+        out.tokenScales = parsePatchLintTokenScales(tokenScales);
     for (const key of PATCH_LINT_SEVERITY_GATE_KEYS) {
         const gate = parseSeverityGate(rec.raw(key), `patchLint.${key}`);
         if (gate !== undefined)
@@ -462,6 +471,12 @@ function parseTypecheckBlock(rec) {
     if (undefinedIdentifiers !== undefined) {
         out.undefinedIdentifiers = undefinedIdentifiers;
     }
+    const litTypes = rec.raw('litTypes');
+    if (litTypes !== undefined && typeof litTypes !== 'boolean') {
+        throw new ConfigError('Config field "typecheck.litTypes" must be a boolean');
+    }
+    if (litTypes !== undefined)
+        out.litTypes = litTypes;
     return out;
 }
 /**

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

@@ -54,6 +54,11 @@ export declare function writeConfig(root: string, config: FireForgeConfig): Prom
  * This is used by CLI `config --force`, where callers may intentionally write
  * keys or value shapes outside the validated FireForgeConfig schema.
  *
+ * An existing file is edited in place: only the values that differ from the
+ * document on disk are rewritten, so a one-key change keeps the file's
+ * formatting (compact objects and arrays, indentation, key order) and stays
+ * a one-hunk diff. A missing or unparseable file is written in full.
+ *
  * Individual writes are atomic via {@link writeJson} (temp file + rename),
  * but atomicity alone does not prevent lost updates across concurrent
  * writers: each writer reads an old copy, mutates its own in-memory view,

package/dist/src/core/config.js

@@ -16,6 +16,7 @@ import { isObject } from '../utils/validation.js';
 import { getProjectPaths } from './config-paths.js';
 import { validateConfig } from './config-validate.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
+import { rewriteJsonPreservingFormat } from './json-preserving-edit.js';
 // ---- re-exports ----
 export { mutateConfig } from './config-mutate.js';
 export { FIREFORGE_DIR, getProjectPaths, SUPPORTED_CONFIG_PATHS, SUPPORTED_CONFIG_ROOT_KEYS, } from './config-paths.js';
@@ -109,6 +110,11 @@ export async function writeConfig(root, config) {
  * This is used by CLI `config --force`, where callers may intentionally write
  * keys or value shapes outside the validated FireForgeConfig schema.
  *
+ * An existing file is edited in place: only the values that differ from the
+ * document on disk are rewritten, so a one-key change keeps the file's
+ * formatting (compact objects and arrays, indentation, key order) and stays
+ * a one-hunk diff. A missing or unparseable file is written in full.
+ *
  * Individual writes are atomic via {@link writeJson} (temp file + rename),
  * but atomicity alone does not prevent lost updates across concurrent
  * writers: each writer reads an old copy, mutates its own in-memory view,
@@ -119,6 +125,16 @@ export async function writeConfig(root, config) {
  */
 export async function writeConfigDocument(root, config) {
     const paths = getProjectPaths(root);
+    if (await fsUtils.pathExists(paths.config)) {
+        const current = await fsUtils.readText(paths.config);
+        // `FireForgeConfig` is plain parsed-config data, so it is a JSON object.
+        const edited = rewriteJsonPreservingFormat(current, config);
+        if (edited !== undefined) {
+            if (edited !== current)
+                await fsUtils.writeText(paths.config, edited);
+            return;
+        }
+    }
     await fsUtils.writeJson(paths.config, config);
 }
 /**

package/dist/src/core/coverage-dispatch.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Dispatch-time half of per-path coverage. A scoped build that followed a
+ * full build carries the full build's anchor forward instead of collapsing
+ * the claim to its own paths. A requested path outside the scoped list is
+ * then still covered while its own staging inputs are unchanged against
+ * that anchor, and a refusal names the inputs that did change.
+ */
+import type { BuildBaseline } from './build-baseline-types.js';
+/** A requested path no recorded claim covers, with the inputs that explain it. */
+export interface UncoveredRequest {
+    path: string;
+    /** Staging inputs changed since the carried full build. Empty when unknown. */
+    changed: string[];
+}
+/**
+ * Re-checks the paths the scoped list does not cover against the carried
+ * full-build anchor. Returns the paths that stay uncovered.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param baseline - Last successful build's baseline
+ * @param uncovered - Request paths outside the scoped list
+ * @param fullSuite - The sentinel standing for a path-less (full-suite) request
+ */
+export declare function filterByCarriedFullCoverage(engineDir: string, baseline: BuildBaseline | undefined, uncovered: readonly string[], fullSuite: string): Promise<UncoveredRequest[]>;

package/dist/src/core/coverage-dispatch.js

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Dispatch-time half of per-path coverage. A scoped build that followed a
+ * full build carries the full build's anchor forward instead of collapsing
+ * the claim to its own paths. A requested path outside the scoped list is
+ * then still covered while its own staging inputs are unchanged against
+ * that anchor, and a refusal names the inputs that did change.
+ */
+import { toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
+import { collectStagingInputs, findChangedInputs, hashEngineFile, readEngineContentState, } from './coverage-records.js';
+/**
+ * Re-checks the paths the scoped list does not cover against the carried
+ * full-build anchor. Returns the paths that stay uncovered.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param baseline - Last successful build's baseline
+ * @param uncovered - Request paths outside the scoped list
+ * @param fullSuite - The sentinel standing for a path-less (full-suite) request
+ */
+export async function filterByCarriedFullCoverage(engineDir, baseline, uncovered, fullSuite) {
+    const unresolved = uncovered.map((path) => ({ path, changed: [] }));
+    const anchor = baseline?.fullCoverageAnchor;
+    if (anchor === undefined || uncovered.length === 0)
+        return unresolved;
+    if ((await hashEngineFile(engineDir, 'mozconfig')) !== anchor.mozconfigHash)
+        return unresolved;
+    let state;
+    try {
+        state = await readEngineContentState(engineDir);
+    }
+    catch (error) {
+        verbose(`Coverage check: engine state unreadable — ${toError(error).message}`);
+        return unresolved;
+    }
+    const remaining = [];
+    for (const path of uncovered) {
+        const inputs = path === fullSuite ? undefined : await collectStagingInputs(engineDir, path);
+        const changed = await findChangedInputs(state, anchor, inputs);
+        if (changed === undefined || changed.length > 0)
+            remaining.push({ path, changed: changed ?? [] });
+    }
+    return remaining;
+}

package/dist/src/core/coverage-extend.d.ts

@@ -1,62 +1,87 @@
 /**
- * Retains prior test staging only when HEAD, mozconfig and every recorded
- * dirty input outside the newly rebuilt scope are unchanged. Complete
- * input fingerprints are required: packageable-only legacy records cannot
+ * Decides which earlier packaging claims a scoped `fireforge test --build`
+ * keeps. Retention is per staged path (see `coverage-records.ts`): an
+ * earlier path stays covered while its own staging inputs are unchanged,
+ * whatever moved elsewhere in the engine, and a full claim narrows to
+ * per-path checks once something outside the new scope changed instead of
+ * collapsing to this build's paths. `--extend-coverage` turns any drop into
+ * a refusal before the build.
+ *
+ * Fingerprints must be complete: a legacy packageable-only record cannot
  * prove that a test fixture or manifest still matches its staged copy.
  */
-import { type BuildBaseline, type TestPackagingCoverage } from './build-baseline-types.js';
-/** Why `--extend-coverage` could not union onto the recorded claim. */
-export type ExtendAnchorReason = 'no-baseline' | 'no-fingerprints' | 'no-mozconfig-hash' | 'head-moved' | 'fingerprint-diverged' | 'mozconfig-changed';
-/** Outcome of an anchor check: either extend is sound, or it is refused. */
-export type ExtendAnchorResult = {
-    ok: true;
-} | {
-    ok: false;
-    reason: ExtendAnchorReason;
-    detail: string[];
-};
+import type { BuildBaseline, CoverageAnchor, CoverageRecord, TestPackagingCoverage } from './build-baseline-types.js';
+export { hashEngineFile } from './coverage-records.js';
+/** What a dropped full claim is called in notices and refusals. */
+export declare const FULL_CLAIM_LABEL = "full coverage";
+/** An earlier claim this build cannot keep, and why. */
+export interface DroppedClaim {
+    /** Request path, or {@link FULL_CLAIM_LABEL}. */
+    path: string;
+    /** Staging inputs whose content changed since the claim was staged. */
+    changed: string[];
+    /** Why the claim cannot be verified at all, when no input list explains it. */
+    reason?: string;
+}
+/** What a scoped build keeps of the recorded coverage. */
+export interface CoverageRetentionPlan {
+    /** The previous claim was full and nothing outside this build's scope moved. */
+    keepFull: boolean;
+    /** Earlier per-path records kept, refreshed for this build's paths. */
+    retained: Record<string, CoverageRecord>;
+    /** Full-build anchor carried for dispatch-time per-path checks. */
+    fullAnchor: CoverageAnchor | undefined;
+    /** Changed inputs that narrowed a full claim to per-path checks. */
+    narrowedBy: string[];
+    /** Earlier claims this build cannot keep. */
+    dropped: DroppedClaim[];
+}
+/** The baseline-wide anchor a baseline's own fields describe, when complete. */
+export declare function baselineAnchor(baseline: BuildBaseline): CoverageAnchor | undefined;
 /**
- * Verifies the parts of the anchor knowable before the build runs: a usable
- * previous baseline, an unchanged engine HEAD, and byte-identical content
- * for every path that baseline fingerprinted.
+ * Plans which earlier claims a scoped build over `requested` keeps. Runs
+ * before the build lock, so a refusal costs neither build time nor the
+ * lock. The mozconfig half runs later, via {@link applyMozconfigAnchor}.
+ *
  * @param engineDir - Path to the engine directory
- * @param previousBaseline - Baseline recorded by the previous build
+ * @param previous - Baseline recorded by the previous build
+ * @param requested - Normalized request paths this build packages
  */
-export declare function checkExtendCoverageAnchor(engineDir: string, previousBaseline: BuildBaseline | undefined, rebuiltPaths?: readonly string[]): Promise<ExtendAnchorResult>;
+export declare function planCoverageRetention(engineDir: string, previous: BuildBaseline | undefined, requested: string[]): Promise<CoverageRetentionPlan>;
 /**
- * Verifies the mozconfig half of the anchor. Split from
- * {@link checkExtendCoverageAnchor} because it can only run after
- * `prepareBuildEnvironment` regenerates `engine/mozconfig` (the file this
- * build will configure with), and must still run before mach, so a refusal
- * costs no build time.
+ * Applies the mozconfig half of the anchor: a claim staged under a different
+ * `engine/mozconfig` is dropped. Runs after `prepareBuildEnvironment`
+ * regenerated the file this build configures with, and before mach.
+ *
  * @param engineDir - Path to the engine directory
- * @param previousBaseline - Baseline recorded by the previous build
+ * @param plan - Plan from {@link planCoverageRetention}
  */
-export declare function checkExtendMozconfigAnchor(engineDir: string, previousBaseline: BuildBaseline | undefined): Promise<ExtendAnchorResult>;
+export declare function applyMozconfigAnchor(engineDir: string, plan: CoverageRetentionPlan): Promise<CoverageRetentionPlan>;
+/** Fields a scoped build writes onto its baseline. */
+export interface RecordedCoverage {
+    testPackagingCoverage: TestPackagingCoverage;
+    testCoverageRecords?: Record<string, CoverageRecord>;
+    fullCoverageAnchor?: CoverageAnchor;
+}
 /**
- * Unions the newly built paths onto the recorded claim. A `'full'` claim, or
- * an absent one (which means full), stays `'full'`, since it already covers
- * everything.
+ * The coverage a green scoped build records: `'full'` when the plan kept a
+ * full claim, otherwise this build's paths with fresh records plus every
+ * retained earlier path, and the carried full anchor.
  *
- * @param previous - Coverage recorded by the previous build
+ * @param engineDir - Path to the engine directory
+ * @param plan - Plan after {@link applyMozconfigAnchor}
  * @param requested - Normalized request paths this build packaged
  */
-export declare function unionTestPackagingCoverage(previous: TestPackagingCoverage | undefined, requested: readonly string[]): TestPackagingCoverage;
+export declare function recordScopedCoverage(engineDir: string, plan: CoverageRetentionPlan, requested: string[]): Promise<RecordedCoverage>;
+/** Renders one dropped claim with its cause. */
+export declare function describeDroppedClaim(claim: DroppedClaim): string;
 /**
- * Renders the fail-closed refusal for an anchor check that did not pass.
- * Kept separate from the probes so tests can assert the structured result
- * without matching copy.
- * @param result - Failing result from an anchor check
+ * The notice a scoped build prints about earlier coverage, or undefined
+ * when nothing was dropped or narrowed.
  */
-export declare function formatExtendCoverageRefusal(result: {
-    reason: ExtendAnchorReason;
-    detail: string[];
-}): string;
+export declare function formatCoverageRetentionNotice(plan: CoverageRetentionPlan): string | undefined;
 /**
- * Hex-encoded SHA-256 of an engine-relative file, matching the digest the
- * baseline writer produces. `undefined` on any IO error, which every caller
- * treats as "cannot prove unchanged", i.e. a refusal.
- * @param engineDir - Path to the engine directory
- * @param relPath - Engine-relative POSIX path
+ * The `--extend-coverage` refusal: the flag asks that no earlier claim be
+ * dropped, and the plan would drop some.
  */
-export declare function hashEngineFile(engineDir: string, relPath: string): Promise<string | undefined>;
+export declare function formatExtendCoverageRefusal(dropped: readonly DroppedClaim[]): string;