@hominis/fireforge 0.52.0 → 0.53.0

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

@@ -21,6 +21,22 @@ import { warn } from '../../utils/logger.js';
 import {} from '../export-flow.js';
 import { projectEntryBody } from './entry-projection.js';
 import { describeStagedMaintenance, findDeclarationsMadeUnused, keptRelocatedDeclarations, relocatedSourceDeclarations, rewriteSplitOwners, withoutRelocatedDeclarations, } from './split-staged.js';
+/**
+ * The `reason` a move records on a forward declaration it writes, so the
+ * declaration explains itself in `patches.json` and `staged-dependency
+ * --add --from` accepts it without a hand-written `--reason`.
+ *
+ * @param source - Patch the files left
+ * @param destination - Patch the files moved into
+ * @param operation - The command that moved them
+ */
+export function moveDeclarationReason(source, destination, operation) {
+    return `${source} → ${destination} by ${operation}`;
+}
+/** The {@link moveDeclarationReason} of a split plan. */
+export function splitDeclarationReason(plan) {
+    return moveDeclarationReason(plan.source.filename, plan.placement.newFilename, plan.operation ?? 'patch split');
+}
 /**
  * Refuses the split unless the source patch currently owns every requested
  * file. Splitting out a file the source does not own would produce a new patch
@@ -118,7 +134,7 @@ function buildProjectedSplitEntries(baseCtx, plan) {
  * them once declared. Auto-declaring keeps the two in lock-step and lets a
  * sound split read as sound.
  */
-function computeSplitStagedDependencyAdditions(projectedEntries, newFilename) {
+function computeSplitStagedDependencyAdditions(projectedEntries, newFilename, reason) {
     const additions = new Map();
     for (const edge of collectForwardImportEdges({ entries: projectedEntries })) {
         if (edge.owner !== newFilename)
@@ -128,6 +144,7 @@ function computeSplitStagedDependencyAdditions(projectedEntries, newFilename) {
             specifier: edge.specifier,
             creates: edge.creates,
             owner: newFilename,
+            reason,
         };
         const list = additions.get(edge.entry) ?? [];
         const dup = list.some((d) => d.file === decl.file &&
@@ -179,15 +196,14 @@ export function runProjectedSplitLint(plan, baseCtx) {
     const projectedEntries = buildProjectedSplitEntries(baseCtx, plan);
     // Discover and auto-declare the forward edges this split introduces into
     // the new patch, then inject them before linting so they resolve.
-    const stagedDependencyAdditions = computeSplitStagedDependencyAdditions(projectedEntries, plan.placement.newFilename);
+    const stagedDependencyAdditions = computeSplitStagedDependencyAdditions(projectedEntries, plan.placement.newFilename, splitDeclarationReason(plan));
     injectStagedDependencyAdditions(projectedEntries, stagedDependencyAdditions);
     const baselineAll = lintPatchQueue(baseCtx);
-    const projectedAll = lintPatchQueue({
-        entries: projectedEntries,
-        // Keep the projection patch-policy-aware whenever the baseline is, so
-        // computeProjectedLintRegressions compares symmetric rule sets.
-        ...(baseCtx.patchPolicy ? { patchPolicy: baseCtx.patchPolicy } : {}),
-    });
+    // Keep every queue-wide lint setting of the baseline (patch policy,
+    // forward-registration scope, token scales), so
+    // computeProjectedLintRegressions compares symmetric rule sets and a
+    // test-manifest suite entry is projected as the committed gate sees it.
+    const projectedAll = lintPatchQueue({ ...baseCtx, entries: projectedEntries });
     const baselineIssues = baselineAll.filter((i) => i.severity === 'error');
     const projectedIssues = projectedAll.filter((i) => i.severity === 'error');
     const oldNameByNew = new Map([...plan.placement.renameMap].map(([oldName, entry]) => [entry.newFilename, oldName]));
@@ -257,6 +273,12 @@ export function buildSplitSummary(plan) {
     const summary = [
         `split ${plan.source.filename}`,
         `moved files (${plan.movedFiles.length}): ${plan.movedFiles.join(', ')}`,
+        ...(plan.adoptedFiles?.length
+            ? [
+                `of which adopted from the worktree (no patch owned them) (${plan.adoptedFiles.length}): ` +
+                    plan.adoptedFiles.join(', '),
+            ]
+            : []),
         `source keeps (${plan.remainingFiles.length}): ${plan.remainingFiles.join(', ')}`,
         `new patch: ${plan.placement.newFilename} (order ${plan.placement.insertionOrder})`,
     ];
@@ -274,9 +296,11 @@ export function buildSplitSummary(plan) {
 }
 /**
  * Maps a declaration the split projection proposes back onto the queue as
- * it stands: renumbered patches take their current names, and an owner
- * that is the patch the split would create is dropped (it does not exist
- * until the split runs).
+ * it stands: renumbered patches take their current names. An owner that is
+ * the patch the split would create keeps the planned filename, so the
+ * report declares the owner the rerun creates (`staged-dependency --add`
+ * accepts an owner the queue does not hold yet, and the move then lands
+ * with the declaration already right).
  */
 export function splitDeclarationRenamer(plan) {
     const oldNameByNew = new Map([...plan.placement.renameMap].map(([oldName, entry]) => [entry.newFilename, oldName]));
@@ -284,6 +308,6 @@ export function splitDeclarationRenamer(plan) {
     return ({ owner, ...declaration }) => ({
         ...declaration,
         patch: current(declaration.patch),
-        ...(owner !== plan.placement.newFilename ? { owner: current(owner) } : {}),
+        owner: owner === plan.placement.newFilename ? owner : current(owner),
     });
 }

package/dist/src/commands/patch/split-staged.d.ts

@@ -14,8 +14,8 @@
  *    the imported file landed in one patch) is dropped
  *    ({@link findDeclarationsMadeUnused}).
  *
- * Without this the move wrote the bodies and left the queue audit and the
- * per-patch lint to report `queue-dependency-creates-unowned` and
+ * Without this the move would write the bodies and leave the queue audit
+ * and the per-patch lint to report `queue-dependency-creates-unowned` and
  * `staged-dependency-unused` afterwards, one `--remove`/`--add` pair per
  * entry to repair by hand.
  */

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

@@ -15,8 +15,8 @@
  *    the imported file landed in one patch) is dropped
  *    ({@link findDeclarationsMadeUnused}).
  *
- * Without this the move wrote the bodies and left the queue audit and the
- * per-patch lint to report `queue-dependency-creates-unowned` and
+ * Without this the move would write the bodies and leave the queue audit
+ * and the per-patch lint to report `queue-dependency-creates-unowned` and
  * `staged-dependency-unused` afterwards, one `--remove`/`--add` pair per
  * entry to repair by hand.
  */

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

@@ -36,8 +36,10 @@ import { normalizePatchDisplayName, parsePositiveIntegerFlag } from '../../utils
 import { withDeclarationsReport } from '../declarations-report.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { placementPlansEqual, resolvePlacementPlan } from '../export-flow.js';
-import { runPatchLint } from '../export-shared.js';
-import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, mergeStagedForwardImports, projectSplitManifest, runProjectedSplitLint, splitDeclarationRenamer, } from './split-plan.js';
+import { writeRenameMapFile } from '../patch-rename-map.js';
+import { assertAdoptedStillUnowned } from './move-files-adopt.js';
+import { runMoveSideLint } from './move-size-tier.js';
+import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, mergeStagedForwardImports, projectSplitManifest, runProjectedSplitLint, splitDeclarationReason, splitDeclarationRenamer, } from './split-plan.js';
 import { describeStagedMaintenance, emptyStagedMaintenance, findOwnerRewriteHolders, rewriteSplitOwners, withoutDroppedDeclarations, withoutRelocatedDeclarations, } from './split-staged.js';
 /**
  * History payload for the declarations a split re-homed or dropped, omitted
@@ -79,6 +81,7 @@ export async function commitPatchSplit(patchesDir, plan, newMetadata, options, c
         if (!current || current.filesAffected.join('\n') !== plan.source.filesAffected.join('\n')) {
             throw new InvalidArgumentError('Patch queue changed while waiting for split confirmation. Re-run the command.', 'patch split');
         }
+        assertAdoptedStillUnowned(manifest.patches, plan.adoptedFiles, 'patch split');
         const currentPlacement = await resolvePlacementPlan(patchesDir, plan.placementOptions, plan.category, plan.name, config);
         if (!placementPlansEqual(currentPlacement, plan.placement)) {
             throw new InvalidArgumentError('Patch queue changed while waiting for split confirmation. Re-run the command.', 'patch split');
@@ -266,9 +269,11 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
     // instead of linting each projected body blind.
     const patchQueueCtx = await buildPatchQueueContext(paths.patches, config);
     const ignoreChecks = buildLintIgnoreChecks(source.lintIgnore);
-    await runPatchLint({
+    await runMoveSideLint({
         engineDir: paths.engine,
         filesAffected: remainingFiles,
+        filesBefore: source.filesAffected,
+        role: 'source',
         diffContent: remainingDiff,
         config,
         skipLint: options.skipLint,
@@ -276,9 +281,10 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         ignoreChecks,
         patchTier: source.tier,
     });
-    await runPatchLint({
+    await runMoveSideLint({
         engineDir: paths.engine,
         filesAffected: movedFiles,
+        role: 'new patch',
         diffContent: movedDiff,
         config,
         skipLint: options.skipLint,
@@ -294,6 +300,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         regressions: projected.regressions,
         out: options.declarationsOut,
         rename: splitDeclarationRenamer(plan),
+        reason: splitDeclarationReason(plan),
     });
     const newMetadata = buildNewPatchMetadata(plan, config);
     const decision = await confirmDestructive({
@@ -308,6 +315,10 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
     if (!proceedAfterDecision(decision, 'Split cancelled'))
         return;
     await commitPatchSplit(paths.patches, plan, newMetadata, options, config);
+    if (options.mapOut !== undefined) {
+        const written = await writeRenameMapFile(options.mapOut, plan.placement.renameMap);
+        info(`Wrote the old-to-new filename map (${plan.placement.renameMap.size} rename(s)) to ${written}`);
+    }
     success(`Split ${source.filename}: ${placement.newFilename} now owns ${plan.movedFiles.length} file(s)`);
     reportSplitStagedChanges(plan);
     outro('Split complete');
@@ -331,7 +342,8 @@ export function registerPatchSplit(parent, context) {
         .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')
-        .option('--declarations-out <path>', 'Where a refusal writes its one --from-ready staged-declaration report (default: .fireforge/declarations/<timestamp>.json)');
+        .option('--declarations-out <path>', 'Where a refusal writes its one --from-ready staged-declaration report (default: .fireforge/declarations/<timestamp>.json)')
+        .option('--map-out <file>', 'Write the old-to-new filename map of the patches the split renumbers as JSON');
     addWaitLockOption(command).action(withErrorHandling(async (sourceId, options) => {
         await patchSplitCommand(getProjectRoot(), sourceId, {
             files: options.files,
@@ -347,6 +359,7 @@ export function registerPatchSplit(parent, context) {
                 forceUnsafe: options.forceUnsafe,
                 skipLint: options.skipLint,
                 declarationsOut: options.declarationsOut,
+                mapOut: options.mapOut,
                 waitLock: options.waitLock,
             }),
         });

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

@@ -29,8 +29,16 @@ export declare function registrationView(dependency: PatchStagedRegistration): S
 export declare function dependencyLabel(kind: StagedDependencyKind, view: StagedEntryView): string;
 /**
  * Applies one add/remove/clear to a declaration list: `add` appends unless
- * an entry with the same file, matcher, creates and owner exists.
+ * an entry with the same file, matcher, creates and owner exists. A
+ * matching entry whose `reason` differs from the addition's takes
+ * the new reason in place, keeping its position in the list; an addition
+ * without a reason leaves the existing one alone.
  */
 export declare function applyMode<T>(existing: readonly T[], mode: StagedDependencyMode, target: StagedEntryView | undefined, toView: (entry: T) => StagedEntryView, addition: T | undefined): T[];
+/**
+ * Number of declarations in `after` whose key matches one in `before` but
+ * whose `reason` differs: the in-place reason updates of an `--add`.
+ */
+export declare function countReasonUpdates(before: PatchStagedDependencies | undefined, after: PatchStagedDependencies | undefined): number;
 /** Number of declarations of both kinds. */
 export declare function countStagedEntries(staged: PatchStagedDependencies | undefined): number;

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

@@ -32,7 +32,10 @@ function matchesTarget(view, target) {
 }
 /**
  * Applies one add/remove/clear to a declaration list: `add` appends unless
- * an entry with the same file, matcher, creates and owner exists.
+ * an entry with the same file, matcher, creates and owner exists. A
+ * matching entry whose `reason` differs from the addition's takes
+ * the new reason in place, keeping its position in the list; an addition
+ * without a reason leaves the existing one alone.
  */
 export function applyMode(existing, mode, target, toView, addition) {
     if (mode === 'clear')
@@ -41,10 +44,35 @@ export function applyMode(existing, mode, target, toView, addition) {
         return [...existing];
     if (mode === 'remove')
         return existing.filter((entry) => !matchesTarget(toView(entry), target));
-    const seen = new Set(existing.map((entry) => dependencyKey(toView(entry))));
-    if (seen.has(dependencyKey(target)) || addition === undefined)
+    if (addition === undefined)
         return [...existing];
-    return [...existing, addition];
+    const key = dependencyKey(target);
+    const index = existing.findIndex((entry) => dependencyKey(toView(entry)) === key);
+    if (index === -1)
+        return [...existing, addition];
+    const current = existing[index];
+    if (target.reason === undefined || toView(current).reason === target.reason) {
+        return [...existing];
+    }
+    const next = [...existing];
+    next[index] = addition;
+    return next;
+}
+/**
+ * Number of declarations in `after` whose key matches one in `before` but
+ * whose `reason` differs: the in-place reason updates of an `--add`.
+ */
+export function countReasonUpdates(before, after) {
+    const updates = (left, right, toView) => {
+        const reasons = new Map((left ?? []).map((entry) => [dependencyKey(toView(entry)), toView(entry).reason]));
+        return (right ?? []).filter((entry) => {
+            const view = toView(entry);
+            const key = dependencyKey(view);
+            return reasons.has(key) && reasons.get(key) !== view.reason;
+        }).length;
+    };
+    return (updates(before?.forwardImports, after?.forwardImports, importView) +
+        updates(before?.registrations, after?.registrations, registrationView));
 }
 /** Number of declarations of both kinds. */
 export function countStagedEntries(staged) {

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

@@ -12,7 +12,7 @@ import { info, outro } from '../../utils/logger.js';
 import { resolveWaitLockSeconds } from '../../utils/options.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 import { readStagedDependencyBatch, stagedDependencyDelta, } from './staged-dependency-batch.js';
-import { applyMode, countStagedEntries, importView, registrationView, } from './staged-dependency-entries.js';
+import { applyMode, countReasonUpdates, countStagedEntries, importView, registrationView, } from './staged-dependency-entries.js';
 import { validateStagedDependencyAdd } from './staged-dependency-validate.js';
 /** Flags that describe one declaration and so cannot combine with `--from`. */
 const SINGLE_DECLARATION_FLAGS = [
@@ -23,7 +23,10 @@ const SINGLE_DECLARATION_FLAGS = [
     ['--creates', 'creates'],
     ['--owner', 'owner'],
 ];
-/** Adds every `--from` declaration not already present, keyed like a single `--add`. */
+/**
+ * Adds every `--from` declaration not already present, keyed like a single
+ * `--add`; a present one whose `reason` differs takes the new reason in place.
+ */
 function mergeBatch(staged, batch) {
     let forwardImports = [...(staged?.forwardImports ?? [])];
     for (const entry of batch.forwardImports) {
@@ -68,13 +71,16 @@ export async function runBatchAdd(projectRoot, identifier, mode, options) {
         return;
     }
     const existing = targetPatch.stagedDependencies;
-    const projectedCount = countStagedEntries(mergeBatch(existing, batch));
-    const describe = (beforeCount, afterCount) => `added ${afterCount - beforeCount} of ${supplied} staged declaration(s) from ${from}` +
-        (supplied > afterCount - beforeCount
-            ? ` (${supplied - (afterCount - beforeCount)} already present or repeated)`
-            : '');
+    const describe = (before, after) => {
+        const added = countStagedEntries(after) - countStagedEntries(before);
+        const updated = countReasonUpdates(before, after);
+        const unchanged = supplied - added - updated;
+        return (`added ${added} of ${supplied} staged declaration(s) from ${from}` +
+            (updated > 0 ? `, updated the reason of ${updated}` : '') +
+            (unchanged > 0 ? ` (${unchanged} already present or repeated)` : ''));
+    };
     if (options.dryRun === true) {
-        info(`[dry-run] ${targetPatch.filename}: ${describe(countStagedEntries(existing), projectedCount)}.`);
+        info(`[dry-run] ${targetPatch.filename}: ${describe(existing, mergeBatch(existing, batch))}.`);
         outro('Dry run complete — no changes made');
         return;
     }
@@ -92,7 +98,7 @@ export async function runBatchAdd(projectRoot, identifier, mode, options) {
     }
     const before = result.before.stagedDependencies;
     const after = result.after.stagedDependencies;
-    info(`${targetPatch.filename}: ${describe(countStagedEntries(before), countStagedEntries(after))}.`);
+    info(`${targetPatch.filename}: ${describe(before, after)}.`);
     await appendHistoryBestEffort(paths.patches, {
         operation: 'patch-staged-dependency',
         args: {

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

@@ -11,7 +11,7 @@ import { info, intro, outro } from '../../utils/logger.js';
 import { addWaitLockOption, resolveWaitLockSeconds } from '../../utils/options.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 import { stagedDependencyDelta } from './staged-dependency-batch.js';
-import { applyMode, countStagedEntries, dependencyLabel, importView, registrationView, } from './staged-dependency-entries.js';
+import { applyMode, countReasonUpdates, countStagedEntries, dependencyLabel, importView, registrationView, } from './staged-dependency-entries.js';
 import { runBatchAdd } from './staged-dependency-from.js';
 import { selectRemovalEntries } from './staged-dependency-remove.js';
 import { validateStagedDependencyAdd } from './staged-dependency-validate.js';
@@ -89,7 +89,9 @@ function requireRegistrationOptions(options) {
 /**
  * Renders a one-line summary of a staged-dependency metadata change.
  */
-function describeStagedDependencyChange(beforeCount, afterCount, mode, kind, targets) {
+function describeStagedDependencyChange(before, after, mode, kind, targets) {
+    const beforeCount = countStagedEntries(before);
+    const afterCount = countStagedEntries(after);
     const noun = kind === 'import' ? 'staged forward-import' : 'staged registration';
     if (mode === 'clear') {
         return beforeCount === 0
@@ -100,9 +102,11 @@ function describeStagedDependencyChange(beforeCount, afterCount, mode, kind, tar
     if (targets.length === 0)
         return 'stagedDependencies unchanged';
     if (mode === 'add') {
-        return afterCount === beforeCount
-            ? `${noun} already present: ${label}`
-            : `added ${noun}: ${label}`;
+        if (afterCount !== beforeCount)
+            return `added ${noun}: ${label}`;
+        return countReasonUpdates(before, after) > 0
+            ? `updated 1 ${noun} reason in place: ${label}`
+            : `${noun} already present: ${label}`;
     }
     return afterCount === beforeCount
         ? `no ${noun} matched: ${label}`
@@ -132,7 +136,7 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     const importDependency = mode === 'add' && kind === 'import' ? requireForwardImportOptions(options) : undefined;
     const registrationDependency = mode === 'add' && kind === 'registration' ? requireRegistrationOptions(options) : undefined;
     // Shape-check --add declarations against the loaded queue: a
-    // patch-name-shaped --creates/--file is refused now instead of surfacing
+    // patch-name-shaped --creates/--file is refused here instead of surfacing
     // later as an undischargeable staged-dependency-unused.
     const added = importDependency ?? registrationDependency;
     if (added !== undefined) {
@@ -164,7 +168,7 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     };
     const existing = targetPatch.stagedDependencies;
     const projected = applyToStaged(existing);
-    const summary = describeStagedDependencyChange(countStagedEntries(existing), countStagedEntries(projected), mode, kind, targets);
+    const summary = describeStagedDependencyChange(existing, projected, mode, kind, targets);
     if (isDryRun) {
         info(`[dry-run] ${targetPatch.filename}: ${summary}.`);
         outro('Dry run complete — no changes made');
@@ -184,7 +188,7 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     }
     const before = result.before.stagedDependencies;
     const after = result.after.stagedDependencies;
-    info(`${targetPatch.filename}: ${describeStagedDependencyChange(countStagedEntries(before), countStagedEntries(after), mode, kind, targets)}.`);
+    info(`${targetPatch.filename}: ${describeStagedDependencyChange(before, after, mode, kind, targets)}.`);
     if (mode === 'remove' && countStagedEntries(after) === countStagedEntries(before)) {
         // The selection matched when the queue was read; a peer removed the
         // entries before the locked write. Still a miss, so still a refusal.
@@ -225,7 +229,7 @@ export function registerPatchStagedDependency(parent, context) {
         .option('--line <text>', 'Registration/packaging line as the patch adds it, compared whitespace-insensitively (--kind registration)')
         .option('--creates <path>', 'Later-created file path relative to engine/ (with --remove and no --file: removes every declaration for that path)')
         .option('--owner <patch>', 'Exact later patch filename expected to create --creates')
-        .option('--reason <text>', 'Human-readable rationale stored with the declaration (with --from: the default for entries without one)')
+        .option('--reason <text>', 'Human-readable rationale stored with the declaration; --add on a declaration already present replaces its reason in place (with --from: the default for entries without one)')
         .option('--from <json-file>', 'Add every declaration in a JSON file under one lock hold (--add only): a "lint --per-patch --report" ' +
         "document (its findings' stagedDeclarations for this patch) or an array of " +
         '{ file, specifier | line, creates, owner?, reason?, patch? } entries')

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

@@ -63,8 +63,8 @@ export async function patchTierCommand(projectRoot, identifier, options = {}) {
             : `change tier from "${before}" to "${after}"`;
     // Destructive-operation contract (docs/lifecycle-invariants.md): manifest
     // metadata mutations get summary + dry-run + confirmation/--yes + history
-    // uniformly. This command used to accept --yes without ever prompting, so
-    // the flag only appeared in the history record.
+    // uniformly, so --yes skips a real prompt rather than only appearing in
+    // the history record.
     const decision = await confirmDestructive({
         operation: 'patch-tier',
         title: `Patch tier: ${target.filename}`,

package/dist/src/commands/patch-rename-map.d.ts

@@ -1,9 +1,8 @@
 /**
  * Structural equality for patch rename maps, shared by the placement-mode
  * export preview/commit check (`export-flow.ts`) and `patch reorder`'s
- * under-lock drift check. Both previously carried a byte-identical copy of
- * the sorted-entries comparison. One helper keeps the two commit gates from
- * drifting.
+ * under-lock drift check. One helper for the sorted-entries comparison
+ * keeps the two commit gates from drifting.
  */
 import type { PatchRenameEntry } from '../core/patch-manifest.js';
 /**
@@ -17,3 +16,15 @@ export declare function getSortedRenameEntries(renameMap: Map<string, PatchRenam
  * triple matches positionally.
  */
 export declare function renameMapsEqual(left: Map<string, PatchRenameEntry>, right: Map<string, PatchRenameEntry>): boolean;
+/**
+ * Writes a committed rename map as one JSON object, old filename to new
+ * filename in the queue's new order (`{}` when nothing was renumbered), so
+ * a session can rewrite its references to the renumbered patches from the
+ * file instead of from the printed summary. Used by `patch reorder
+ * --map-out` and `patch split --map-out`.
+ *
+ * @param path - Output path, relative to the working directory
+ * @param renameMap - The committed rename map
+ * @returns The absolute path written
+ */
+export declare function writeRenameMapFile(path: string, renameMap: Map<string, PatchRenameEntry>): Promise<string>;

package/dist/src/commands/patch-rename-map.js

@@ -2,10 +2,11 @@
 /**
  * Structural equality for patch rename maps, shared by the placement-mode
  * export preview/commit check (`export-flow.ts`) and `patch reorder`'s
- * under-lock drift check. Both previously carried a byte-identical copy of
- * the sorted-entries comparison. One helper keeps the two commit gates from
- * drifting.
+ * under-lock drift check. One helper for the sorted-entries comparison
+ * keeps the two commit gates from drifting.
  */
+import { dirname, resolve } from 'node:path';
+import { ensureDir, writeJson } from '../utils/fs.js';
 /**
  * Rename-map entries ordered by target order, so previews, history entries
  * and equality checks all walk the queue in its final on-disk order.
@@ -34,3 +35,20 @@ export function renameMapsEqual(left, right) {
             leftEntry.newOrder === rightEntry.newOrder);
     });
 }
+/**
+ * Writes a committed rename map as one JSON object, old filename to new
+ * filename in the queue's new order (`{}` when nothing was renumbered), so
+ * a session can rewrite its references to the renumbered patches from the
+ * file instead of from the printed summary. Used by `patch reorder
+ * --map-out` and `patch split --map-out`.
+ *
+ * @param path - Output path, relative to the working directory
+ * @param renameMap - The committed rename map
+ * @returns The absolute path written
+ */
+export async function writeRenameMapFile(path, renameMap) {
+    const absolute = resolve(path);
+    await ensureDir(dirname(absolute));
+    await writeJson(absolute, Object.fromEntries(getSortedRenameEntries(renameMap).map(([from, entry]) => [from, entry.newFilename])));
+    return absolute;
+}

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

@@ -62,11 +62,10 @@ export declare function findMissingFiles(engineDir: string, files: readonly stri
 /**
  * One unmanaged file and the owned directory that made it adjacent.
  *
- * The anchor is what an unattended run could not previously recover: the
- * notice named the offending file and the patch, but not which of the
- * patch's owned locations the file sits beside, so triaging a refusal on a
- * patch that owns files in several directories meant re-deriving the
- * adjacency by hand from the manifest.
+ * 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. */

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

@@ -108,9 +108,10 @@ export declare function storeReExportLintResult(lintCtx: ReExportLintContext, pa
  * when the projection introduces error-severity cross-patch findings the
  * current queue does not have (a forward import an earlier owner gained,
  * say). Mirrors `re-export --files` (its projected-state conflict) and the
- * `--scan` adoption gate, which only covered files a scan adopted: a plain
- * re-export of an unchanged file set with new CONTENT used to pass, and the
- * queue carried the error until the next `export` placement refused it.
+ * `--scan` adoption gate, which only covers files a scan adopted: without
+ * this a plain re-export of an unchanged file set with new CONTENT would
+ * pass, and the queue would carry the error until the next `export`
+ * placement refused it.
  *
  * Runs in dry-run. `--force-unsafe` downgrades the refusal to warnings;
  * `--skip-lint` does not bypass it, same as `--files`. The baseline is the

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

@@ -221,9 +221,10 @@ export async function storeReExportLintResult(lintCtx, patchFilename, projectedM
  * when the projection introduces error-severity cross-patch findings the
  * current queue does not have (a forward import an earlier owner gained,
  * say). Mirrors `re-export --files` (its projected-state conflict) and the
- * `--scan` adoption gate, which only covered files a scan adopted: a plain
- * re-export of an unchanged file set with new CONTENT used to pass, and the
- * queue carried the error until the next `export` placement refused it.
+ * `--scan` adoption gate, which only covers files a scan adopted: without
+ * this a plain re-export of an unchanged file set with new CONTENT would
+ * pass, and the queue would carry the error until the next `export`
+ * placement refused it.
  *
  * Runs in dry-run. `--force-unsafe` downgrades the refusal to warnings;
  * `--skip-lint` does not bypass it, same as `--files`. The baseline is the

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

@@ -6,8 +6,7 @@
  * 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.
+ * swallowed the next flag) is reported before 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.
  */

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

@@ -13,6 +13,6 @@ export declare function fingerprintScopedDryRunState(engineDir: string, patchesD
 /**
  * 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.
+ * lock (which a dry run does not take). 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

@@ -2,10 +2,9 @@
 /**
  * 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
+ * A dry run takes no engine-session lock, so peers keep writing while it
+ * runs. A whole-tree fingerprint would report every peer's write as
+ * "invariant violated … This is a FireForge bug". 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
@@ -17,6 +16,7 @@ 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 { canonicalizePatchRow } from '../core/patch-manifest-key-order.js';
 import { GeneralError } from '../errors/base.js';
 import { getNodeErrorCode, toError } from '../utils/errors.js';
 import { sha256Hex } from '../utils/hash.js';
@@ -33,7 +33,11 @@ async function hashOrAbsent(path, label) {
         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. */
+/**
+ * The selected rows of `patches.json`, so a peer's write to another row is
+ * not a violation. Rows are hashed in canonical key order: a peer's write
+ * that only canonicalizes a selected row's key order changes no content.
+ */
 async function selectedRowsFingerprint(patchesDir, filenames) {
     let raw;
     try {
@@ -47,7 +51,9 @@ async function selectedRowsFingerprint(patchesDir, filenames) {
     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']));
+        const selected = rows
+            .filter((row) => isObject(row) && typeof row['filename'] === 'string' && filenames.has(row['filename']))
+            .map((row) => (isObject(row) ? canonicalizePatchRow(row) : row));
         return sha256Hex(JSON.stringify(selected));
     }
     catch {
@@ -112,7 +118,7 @@ async function foreignHistoryRecords(projectRoot, sinceMs) {
 /**
  * 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.
+ * lock (which a dry run does not take). Empty when there is no evidence.
  */
 export async function describeForeignWriters(patchesDir, sinceMs) {
     const projectRoot = dirname(resolve(patchesDir));

package/dist/src/commands/re-export-retired-declarations.d.ts

@@ -0,0 +1,22 @@
+import type { PatchesManifest, PatchMetadata, ReExportOptions } from '../types/commands/index.js';
+import type { ProjectPaths } from '../types/config.js';
+/** What {@link dropRetiredPathDeclarations} needs from the run. */
+export interface RetiredPathDeclarationsArgs {
+    /** Resolved project paths. */
+    paths: ProjectPaths;
+    /** The queue as the run loaded it (judged in a dry run). */
+    manifest: PatchesManifest;
+    /** The run's options; `expectRemoved` holds the validated paths. */
+    options: ReExportOptions;
+    /** The run's selected patches. */
+    selectedPatches: readonly PatchMetadata[];
+    /** Name the drops without writing. */
+    isDryRun: boolean;
+}
+/**
+ * Drops (or, in a dry run, names) every staged declaration whose `creates`
+ * path this run retired. Runs after the selected patches are written, so a
+ * path whose owner failed to re-export is still owned and its declarations
+ * stay.
+ */
+export declare function dropRetiredPathDeclarations(args: RetiredPathDeclarationsArgs): Promise<void>;