@hominis/fireforge 0.39.0 → 0.41.0

package/dist/src/commands/patch/split.js

@@ -23,6 +23,7 @@ import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { appendHistory, confirmDestructive } from '../../core/destructive.js';
 import { normalizePatchArtifact } from '../../core/patch-artifact-normalize.js';
 import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
+import { buildPatchQueueContext } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, savePatchesManifest, validatePatchesManifest, } from '../../core/patch-manifest.js';
 import { enforcePatchPolicy } from '../../core/patch-policy.js';
@@ -30,7 +31,8 @@ import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { readText, removeFile, writeText } from '../../utils/fs.js';
 import { info, intro, outro, success, warn } from '../../utils/logger.js';
-import { commanderArgParser, pickDefined } from '../../utils/options.js';
+import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../../utils/options.js';
+import { normalizePatchDisplayName } from '../../utils/validation.js';
 import { placementPlansEqual, resolvePlacementPlan } from '../export-flow.js';
 import { runPatchLint } from '../export-shared.js';
 import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, findOwnerRewriteHolders, mergeStagedForwardImports, projectSplitManifest, rewriteSplitOwners, runProjectedSplitLint, } from './split-plan.js';
@@ -156,7 +158,7 @@ export async function commitPatchSplit(patchesDir, plan, newMetadata, options, c
             }
             throw error;
         }
-    });
+    }, { waitLockSeconds: resolveWaitLockSeconds(options.waitLock), command: 'patch split' });
 }
 /**
  * Runs the `patch split` command: plans the split, lints the projection,
@@ -195,6 +197,13 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
             (options.order === undefined && options.before === undefined ? source.filename : undefined),
     });
     const placement = await resolvePlacementPlan(paths.patches, placementOptions, category, options.name, config);
+    // The filename slug pipeline strips redundant category prefixes; the
+    // manifest display name must agree with the bare-slug naming policy,
+    // exactly as `export --name` already does (FORGE G13/H4).
+    const displayName = normalizePatchDisplayName(options.name, category);
+    if (displayName !== options.name) {
+        info(`Patch name normalized: "${options.name}" → "${displayName}" (the filename carries the order and category prefix).`);
+    }
     const plan = {
         source,
         movedFiles,
@@ -204,7 +213,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         placement,
         placementOptions,
         category,
-        name: options.name,
+        name: displayName,
         description: options.description ?? '',
         ownerRewrites: findOwnerRewriteHolders(manifest.patches, source.filename, movedSet),
         // Populated by runProjectedSplitLint below (forward edges into the new patch).
@@ -212,10 +221,14 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
     };
     // Per-patch lint both projected bodies, threading the source patch's
     // tier/lintIgnore so an intentional-advisory patch can still split.
+    // The whole-queue context (built once, with the config for committed-gate
+    // parity) resolves cross-patch imports and sibling head.js harness roots
+    // instead of linting each projected body blind (FORGE I3).
+    const patchQueueCtx = await buildPatchQueueContext(paths.patches, config);
     const ignoreChecks = source.lintIgnore ? new Set(source.lintIgnore) : undefined;
-    await runPatchLint(paths.engine, remainingFiles, remainingDiff, config, options.skipLint, undefined, ignoreChecks, source.tier);
-    await runPatchLint(paths.engine, movedFiles, movedDiff, config, options.skipLint, undefined, ignoreChecks, source.tier);
-    const { conflicts, stagedDependencyAdditions } = await runProjectedSplitLint(paths.patches, plan);
+    await runPatchLint(paths.engine, remainingFiles, remainingDiff, config, options.skipLint, patchQueueCtx, ignoreChecks, source.tier);
+    await runPatchLint(paths.engine, movedFiles, movedDiff, config, options.skipLint, patchQueueCtx, ignoreChecks, source.tier);
+    const { conflicts, stagedDependencyAdditions } = runProjectedSplitLint(plan, patchQueueCtx);
     plan.stagedDependencyAdditions = stagedDependencyAdditions;
     const newMetadata = buildNewPatchMetadata(plan, config);
     enforcePatchPolicy({
@@ -253,7 +266,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
  */
 export function registerPatchSplit(parent, context) {
     const { getProjectRoot, withErrorHandling } = context;
-    parent
+    const command = parent
         .command('split <source>')
         .description('Move files out of a patch into a new patch as one transaction (shrink + create + staged-dependency owner rewrites)')
         .requiredOption('--files <path...>', 'Engine-relative files to move from the source patch to the new patch')
@@ -272,8 +285,8 @@ export function registerPatchSplit(parent, context) {
         .option('--dry-run', 'Show what would happen without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
         .option('--force-unsafe', 'Bypass projected-lint refusals')
-        .option('--skip-lint', 'Skip per-patch lint of the projected bodies')
-        .action(withErrorHandling(async (sourceId, options) => {
+        .option('--skip-lint', 'Skip per-patch lint of the projected bodies');
+    addWaitLockOption(command).action(withErrorHandling(async (sourceId, options) => {
         await patchSplitCommand(getProjectRoot(), sourceId, {
             files: options.files,
             name: options.name,
@@ -287,6 +300,7 @@ export function registerPatchSplit(parent, context) {
                 yes: options.yes,
                 forceUnsafe: options.forceUnsafe,
                 skipLint: options.skipLint,
+                waitLock: options.waitLock,
             }),
         });
     }));

package/dist/src/commands/patch/staged-dependency-validate.d.ts

@@ -0,0 +1,15 @@
+import type { PatchMetadata } from '../../types/commands/index.js';
+/** The declaration fields common to both staged-dependency kinds. */
+interface StagedDependencyShape {
+    file: string;
+    creates: string;
+    owner?: string;
+}
+/**
+ * Validates the `--add` declaration fields against the loaded queue.
+ * Throws on a clear flag mixup; warns (only) when `--owner` is
+ * well-formed but absent from the queue, because the owner may
+ * legitimately be exported moments later and renumbering rewrites owners.
+ */
+export declare function validateStagedDependencyAdd(dependency: StagedDependencyShape, queuePatches: readonly PatchMetadata[]): void;
+export {};

package/dist/src/commands/patch/staged-dependency-validate.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shape validation for `patch staged-dependency --add` (FORGE K10).
+ *
+ * `--creates`/`--file` take engine-relative FILE paths and `--owner`
+ * takes a patch FILENAME, but all three were accepted as arbitrary
+ * strings — a `--creates <patch-name>` mixup produced a declaration
+ * nothing could ever discharge, surfacing only later as a
+ * `staged-dependency-unused` warning. Refusals here fire only on a clear
+ * patch-name shape (slash-free values that end in `.patch` or match a
+ * queue patch filename/stem): legitimate engine paths always contain a
+ * `/`, so deep paths can never false-positive.
+ */
+import { InvalidArgumentError } from '../../errors/base.js';
+import { warn } from '../../utils/logger.js';
+function matchQueuePatch(value, queuePatches) {
+    return queuePatches.find((patch) => patch.filename === value || patch.filename === `${value}.patch`)?.filename;
+}
+function refusePatchShapedPath(flag, value, role, queuePatches) {
+    if (value.includes('/'))
+        return;
+    const matched = matchQueuePatch(value, queuePatches);
+    if (matched === undefined && !value.endsWith('.patch'))
+        return;
+    const evidence = matched !== undefined ? `matches patch ${matched} in the queue` : 'looks like a patch filename';
+    throw new InvalidArgumentError(`${flag} takes ${role} (e.g. browser/components/foo/Foo.sys.mjs), not a patch name — ` +
+        `"${value}" ${evidence}. If you meant to name the owning patch, pass it with --owner.`, flag);
+}
+/**
+ * Validates the `--add` declaration fields against the loaded queue.
+ * Throws on a clear flag mixup; warns (only) when `--owner` is
+ * well-formed but absent from the queue, because the owner may
+ * legitimately be exported moments later and renumbering rewrites owners.
+ */
+export function validateStagedDependencyAdd(dependency, queuePatches) {
+    refusePatchShapedPath('--creates', dependency.creates, 'the engine-relative path of the file a later patch creates', queuePatches);
+    refusePatchShapedPath('--file', dependency.file, 'the engine-relative file containing the declaring site inside this patch', queuePatches);
+    const owner = dependency.owner;
+    if (owner === undefined)
+        return;
+    if (owner.includes('/') || !owner.endsWith('.patch')) {
+        throw new InvalidArgumentError(`--owner names the owning patch artifact (e.g. 012-infra-foo.patch); ` +
+            `"${owner}" does not look like a patch filename. The created file path goes in --creates.`, '--owner');
+    }
+    if (!queuePatches.some((patch) => patch.filename === owner)) {
+        warn(`--owner ${owner} matches no patch currently in the queue. The declaration only ` +
+            'discharges once a patch with exactly this filename creates the --creates path.');
+    }
+}

package/dist/src/commands/patch/staged-dependency.js

@@ -10,35 +10,47 @@ import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
+import { validateStagedDependencyAdd } from './staged-dependency-validate.js';
+/** Joins the names of the missing flags for error attribution (FORGE G12). */
+function missingFlagList(pairs) {
+    return pairs
+        .filter(([, value]) => value === undefined || value === '')
+        .map(([flag]) => flag)
+        .join(', ');
+}
 function modeFromOptions(options) {
     const adding = options.add === true;
     const removing = options.remove === true;
     const clearing = options.clear === true;
     const modeCount = [adding, removing, clearing].filter(Boolean).length;
     if (modeCount > 1) {
-        throw new InvalidArgumentError('--add, --remove, and --clear are mutually exclusive. Pick one mode per invocation.', 'patch staged-dependency');
+        throw new InvalidArgumentError('--add, --remove, and --clear are mutually exclusive. Pick one mode per invocation.', '--add/--remove/--clear');
     }
     if (modeCount === 0) {
-        throw new InvalidArgumentError('Specify --add, --remove, or --clear.', 'patch staged-dependency');
+        throw new InvalidArgumentError('Specify --add, --remove, or --clear.', '--add/--remove/--clear');
     }
     return adding ? 'add' : removing ? 'remove' : 'clear';
 }
 function kindFromOptions(options) {
     const kind = options.kind ?? 'import';
     if (kind !== 'import' && kind !== 'registration') {
-        throw new InvalidArgumentError(`--kind must be "import" or "registration" (got "${kind}").`, 'patch staged-dependency');
+        throw new InvalidArgumentError(`--kind must be "import" or "registration" (got "${kind}").`, '--kind');
     }
     if (kind === 'import' && options.line !== undefined) {
-        throw new InvalidArgumentError('--line only applies to --kind registration; import declarations use --specifier.', 'patch staged-dependency');
+        throw new InvalidArgumentError('--line only applies to --kind registration; import declarations use --specifier.', '--line');
     }
     if (kind === 'registration' && options.specifier !== undefined) {
-        throw new InvalidArgumentError('--specifier only applies to --kind import; registration declarations use --line.', 'patch staged-dependency');
+        throw new InvalidArgumentError('--specifier only applies to --kind import; registration declarations use --line.', '--specifier');
     }
     return kind;
 }
-function requireForwardImportOptions(options, mode) {
+function requireForwardImportOptions(options) {
     if (!options.file || !options.specifier || !options.creates) {
-        throw new InvalidArgumentError(`--${mode} requires --file, --specifier, and --creates.`, 'patch staged-dependency');
+        throw new InvalidArgumentError('--add requires --file, --specifier, and --creates.', missingFlagList([
+            ['--file', options.file],
+            ['--specifier', options.specifier],
+            ['--creates', options.creates],
+        ]));
     }
     const dependency = {
         file: options.file,
@@ -51,9 +63,13 @@ function requireForwardImportOptions(options, mode) {
         dependency.reason = options.reason;
     return dependency;
 }
-function requireRegistrationOptions(options, mode) {
+function requireRegistrationOptions(options) {
     if (!options.file || !options.line || !options.creates) {
-        throw new InvalidArgumentError(`--${mode} --kind registration requires --file, --line, and --creates.`, 'patch staged-dependency');
+        throw new InvalidArgumentError('--add --kind registration requires --file, --line, and --creates.', missingFlagList([
+            ['--file', options.file],
+            ['--line', options.line],
+            ['--creates', options.creates],
+        ]));
     }
     const dependency = {
         file: options.file,
@@ -66,6 +82,70 @@ function requireRegistrationOptions(options, mode) {
         dependency.reason = options.reason;
     return dependency;
 }
+/**
+ * Resolves the `--remove` target for forward-imports (FORGE G12):
+ * `--file` + `--specifier` suffice when they identify at most one staged
+ * entry — `--creates` is inferred from a unique match, an ambiguous match
+ * refuses with the candidate list, and no match falls through to the
+ * honest "no staged forward-import matched" summary.
+ */
+function resolveImportRemovalTarget(options, staged) {
+    if (!options.file || !options.specifier) {
+        throw new InvalidArgumentError('--remove requires --file and --specifier; --creates is only needed to disambiguate when several staged entries share them.', missingFlagList([
+            ['--file', options.file],
+            ['--specifier', options.specifier],
+        ]));
+    }
+    if (options.creates) {
+        return requireForwardImportOptions(options);
+    }
+    const { file, specifier } = options;
+    const candidates = (staged?.forwardImports ?? []).filter((entry) => entry.file === file &&
+        entry.specifier === specifier &&
+        (options.owner === undefined || entry.owner === options.owner));
+    const single = candidates.length === 1 ? candidates[0] : undefined;
+    if (single !== undefined) {
+        info(`Inferred --creates ${single.creates} from the single matching staged entry.`);
+        return { ...single };
+    }
+    if (candidates.length > 1) {
+        const list = candidates
+            .map((entry) => `  - ${dependencyLabel('import', importView(entry))}`)
+            .join('\n');
+        throw new GeneralError(`--remove matches ${String(candidates.length)} staged forward-imports on this patch; ` +
+            `pass --creates to pick one:\n${list}`);
+    }
+    return { file, specifier, creates: '(no match)' };
+}
+/** Registration twin of {@link resolveImportRemovalTarget}, keyed on `--line`. */
+function resolveRegistrationRemovalTarget(options, staged) {
+    if (!options.file || !options.line) {
+        throw new InvalidArgumentError('--remove --kind registration requires --file and --line; --creates is only needed to disambiguate when several staged entries share them.', missingFlagList([
+            ['--file', options.file],
+            ['--line', options.line],
+        ]));
+    }
+    if (options.creates) {
+        return requireRegistrationOptions(options);
+    }
+    const { file, line } = options;
+    const candidates = (staged?.registrations ?? []).filter((entry) => entry.file === file &&
+        entry.line === line &&
+        (options.owner === undefined || entry.owner === options.owner));
+    const single = candidates.length === 1 ? candidates[0] : undefined;
+    if (single !== undefined) {
+        info(`Inferred --creates ${single.creates} from the single matching staged entry.`);
+        return { ...single };
+    }
+    if (candidates.length > 1) {
+        const list = candidates
+            .map((entry) => `  - ${dependencyLabel('registration', registrationView(entry))}`)
+            .join('\n');
+        throw new GeneralError(`--remove matches ${String(candidates.length)} staged registrations on this patch; ` +
+            `pass --creates to pick one:\n${list}`);
+    }
+    return { file, line, creates: '(no match)' };
+}
 function importView(dependency) {
     return { ...dependency, matcher: dependency.specifier };
 }
@@ -137,17 +217,35 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     intro(isDryRun ? 'FireForge patch staged-dependency (dry run)' : 'FireForge patch staged-dependency');
     const mode = modeFromOptions(options);
     const kind = kindFromOptions(options);
-    const importDependency = mode === 'clear' || kind !== 'import' ? undefined : requireForwardImportOptions(options, mode);
+    // The patch queue loads BEFORE the declaration fields resolve so
+    // `--remove` can infer `--creates` from the target patch's staged
+    // entries (FORGE G12).
+    const { paths, manifest } = await requirePatchQueue(projectRoot);
+    const targetPatch = requirePatchTarget(identifier, manifest.patches);
+    const importDependency = mode === 'clear' || kind !== 'import'
+        ? undefined
+        : mode === 'add'
+            ? requireForwardImportOptions(options)
+            : resolveImportRemovalTarget(options, targetPatch.stagedDependencies);
     const registrationDependency = mode === 'clear' || kind !== 'registration'
         ? undefined
-        : requireRegistrationOptions(options, mode);
+        : mode === 'add'
+            ? requireRegistrationOptions(options)
+            : resolveRegistrationRemovalTarget(options, targetPatch.stagedDependencies);
+    // Shape-check --add declarations against the loaded queue (FORGE K10):
+    // a patch-name-shaped --creates/--file is refused HERE instead of
+    // surfacing later as an undischargeable staged-dependency-unused.
+    if (mode === 'add') {
+        const added = importDependency ?? registrationDependency;
+        if (added !== undefined) {
+            validateStagedDependencyAdd(added, manifest.patches);
+        }
+    }
     const target = importDependency !== undefined
         ? importView(importDependency)
         : registrationDependency !== undefined
             ? registrationView(registrationDependency)
             : undefined;
-    const { paths, manifest } = await requirePatchQueue(projectRoot);
-    const targetPatch = requirePatchTarget(identifier, manifest.patches);
     const applyToStaged = (staged) => {
         if (mode === 'clear')
             return {};
@@ -219,7 +317,7 @@ export function registerPatchStagedDependency(parent, context) {
         .option('--owner <patch>', 'Exact later patch filename expected to create --creates')
         .option('--reason <text>', 'Human-readable rationale stored with the declaration')
         .option('--dry-run', 'Show what would change without writing')
-        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .option('-y, --yes', 'Record scripted consent in the destructive-operation history log. This command never prompts; the flag exists for workflow uniformity with commands that do.')
         .action(withErrorHandling(async (name, options) => {
         await patchStagedDependencyCommand(getProjectRoot(), name, options);
     }));

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

@@ -0,0 +1,34 @@
+import type { getProjectPaths } from '../core/config.js';
+import type { PatchesManifest, PatchMetadata } from '../types/commands/index.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;
+    refusals: {
+        patchFilename: string;
+        files: string[];
+    }[];
+}
+/** Returns the subset of `files` that no longer exist under `engineDir`. */
+export declare function findMissingFiles(engineDir: string, files: readonly string[]): Promise<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: ReturnType<typeof getProjectPaths>;
+    manifest: PatchesManifest;
+    currentFilesAffected: readonly string[];
+    ctx: AdjacentUnmanagedContext;
+}): Promise<boolean>;

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

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Scan-less re-export adjacency advisory (FORGE G2). 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.
+ *
+ * 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';
+/** 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;
+}
+async function findAdjacentUnmanagedFiles(args) {
+    const { currentFilesAffected, engineDir, manifest, patchFilename, ctx } = args;
+    const parentDirs = [...new Set(currentFilesAffected.map((file) => dirname(file)))];
+    const currentSet = new Set(currentFilesAffected);
+    const claimedByOthers = getClaimedFiles(manifest, patchFilename);
+    const candidates = new Set();
+    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 (currentSet.has(file) || claimedByOthers.has(file))
+                continue;
+            if (isToolManagedPath(file, untrackedSet.has(file), ctx))
+                continue;
+            candidates.add(file);
+        }
+    }
+    return [...candidates].sort();
+}
+/**
+ * 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 = 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 unmanagedFiles = await findAdjacentUnmanagedFiles({
+        currentFilesAffected,
+        engineDir: paths.engine,
+        manifest,
+        patchFilename: patch.filename,
+        ctx,
+    });
+    if (unmanagedFiles.length === 0)
+        return false;
+    const firstFew = unmanagedFiles.slice(0, 3).join(', ');
+    const more = unmanagedFiles.length > 3 ? `, +${String(unmanagedFiles.length - 3)} more` : '';
+    warn(`${patch.filename}: found ${String(unmanagedFiles.length)} unmanaged file(s) adjacent to this patch's ownership (${firstFew}${more}); plain re-export keeps filesAffected unchanged — use --scan-file to include reviewed files.`);
+    for (const file of unmanagedFiles) {
+        info(`  ${file} — fireforge re-export ${patch.filename} --scan --scan-file ${file}`);
+    }
+    if (ctx.refuseAdjacentUnmanaged) {
+        ctx.refusals.push({ patchFilename: patch.filename, files: unmanagedFiles });
+        return true;
+    }
+    return false;
+}

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

@@ -1,5 +1,18 @@
 import type { PatchesManifest } from '../types/commands/index.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 (FORGE H1): 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. This
+ * turns any recurrence of the 0.40.0 "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 — 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>): 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>;