@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -20,18 +20,20 @@
  *   (`refreshQueueCtxEntry`), so later iterations of an `--all` run lint
  *   against the just-refreshed body instead of the stale one.
  */
-import { buildPatchQueueContext, countNonBinaryDiffLines, detectNewFilesInDiff, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { buildPatchQueueContext, detectNewFilesInDiff, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, measurePatchSize, resolvePatchSizeTier, } from '../core/patch-lint.js';
 import { buildPerPatchLintCacheKey, getCachedPerPatchLintIssues, getPerPatchLintCacheHeadSha, loadPerPatchLintCache, savePerPatchLintCache, setCachedPerPatchLintIssues, } from '../core/patch-lint-cache.js';
 import { invalidateNewFileCreatorsCache } from '../core/patch-lint-cross.js';
+import { lintIgnoreCacheTokens } from '../core/patch-lint-ignore.js';
 import { resolvePatchOwnedSysMjs } from '../core/patch-lint-ownership.js';
 import { computeProjectedLintRegressions } from '../core/patch-lint-projection.js';
 import { GeneralError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
 import { reportPatchLintOutcome } from './export-shared.js';
+import { formatForwardImportRemedy } from './forward-import-remedy.js';
 import { buildPerRunCheckJs } from './lint-per-run-checkjs.js';
 import { projectEntryBody } from './patch/entry-projection.js';
-import { formatForwardImportRemedy } from './re-export-scan.js';
+import { categoryOf, manifestFromQueue } from './re-export-scan.js';
 /**
  * Builds the once-per-invocation lint context.
  *
@@ -135,7 +137,7 @@ export async function lintReExportedPatch(args) {
             queueContext: patchQueueCtx,
             ...(lintCtx.engineHeadSha === undefined ? {} : { engineHeadSha: lintCtx.engineHeadSha }),
         });
-        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey, args.ignoreChecks);
+        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey, lintIgnoreCacheTokens(args.ignoreChecks));
         if (cached) {
             lintCtx.reusedCacheEntries++;
             reportPatchLintOutcome([...globalIssues, ...cached.issues], args.skipLint);
@@ -167,8 +169,10 @@ export async function lintReExportedPatch(args) {
     else if (patchQueueCtx) {
         lintOptions.checkJsReportScope = resolvePatchOwnedSysMjs(detectNewFilesInDiff(diffContent));
     }
+    const patchSize = await measurePatchSize(paths.engine, diffContent, existingFiles, config);
     const issues = await lintExportedPatch(paths.engine, existingFiles, diffContent, config, {
         ...lintOptions,
+        patchSizeMeasurement: patchSize,
         ...(patchQueueCtx ? { patchQueueCtx } : {}),
         ...(args.ignoreChecks ? { ignoreChecks: args.ignoreChecks } : {}),
         ...(args.patchTier ? { patchTier: args.patchTier } : {}),
@@ -177,8 +181,8 @@ export async function lintReExportedPatch(args) {
     return {
         issues,
         suppressed: suppressedIssues,
-        lineCount: countNonBinaryDiffLines(diffContent).textLines,
-        lintIgnore: [...(args.ignoreChecks ?? [])],
+        lineCount: patchSize.lines,
+        lintIgnore: lintIgnoreCacheTokens(args.ignoreChecks),
     };
 }
 /**
@@ -236,10 +240,11 @@ export function assertRefreshedBodyHasNoNewQueueErrors(args) {
     const projectedEntries = ctx.entries.map((entry) => entry.filename === patchFilename ? { ...entry, ...projection } : entry);
     const isError = (issue) => issue.severity === 'error';
     const baseline = lintPatchQueue(ctx).filter(isError);
-    const projected = lintPatchQueue({
-        entries: projectedEntries,
-        ...(ctx.patchPolicy ? { patchPolicy: ctx.patchPolicy } : {}),
-    }).filter(isError);
+    // The whole context carries over (patchPolicy and the
+    // `patchLint.forwardRegistration` scope): dropping the scope here let a
+    // forward jar.mn registration pass this gate and surface only in the
+    // later queue audit, separately from the forward import it packages.
+    const projected = lintPatchQueue({ ...ctx, entries: projectedEntries }).filter(isError);
     const regressions = computeProjectedLintRegressions(baseline, projected);
     if (regressions.length === 0) {
         if (baseline.length > 0 && !lintCtx.queueBaselineWarned) {
@@ -253,7 +258,15 @@ export function assertRefreshedBodyHasNoNewQueueErrors(args) {
     const hasForwardImport = regressions.some((issue) => issue.check === 'forward-import');
     const message = `Refusing to re-export ${patchFilename} because the refreshed body introduces ` +
         `${regressions.length} new cross-patch lint error${regressions.length === 1 ? '' : 's'}:\n${details}` +
-        (hasForwardImport ? `\n${formatForwardImportRemedy('re-running the re-export')}` : '');
+        (hasForwardImport
+            ? `\n${formatForwardImportRemedy({
+                reRunHint: 're-running the re-export',
+                issues: regressions,
+                manifest: manifestFromQueue(ctx),
+                config: lintCtx.config,
+                ...categoryOf(ctx, patchFilename),
+            })}`
+            : '');
     if (forceUnsafe) {
         warn(message);
         warn('Proceeding because --force-unsafe was provided.');

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

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { InvalidArgumentError } from '../errors/base.js';
 import { info } from '../utils/logger.js';
+import { validateScanFileOwners } from './re-export-scan-owner.js';
 /**
  * Heuristic for `--files` positional folding: an extra positional that
  * contains a path separator and is not a `.patch` filename is an engine
@@ -62,6 +63,39 @@ function validateWhitelistFlagDependencies(options) {
         options.refuseAdjacentUnmanaged !== true) {
         throw new InvalidArgumentError('--expect-unmanaged names approved exceptions to --refuse-adjacent-unmanaged and has no effect without it. Pass --refuse-adjacent-unmanaged, or drop --expect-unmanaged.', '--expect-unmanaged');
     }
+    for (const [flag, values] of [
+        ['--expect-new', options.expectNew],
+        ['--adjacent-ignore', options.adjacentIgnore],
+    ]) {
+        if (values !== undefined && values.length > 0 && options.refuseAdjacentUnmanaged !== true) {
+            throw new InvalidArgumentError(`${flag} relaxes --refuse-adjacent-unmanaged and has no effect without it. Pass --refuse-adjacent-unmanaged, or drop ${flag}.`, flag);
+        }
+    }
+    if (options.adjacentIgnore?.some((entry) => entry.includes('**'))) {
+        throw new InvalidArgumentError('--adjacent-ignore takes a path or a glob whose * stays within one path segment; ** is refused, because a subtree carve-out is how a reviewed exception becomes a blanket one.', '--adjacent-ignore');
+    }
+}
+/**
+ * Refuses a path-valued flag whose value starts with `-`. Commander hands a
+ * required option value whatever follows it, so a list that ended early
+ * (`--expect-unmanaged --dry-run`) silently turned the next flag into a path
+ * and the dry run into a write. No engine path starts with a dash.
+ */
+function validatePathFlagValues(options) {
+    for (const [flag, values] of [
+        ['--expect', options.expect],
+        ['--expect-unmanaged', options.expectUnmanaged],
+        ['--expect-new', options.expectNew],
+        ['--expect-removed', options.expectRemoved],
+        ['--adjacent-ignore', options.adjacentIgnore],
+        ['--scan-file', options.scanFiles],
+    ]) {
+        const swallowed = (values ?? []).filter((value) => value.trim().startsWith('-'));
+        if (swallowed.length > 0) {
+            throw new InvalidArgumentError(`${flag} was given ${swallowed.map((value) => `"${value}"`).join(', ')}, which is a flag, not an engine path: ` +
+                `the ${flag} before it had no value, so it took the next argument. Give every ${flag} a path.`, flag);
+        }
+    }
 }
 function validateExpectedRemovalUsage(patches, options) {
     if (options.expectRemoved?.length &&
@@ -69,9 +103,37 @@ function validateExpectedRemovalUsage(patches, options) {
         throw new InvalidArgumentError('--expect-removed requires explicit selected patches and the scan-less path (no --scan, --files, or --all).', '--expect-removed');
     }
 }
+/**
+ * `--hunks-from` and `--exclude-hunks` rebuild one patch's files from named
+ * hunks, so they take exactly one explicit patch and no flag that sets the
+ * file list another way.
+ */
+function validateHunkSelectionUsage(patches, options) {
+    if (options.hunksFrom !== undefined && options.excludeHunks !== undefined) {
+        throw new InvalidArgumentError('--hunks-from and --exclude-hunks are alternatives; pass one.', '--hunks-from');
+    }
+    const flag = options.hunksFrom !== undefined
+        ? '--hunks-from'
+        : options.excludeHunks !== undefined
+            ? '--exclude-hunks'
+            : undefined;
+    if (flag === undefined)
+        return;
+    if (patches.length !== 1 ||
+        options.all ||
+        options.scan ||
+        options.files !== undefined ||
+        options.scanFilesManifest !== undefined) {
+        throw new InvalidArgumentError(`${flag} rebuilds one patch's files from named hunks: pass exactly one patch, without --scan, --files or --all.`, flag);
+    }
+}
 /** Validates mutually exclusive `re-export` targeting and metadata options. */
 export function validateReExportOptionCombinations(patches, options) {
+    // First: a swallowed flag would otherwise surface as whichever
+    // combination error it happens to trip, naming the wrong problem.
+    validatePathFlagValues(options);
     validateExpectedRemovalUsage(patches, options);
+    validateHunkSelectionUsage(patches, options);
     if (options.files !== undefined) {
         if (options.all || options.scan) {
             throw new InvalidArgumentError('--files cannot be combined with --scan or --all.', '--files');
@@ -91,9 +153,10 @@ export function validateReExportOptionCombinations(patches, options) {
         if (options.scanFilesManifest !== undefined) {
             throw new InvalidArgumentError('--scan-file cannot be combined with --scan-files.', '--scan-file');
         }
-        if (options.all || patches.length !== 1) {
-            throw new InvalidArgumentError('--scan-file operates on exactly one target patch. Pass a single patch identifier.', '--scan-file');
+        if (options.all) {
+            throw new InvalidArgumentError('--scan-file cannot be combined with --all. Pass the target patch identifiers.', '--scan-file');
         }
+        validateScanFileOwners(patches, options.scanFiles);
     }
     if (options.scanFilesManifest !== undefined) {
         if (!options.scan)
@@ -102,11 +165,16 @@ export function validateReExportOptionCombinations(patches, options) {
             throw new InvalidArgumentError('--scan-files selects patches from its manifest and cannot be combined with positional patches or --all.', '--scan-files');
         }
     }
-    if (options.refuseAdjacentUnmanaged === true && (options.scan || options.files !== undefined)) {
-        throw new InvalidArgumentError('--refuse-adjacent-unmanaged applies to the scan-less path only and cannot be combined with --scan or --files (those set filesAffected explicitly).', '--refuse-adjacent-unmanaged');
+    // Beside --scan the belt judges the neighbours the scan did not adopt;
+    // --files replaces the file list outright, so there is nothing to judge.
+    if (options.refuseAdjacentUnmanaged === true && options.files !== undefined) {
+        throw new InvalidArgumentError('--refuse-adjacent-unmanaged cannot be combined with --files (it sets filesAffected explicitly).', '--refuse-adjacent-unmanaged');
     }
-    if (options.refuseForeignDrift === true && (options.scan || options.files !== undefined)) {
-        throw new InvalidArgumentError('--refuse-foreign-drift applies to the scan-less path only and cannot be combined with --scan or --files (those explicitly capture the current engine state).', '--refuse-foreign-drift');
+    // Beside --scan the belt covers the files each patch already owns; the
+    // files a scan adopts are the run's stated intent. --files replaces the
+    // file list outright, so there is no owned set left to guard.
+    if (options.refuseForeignDrift === true && options.files !== undefined) {
+        throw new InvalidArgumentError('--refuse-foreign-drift cannot be combined with --files (it sets filesAffected explicitly and captures the current engine state).', '--refuse-foreign-drift');
     }
     validateWhitelistFlagDependencies(options);
     const usingTierFlag = options.tier !== undefined;

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

@@ -0,0 +1,23 @@
+import type { ReExportOptions } from '../types/commands/index.js';
+/**
+ * Reads a path list file: one engine-relative path per line, blank lines
+ * and `#` comment lines ignored. Backs `--expect-from`, which exists because
+ * a list held in one shell variable reaches the CLI as one argument under
+ * zsh, and splitting it by hand left every path after the first as a
+ * positional patch name.
+ *
+ * @param file - The list file, relative to the working directory
+ * @param flag - Flag name for error messages
+ */
+export declare function readPathListFile(file: string, flag: string): Promise<string[]>;
+/**
+ * Runs every lock-free argument check: empty or unknown patch names
+ * (naming an engine file passed by mistake), option combinations, path
+ * flag values that are flags, and path flag values that name no changed
+ * file. Throws the refusal the locked run would have thrown, only sooner.
+ *
+ * @param projectRoot - Project root
+ * @param patches - Positional patch arguments as given
+ * @param options - Options as the command layer builds them
+ */
+export declare function preflightReExportArguments(projectRoot: string, patches: readonly string[], options: ReExportOptions): Promise<void>;

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

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Argument checks `fireforge re-export` runs before it queues for the
+ * engine session lock.
+ *
+ * Under contention the lock wait runs to many minutes, and an argument the
+ * run was always going to refuse (an empty patch name from an unquoted
+ * `"$@"`, a changed-file path passed as a positional, a path flag that
+ * swallowed the next flag) used to be reported only after that wait. These
+ * checks read the manifest and a path-scoped `git status` without the lock.
+ * The command repeats its own resolution under the lock, so a manifest that
+ * changes in between is still read fresh there.
+ */
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { getProjectPaths } from '../core/config.js';
+import { isGitRepository } from '../core/git.js';
+import { chunkPathspecs } from '../core/git-base.js';
+import { getDirtyFiles } from '../core/git-status.js';
+import { formatPatchNotFoundError } from '../core/patch-identifier-suggest.js';
+import { loadPatchesManifest, resolvePatchIdentifier } from '../core/patch-manifest.js';
+import { InvalidArgumentError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { pathExists } from '../utils/fs.js';
+import { normalizeReExportFilesPositionals, validateReExportOptionCombinations, } from './re-export-options.js';
+import { normalizeEngineRelativeInput } from './re-export-scan.js';
+import { splitScanFileOwner } from './re-export-scan-owner.js';
+/**
+ * Reads a path list file: one engine-relative path per line, blank lines
+ * and `#` comment lines ignored. Backs `--expect-from`, which exists because
+ * a list held in one shell variable reaches the CLI as one argument under
+ * zsh, and splitting it by hand left every path after the first as a
+ * positional patch name.
+ *
+ * @param file - The list file, relative to the working directory
+ * @param flag - Flag name for error messages
+ */
+export async function readPathListFile(file, flag) {
+    let text;
+    try {
+        text = await readFile(resolve(file), 'utf8');
+    }
+    catch (error) {
+        throw new InvalidArgumentError(`${flag} could not read ${file}: ${toError(error).message}`, flag);
+    }
+    const paths = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith('#'));
+    if (paths.length === 0) {
+        throw new InvalidArgumentError(`${flag} file ${file} lists no paths. An empty list is usually a generation step that ` +
+            `failed; write one engine-relative path per line, or drop ${flag}.`, flag);
+    }
+    return paths;
+}
+/** Engine-relative form of a positional, or undefined when it cannot be one. */
+function asEnginePath(value) {
+    try {
+        return normalizeEngineRelativeInput(value, 'patch');
+    }
+    catch {
+        return undefined;
+    }
+}
+async function resolvePositionals(engineDir, patches, manifest) {
+    for (const identifier of patches) {
+        if (resolvePatchIdentifier(identifier, manifest.patches))
+            continue;
+        const enginePath = asEnginePath(identifier);
+        if (enginePath !== undefined && (await pathExists(join(engineDir, enginePath)))) {
+            throw new InvalidArgumentError(`"${identifier}" is a file in engine/, not a patch. re-export takes patch identifiers ` +
+                `as positionals. To name a file whose drift this run expects, pass --expect ` +
+                `${enginePath} (one --expect per path), or list the paths one per line in a file ` +
+                'and pass --expect-from <file>.', identifier);
+        }
+        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
+    }
+}
+/**
+ * Refuses a path flag value that names no changed file in engine/. Every
+ * one of these flags is about a changed file (drift to expect, an unmanaged
+ * file to admit, a file to adopt), so a clean or absent path is a typo or a
+ * swallowed argument, and the run would otherwise treat it as a no-op.
+ */
+async function assertFlagPathsInStatus(engineDir, options, manifest) {
+    const normalize = (flag, values) => [
+        flag,
+        (values ?? []).map((value) => normalizeEngineRelativeInput(value, flag)),
+    ];
+    const expectNew = normalize('--expect-new', options.expectNew);
+    const byFlag = [
+        normalize('--expect', options.expect),
+        normalize('--expect-unmanaged', options.expectUnmanaged),
+        expectNew,
+        normalize('--scan-file', options.scanFiles?.map((value) => splitScanFileOwner(value).path)),
+    ];
+    const all = [...new Set(byFlag.flatMap(([, values]) => values))];
+    if (all.length === 0 || !(await isGitRepository(engineDir)))
+        return;
+    const changed = new Set();
+    try {
+        for (const chunk of chunkPathspecs(all)) {
+            for (const file of await getDirtyFiles(engineDir, chunk))
+                changed.add(file);
+        }
+    }
+    catch {
+        // An engine git cannot answer for (no HEAD yet, a broken checkout) is
+        // the locked run's engine precondition to report, with its own remedy.
+        return;
+    }
+    for (const [flag, values] of byFlag) {
+        const absent = values.filter((value) => !changed.has(value));
+        if (absent.length > 0) {
+            throw new InvalidArgumentError(`${flag} names no changed file in engine/: ${absent.join(', ')}. Each value must be a ` +
+                'path git status lists (modified, deleted or untracked); a clean or missing path is a ' +
+                'typo or a list that ended early, and the run would have ignored it.', flag);
+        }
+    }
+    const owners = new Map();
+    for (const patch of manifest.patches) {
+        for (const file of patch.filesAffected)
+            owners.set(file, patch.filename);
+    }
+    const owned = expectNew[1].filter((file) => owners.has(file));
+    if (owned.length > 0) {
+        throw new InvalidArgumentError(`--expect-new names a file a patch already owns: ` +
+            `${owned.map((file) => `${file} (${owners.get(file) ?? ''})`).join(', ')}. ` +
+            '--expect-new is for files no patch owns yet; drop it for these.', '--expect-new');
+    }
+}
+/**
+ * Runs every lock-free argument check: empty or unknown patch names
+ * (naming an engine file passed by mistake), option combinations, path
+ * flag values that are flags, and path flag values that name no changed
+ * file. Throws the refusal the locked run would have thrown, only sooner.
+ *
+ * @param projectRoot - Project root
+ * @param patches - Positional patch arguments as given
+ * @param options - Options as the command layer builds them
+ */
+export async function preflightReExportArguments(projectRoot, patches, options) {
+    const empty = patches.filter((patch) => patch.trim().length === 0).length;
+    if (empty > 0) {
+        throw new InvalidArgumentError(`re-export was given ${empty} empty patch argument(s). An empty argument is usually a ` +
+            'shell expansion that produced nothing (an unquoted "$@" in a heredoc, an unset ' +
+            'variable); pass patch identifiers, or --all.', 'patches');
+    }
+    const normalized = normalizeReExportFilesPositionals(patches, options);
+    validateReExportOptionCombinations(normalized.patches, normalized.options);
+    const paths = getProjectPaths(projectRoot);
+    const manifest = await loadPatchesManifest(paths.patches);
+    // No manifest: the locked run reports that with its own remedy.
+    if (!manifest || manifest.patches.length === 0)
+        return;
+    if (options.all !== true && options.scanFilesManifest === undefined) {
+        await resolvePositionals(paths.engine, normalized.patches, manifest);
+    }
+    await assertFlagPathsInStatus(paths.engine, normalized.options, manifest);
+}

package/dist/src/commands/re-export-purity-scope.d.ts

@@ -0,0 +1,18 @@
+import type { PatchMetadata } from '../types/commands/index.js';
+/** What a scoped dry run could touch: the patches it was asked about. */
+export interface DryRunPurityScope {
+    /** The selected patches. */
+    patches: readonly PatchMetadata[];
+}
+/**
+ * Fingerprints exactly the state a scoped `re-export --dry-run` could
+ * disturb. Every key names what it covers, so a violation reads as the
+ * path that moved.
+ */
+export declare function fingerprintScopedDryRunState(engineDir: string, patchesDir: string, scope: DryRunPurityScope): Promise<Map<string, string>>;
+/**
+ * Names whoever else wrote during the dry run: history records from other
+ * invocations since it started, and a live holder of the engine-session
+ * lock (which a dry run no longer takes). Empty when there is no evidence.
+ */
+export declare function describeForeignWriters(patchesDir: string, sinceMs: number): Promise<string[]>;

package/dist/src/commands/re-export-purity-scope.js

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The scoped half of the `re-export --dry-run` purity guard.
+ *
+ * A dry run takes no engine-session lock since 0.51.0, so peers keep
+ * writing while it runs. The whole-tree fingerprint then reported every
+ * peer's write as "invariant violated … This is a FireForge bug", and an
+ * immediate repeat was clean. The scoped fingerprint covers only what the
+ * dry run could touch: the selected patches' bodies and manifest rows, the
+ * engine files they own, the engine HEAD and the engine index. A mismatch
+ * that remains is attributed to a foreign writer when the history log or
+ * the engine lock shows one in the window.
+ */
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { readEngineSessionLockStatus } from '../core/engine-session-lock.js';
+import { git } from '../core/git-base.js';
+import { historyRecordIdentity, resolveHistoryLogPath } from '../core/history-log-file.js';
+import { PATCHES_MANIFEST } from '../core/patch-manifest-io.js';
+import { GeneralError } from '../errors/base.js';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
+import { sha256Hex } from '../utils/hash.js';
+import { isArray, isObject } from '../utils/validation.js';
+/** Reads a file's bytes as a hash, `absent` when it does not exist. */
+async function hashOrAbsent(path, label) {
+    try {
+        return sha256Hex(await readFile(path));
+    }
+    catch (error) {
+        const code = getNodeErrorCode(error);
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return 'absent';
+        throw new GeneralError(`[dry-run] cannot fingerprint ${label} for the purity guard: ${toError(error).message}`, error);
+    }
+}
+/** The selected rows of `patches.json`, so a peer's write to another row is not a violation. */
+async function selectedRowsFingerprint(patchesDir, filenames) {
+    let raw;
+    try {
+        raw = await readFile(join(patchesDir, PATCHES_MANIFEST), 'utf8');
+    }
+    catch (error) {
+        if (getNodeErrorCode(error) === 'ENOENT')
+            return 'absent';
+        throw error;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const rows = isObject(parsed) && isArray(parsed['patches']) ? parsed['patches'] : [];
+        const selected = rows.filter((row) => isObject(row) && typeof row['filename'] === 'string' && filenames.has(row['filename']));
+        return sha256Hex(JSON.stringify(selected));
+    }
+    catch {
+        // A manifest that no longer parses changed, whoever wrote it.
+        return sha256Hex(raw);
+    }
+}
+/**
+ * Fingerprints exactly the state a scoped `re-export --dry-run` could
+ * disturb. Every key names what it covers, so a violation reads as the
+ * path that moved.
+ */
+export async function fingerprintScopedDryRunState(engineDir, patchesDir, scope) {
+    const fingerprint = new Map();
+    try {
+        fingerprint.set('engine HEAD', (await git(['rev-parse', 'HEAD'], engineDir)).trim());
+        // The index as a whole: the historic purity defect was a transient
+        // `--intent-to-add` entry, which may land on any path a scan reads.
+        fingerprint.set('the engine index', sha256Hex(await git(['ls-files', '--stage', '-z'], engineDir)));
+    }
+    catch (error) {
+        throw new GeneralError(`[dry-run] cannot fingerprint the engine for the purity guard: ${toError(error).message}`, error);
+    }
+    const filenames = new Set(scope.patches.map((patch) => patch.filename));
+    fingerprint.set(`${PATCHES_MANIFEST} rows of ${[...filenames].sort().join(', ')}`, await selectedRowsFingerprint(patchesDir, filenames));
+    for (const filename of [...filenames].sort()) {
+        fingerprint.set(`patches/${filename}`, await hashOrAbsent(join(patchesDir, filename), `patches/${filename}`));
+    }
+    const owned = [...new Set(scope.patches.flatMap((patch) => patch.filesAffected))].sort();
+    for (const file of owned) {
+        fingerprint.set(`engine/${file}`, await hashOrAbsent(join(engineDir, file), `engine/${file}`));
+    }
+    return fingerprint;
+}
+/** History records another invocation wrote at or after `sinceMs`. */
+async function foreignHistoryRecords(projectRoot, sinceMs) {
+    let text;
+    try {
+        text = await readFile(await resolveHistoryLogPath(projectRoot), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const own = historyRecordIdentity().invocationId;
+    const writers = [];
+    for (const line of text.split('\n').slice(-500)) {
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const ts = typeof record.ts === 'string' ? Date.parse(record.ts) : Number.NaN;
+        if (!(ts >= sinceMs) || record.invocationId === own)
+            continue;
+        const session = typeof record.sessionId === 'string' ? `, session ${record.sessionId}` : '';
+        writers.push(`${String(record.operation)} (PID ${String(record.pid)}${session})`);
+    }
+    return writers;
+}
+/**
+ * Names whoever else wrote during the dry run: history records from other
+ * invocations since it started, and a live holder of the engine-session
+ * lock (which a dry run no longer takes). Empty when there is no evidence.
+ */
+export async function describeForeignWriters(patchesDir, sinceMs) {
+    const projectRoot = dirname(resolve(patchesDir));
+    const writers = await foreignHistoryRecords(projectRoot, sinceMs);
+    try {
+        const lock = await readEngineSessionLockStatus(projectRoot);
+        if (lock.held && lock.holder !== undefined && lock.holder.pid !== process.pid) {
+            const detail = lock.holder.metadata.length > 0 ? ` (${lock.holder.metadata.join(', ')})` : '';
+            writers.push(`the engine-session lock holder, PID ${lock.holder.pid}${detail}`);
+        }
+    }
+    catch {
+        // Attribution is best effort; the violation is reported either way.
+    }
+    return writers;
+}