@hominis/fireforge 0.52.0 → 0.54.0

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

@@ -11,9 +11,9 @@ 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 { declarationNoun, inferRemovalKinds, selectRemovalEntries, } from './staged-dependency-remove.js';
 import { validateStagedDependencyAdd } from './staged-dependency-validate.js';
 /** Joins the names of the missing flags for error attribution. */
 function missingFlagList(pairs) {
@@ -89,20 +89,25 @@ function requireRegistrationOptions(options) {
 /**
  * Renders a one-line summary of a staged-dependency metadata change.
  */
-function describeStagedDependencyChange(beforeCount, afterCount, mode, kind, targets) {
-    const noun = kind === 'import' ? 'staged forward-import' : 'staged registration';
+function describeStagedDependencyChange(before, after, mode, kinds, targets) {
+    const beforeCount = countStagedEntries(before);
+    const afterCount = countStagedEntries(after);
+    const targetKinds = [...new Set(targets.map((target) => target.kind))];
+    const noun = declarationNoun(targetKinds.length > 0 ? targetKinds : kinds);
     if (mode === 'clear') {
         return beforeCount === 0
             ? 'stagedDependencies was already empty — no change'
             : `cleared ${beforeCount} staged dependency declaration(s)`;
     }
-    const label = targets.map((target) => dependencyLabel(kind, target)).join('; ');
+    const label = targets.map(({ kind, view }) => dependencyLabel(kind, view)).join('; ');
     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}`
@@ -123,7 +128,11 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
         await runBatchAdd(projectRoot, identifier, mode, options);
         return;
     }
-    const kind = kindFromOptions(options);
+    // Without --kind, --remove searches the kind its matcher names, or both.
+    const kinds = (mode === 'remove' ? inferRemovalKinds(options) : undefined) ?? [
+        kindFromOptions(options),
+    ];
+    const kind = kinds.length === 1 ? kinds[0] : undefined;
     // The patch queue loads before the declaration fields resolve so
     // `--remove` can infer `--creates` from the target patch's staged
     // entries.
@@ -132,31 +141,32 @@ 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) {
         validateStagedDependencyAdd(added, manifest.patches);
     }
     const targets = mode === 'remove'
-        ? selectRemovalEntries(kind, options, targetPatch.stagedDependencies)
+        ? selectRemovalEntries(kinds, options, targetPatch.stagedDependencies)
         : importDependency !== undefined
-            ? [importView(importDependency)]
+            ? [{ kind: 'import', view: importView(importDependency) }]
             : registrationDependency !== undefined
-                ? [registrationView(registrationDependency)]
+                ? [{ kind: 'registration', view: registrationView(registrationDependency) }]
                 : [];
-    const applyKind = (entries, own, toView, addition) => {
-        if (!own)
+    const applyKind = (entries, entryKind, toView, addition) => {
+        if (!kinds.includes(entryKind))
             return [...entries];
+        const own = targets.filter((target) => target.kind === entryKind).map(({ view }) => view);
         if (mode !== 'remove')
-            return applyMode(entries, mode, targets[0], toView, addition);
-        return targets.reduce((remaining, target) => applyMode(remaining, 'remove', target, toView, undefined), [...entries]);
+            return applyMode(entries, mode, own[0], toView, addition);
+        return own.reduce((remaining, target) => applyMode(remaining, 'remove', target, toView, undefined), [...entries]);
     };
     const applyToStaged = (staged) => {
         if (mode === 'clear')
             return {};
-        const forwardImports = applyKind(staged?.forwardImports ?? [], kind === 'import', importView, importDependency);
-        const registrations = applyKind(staged?.registrations ?? [], kind === 'registration', registrationView, registrationDependency);
+        const forwardImports = applyKind(staged?.forwardImports ?? [], 'import', importView, importDependency);
+        const registrations = applyKind(staged?.registrations ?? [], 'registration', registrationView, registrationDependency);
         return {
             ...(forwardImports.length > 0 ? { forwardImports } : {}),
             ...(registrations.length > 0 ? { registrations } : {}),
@@ -164,7 +174,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, kinds, targets);
     if (isDryRun) {
         info(`[dry-run] ${targetPatch.filename}: ${summary}.`);
         outro('Dry run complete — no changes made');
@@ -184,7 +194,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, kinds, 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.
@@ -197,7 +207,8 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
         args: {
             filename: targetPatch.filename,
             mode,
-            kind,
+            // A kind-less --remove searched both kinds; the delta names which.
+            ...(kind !== undefined ? { kind } : {}),
             ...stagedDependencyDelta(before, after),
         },
         ...(options.yes === true ? { yes: true } : {}),
@@ -219,13 +230,13 @@ export function registerPatchStagedDependency(parent, context) {
         .option('--add', 'Add a staged dependency declaration')
         .option('--remove', 'Remove matching staged dependency declaration(s); a selection that matches nothing exits 8')
         .option('--clear', 'Drop the stagedDependencies field entirely')
-        .option('--kind <kind>', 'Declaration shape: "import" (forward import, the default) or "registration" (jar.mn packaging line, customElements or actor registration)')
+        .option('--kind <kind>', 'Declaration shape: "import" (forward import, the default) or "registration" (jar.mn packaging line, customElements or actor registration); --remove without it takes the kind --specifier or --line names, or both kinds')
         .option('--file <path>', 'Declaring file path relative to engine/')
         .option('--specifier <specifier>', 'Exact import specifier as it appears in source (--kind import)')
         .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-options.js

@@ -97,10 +97,16 @@ function validatePathFlagValues(options) {
         }
     }
 }
+/**
+ * A retirement names its owner among explicitly selected patches. It
+ * combines with `--scan`: the retired path leaves the scan's base first,
+ * and the scan cannot adopt it back, since a retired created file is absent
+ * and a retired upstream file is clean at HEAD.
+ */
 function validateExpectedRemovalUsage(patches, options) {
     if (options.expectRemoved?.length &&
-        (options.scan || options.all || options.files !== undefined || patches.length === 0)) {
-        throw new InvalidArgumentError('--expect-removed requires explicit selected patches and the scan-less path (no --scan, --files, or --all).', '--expect-removed');
+        (options.all || options.files !== undefined || patches.length === 0)) {
+        throw new InvalidArgumentError('--expect-removed requires explicit selected patches and cannot combine with --files or --all.', '--expect-removed');
     }
 }
 /**

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>;

package/dist/src/commands/re-export-retired-declarations.js

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `re-export --expect-removed` drops the staged declarations whose
+ * `creates` path the run retires.
+ *
+ * Retiring a file would otherwise leave another patch's staged
+ * registration (or forward import) for it in place, unflagged until the
+ * per-patch lint after both re-exports reported `staged-dependency-unused`.
+ * The run that retires the path drops every such declaration, in any patch of the queue, in one manifest
+ * update, and names each one.
+ */
+import { withPatchDirectoryLock } from '../core/patch-lock.js';
+import { loadPatchesManifestForWrite, mutatePatchRowsInManifest } from '../core/patch-manifest.js';
+import { info } from '../utils/logger.js';
+import { recordStagedDeclarationPrune, } from './re-export-stale-registrations.js';
+/**
+ * Finds the declarations whose `creates` path is retired and owned by no
+ * patch outside `retiring`.
+ *
+ * @param manifest - The queue to judge
+ * @param removed - The run's `--expect-removed` paths
+ * @param retiring - Patches whose ownership of a removed path does not
+ *   count: the selected owners in a dry run, whose rows are not rewritten
+ *   yet; nothing after the write, where a failed owner still owns its path
+ */
+function planRetiredDeclarationDrops(manifest, removed, retiring) {
+    const orphaned = new Set(removed.filter((file) => !manifest.patches.some((patch) => !retiring.has(patch.filename) && patch.filesAffected.includes(file))));
+    if (orphaned.size === 0)
+        return [];
+    const drops = [];
+    for (const patch of manifest.patches) {
+        const drop = planHolderDrop(patch, orphaned);
+        if (drop !== undefined)
+            drops.push(drop);
+    }
+    return drops;
+}
+function planHolderDrop(patch, orphaned) {
+    const forwardImports = patch.stagedDependencies?.forwardImports ?? [];
+    const registrations = patch.stagedDependencies?.registrations ?? [];
+    const dropped = [
+        ...registrations
+            .filter((entry) => orphaned.has(entry.creates))
+            .map((entry) => ({ kind: 'registration', ...entry })),
+        ...forwardImports
+            .filter((entry) => orphaned.has(entry.creates))
+            .map((entry) => ({ kind: 'import', ...entry })),
+    ];
+    if (dropped.length === 0)
+        return undefined;
+    const keptImports = forwardImports.filter((entry) => !orphaned.has(entry.creates));
+    const keptRegistrations = registrations.filter((entry) => !orphaned.has(entry.creates));
+    const staged = {
+        ...(keptImports.length > 0 ? { forwardImports: keptImports } : {}),
+        ...(keptRegistrations.length > 0 ? { registrations: keptRegistrations } : {}),
+    };
+    return {
+        holder: patch.filename,
+        dropped,
+        stagedDependencies: Object.keys(staged).length > 0 ? staged : undefined,
+    };
+}
+function reportRetiredDeclarationDrops(drops, isDryRun) {
+    const verb = isDryRun ? 'would drop' : 'drops';
+    for (const { holder, dropped } of drops) {
+        for (const entry of dropped) {
+            const what = entry.kind === 'registration'
+                ? `staged registration ${entry.file} "${entry.line.trim()}"`
+                : `staged forward-import ${entry.file} "${entry.specifier}"`;
+            info(`${holder}: ${verb} ${what}: --expect-removed retires ${entry.creates}.`);
+        }
+    }
+}
+/**
+ * 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 async function dropRetiredPathDeclarations(args) {
+    const { manifest, isDryRun } = args;
+    const patchesDir = args.paths.patches;
+    const removed = args.options.expectRemoved ?? [];
+    const selected = new Set(args.selectedPatches.map((patch) => patch.filename));
+    if (removed.length === 0)
+        return;
+    if (isDryRun) {
+        reportRetiredDeclarationDrops(planRetiredDeclarationDrops(manifest, removed, selected), isDryRun);
+        return;
+    }
+    const drops = await withPatchDirectoryLock(patchesDir, async () => {
+        const current = await loadPatchesManifestForWrite(patchesDir);
+        if (!current)
+            return [];
+        const planned = planRetiredDeclarationDrops(current, removed, new Set());
+        const byHolder = new Map(planned.map((drop) => [drop.holder, drop]));
+        if (byHolder.size === 0)
+            return [];
+        await mutatePatchRowsInManifest(patchesDir, [...byHolder.keys()], (existing) => {
+            const drop = byHolder.get(existing.filename);
+            if (drop === undefined)
+                return null;
+            return drop.stagedDependencies === undefined
+                ? { unset: ['stagedDependencies'] }
+                : { set: { stagedDependencies: drop.stagedDependencies } };
+        });
+        return planned;
+    }, { command: 're-export' });
+    reportRetiredDeclarationDrops(drops, isDryRun);
+    for (const drop of drops) {
+        await recordStagedDeclarationPrune(patchesDir, drop.holder, drop.dropped, 'staged declarations on retired paths');
+    }
+}

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

@@ -23,7 +23,7 @@ import { reportForeignDrift } from './re-export-drift.js';
 import { buildHunkSelectedDiff, hunkSelectionOf } from './re-export-hunks.js';
 import { assertRefreshedBodyHasNoNewQueueErrors, lintReExportedPatch, refreshQueueCtxEntry, storeReExportLintResult, } from './re-export-lint.js';
 import { assertScanAdoptionsHaveNoForwardImports, assertScanFileAdditionsHaveDiffHunks, confirmBroadScanAdditions, scanPatchFilesForReExport, } from './re-export-scan.js';
-import { planStaleRegistrationDrop, recordStaleRegistrationDrop, reportStaleRegistrationDrop, } from './re-export-stale-registrations.js';
+import { findPendingRegistrationCreates, planStaleRegistrationDrop, recordStaleRegistrationDrop, reportStaleRegistrationDrop, } from './re-export-stale-registrations.js';
 const GIT_INDEX_LOCK_RETRY_MS = 300;
 /**
  * Retries a single patch re-export exactly once when the failure is
@@ -211,7 +211,7 @@ async function reExportSinglePatch(args) {
         return false;
     }
     const { updates, ignoreChecks, effectiveTier, existingIgnoreSet, flagIgnoreSet } = computeReExportUpdates(patch, options, currentFilesAffected);
-    const stalePlan = planStaleRegistrationDrop(manifest, patch, currentFilesAffected);
+    const stalePlan = planStaleRegistrationDrop(manifest, patch, currentFilesAffected, await findPendingRegistrationCreates(paths.engine, manifest, patch, currentFilesAffected, adjacentCtx.expectedNew));
     if (stalePlan !== undefined)
         reportStaleRegistrationDrop(patch.filename, stalePlan, isDryRun);
     const unset = applyStaleRegistrationDrop(stalePlan, updates);

package/dist/src/commands/re-export-stale-registrations.d.ts

@@ -1,18 +1,39 @@
-import type { PatchesManifest, PatchMetadata, PatchStagedDependencies, PatchStagedRegistration } from '../types/commands/index.js';
+import type { PatchesManifest, PatchMetadata, PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration } from '../types/commands/index.js';
 /** The holder's registrations split by whether the queue still owns `creates`. */
 export interface StaleRegistrationPlan {
     /** Registrations whose `creates` path no patch owns. */
     dropped: PatchStagedRegistration[];
+    /** Unowned registrations kept because their `creates` file is pending adoption. */
+    pending: PatchStagedRegistration[];
     /** The staged block to write, or undefined when nothing is left. */
     stagedDependencies: PatchStagedDependencies | undefined;
 }
+/**
+ * The unowned `creates` paths of `patch`'s registrations that are pending
+ * adoption: the file exists in `engine/`, or is an `--expect-new` path of
+ * this run. Such a registration is waiting for its subject patch's scan.
+ */
+export declare function findPendingRegistrationCreates(engineDir: string, manifest: PatchesManifest, patch: PatchMetadata, currentFilesAffected: readonly string[], expectedNew: ReadonlySet<string>): Promise<Set<string>>;
 /**
  * Finds `patch`'s registrations whose `creates` path no patch in the queue
- * owns, judging `patch` by the file list this re-export will write.
- * Returns undefined when nothing is stale.
+ * owns, judging `patch` by the file list this re-export will write. A
+ * registration whose `creates` path is in `pending` (see
+ * {@link findPendingRegistrationCreates}) is kept and reported instead.
+ * Returns undefined when nothing is stale or pending.
  */
-export declare function planStaleRegistrationDrop(manifest: PatchesManifest, patch: PatchMetadata, currentFilesAffected: readonly string[]): StaleRegistrationPlan | undefined;
-/** Names each dropped registration, in both a dry run and a write. */
+export declare function planStaleRegistrationDrop(manifest: PatchesManifest, patch: PatchMetadata, currentFilesAffected: readonly string[], pendingCreates?: ReadonlySet<string>): StaleRegistrationPlan | undefined;
+/** Names each dropped and each kept-pending registration, in both a dry run and a write. */
 export declare function reportStaleRegistrationDrop(patchFilename: string, plan: StaleRegistrationPlan, isDryRun: boolean): void;
-/** Records the dropped declarations as a delta, like `staged-dependency --remove`. */
+/** One declaration a re-export pruned, as the history log records it. */
+export type PrunedStagedDeclaration = ({
+    kind: 'registration';
+} & PatchStagedRegistration) | ({
+    kind: 'import';
+} & PatchStagedForwardImport);
+/**
+ * Records declarations a re-export pruned from one patch as a delta, like
+ * `staged-dependency --remove`.
+ */
+export declare function recordStagedDeclarationPrune(patchesDir: string, patchFilename: string, removed: readonly PrunedStagedDeclaration[], what: string): Promise<void>;
+/** Records the dropped registrations as a delta, like `staged-dependency --remove`. */
 export declare function recordStaleRegistrationDrop(patchesDir: string, patchFilename: string, plan: StaleRegistrationPlan): Promise<void>;