@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -0,0 +1,384 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * 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 { readdir, readFile, stat } from 'node:fs/promises';
+import { join, posix } from 'node:path';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
+import { sha256Hex } from '../utils/hash.js';
+import { verbose } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.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';
+/**
+ * Basenames of the test manifests whose entries decide what a packaged test
+ * runtime stages.
+ */
+const TEST_MANIFEST_BASENAMES = new Set([
+    'xpcshell.toml',
+    'xpcshell.ini',
+    'browser.toml',
+    'browser.ini',
+    'mochitest.toml',
+    'mochitest.ini',
+    'chrome.toml',
+    'chrome.ini',
+    'a11y.toml',
+    'a11y.ini',
+]);
+/** Directory entries a directory request's manifest walk visits at most. */
+const MAX_WALK_ENTRIES = 5000;
+/**
+ * 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 async function hashEngineFile(engineDir, relPath) {
+    try {
+        return sha256Hex(await readFile(join(engineDir, relPath)));
+    }
+    catch (error) {
+        if (getNodeErrorCode(error) === 'ENOENT')
+            return DELETED_FILE_FINGERPRINT;
+        verbose(`Coverage anchor: could not hash ${relPath} — ${toError(error).message}`);
+        return undefined;
+    }
+}
+/** True for a test manifest path (by basename). */
+export function isTestManifestPath(path) {
+    return TEST_MANIFEST_BASENAMES.has(posix.basename(path));
+}
+/** Normalizes a request path: forward slashes, no `./`, no trailing slash. */
+export function normalizeRequestPath(path) {
+    const normalized = posix.normalize(normalizePathSlashes(path.trim())).replace(/\/+$/, '');
+    return normalized === '.' ? '' : normalized;
+}
+/** True when `file` is `prefix` or sits beneath it. The empty prefix is the whole tree. */
+export function isUnderPath(file, prefix) {
+    return prefix === '' || file === prefix || file.startsWith(`${prefix}/`);
+}
+/**
+ * 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 async function readEngineContentState(engineDir) {
+    let head;
+    try {
+        head = await getHead(engineDir);
+    }
+    catch (error) {
+        if (!isMissingHeadError(error))
+            throw error;
+    }
+    const dirty = new Set();
+    if (head !== undefined) {
+        for (const line of (await git(['diff', '--name-only', 'HEAD'], engineDir)).split('\n')) {
+            if (line.trim())
+                dirty.add(line.trim());
+        }
+    }
+    for (const file of await getUntrackedFiles(engineDir))
+        dirty.add(file);
+    return { engineDir, head, dirty, hashes: new Map(), diffs: new Map() };
+}
+function liveHash(state, path) {
+    let pending = state.hashes.get(path);
+    if (pending === undefined) {
+        pending = hashEngineFile(state.engineDir, path);
+        state.hashes.set(path, pending);
+    }
+    return pending;
+}
+/** Paths committed between `from` and HEAD, or undefined when `from` cannot be diffed. */
+function committedSince(state, from) {
+    let pending = state.diffs.get(from);
+    if (pending === undefined) {
+        pending = git(['diff', '--name-only', `${from}..HEAD`], state.engineDir).then((output) => new Set(output
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean)), (error) => {
+            verbose(`Coverage anchor: cannot diff ${from}..HEAD — ${toError(error).message}`);
+            return undefined;
+        });
+        state.diffs.set(from, pending);
+    }
+    return pending;
+}
+/**
+ * Paths whose content may differ from the anchor, restricted to `inputs`
+ * (undefined: the whole tree) and excluding `rebuilt` paths. Undefined when
+ * the anchor cannot be compared at all (no usable HEAD on either side).
+ */
+async function candidatePaths(state, anchor, inputs, rebuilt) {
+    if (state.head === undefined || anchor.engineHeadSha === '')
+        return undefined;
+    const inScope = (file) => (inputs === undefined || inputs.some((input) => isUnderPath(file, input))) &&
+        !rebuilt.some((path) => isUnderPath(file, path));
+    const candidates = new Set();
+    if (state.head !== anchor.engineHeadSha) {
+        const committed = await committedSince(state, anchor.engineHeadSha);
+        if (committed === undefined)
+            return undefined;
+        for (const file of committed)
+            if (inScope(file))
+                candidates.add(file);
+    }
+    for (const file of state.dirty)
+        if (inScope(file))
+            candidates.add(file);
+    for (const file of Object.keys(anchor.fingerprints))
+        if (inScope(file))
+            candidates.add(file);
+    return candidates;
+}
+/**
+ * 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 async function findChangedInputs(state, anchor, inputs, rebuilt = []) {
+    const candidates = await candidatePaths(state, anchor, inputs, rebuilt);
+    if (candidates === undefined)
+        return undefined;
+    const changed = [];
+    for (const file of candidates) {
+        const recorded = anchor.fingerprints[file];
+        // Not recorded: the staged copy is the anchor HEAD's, and the file is
+        // a candidate only because it was committed or dirtied since.
+        if (recorded === undefined || (await liveHash(state, file)) !== recorded)
+            changed.push(file);
+    }
+    return changed.sort();
+}
+/**
+ * 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 async function refreshAnchor(state, anchor, rebuilt) {
+    const everything = await candidatePaths(state, anchor, undefined, []);
+    if (everything === undefined)
+        return undefined;
+    const restaged = (file) => rebuilt.some((path) => isUnderPath(file, path));
+    const fingerprints = {};
+    for (const [file, hash] of Object.entries(anchor.fingerprints)) {
+        if (!restaged(file))
+            fingerprints[file] = hash;
+    }
+    for (const file of everything) {
+        // A restaged file equal to the anchor HEAD's content needs no entry.
+        if (!restaged(file) || (state.head === anchor.engineHeadSha && !state.dirty.has(file))) {
+            continue;
+        }
+        const live = await liveHash(state, file);
+        if (live === undefined)
+            return undefined;
+        fingerprints[file] = live;
+    }
+    return { ...anchor, fingerprints };
+}
+/** Nearest directory at or above `dir` that holds a test manifest, or undefined. */
+async function findManifestDirectory(engineDir, dir) {
+    for (let current = dir;; current = posix.dirname(current)) {
+        const base = current === '.' ? '' : current;
+        try {
+            const entries = await readdir(join(engineDir, base));
+            if (entries.some((entry) => TEST_MANIFEST_BASENAMES.has(entry)))
+                return base;
+        }
+        catch {
+            // A missing directory has no manifest. Keep walking up.
+        }
+        if (base === '')
+            return undefined;
+    }
+}
+/**
+ * The request paths a scoped build restages, widened by the test manifests
+ * of every requested file: packaging one file of a manifest re-processes
+ * the manifest itself, so a manifest that gained an entry for that file is
+ * restaged too, and must not count as a changed input of the manifest's
+ * other files afterwards.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param requested - Normalized request paths of the build
+ */
+export async function widenWithRestagedManifests(engineDir, requested) {
+    const widened = new Set(requested);
+    for (const path of requested) {
+        if (!TEST_FILE_PATTERN.test(posix.basename(path)))
+            continue;
+        const dir = await findManifestDirectory(engineDir, posix.dirname(path));
+        if (dir === undefined)
+            continue;
+        let entries;
+        try {
+            entries = await readdir(join(engineDir, dir));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (TEST_MANIFEST_BASENAMES.has(entry))
+                widened.add(dir === '' ? entry : `${dir}/${entry}`);
+        }
+    }
+    return [...widened];
+}
+/** A test implementation file (`browser_*.js`, `test_*.js`, …), not a directory. */
+const TEST_FILE_PATTERN = /^(?:browser|test)_.*\.m?js$/;
+/** Test manifests at or beneath `dir`, bounded by {@link MAX_WALK_ENTRIES}. */
+async function findManifestsBeneath(engineDir, dir) {
+    const manifests = [];
+    const pending = [dir];
+    let visited = 0;
+    while (pending.length > 0 && visited < MAX_WALK_ENTRIES) {
+        const current = pending.pop() ?? '';
+        let entries;
+        try {
+            entries = await readdir(join(engineDir, current), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            visited += 1;
+            const path = current ? `${current}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                pending.push(path);
+            else if (TEST_MANIFEST_BASENAMES.has(entry.name))
+                manifests.push(path);
+        }
+    }
+    return manifests;
+}
+/**
+ * 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 function manifestExternalReferences(manifestPath, text) {
+    const dir = posix.dirname(manifestPath);
+    const refs = [];
+    for (const token of text.match(/[\w.!~@+\-/*?{}]+/g) ?? []) {
+        if (!token.includes('/') || token.includes('//'))
+            continue;
+        const rooted = token.startsWith('!/')
+            ? token.slice(2)
+            : token.startsWith('/')
+                ? token.slice(1)
+                : undefined;
+        const resolved = rooted === undefined ? posix.join(dir, token) : posix.normalize(rooted);
+        const segments = resolved.split('/');
+        const wildcard = segments.findIndex((segment) => /[*?{}]/.test(segment));
+        const path = normalizeRequestPath(wildcard >= 0 ? segments.slice(0, wildcard).join('/') : resolved);
+        if (path === '' || path.startsWith('..') || isUnderPath(path, dir))
+            continue;
+        refs.push(path);
+    }
+    return refs;
+}
+/** Drops entries that sit beneath another entry, then sorts. */
+function collapsePaths(paths) {
+    const unique = [...new Set(paths)].sort();
+    return unique.filter((path) => !unique.some((other) => other !== path && isUnderPath(path, other)));
+}
+/**
+ * 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 async function collectStagingInputs(engineDir, requestPath) {
+    const path = normalizeRequestPath(requestPath);
+    let isDirectory = false;
+    try {
+        isDirectory = (await stat(join(engineDir, path))).isDirectory();
+    }
+    catch {
+        // A missing request path is staged by nothing. Its directory still decides.
+    }
+    const start = isDirectory ? path : posix.dirname(path);
+    const base = await findManifestDirectory(engineDir, start === '.' ? '' : start);
+    const fallback = start === '.' || start === '' ? path : start;
+    const root = base === undefined || base === '' ? fallback : base;
+    const manifests = new Set();
+    for (const entry of await readdir(join(engineDir, root)).catch(() => [])) {
+        if (TEST_MANIFEST_BASENAMES.has(entry))
+            manifests.add(`${root}/${entry}`);
+    }
+    if (isDirectory) {
+        for (const manifest of await findManifestsBeneath(engineDir, path))
+            manifests.add(manifest);
+    }
+    const inputs = [root, path];
+    for (const manifest of manifests) {
+        try {
+            const text = await readFile(join(engineDir, manifest), 'utf8');
+            inputs.push(...manifestExternalReferences(manifest, text));
+        }
+        catch (error) {
+            verbose(`Coverage anchor: cannot read ${manifest} — ${toError(error).message}`);
+        }
+    }
+    return collapsePaths(inputs);
+}
+/**
+ * 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 async function createCoverageRecord(state, requestPath, mozconfigHash) {
+    if (state.head === undefined)
+        return undefined;
+    const inputs = await collectStagingInputs(state.engineDir, requestPath);
+    return narrowAnchor(state, { engineHeadSha: state.head, mozconfigHash, fingerprints: {} }, inputs, [...state.dirty]);
+}
+/**
+ * Restricts an anchor to `inputs`. `extraDirty` adds paths whose live content
+ * becomes the recorded one (the dirty set of a record being created).
+ */
+export async function narrowAnchor(state, anchor, inputs, extraDirty = []) {
+    const fingerprints = {};
+    for (const [file, hash] of Object.entries(anchor.fingerprints)) {
+        if (inputs.some((input) => isUnderPath(file, input)))
+            fingerprints[file] = hash;
+    }
+    for (const file of extraDirty) {
+        if (!inputs.some((input) => isUnderPath(file, input)))
+            continue;
+        const live = await liveHash(state, file);
+        if (live === undefined)
+            return undefined;
+        fingerprints[file] = live;
+    }
+    return { ...anchor, fingerprints, inputs };
+}

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

@@ -11,8 +11,6 @@
  * forward-import that later-patch lint would then block). Without a single
  * helper, every new destructive command would re-implement this and drift.
  */
-/** Filename of the audit log, relative to the patches directory. */
-export declare const HISTORY_LOG_FILENAME = ".fireforge-history.jsonl";
 /**
  * A structural conflict that must block the operation even under `--force`.
  *
@@ -128,12 +126,17 @@ export declare function assertConfirmationAvailable(operation: string, options:
  */
 export declare function confirmDestructive(input: DestructiveOpInput): Promise<DestructiveOpResult>;
 /**
- * Appends a single JSONL record to `patches/.fireforge-history.jsonl`.
+ * Appends a single JSONL record to the project's patch history log
+ * (`.fireforge/history.jsonl` unless `fireforge.json#history.path` says
+ * otherwise; a log at the pre-0.50 `patches/.fireforge-history.jsonl` is
+ * moved there first).
  *
  * Call order matters: append only after the mutation succeeds, never
  * pre-emptively, so rolled-back failures do not leave ghost entries. The log
  * is append-only and advisory: no code path reads it back. It exists so
- * operators have a post-hoc audit trail when something goes wrong.
+ * operators have a post-hoc audit trail when something goes wrong. Every
+ * record carries the writing invocation's id (and `FIREFORGE_SESSION_ID`
+ * when set), so a session sharing the checkout can pick out its own lines.
  *
  * @param patchesDir - Path to the patches directory
  * @param entry - Serializable history record

package/dist/src/core/destructive.js

@@ -12,14 +12,10 @@
  * forward-import that later-patch lint would then block). Without a single
  * helper, every new destructive command would re-implement this and drift.
  */
-import { appendFile } from 'node:fs/promises';
-import { join } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { CancellationError, InvalidArgumentError } from '../errors/base.js';
-import { ensureDir } from '../utils/fs.js';
 import { info, isCancel, warn } from '../utils/logger.js';
-/** Filename of the audit log, relative to the patches directory. */
-export const HISTORY_LOG_FILENAME = '.fireforge-history.jsonl';
+import { appendHistoryLine, historyRecordIdentity } from './history-log-file.js';
 /**
  * Prints the change summary lines at warn-severity so the prompt stands out.
  */
@@ -161,22 +157,26 @@ export async function confirmDestructive(input) {
     return 'proceed';
 }
 /**
- * Appends a single JSONL record to `patches/.fireforge-history.jsonl`.
+ * Appends a single JSONL record to the project's patch history log
+ * (`.fireforge/history.jsonl` unless `fireforge.json#history.path` says
+ * otherwise; a log at the pre-0.50 `patches/.fireforge-history.jsonl` is
+ * moved there first).
  *
  * Call order matters: append only after the mutation succeeds, never
  * pre-emptively, so rolled-back failures do not leave ghost entries. The log
  * is append-only and advisory: no code path reads it back. It exists so
- * operators have a post-hoc audit trail when something goes wrong.
+ * operators have a post-hoc audit trail when something goes wrong. Every
+ * record carries the writing invocation's id (and `FIREFORGE_SESSION_ID`
+ * when set), so a session sharing the checkout can pick out its own lines.
  *
  * @param patchesDir - Path to the patches directory
  * @param entry - Serializable history record
  */
 export async function appendHistory(patchesDir, entry) {
-    await ensureDir(patchesDir);
     const record = {
         ts: new Date().toISOString(),
+        ...historyRecordIdentity(),
         ...entry,
     };
-    const line = `${JSON.stringify(record)}\n`;
-    await appendFile(join(patchesDir, HISTORY_LOG_FILENAME), line, 'utf-8');
+    await appendHistoryLine(patchesDir, JSON.stringify(record));
 }

package/dist/src/core/engine-session-lock.d.ts

@@ -1,3 +1,4 @@
+import type { LockMode } from './file-lock.js';
 import { type LockStatusSnapshot } from './file-lock.js';
 export interface EngineSessionLockOptions {
     /**
@@ -7,6 +8,11 @@ export interface EngineSessionLockOptions {
      * fail-fast behaviour.
      */
     waitLockSeconds?: number | undefined;
+    /**
+     * `shared` lets build-less test runs overlap each other; see
+     * `file-lock-shared.ts`. Every other caller holds the lock exclusively.
+     */
+    mode?: LockMode | undefined;
 }
 /**
  * Formats the notice printed when the wait budget is extended because the
@@ -59,6 +65,15 @@ export declare function isIndexLockError(error: unknown): boolean;
 export declare function isUnavailableGenerationToken(token: string): boolean;
 /** Strips the marker prefix off an unavailable token for display. */
 export declare function unavailableGenerationReason(token: string): string;
+/**
+ * Engine-relative paths whose working-tree status differs between two
+ * generation tokens (both sides of a rename), and whether HEAD moved. An
+ * untracked directory keeps git's trailing `/`.
+ */
+export declare function generationDeltaPaths(before: string, after: string): {
+    headMoved: boolean;
+    paths: string[];
+};
 /**
  * Describes what moved between two generation tokens, in operator terms.
  *
@@ -101,4 +116,4 @@ export declare function describeEngineGenerationDelta(before: string, after: str
  * demonstrably had something to measure. The reverse means there was never a
  * baseline to compare against. Neither verdict can be trusted, so both throw.
  */
-export declare function assertEngineGenerationUnchanged(engineDir: string, before: string): Promise<void>;
+export declare function assertEngineGenerationUnchanged(engineDir: string, before: string, tolerateDelta?: (before: string, after: string) => Promise<boolean>): Promise<void>;

package/dist/src/core/engine-session-lock.js

@@ -3,8 +3,9 @@ import { join } from 'node:path';
 import { InconclusiveVerdictError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { info, warn } from '../utils/logger.js';
+import { MAX_WAIT_LOCK_SECONDS } from '../utils/options.js';
 import { sleep } from '../utils/sleep.js';
-import { readLockStatus, withFileLock } from './file-lock.js';
+import { formatLockQueuePosition, readLockStatus, withFileLock, } from './file-lock.js';
 import { git } from './git-base.js';
 const ENGINE_SESSION_LOCK_PATH = join('.fireforge', 'engine-session.lock');
 /**
@@ -14,7 +15,7 @@ const ENGINE_SESSION_LOCK_PATH = join('.fireforge', 'engine-session.lock');
  * never gets one longer than the largest wait they could have asked for.
  */
 const WAIT_EXTENSION_FACTOR = 4;
-const MAX_WAIT_LOCK_MS = 3600 * 1000;
+const MAX_WAIT_LOCK_MS = MAX_WAIT_LOCK_SECONDS * 1000;
 /**
  * Formats the periodic operator-facing waiting line printed while `--wait-lock`
  * polls a contended engine session lock. The holder identification comes from
@@ -24,12 +25,9 @@ const MAX_WAIT_LOCK_MS = 3600 * 1000;
 function formatWaitProgressLine(waitedMs, timeoutMs, holder, queue) {
     const progress = `${Math.round(waitedMs / 1000)}s of up to ${Math.round(timeoutMs / 1000)}s`;
     // Queue position: under several concurrent sessions the wait
-    // line alone left operators inferring their place from `ps`.
-    const position = queue === undefined || queue.depth === 0
-        ? ''
-        : queue.ahead === 0
-            ? ` You are next in a queue of ${queue.depth}.`
-            : ` ${queue.ahead} ahead of you (queue of ${queue.depth}).`;
+    // line alone left operators inferring their place from `ps`. It names the
+    // ordering rule, because the count is only useful if the grant honours it.
+    const position = formatLockQueuePosition(queue);
     if (holder === undefined) {
         return `Waiting for the FireForge engine lock — ${progress}.${position}`;
     }
@@ -69,6 +67,7 @@ export async function withEngineSessionLock(projectRoot, command, operation, opt
     }
     const { waitLockSeconds } = options;
     return withFileLock(join(projectRoot, ENGINE_SESSION_LOCK_PATH), operation, {
+        ...(options.mode === 'shared' ? { mode: 'shared' } : {}),
         timeoutMs: waitLockSeconds !== undefined ? waitLockSeconds * 1000 : 1000,
         ...(waitLockSeconds !== undefined
             ? {
@@ -124,8 +123,13 @@ export async function readEngineSessionLockStatus(projectRoot) {
  * Pure, so the wording is unit-testable without a lock on disk.
  */
 export function formatEngineSessionLockStatus(snapshot, holderCpuSeconds) {
+    const shared = snapshot.sharedHolders !== undefined && snapshot.sharedHolders > 0
+        ? `Shared holders: ${snapshot.sharedHolders} build-less test run(s) under a shared lock.`
+        : undefined;
     if (!snapshot.held) {
-        return ['Engine session lock: free (no FireForge engine-mutating command is running).'];
+        return shared === undefined
+            ? ['Engine session lock: free (no FireForge engine-mutating command is running).']
+            : ['Engine session lock: no exclusive holder.', shared];
     }
     const elapsed = snapshot.heldForMs === undefined
         ? 'unknown duration'
@@ -138,6 +142,7 @@ export function formatEngineSessionLockStatus(snapshot, holderCpuSeconds) {
     const lines = [
         `Engine session lock: ${identity}, for ${elapsed}.`,
         `Queue depth: ${snapshot.queueDepth} waiter(s).`,
+        ...(shared === undefined ? [] : [shared]),
     ];
     // Liveness answers "does the process exist". It does not answer "is it
     // getting anywhere". A holder alive for minutes having used a fraction of
@@ -254,6 +259,25 @@ function parsePorcelainRecords(body) {
     }
     return records;
 }
+/**
+ * Engine-relative paths whose working-tree status differs between two
+ * generation tokens (both sides of a rename), and whether HEAD moved. An
+ * untracked directory keeps git's trailing `/`.
+ */
+export function generationDeltaPaths(before, after) {
+    const from = splitGenerationToken(before);
+    const to = splitGenerationToken(after);
+    const beforeRecords = new Set(parsePorcelainRecords(from.body));
+    const afterRecords = new Set(parsePorcelainRecords(to.body));
+    const paths = new Set();
+    for (const record of [...afterRecords, ...beforeRecords]) {
+        if (beforeRecords.has(record) && afterRecords.has(record))
+            continue;
+        for (const path of record.slice(3).split(' -> '))
+            paths.add(path);
+    }
+    return { headMoved: from.head !== to.head, paths: [...paths].sort() };
+}
 /**
  * Describes what moved between two generation tokens, in operator terms.
  *
@@ -317,7 +341,7 @@ export function describeEngineGenerationDelta(before, after) {
  * demonstrably had something to measure. The reverse means there was never a
  * baseline to compare against. Neither verdict can be trusted, so both throw.
  */
-export async function assertEngineGenerationUnchanged(engineDir, before) {
+export async function assertEngineGenerationUnchanged(engineDir, before, tolerateDelta) {
     const after = await snapshotEngineGeneration(engineDir);
     const beforeUnavailable = isUnavailableGenerationToken(before);
     const afterUnavailable = isUnavailableGenerationToken(after);
@@ -339,6 +363,10 @@ export async function assertEngineGenerationUnchanged(engineDir, before) {
     }
     if (after === before)
         return;
+    // A caller that can prove the delta never reached the runtime under test
+    // (a perf sample, see `test-perf-scope.ts`) keeps its verdict.
+    if (tolerateDelta !== undefined && (await tolerateDelta(before, after)))
+        return;
     const delta = describeEngineGenerationDelta(before, after);
     throw new InconclusiveVerdictError('engine/ changed while `fireforge test` was running, so this test verdict is invalid/inconclusive.\n\n' +
         (delta.length > 0 ? `What moved:\n${delta.map((line) => `  ${line}`).join('\n')}\n\n` : '') +