@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/commands/re-export-adjacent.d.ts

@@ -1,111 +0,0 @@
-import type { PatchesManifest, PatchMetadata, ReExportOptions } from '../types/commands/index.js';
-import type { ProjectPaths } from '../types/config.js';
-/**
- * Shared per-run context for the adjacency advisory: the classification
- * inputs computed once by `reExportCommand`, plus the collection of
- * patches refused under `--refuse-adjacent-unmanaged` (collected across
- * the loop so a multi-patch run reports every offender in one refusal).
- */
-export interface AdjacentUnmanagedContext {
-    binaryName: string;
-    furnacePrefixes: ReadonlySet<string>;
-    refuseAdjacentUnmanaged: boolean;
-    /**
-     * Engine-relative paths named by `--expect-unmanaged`: reviewed, recorded
-     * exceptions that are reported but never refuse. Normalized once by the
-     * caller so the comparison matches git's engine-relative output.
-     */
-    approvedUnmanaged: ReadonlySet<string>;
-    /** Approved paths actually met this run, so unused ones can be surfaced. */
-    approvedSeen: Set<string>;
-    /**
-     * Engine-relative paths named by `--expect-new`: files this session
-     * created and will adopt with its next export (or `--scan-file`). They
-     * pass the belt and are reported, while every other adjacent file still
-     * refuses, so a peer's neighbour is not admitted with them.
-     */
-    expectedNew: ReadonlySet<string>;
-    /** `--expect-new` paths actually met this run. */
-    expectedNewSeen: Set<string>;
-    /**
-     * Reviewed `--adjacent-ignore` entries: an engine-relative path, or a
-     * glob whose `*` stays within one path segment. Matches are reported in
-     * one line and never refuse.
-     */
-    adjacentIgnore: readonly string[];
-    /** `--adjacent-ignore` entries that matched a file this run. */
-    adjacentIgnoreSeen: Set<string>;
-    /**
-     * Offenders collected across the loop. `files` stays the bare paths that
-     * downstream consumers already read. `anchored` carries the same entries
-     * with the owned directory that made each one adjacent, so the run-level
-     * refusal can name the anchor without re-deriving it.
-     */
-    refusals: {
-        patchFilename: string;
-        files: string[];
-        anchored: string[];
-    }[];
-}
-/**
- * Builds the run's adjacency context. The path flags are normalized once
- * here, so the per-file comparison matches git's engine-relative output.
- */
-export declare function buildAdjacentUnmanagedContext(options: ReExportOptions, binaryName: string, furnacePrefixes: ReadonlySet<string>): AdjacentUnmanagedContext;
-/**
- * The one definition of "adjacent", shared by the per-patch notice and the
- * run-level refusal so the two cannot drift apart.
- */
-export declare const ADJACENT_MEANS: string;
-/** Returns the subset of `files` that no longer exist under `engineDir`. */
-export declare function findMissingFiles(engineDir: string, files: readonly string[]): Promise<string[]>;
-/**
- * One unmanaged file and the owned directory that made it adjacent.
- *
- * The anchor names which of the patch's owned locations the file sits
- * beside, so an unattended run can triage a refusal on a patch that owns
- * files in several directories without re-deriving the adjacency by hand
- * from the manifest.
- */
-export interface AdjacentUnmanagedFile {
-    /** Engine-relative path of the unmanaged file. */
-    file: string;
-    /**
-     * Directory holding at least one file this patch owns, or for a
-     * registration-named file, the directory of the carrier naming it.
-     */
-    anchorDir: string;
-    /** The owned carrier whose added registration line names the file. */
-    registeredBy?: string;
-}
-/**
- * Emits the scan-less advisory for one patch: missing manifest files and
- * unmanaged files adjacent to the patch's ownership. When
- * `--refuse-adjacent-unmanaged` is set and any unmanaged adjacent file
- * exists, records the patch into `ctx.refusals` and returns true. The
- * caller then skips the write for this patch and converts the collection
- * into one run-level non-zero refusal after the loop.
- */
-export declare function reportAdjacentUnmanagedFiles(args: {
-    patch: PatchMetadata;
-    paths: ProjectPaths;
-    manifest: PatchesManifest;
-    currentFilesAffected: readonly string[];
-    ctx: AdjacentUnmanagedContext;
-    /**
-     * Set beside `--scan`: the scan has already reconciled missing files and
-     * adopted what it was asked to, so only the neighbours it left are judged.
-     */
-    afterScan?: boolean;
-}): Promise<boolean>;
-/**
- * End-of-run accounting for `--expect-new` and `--adjacent-ignore`.
- *
- * An `--expect-new` path is a promise that the next export adopts it, so a
- * met one is repeated as the export still owed, and an unmet one is a
- * warning: a typo there leaves the refusal armed for the file it meant to
- * admit. An unmatched `--adjacent-ignore` entry is only noted, because a
- * reviewed ignore list is reused across runs and patches, and "not met"
- * is its normal case.
- */
-export declare function reportAdjacentCarveOutUsage(ctx: AdjacentUnmanagedContext): void;

package/dist/src/commands/re-export-adjacent.js

@@ -1,267 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Re-export adjacency advisory.
- *
- * A plain `re-export` keeps the manifest's filesAffected unchanged, so a
- * brand-new file an author just created beside a patch's owned files is
- * silently left out of the refreshed body. This module detects such adjacent
- * files, filters out tool-managed paths (branding, furnace) so the notice
- * names only genuinely unmanaged candidates, and, under
- * `--refuse-adjacent-unmanaged`, lets the caller turn the notice into a
- * non-zero refusal. Beside `--scan` it judges the files the scan did not
- * adopt, so a targeted `--scan-file` adoption keeps the belt.
- *
- * Split out of re-export.ts to keep that file inside the max-lines budget.
- * Exports helpers consumed by re-export.ts, no registrar.
- */
-import { dirname, join } from 'node:path';
-import { isBrandingManagedPath } from '../core/branding.js';
-import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
-import { getClaimedFiles } from '../core/patch-manifest.js';
-import { isGeneratedBrandingPath } from '../core/status-classify.js';
-import { mapWithConcurrency } from '../utils/concurrency.js';
-import { pathExists } from '../utils/fs.js';
-import { info, warn } from '../utils/logger.js';
-import { escapeRegex } from '../utils/regex.js';
-import { findRegisteredChangedFiles } from './re-export-adjacent-registrations.js';
-import { normalizeEngineRelativeInput } from './re-export-scan.js';
-/**
- * Builds the run's adjacency context. The path flags are normalized once
- * here, so the per-file comparison matches git's engine-relative output.
- */
-export function buildAdjacentUnmanagedContext(options, binaryName, furnacePrefixes) {
-    const normalized = (flag, values) => (values ?? []).map((value) => normalizeEngineRelativeInput(value, flag));
-    return {
-        binaryName,
-        furnacePrefixes,
-        refuseAdjacentUnmanaged: options.refuseAdjacentUnmanaged === true,
-        approvedUnmanaged: new Set(normalized('--expect-unmanaged', options.expectUnmanaged)),
-        approvedSeen: new Set(),
-        expectedNew: new Set(normalized('--expect-new', options.expectNew)),
-        expectedNewSeen: new Set(),
-        adjacentIgnore: normalized('--adjacent-ignore', options.adjacentIgnore),
-        adjacentIgnoreSeen: new Set(),
-        refusals: [],
-    };
-}
-/**
- * The one definition of "adjacent", shared by the per-patch notice and the
- * run-level refusal so the two cannot drift apart.
- */
-export const ADJACENT_MEANS = 'Adjacent means the file sits in the same directory as a file this patch owns, ' +
-    'or a registration line this patch adds (jar.mn, moz.build, test manifest) names it.';
-/** Concurrency bound for existence probes (matches the classify/lint pools). */
-const PATH_PROBE_CONCURRENCY = 8;
-/** Returns the subset of `files` that no longer exist under `engineDir`. */
-export async function findMissingFiles(engineDir, files) {
-    const exists = await mapWithConcurrency(files, PATH_PROBE_CONCURRENCY, (file) => pathExists(join(engineDir, file)));
-    return files.filter((_, index) => exists[index] !== true);
-}
-function isToolManagedPath(file, isNewFile, ctx) {
-    // Mirrors status-classify: a generated branding path is tool-managed
-    // outright. A brand-new unowned file under the branding root is still a
-    // patch candidate (the Assets.car precedent) and must stay listed.
-    if (isBrandingManagedPath(file, ctx.binaryName) &&
-        (!isNewFile || isGeneratedBrandingPath(file, ctx.binaryName))) {
-        return true;
-    }
-    for (const prefix of ctx.furnacePrefixes) {
-        if (file.startsWith(prefix))
-            return true;
-    }
-    return false;
-}
-/**
- * Matches an `--adjacent-ignore` entry. A `*` stays inside one path
- * segment, the same narrowness as `buildAudit.unpackaged`: a carve-out that
- * silently spans subtrees is how a reviewed exception becomes a blanket one.
- */
-function matchesIgnoreEntry(entry, file) {
-    if (!entry.includes('*'))
-        return entry === file;
-    const pattern = entry
-        .split('*')
-        .map((part) => escapeRegex(part))
-        .join('[^/]*');
-    return new RegExp(`^${pattern}$`).test(file);
-}
-/**
- * Lists the unmanaged files a re-export of this patch would plausibly have
- * to capture: changed files directly in a directory the patch owns a file
- * in, and changed files a registration line the patch adds names. A file in
- * a sibling or nested directory is not adjacent. The directory listing
- * recurses (pathspecs do), so it is filtered back to the exact directories,
- * the same footprint the broad `--scan` adopts from.
- */
-async function findAdjacentUnmanagedFiles(args) {
-    const { currentFilesAffected, engineDir, manifest, patchFilename, ctx } = args;
-    const parentDirs = [...new Set(currentFilesAffected.map((file) => dirname(file)))];
-    const parentDirSet = new Set(parentDirs);
-    const currentSet = new Set(currentFilesAffected);
-    const claimedByOthers = getClaimedFiles(manifest, patchFilename);
-    // First anchor wins: a file lives in exactly one directory, and a
-    // directory anchor is the stronger statement than a registration one.
-    const candidates = new Map();
-    const isCandidate = (file, isNewFile) => !currentSet.has(file) &&
-        !claimedByOthers.has(file) &&
-        !candidates.has(file) &&
-        !isToolManagedPath(file, isNewFile, ctx);
-    for (const dir of parentDirs) {
-        const [modifiedFiles, untrackedFiles] = await Promise.all([
-            getModifiedFilesInDir(engineDir, dir),
-            getUntrackedFilesInDir(engineDir, dir),
-        ]);
-        const untrackedSet = new Set(untrackedFiles);
-        for (const file of [...modifiedFiles, ...untrackedFiles]) {
-            if (!parentDirSet.has(dirname(file)))
-                continue;
-            if (isCandidate(file, untrackedSet.has(file))) {
-                candidates.set(file, { file, anchorDir: dirname(file) });
-            }
-        }
-    }
-    const registered = await findRegisteredChangedFiles(engineDir, currentFilesAffected);
-    for (const { file, carrier } of registered) {
-        // A registered path is a patch candidate whatever its tracking state,
-        // so it is classified as new: only a generated path is tool-managed.
-        if (isCandidate(file, true)) {
-            candidates.set(file, { file, anchorDir: dirname(carrier), registeredBy: carrier });
-        }
-    }
-    return [...candidates.values()].sort((a, b) => a.file.localeCompare(b.file));
-}
-function dispositionOf(file, ctx) {
-    if (ctx.approvedUnmanaged.has(file)) {
-        ctx.approvedSeen.add(file);
-        return 'approved';
-    }
-    if (ctx.expectedNew.has(file)) {
-        ctx.expectedNewSeen.add(file);
-        return 'expected-new';
-    }
-    const ignore = ctx.adjacentIgnore.find((entry) => matchesIgnoreEntry(entry, file));
-    if (ignore !== undefined) {
-        ctx.adjacentIgnoreSeen.add(ignore);
-        return 'ignored';
-    }
-    return 'refusing';
-}
-/**
- * Splits the candidates into the ones that refuse and the ones a carve-out
- * (`--expect-unmanaged`, `--expect-new`, `--adjacent-ignore`) admits. Met
- * carve-outs are recorded so an unused one can be reported, and admitted
- * files are returned rather than dropped, so the exception stays visible
- * instead of quietly widening.
- */
-function partitionApproved(files, ctx) {
-    const groups = {
-        refusing: [],
-        approved: [],
-        'expected-new': [],
-        ignored: [],
-    };
-    for (const entry of files)
-        groups[dispositionOf(entry.file, ctx)].push(entry);
-    return groups;
-}
-/** How a notice names one file's anchor. */
-function describeAnchor(entry) {
-    return entry.registeredBy !== undefined
-        ? `registered by engine/${entry.registeredBy}`
-        : `beside engine/${entry.anchorDir}`;
-}
-/** Renders `<file> (beside engine/<dir>)` or `<file> (registered by engine/<carrier>)`. */
-function describeAnchored(entry) {
-    return `${entry.file} (${describeAnchor(entry)})`;
-}
-/** The admitted-file notice lines, one per carve-out that admitted anything. */
-function reportAdmitted(patchFilename, groups) {
-    const notices = [
-        [groups.approved, 'admitted by --expect-unmanaged'],
-        [groups['expected-new'], 'expected by --expect-new'],
-        [groups.ignored, 'ignored by --adjacent-ignore'],
-    ];
-    for (const [entries, how] of notices) {
-        if (entries.length === 0)
-            continue;
-        info(`${patchFilename}: ${entries.length} adjacent unmanaged file(s) ${how} ` +
-            `(${entries.map(describeAnchored).join(', ')}) — reported, not refused.`);
-    }
-}
-/**
- * Emits the scan-less advisory for one patch: missing manifest files and
- * unmanaged files adjacent to the patch's ownership. When
- * `--refuse-adjacent-unmanaged` is set and any unmanaged adjacent file
- * exists, records the patch into `ctx.refusals` and returns true. The
- * caller then skips the write for this patch and converts the collection
- * into one run-level non-zero refusal after the loop.
- */
-export async function reportAdjacentUnmanagedFiles(args) {
-    const { patch, paths, manifest, currentFilesAffected, ctx } = args;
-    const missingFiles = args.afterScan === true ? [] : await findMissingFiles(paths.engine, currentFilesAffected);
-    if (missingFiles.length > 0) {
-        warn(`${patch.filename}: some files in patches.json no longer exist on disk ` +
-            `(${missingFiles.join(', ')}). Without --scan, re-export keeps the manifest's ` +
-            `filesAffected unchanged and the missing entries will be preserved — ` +
-            `\`fireforge verify\` may flag manifest inconsistency after this run.\n` +
-            `  Re-run with --scan to reconcile filesAffected with the current worktree, ` +
-            `or pass --files <paths> to set the list explicitly.`);
-    }
-    const allUnmanaged = await findAdjacentUnmanagedFiles({
-        currentFilesAffected,
-        engineDir: paths.engine,
-        manifest,
-        patchFilename: patch.filename,
-        ctx,
-    });
-    const groups = partitionApproved(allUnmanaged, ctx);
-    reportAdmitted(patch.filename, groups);
-    const unmanagedFiles = groups.refusing;
-    if (unmanagedFiles.length === 0)
-        return false;
-    const firstFew = unmanagedFiles.slice(0, 3).map(describeAnchored).join(', ');
-    const more = unmanagedFiles.length > 3 ? `, +${unmanagedFiles.length - 3} more` : '';
-    warn(`${patch.filename}: found ${unmanagedFiles.length} unmanaged file(s) adjacent to this patch's ownership (${firstFew}${more}). ` +
-        `${ADJACENT_MEANS} ` +
-        `Plain re-export keeps filesAffected unchanged — use --scan-file to include reviewed files, ` +
-        `or --expect-new for a file your next export adopts.`);
-    for (const entry of unmanagedFiles) {
-        info(`  ${entry.file} — ${describeAnchor(entry)} — ` +
-            `fireforge re-export ${patch.filename} --scan --scan-file ${entry.file}`);
-    }
-    if (ctx.refuseAdjacentUnmanaged) {
-        ctx.refusals.push({
-            patchFilename: patch.filename,
-            files: unmanagedFiles.map((entry) => entry.file),
-            anchored: unmanagedFiles.map(describeAnchored),
-        });
-        return true;
-    }
-    return false;
-}
-/**
- * End-of-run accounting for `--expect-new` and `--adjacent-ignore`.
- *
- * An `--expect-new` path is a promise that the next export adopts it, so a
- * met one is repeated as the export still owed, and an unmet one is a
- * warning: a typo there leaves the refusal armed for the file it meant to
- * admit. An unmatched `--adjacent-ignore` entry is only noted, because a
- * reviewed ignore list is reused across runs and patches, and "not met"
- * is its normal case.
- */
-export function reportAdjacentCarveOutUsage(ctx) {
-    const unseenNew = [...ctx.expectedNew].filter((file) => !ctx.expectedNewSeen.has(file));
-    if (unseenNew.length > 0) {
-        warn(`--expect-new path(s) were not met as adjacent unmanaged files this run: ` +
-            `${unseenNew.join(', ')}. Check the path for a typo, and that a selected patch owns a ` +
-            'file in its directory or registers it. The refusal stayed armed for everything else.');
-    }
-    if (ctx.expectedNewSeen.size > 0) {
-        info(`--expect-new admitted ${[...ctx.expectedNewSeen].sort().join(', ')}, which no patch owns ` +
-            'yet. Export them next so the queue does not register files it does not ship.');
-    }
-    const unseenIgnore = ctx.adjacentIgnore.filter((entry) => !ctx.adjacentIgnoreSeen.has(entry));
-    if (unseenIgnore.length > 0) {
-        info(`--adjacent-ignore entries matched no adjacent file this run: ${unseenIgnore.join(', ')}.`);
-    }
-}

package/dist/src/commands/re-export-bulk-scan.d.ts

@@ -1,19 +0,0 @@
-import type { PatchesManifest } from '../types/commands/index.js';
-import { type DryRunPurityScope } from './re-export-purity-scope.js';
-/** Loads and validates a `re-export --scan-files` assignment manifest. */
-export declare function loadScanFilesAssignments(manifestPath: string, manifest: PatchesManifest): Promise<Map<string, string[]>>;
-/**
- * Runtime enforcement of the dry-run purity contract: fingerprints the engine
- * tree and every patch artifact before and after `operation`, and throws when
- * a dry-run changed anything it promised only to inspect. That turns a
- * "dry-run reverted a just-written export" incident into a hard, named
- * failure instead of silent data loss discovered only when a later gate
- * fails. The post-fingerprint runs whether `operation` resolves or rejects,
- * because a dry-run that mutates state and then fails is exactly the case
- * where a rollback defect must not go unreported. A rejection with a purity
- * violation surfaces the violation with the original error as `cause`.
- * No-op outside dry-run.
- */
-export declare function withDryRunPurityGuard<T>(engineDir: string, patchesDir: string, isDryRun: boolean, operation: () => Promise<T>, scope?: DryRunPurityScope): Promise<T>;
-/** Serializes dry-run re-export git inspection against the same project tree. */
-export declare function withDryRunReExportLock<T>(fireforgeDir: string, isDryRun: boolean, operation: () => Promise<T>): Promise<T>;

package/dist/src/commands/re-export-bulk-scan.js

@@ -1,233 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { readdir, readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { isUnavailableGenerationToken, snapshotEngineGeneration, unavailableGenerationReason, } from '../core/engine-session-lock.js';
-import { createSiblingLockPath, withFileLock } from '../core/file-lock.js';
-import { formatPatchNotFoundError } from '../core/patch-identifier-suggest.js';
-import { resolvePatchIdentifier } from '../core/patch-manifest.js';
-import { GeneralError, InvalidArgumentError } from '../errors/base.js';
-import { mapWithConcurrency } from '../utils/concurrency.js';
-import { getNodeErrorCode, toError } from '../utils/errors.js';
-import { readText } from '../utils/fs.js';
-import { sha256Hex } from '../utils/hash.js';
-import { isObject } from '../utils/validation.js';
-import { describeForeignWriters, fingerprintScopedDryRunState, } from './re-export-purity-scope.js';
-import { normalizeEngineRelativeInput } from './re-export-scan.js';
-/** Concurrency bound for patch-body hashing (matches the classify/lint pools). */
-const PATCH_HASH_CONCURRENCY = 8;
-function parseScanFilesManifest(raw, manifestPath) {
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        throw new InvalidArgumentError(`--scan-files manifest is not valid JSON (${manifestPath}): ${toError(error).message}`, '--scan-files');
-    }
-    if (!isObject(parsed) || !Array.isArray(parsed['assignments'])) {
-        throw new InvalidArgumentError('--scan-files manifest must contain an assignments array.', '--scan-files');
-    }
-    const assignments = [];
-    for (const [index, assignment] of parsed['assignments'].entries()) {
-        if (!isObject(assignment)) {
-            throw new InvalidArgumentError(`--scan-files assignments[${index}] must be an object.`, '--scan-files');
-        }
-        const { patch, files } = assignment;
-        if (typeof patch !== 'string' || patch.trim().length === 0) {
-            throw new InvalidArgumentError(`--scan-files assignments[${index}].patch must be a non-empty string.`, '--scan-files');
-        }
-        if (!Array.isArray(files) ||
-            files.length === 0 ||
-            !files.every((file) => typeof file === 'string')) {
-            throw new InvalidArgumentError(`--scan-files assignments[${index}].files must be a non-empty string array.`, '--scan-files');
-        }
-        assignments.push({ patch, files });
-    }
-    if (assignments.length === 0) {
-        throw new InvalidArgumentError('--scan-files manifest must assign at least one file.', '--scan-files');
-    }
-    return { assignments };
-}
-/** Loads and validates a `re-export --scan-files` assignment manifest. */
-export async function loadScanFilesAssignments(manifestPath, manifest) {
-    const parsed = parseScanFilesManifest(await readText(manifestPath), manifestPath);
-    const filesByPatch = new Map();
-    const ownerByFile = new Map();
-    for (const assignment of parsed.assignments) {
-        const patch = resolvePatchIdentifier(assignment.patch, manifest.patches);
-        if (!patch) {
-            // Suggest close matches instead of dumping the whole queue.
-            throw new InvalidArgumentError(`--scan-files: ${formatPatchNotFoundError(assignment.patch, manifest.patches)}`, '--scan-files');
-        }
-        const patchFiles = filesByPatch.get(patch.filename) ?? new Set();
-        filesByPatch.set(patch.filename, patchFiles);
-        for (const rawFile of assignment.files) {
-            const file = normalizeEngineRelativeInput(rawFile, '--scan-files');
-            const previousOwner = ownerByFile.get(file);
-            if (previousOwner !== undefined && previousOwner !== patch.filename) {
-                throw new InvalidArgumentError(`--scan-files path is assigned to more than one patch: ${file} (${previousOwner}, ${patch.filename})`, '--scan-files');
-            }
-            ownerByFile.set(file, patch.filename);
-            patchFiles.add(file);
-        }
-    }
-    return new Map([...filesByPatch.entries()].map(([patchFilename, files]) => [patchFilename, [...files].sort()]));
-}
-/**
- * Fingerprints every piece of state a `re-export --dry-run` promises not to
- * disturb: the engine's commit + working-tree status (via the same
- * generation token `fireforge test` uses) and the byte content of every
- * regular file under `patches/`. That covers all of them, not just the
- * selected patches, because a dry-run of patch B can revert a just-written
- * export of patch A.
- *
- * A missing patches directory (ENOENT/ENOTDIR) fingerprints as empty, since
- * there is nothing there to protect. Any other listing failure (EACCES, EIO,
- * …) throws: an unreadable directory is not evidence it is empty, and
- * treating it as such lets the guard silently vouch for state it never saw.
- * The same rule covers an unmeasurable engine generation and an unreadable
- * individual patch file. A before-pass failure aborts the dry run before it
- * starts, since a guard that measured nothing cannot vouch for anything.
- */
-async function fingerprintDryRunState(engineDir, patchesDir) {
-    const fingerprint = new Map();
-    const generation = await snapshotEngineGeneration(engineDir);
-    if (isUnavailableGenerationToken(generation)) {
-        // A failed probe measured nothing. Hashing the failure token would let
-        // two identical failures compare "unchanged" (vouching for unmeasured
-        // state) and two differing messages report a spurious violation.
-        throw new GeneralError(`[dry-run] cannot fingerprint the engine working tree for the purity guard: ` +
-            unavailableGenerationReason(generation));
-    }
-    fingerprint.set('the engine working tree', sha256Hex(generation));
-    let names = [];
-    try {
-        const entries = await readdir(patchesDir, { withFileTypes: true });
-        names = entries
-            .filter((entry) => entry.isFile())
-            .map((entry) => entry.name)
-            .sort();
-    }
-    catch (error) {
-        // No patches directory, so nothing there to protect. The same condition
-        // on the post-run pass produces the same empty set, and a directory that
-        // appears mid-dry-run correctly reports as a violation. Any other failure
-        // must not read as "empty": the guard would be vouching for state it
-        // never saw.
-        const code = getNodeErrorCode(error);
-        if (code !== 'ENOENT' && code !== 'ENOTDIR') {
-            throw new GeneralError(`[dry-run] cannot fingerprint ${patchesDir} for the purity guard: ${toError(error).message}`, error);
-        }
-    }
-    const results = await mapWithConcurrency(names, PATCH_HASH_CONCURRENCY, async (name) => {
-        try {
-            return {
-                hash: sha256Hex(await readFile(join(patchesDir, name))),
-            };
-        }
-        catch (error) {
-            // A file that vanished between the listing and the read is omitted, so
-            // a dry run that deleted a patch artifact reports as the violation it
-            // is (key present before, absent after) instead of hiding behind a
-            // fingerprinting error. Every other failure fails closed: a constant
-            // placeholder would make unreadable-before equal unreadable-after even
-            // when the bytes changed underneath.
-            const code = getNodeErrorCode(error);
-            if (code === 'ENOENT' || code === 'ENOTDIR')
-                return { vanished: true };
-            return { error };
-        }
-    });
-    for (const [index, name] of names.entries()) {
-        const result = results[index];
-        if (result === undefined)
-            continue;
-        if ('error' in result) {
-            throw new GeneralError(`[dry-run] cannot fingerprint ${join(patchesDir, name)} for the purity guard: ${toError(result.error).message}`, result.error);
-        }
-        if ('vanished' in result)
-            continue;
-        fingerprint.set(`patches/${name}`, result.hash);
-    }
-    return fingerprint;
-}
-/**
- * Runtime enforcement of the dry-run purity contract: fingerprints the engine
- * tree and every patch artifact before and after `operation`, and throws when
- * a dry-run changed anything it promised only to inspect. That turns a
- * "dry-run reverted a just-written export" incident into a hard, named
- * failure instead of silent data loss discovered only when a later gate
- * fails. The post-fingerprint runs whether `operation` resolves or rejects,
- * because a dry-run that mutates state and then fails is exactly the case
- * where a rollback defect must not go unreported. A rejection with a purity
- * violation surfaces the violation with the original error as `cause`.
- * No-op outside dry-run.
- */
-export async function withDryRunPurityGuard(engineDir, patchesDir, isDryRun, operation, scope) {
-    if (!isDryRun)
-        return operation();
-    const fingerprint = () => scope === undefined
-        ? fingerprintDryRunState(engineDir, patchesDir)
-        : fingerprintScopedDryRunState(engineDir, patchesDir, scope);
-    const startedAt = Date.now();
-    const before = await fingerprint();
-    let result;
-    let operationError;
-    let failed = false;
-    try {
-        result = await operation();
-    }
-    catch (error) {
-        failed = true;
-        operationError = error;
-    }
-    let after;
-    try {
-        after = await fingerprint();
-    }
-    catch (fingerprintError) {
-        // The post-run fingerprint failing must not swallow the dry run's own
-        // failure: an operation that mutated state, broke it, and made it
-        // unreadable is exactly the case where both facts matter. The combined
-        // message carries both. The operation error stays the `cause`.
-        if (failed) {
-            throw new GeneralError(`[dry-run] this dry run failed (${toError(operationError).message}), and its purity could ` +
-                `not be verified afterwards: ${toError(fingerprintError).message}. Inspect engine/ and ` +
-                'your patches/ diff before trusting them.', operationError);
-        }
-        throw fingerprintError;
-    }
-    const touched = [...new Set([...before.keys(), ...after.keys()])]
-        .sort()
-        .filter((key) => before.get(key) !== after.get(key));
-    if (touched.length > 0) {
-        const also = failed ? ` The dry run also failed: ${toError(operationError).message}` : '';
-        const writers = await describeForeignWriters(patchesDir, startedAt);
-        if (writers.length > 0) {
-            throw new GeneralError(`[dry-run] ${touched.join(', ')} changed during this dry run, written by another ` +
-                `writer: ${writers.join('; ')}. The preview raced that write; rerun it once the ` +
-                `writer is done.${also}`, operationError);
-        }
-        throw new GeneralError(`[dry-run] invariant violated: ${touched.join(', ')} changed during this dry run. No ` +
-            'other FireForge command recorded a write in that window, so either another writer ' +
-            '(an editor, an agent or a git command in engine/) changed it, or this is a FireForge ' +
-            'bug. Rerun the dry run; if it repeats on a quiet tree, please report it, and inspect ' +
-            'the listed state (e.g. `git status` in engine/ and your patches/ diff) before ' +
-            'trusting it.' +
-            also, operationError);
-    }
-    if (failed)
-        throw operationError;
-    return result;
-}
-/** Serializes dry-run re-export git inspection against the same project tree. */
-export async function withDryRunReExportLock(fireforgeDir, isDryRun, operation) {
-    if (!isDryRun)
-        return operation();
-    const lockPath = createSiblingLockPath(join(fireforgeDir, 're-export-dry-run'), '.lock');
-    return withFileLock(lockPath, operation, {
-        timeoutMs: 24 * 60 * 60 * 1000,
-        onTimeoutMessage: `Timed out waiting for the FireForge re-export dry-run lock at ${lockPath}. ` +
-            'If no other `fireforge re-export --dry-run` is running, remove the lock directory and retry.',
-        onStaleLockMessage: (ageMs) => `Removing stale FireForge re-export dry-run lock (age: ${Math.round(ageMs / 1000)}s). A previous dry-run process may have crashed.`,
-    });
-}