@hominis/fireforge 0.49.1 → 0.50.0

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;

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

@@ -1,179 +1,234 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * 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 { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { getNodeErrorCode, toError } from '../utils/errors.js';
-import { sha256Hex } from '../utils/hash.js';
+import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';
-import { DELETED_FILE_FINGERPRINT, } from './build-baseline-types.js';
-import { getHead, isMissingHeadError } from './git.js';
-import { git } from './git-base.js';
-import { getUntrackedFiles } from './git-status.js';
+import { collectStagingInputs, createCoverageRecord, findChangedInputs, hashEngineFile, isUnderPath, narrowAnchor, normalizeRequestPath, readEngineContentState, refreshAnchor, } from './coverage-records.js';
+export { hashEngineFile } from './coverage-records.js';
 /** Filename of the generated mozconfig, relative to the engine directory. */
 const MOZCONFIG_FILENAME = 'mozconfig';
-/** How many diverged paths a refusal names before truncating. */
-const MAX_DIVERGED_REPORTED = 5;
+/** How many paths a notice or refusal names before truncating. */
+const MAX_PATHS_REPORTED = 5;
+/** What a dropped full claim is called in notices and refusals. */
+export const FULL_CLAIM_LABEL = 'full coverage';
+const UNVERIFIABLE = 'engine HEAD or the recorded anchor cannot be compared';
+const NO_FINGERPRINTS = 'the record has no complete staging-input fingerprints';
+/** The baseline-wide anchor a baseline's own fields describe, when complete. */
+export function baselineAnchor(baseline) {
+    if (baseline.testInputFingerprints === undefined || baseline.mozconfigHash === undefined) {
+        return undefined;
+    }
+    return {
+        engineHeadSha: baseline.engineHeadSha,
+        mozconfigHash: baseline.mozconfigHash,
+        fingerprints: baseline.testInputFingerprints,
+    };
+}
+function emptyPlan() {
+    return { keepFull: false, retained: {}, fullAnchor: undefined, narrowedBy: [], dropped: [] };
+}
+/** True when a request path in `requested` stages `path` afresh. */
+function rebuiltBy(path, rebuilt) {
+    const normalized = normalizeRequestPath(path);
+    return rebuilt.some((request) => isUnderPath(normalized, request));
+}
+async function planFullClaim(state, previous, requested) {
+    const plan = emptyPlan();
+    const anchor = previous.fullCoverageAnchor ?? baselineAnchor(previous);
+    if (anchor === undefined) {
+        plan.dropped.push({ path: FULL_CLAIM_LABEL, changed: [], reason: NO_FINGERPRINTS });
+        return plan;
+    }
+    const changed = await findChangedInputs(state, anchor, undefined, requested);
+    const refreshed = changed === undefined ? undefined : await refreshAnchor(state, anchor, requested);
+    if (changed === undefined || refreshed === undefined) {
+        plan.dropped.push({ path: FULL_CLAIM_LABEL, changed: [], reason: UNVERIFIABLE });
+        return plan;
+    }
+    plan.keepFull = changed.length === 0;
+    plan.fullAnchor = refreshed;
+    plan.narrowedBy = changed;
+    return plan;
+}
+async function retainRecord(state, previous, path, requested) {
+    let record = previous.testCoverageRecords?.[path];
+    if (record === undefined) {
+        // A path recorded before per-path anchors existed: the baseline-wide
+        // anchor, restricted to the path's own inputs, says the same thing.
+        const anchor = baselineAnchor(previous);
+        if (anchor === undefined)
+            return { path, changed: [], reason: NO_FINGERPRINTS };
+        const inputs = await collectStagingInputs(state.engineDir, path);
+        record = await narrowAnchor(state, anchor, inputs);
+        if (record === undefined)
+            return { path, changed: [], reason: UNVERIFIABLE };
+    }
+    const changed = await findChangedInputs(state, record, record.inputs, requested);
+    if (changed === undefined)
+        return { path, changed: [], reason: UNVERIFIABLE };
+    if (changed.length > 0)
+        return { path, changed };
+    const refreshed = await refreshAnchor(state, record, requested);
+    return refreshed === undefined
+        ? { path, changed: [], reason: UNVERIFIABLE }
+        : { record: refreshed };
+}
 /**
- * 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 async function checkExtendCoverageAnchor(engineDir, previousBaseline, rebuiltPaths = []) {
-    if (previousBaseline === undefined) {
-        return { ok: false, reason: 'no-baseline', detail: [] };
-    }
-    if (previousBaseline.mozconfigHash === undefined) {
-        return { ok: false, reason: 'no-mozconfig-hash', detail: [] };
-    }
-    const recordedFingerprints = previousBaseline.testInputFingerprints;
-    const rebuilt = (file) => rebuiltPaths.some((path) => file === path || file.startsWith(path.replace(/\/$/, '') + '/'));
-    if (recordedFingerprints === undefined) {
-        return { ok: false, reason: 'no-fingerprints', detail: [] };
-    }
-    const currentHead = await readEngineHead(engineDir);
-    if (currentHead === undefined || previousBaseline.engineHeadSha === '') {
-        // An unborn or unreadable HEAD gives nothing to anchor to.
-        return { ok: false, reason: 'head-moved', detail: [] };
+export async function planCoverageRetention(engineDir, previous, requested) {
+    if (previous === undefined)
+        return emptyPlan();
+    const coverage = previous.testPackagingCoverage ?? 'full';
+    const rebuilt = requested.map(normalizeRequestPath).filter((path) => path !== '');
+    let state;
+    try {
+        state = await readEngineContentState(engineDir);
     }
-    if (currentHead !== previousBaseline.engineHeadSha) {
+    catch (error) {
+        verbose(`Coverage retention: engine state unreadable — ${toError(error).message}`);
+        const paths = coverage === 'full' ? [FULL_CLAIM_LABEL] : coverage;
         return {
-            ok: false,
-            reason: 'head-moved',
-            detail: [`recorded ${previousBaseline.engineHeadSha}`, `current ${currentHead}`],
+            ...emptyPlan(),
+            dropped: paths.map((path) => ({ path, changed: [], reason: UNVERIFIABLE })),
         };
     }
-    const diverged = [];
-    for (const [relPath, recordedHash] of Object.entries(recordedFingerprints)) {
-        if (rebuilt(relPath))
-            continue;
-        const liveHash = await hashEngineFile(engineDir, relPath);
-        if (liveHash !== recordedHash)
-            diverged.push(relPath);
-    }
-    // New dirty test inputs are absent from the previous fingerprint map.
-    // They invalidate retained staging too; explicitly rebuilt inputs are safe.
-    if (previousBaseline.testInputFingerprints !== undefined) {
-        const changed = (await git(['diff', '--name-only', 'HEAD'], engineDir)).split('\n');
-        changed.push(...(await getUntrackedFiles(engineDir)));
-        for (const file of changed.filter(Boolean)) {
-            if (file === MOZCONFIG_FILENAME || rebuilt(file) || Object.hasOwn(recordedFingerprints, file))
-                continue;
-            // A retained manifest may stage a shared fixture outside test-named
-            // directories. Without its full dependency graph, refuse conservatively.
-            diverged.push(file);
+    if (coverage === 'full')
+        return planFullClaim(state, previous, rebuilt);
+    const plan = emptyPlan();
+    if (previous.fullCoverageAnchor !== undefined) {
+        plan.fullAnchor = await refreshAnchor(state, previous.fullCoverageAnchor, rebuilt);
+        if (plan.fullAnchor === undefined) {
+            plan.dropped.push({ path: FULL_CLAIM_LABEL, changed: [], reason: UNVERIFIABLE });
         }
     }
-    if (diverged.length > 0) {
-        return { ok: false, reason: 'fingerprint-diverged', detail: diverged.sort() };
+    for (const path of coverage) {
+        if (rebuiltBy(path, rebuilt))
+            continue;
+        const outcome = await retainRecord(state, previous, path, rebuilt);
+        if ('record' in outcome)
+            plan.retained[path] = outcome.record;
+        else
+            plan.dropped.push(outcome);
     }
-    return { ok: true };
+    return plan;
 }
 /**
- * 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 async function checkExtendMozconfigAnchor(engineDir, previousBaseline) {
-    const recorded = previousBaseline?.mozconfigHash;
-    if (recorded === undefined) {
-        return { ok: false, reason: 'no-mozconfig-hash', detail: [] };
-    }
+export async function applyMozconfigAnchor(engineDir, plan) {
     const live = await hashEngineFile(engineDir, MOZCONFIG_FILENAME);
-    if (live === undefined || live !== recorded) {
-        return { ok: false, reason: 'mozconfig-changed', detail: [] };
-    }
-    return { ok: true };
+    const reason = 'engine/mozconfig differs from the build that staged it';
+    const next = { ...plan, retained: {}, dropped: [...plan.dropped] };
+    for (const [path, record] of Object.entries(plan.retained)) {
+        if (live !== undefined && record.mozconfigHash === live)
+            next.retained[path] = record;
+        else
+            next.dropped.push({ path, changed: [], reason });
+    }
+    if (plan.fullAnchor !== undefined &&
+        (live === undefined || plan.fullAnchor.mozconfigHash !== live)) {
+        next.fullAnchor = undefined;
+        next.keepFull = false;
+        next.narrowedBy = [];
+        next.dropped.push({ path: FULL_CLAIM_LABEL, changed: [], reason });
+    }
+    return next;
 }
 /**
- * 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 function unionTestPackagingCoverage(previous, requested) {
-    if (previous === undefined || previous === 'full') {
-        return 'full';
-    }
-    return [...new Set([...previous, ...requested])].sort();
-}
-/**
- * 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
- */
-export function formatExtendCoverageRefusal(result) {
-    const remedy = 'Re-run without --extend-coverage: a plain scoped build REPLACES the coverage claim ' +
-        'with the paths it actually vouches for.';
-    switch (result.reason) {
-        case 'no-baseline':
-            return `--extend-coverage has nothing to extend: no previous build baseline is recorded. ${remedy}`;
-        case 'no-mozconfig-hash':
-            return ('--extend-coverage refused: the recorded baseline predates the mozconfig anchor, so it ' +
-                `cannot be proven that this build configures identically. ${remedy}`);
-        case 'no-fingerprints':
-            return ('--extend-coverage refused: the recorded baseline carries no complete test-input fingerprints, so ' +
-                `the earlier scope's staging inputs cannot be verified unchanged. ${remedy}`);
-        case 'head-moved':
-            return ('--extend-coverage refused: engine HEAD moved since the recorded build ' +
-                `(${result.detail.join(', ') || 'no usable HEAD'}), so the earlier scope's packaging is no ` +
-                `longer anchored. ${remedy}`);
-        case 'fingerprint-diverged':
-            return ('--extend-coverage refused: ' +
-                `${result.detail.length} staging input(s) the recorded build staged have changed ` +
-                `since (${formatDivergedPaths(result.detail)}). Extending would vouch for the earlier scope ` +
-                `while obj-*/_tests/ still holds its stale staging. ${remedy}`);
-        case 'mozconfig-changed':
-            return ('--extend-coverage refused: engine/mozconfig differs from the recorded build (it is ' +
-                'regenerated from configs/*.mozconfig and fireforge.json on every build, so engine HEAD ' +
-                `does not cover it). ${remedy}`);
+export async function recordScopedCoverage(engineDir, plan, requested) {
+    if (plan.keepFull)
+        return { testPackagingCoverage: 'full' };
+    const records = { ...plan.retained };
+    try {
+        const state = await readEngineContentState(engineDir);
+        const mozconfigHash = await hashEngineFile(engineDir, MOZCONFIG_FILENAME);
+        for (const path of requested) {
+            const record = mozconfigHash === undefined
+                ? undefined
+                : await createCoverageRecord(state, path, mozconfigHash);
+            if (record !== undefined)
+                records[path] = record;
+        }
     }
+    catch (error) {
+        verbose(`Coverage records: could not anchor this build's paths — ${toError(error).message}`);
+    }
+    const kept = Object.keys(plan.retained);
+    const coverage = kept.length === 0 ? [...requested] : [...new Set([...kept, ...requested])].sort();
+    return {
+        testPackagingCoverage: coverage,
+        ...(Object.keys(records).length > 0 ? { testCoverageRecords: records } : {}),
+        ...(plan.fullAnchor !== undefined ? { fullCoverageAnchor: plan.fullAnchor } : {}),
+    };
 }
-function formatDivergedPaths(paths) {
-    const head = paths.slice(0, MAX_DIVERGED_REPORTED).join(', ');
-    const extra = paths.length - Math.min(paths.length, MAX_DIVERGED_REPORTED);
+function capList(paths) {
+    const head = paths.slice(0, MAX_PATHS_REPORTED).join(', ');
+    const extra = paths.length - Math.min(paths.length, MAX_PATHS_REPORTED);
     return extra > 0 ? `${head}, … (+${extra} more)` : head;
 }
+/** Renders one dropped claim with its cause. */
+export function describeDroppedClaim(claim) {
+    const cause = claim.changed.length > 0
+        ? `staging inputs changed: ${capList(claim.changed)}`
+        : (claim.reason ?? UNVERIFIABLE);
+    return `${claim.path} (${cause})`;
+}
 /**
- * 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 notice a scoped build prints about earlier coverage, or undefined
+ * when nothing was dropped or narrowed.
  */
-export async function hashEngineFile(engineDir, relPath) {
-    try {
-        const buffer = await readFile(join(engineDir, relPath));
-        return sha256Hex(buffer);
-    }
-    catch (error) {
-        if (getNodeErrorCode(error) === 'ENOENT') {
-            return DELETED_FILE_FINGERPRINT;
-        }
-        verbose(`Extend-coverage anchor: could not hash ${relPath} — ${toError(error).message}`);
-        return undefined;
-    }
+export function formatCoverageRetentionNotice(plan) {
+    const lines = [];
+    if (plan.dropped.length > 0) {
+        const kept = Object.keys(plan.retained);
+        lines.push(`Scoped build drops previous packaging coverage for ${plan.dropped.map(describeDroppedClaim).join('; ')}.` +
+            (kept.length > 0 ? ` Kept: ${capList(kept)}.` : '') +
+            ' Rebuild a dropped path (alone or with this one) before running it without --build.');
+    }
+    if (!plan.keepFull && plan.fullAnchor !== undefined && plan.narrowedBy.length > 0) {
+        lines.push(`Full packaging coverage is now checked per path: ${capList(plan.narrowedBy)} changed outside ` +
+            "this build's scope, so a later run is refused only for paths whose own staging inputs include a changed file.");
+    }
+    return lines.length > 0 ? lines.join('\n') : undefined;
 }
-async function readEngineHead(engineDir) {
-    try {
-        return await getHead(engineDir);
-    }
-    catch (error) {
-        if (isMissingHeadError(error))
-            return undefined;
-        throw error;
-    }
+/**
+ * The `--extend-coverage` refusal: the flag asks that no earlier claim be
+ * dropped, and the plan would drop some.
+ */
+export function formatExtendCoverageRefusal(dropped) {
+    return (`--extend-coverage refused: this build would drop earlier packaging coverage for ` +
+        `${dropped.length} claim(s): ${dropped.map(describeDroppedClaim).join('; ')}. ` +
+        'Extending would vouch for staging that obj-*/_tests/ no longer matches. Rebuild those paths ' +
+        'together with this one, or drop the flag: without it the dropped claims are named and the ' +
+        'rest of the coverage is kept.');
 }

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

@@ -0,0 +1,97 @@
+/**
+ * Per-path packaging-coverage anchors for scoped `fireforge test --build`.
+ *
+ * A scoped build used to carry one claim anchored to the whole engine, so
+ * any edit outside the new scope (a peer's, on a shared engine, nearly
+ * always) replaced it. Each staged request path now carries its own anchor
+ * restricted to its own staging inputs, and a claim is dropped only when
+ * one of those inputs changed.
+ *
+ * The staging inputs of a request path are its manifest directory (the
+ * nearest directory at or above it that holds a test manifest) plus every
+ * path a manifest there names outside that directory (`support-files`,
+ * `head`, `!/`-rooted shared fixtures). Without the full mozbuild graph
+ * that is the closest sound boundary: an edit outside it cannot change
+ * what the harness stages for that path.
+ */
+import { type CoverageAnchor, type CoverageRecord } from './build-baseline-types.js';
+/**
+ * Hex-encoded SHA-256 of an engine-relative file, matching the digest the
+ * baseline writer produces. A missing file hashes to
+ * {@link DELETED_FILE_FINGERPRINT}. `undefined` on any other IO error,
+ * which every caller treats as "cannot prove unchanged".
+ * @param engineDir - Path to the engine directory
+ * @param relPath - Engine-relative POSIX path
+ */
+export declare function hashEngineFile(engineDir: string, relPath: string): Promise<string | undefined>;
+/** True for a test manifest path (by basename). */
+export declare function isTestManifestPath(path: string): boolean;
+/** Normalizes a request path: forward slashes, no `./`, no trailing slash. */
+export declare function normalizeRequestPath(path: string): string;
+/** True when `file` is `prefix` or sits beneath it. The empty prefix is the whole tree. */
+export declare function isUnderPath(file: string, prefix: string): boolean;
+/**
+ * Engine state one coverage decision reads. Shared across every anchor a
+ * decision verifies, so the git probes run once and each file is hashed
+ * once.
+ */
+export interface EngineContentState {
+    engineDir: string;
+    /** Current engine HEAD, or undefined for an unborn branch. */
+    head: string | undefined;
+    /** Engine-relative paths dirty against HEAD (tracked and untracked). */
+    dirty: ReadonlySet<string>;
+    hashes: Map<string, Promise<string | undefined>>;
+    diffs: Map<string, Promise<ReadonlySet<string> | undefined>>;
+}
+/**
+ * Reads HEAD and the dirty set. Throws on a git failure other than an
+ * unborn HEAD: callers treat that as "nothing can be proven unchanged".
+ * @param engineDir - Path to the engine directory
+ */
+export declare function readEngineContentState(engineDir: string): Promise<EngineContentState>;
+/**
+ * Inputs whose live content differs from what the anchor staged, sorted.
+ * Undefined when the anchor cannot be compared, which every caller treats as
+ * "changed".
+ *
+ * @param state - Engine state from {@link readEngineContentState}
+ * @param anchor - The claim's anchor
+ * @param inputs - Staging inputs to compare, or undefined for the whole tree
+ * @param rebuilt - Request paths the current build stages afresh
+ */
+export declare function findChangedInputs(state: EngineContentState, anchor: CoverageAnchor, inputs: readonly string[] | undefined, rebuilt?: readonly string[]): Promise<string[] | undefined>;
+/**
+ * The anchor after the current build restaged `rebuilt`: recorded content
+ * for those paths becomes their live content. Undefined when that content
+ * cannot be read or the anchor cannot be compared.
+ */
+export declare function refreshAnchor<T extends CoverageAnchor>(state: EngineContentState, anchor: T, rebuilt: readonly string[]): Promise<T | undefined>;
+/**
+ * Engine-relative paths a manifest names outside its own directory. Bare
+ * names stay inside it. `!/` and `/` prefixes are engine-root relative, as
+ * in mozbuild manifests. A glob keeps the directory part before its first
+ * wildcard segment.
+ */
+export declare function manifestExternalReferences(manifestPath: string, text: string): string[];
+/**
+ * Staging inputs of one request path. See the module comment.
+ * @param engineDir - Path to the engine directory
+ * @param requestPath - Engine-relative request path (file or directory)
+ */
+export declare function collectStagingInputs(engineDir: string, requestPath: string): Promise<string[]>;
+/**
+ * Records the anchor of a request path this build staged. Undefined when
+ * HEAD is unborn or an input's content cannot be read: the path is still
+ * claimed, and later retention falls back to the baseline-wide anchor.
+ *
+ * @param state - Engine state after the build
+ * @param requestPath - Engine-relative request path
+ * @param mozconfigHash - Hash of the mozconfig the build configured with
+ */
+export declare function createCoverageRecord(state: EngineContentState, requestPath: string, mozconfigHash: string): Promise<CoverageRecord | undefined>;
+/**
+ * Restricts an anchor to `inputs`. `extraDirty` adds paths whose live content
+ * becomes the recorded one (the dirty set of a record being created).
+ */
+export declare function narrowAnchor(state: EngineContentState, anchor: CoverageAnchor, inputs: string[], extraDirty?: readonly string[]): Promise<CoverageRecord | undefined>;