@hominis/fireforge 0.50.0 → 0.52.0

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

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

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

@@ -8,7 +8,9 @@
  * the orchestrator would go the wrong way.
  */
 import { Command, Option } from 'commander';
+import { getProjectPaths } from '../core/config.js';
 import { withEngineSessionLock } from '../core/engine-session-lock.js';
+import { withPrivateGitIndex } from '../core/git-readonly-index.js';
 import { addWaitLockOption, pickDefined, resolveWaitLockSeconds, stringListOption, } from '../utils/options.js';
 import { reExportCommand } from './re-export.js';
 import { preflightReExportArguments, readPathListFile } from './re-export-preflight.js';
@@ -27,7 +29,7 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .split(',')
         .map((v) => v.trim())
         .filter((v) => v.length > 0))
-        .option('--refuse-adjacent-unmanaged', 'Refuse a scan-less re-export (non-zero exit, patch not written) when unmanaged files exist adjacent to the patch ownership, instead of warning. Adjacent means the same directory as an owned file (not a sibling or nested directory), or named by a registration line the patch adds. Mutually exclusive with --scan and --files.')
+        .option('--refuse-adjacent-unmanaged', 'Refuse a re-export (non-zero exit, patch not written) when unmanaged files exist adjacent to the patch ownership, instead of warning. Adjacent means the same directory as an owned file (not a sibling or nested directory), or named by a registration line the patch adds. Beside --scan it judges the files the scan did not adopt. Mutually exclusive with --files.')
         .option('--refuse-foreign-drift', "Refuse a re-export (non-zero exit, patch not written) when the refreshed body would add or drop lines, in a file the patch already owns, that the old patch body did not carry — protects multi-session checkouts from silently capturing another session's uncommitted edits. Beside --scan it guards each patch's existing files (adopted files count as expected). Mutually exclusive with --files.")
         .option('--expect <path>', "With --refuse-foreign-drift, name an engine-relative file whose drift is this session's intended edit: drift confined to --expect files proceeds, drift anywhere else still refuses. Repeatable, and the whitelist applies across EVERY patch in this invocation, not per patch — so pass all the patches and all their --expect paths in one call rather than looping one patch at a time.", ...stringListOption())
         .option('--expect-unmanaged <path>', 'With --refuse-adjacent-unmanaged, name an engine-relative file that is a REVIEWED, recorded exception to the adjacency refusal: an approved unmanaged path is still listed, but no longer refuses. Repeatable, and the carve-out applies across EVERY patch in this invocation, not per patch. Use it to keep the belt armed for everything else instead of dropping --refuse-adjacent-unmanaged entirely.', ...stringListOption())
@@ -40,6 +42,9 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .option('--no-cache', 'Bypass per-patch lint result cache reads and writes for this re-export')
         .option('--allow-stale-furnace', 'Export the deployed engine copy even when the components/ source changed since the last furnace apply')
         .option('--allow-shrink', 'Allow --files to remove paths currently owned by the patch. Required before --yes can bypass the shrink confirmation.')
+        .option('--declarations-out <path>', 'Where a refused --scan adoption writes its one --from-ready staged-declaration report (default: .fireforge/declarations/<timestamp>.json).')
+        .option('--hunks-from <diff>', "Export each file the diff names as the patch's current body plus only the diff's hunks, so another session's edits in the same file stay out. One explicit patch; not with --scan, --files or --all.")
+        .option('--exclude-hunks <diff>', "Export each file the diff names as the working tree minus the diff's hunks. One explicit patch; not with --scan, --files or --all.")
         .option('-y, --yes', 'Skip confirmation prompts (required for non-TTY destructive writes)')
         .option('--force-unsafe', 'Bypass cross-patch lint refusal when --files shrinks a patch')
         .option('--stamp', "After every selected patch refreshes cleanly, stamp each re-exported patch's sourceVersion/sourceProduct in patches.json to firefox.version/firefox.product from fireforge.json. No effect on a partial run.")
@@ -51,6 +56,15 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         // Refuse what the locked run would refuse before queueing for the
         // lock, which can be a long wait under contention.
         await preflightReExportArguments(projectRoot, patches, reExportOptions);
+        // A dry run writes nothing, so it does not queue behind peers' builds
+        // and test runs for the engine lock. Its git plumbing runs on a
+        // private index, so not even git's stat-cache refresh reaches the
+        // shared `.git/index`; dry runs still serialize among themselves.
+        if (reExportOptions.dryRun === true) {
+            const engineDir = getProjectPaths(projectRoot).engine;
+            await withPrivateGitIndex(engineDir, () => reExportCommand(projectRoot, patches, reExportOptions));
+            return;
+        }
         await withEngineSessionLock(projectRoot, 're-export', () => reExportCommand(projectRoot, patches, reExportOptions), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));
 }

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

@@ -12,4 +12,4 @@ import type { ProjectPaths } from '../types/config.js';
  *    `filesAffected` as it is, so without this the stale entry would stay
  *    in the manifest and in the reserved-range policy check.
  */
-export declare function validateExpectedRemovals(paths: ProjectPaths, patches: PatchMetadata[], options: ReExportOptions): Promise<string[]>;
+export declare function validateExpectedRemovals(paths: ProjectPaths, patches: PatchMetadata[], options: ReExportOptions, queue?: readonly PatchMetadata[]): Promise<string[]>;

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

@@ -20,7 +20,7 @@ import { normalizeEngineRelativeInput } from './re-export-scan.js';
  *    `filesAffected` as it is, so without this the stale entry would stay
  *    in the manifest and in the reserved-range policy check.
  */
-export async function validateExpectedRemovals(paths, patches, options) {
+export async function validateExpectedRemovals(paths, patches, options, queue = patches) {
     const removed = [
         ...new Set((options.expectRemoved ?? []).map((file) => normalizeEngineRelativeInput(file, '--expect-removed'))),
     ];
@@ -32,7 +32,8 @@ export async function validateExpectedRemovals(paths, patches, options) {
         const owners = patches.filter((patch) => patch.filesAffected.includes(file));
         const owner = owners[0];
         if (owners.length !== 1 || owner === undefined) {
-            throw new InvalidArgumentError(`--expect-removed ${file} must be owned by exactly one selected patch.`, '--expect-removed');
+            throw new InvalidArgumentError(`--expect-removed ${file} must be owned by exactly one selected patch.` +
+                unselectedOwnerHint(file, patches, queue), '--expect-removed');
         }
         const section = parseDiffSections(await readText(join(paths.patches, owner.filename))).find((candidate) => candidate.targetPath === file);
         if (tracked.has(file)) {
@@ -47,6 +48,20 @@ export async function validateExpectedRemovals(paths, patches, options) {
     }
     return removed;
 }
+/**
+ * Each path retires from its own owner, so one run may retire paths from
+ * several selected patches. A path whose owner was left out of the
+ * selection names that owner, since adding it is the usual fix.
+ */
+function unselectedOwnerHint(file, selected, queue) {
+    const selectedNames = new Set(selected.map((patch) => patch.filename));
+    const outside = queue
+        .filter((patch) => !selectedNames.has(patch.filename) && patch.filesAffected.includes(file))
+        .map((patch) => patch.filename);
+    if (outside.length === 0)
+        return '';
+    return ` It is owned by ${outside.join(', ')}, which this run did not select; add it to the selection to retire both in one run.`;
+}
 async function assertCreatedFileAbsent(paths, file, owner, createdByOwner) {
     if (await removalPathPresent(join(paths.engine, file))) {
         throw new InvalidArgumentError(`--expect-removed ${file} is untracked in engine HEAD and still present on disk; ` +

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

@@ -54,6 +54,8 @@ export declare function assertScanAdoptionsHaveNoForwardImports(args: {
      * too, and `patchPolicy`, so the remedy names a legal order.
      */
     config?: FireForgeConfig;
+    /** `--declarations-out`: where the one `--from`-ready report goes. */
+    declarationsOut?: string | undefined;
 }): Promise<void>;
 /** The manifest rows a queue context carries, for remedy computations. */
 export declare function manifestFromQueue(ctx: PatchQueueContext): PatchesManifest;

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

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { listTrackedInHead } from '../core/git-file-ops.js';
@@ -15,6 +15,7 @@ import { mapWithConcurrency } from '../utils/concurrency.js';
 import { pathExists } from '../utils/fs.js';
 import { cancel, info, isCancel, warn } from '../utils/logger.js';
 import { isContainedRelativePath, normalizePathSlashes, stripEnginePrefix, } from '../utils/paths.js';
+import { formatDeclarationsReport, writeDeclarationsReport } from './declarations-report.js';
 import { formatForwardImportRemedy } from './forward-import-remedy.js';
 import { joinScanFileOwner, splitScanFileOwner } from './re-export-scan-owner.js';
 const SCAN_ADD_COUNT_THRESHOLD = 3;
@@ -227,7 +228,9 @@ export async function assertScanAdoptionsHaveNoForwardImports(args) {
     if (registrations.length > 0) {
         parts.push(`${registrations.length} forward registration${registrations.length === 1 ? '' : 's'} the adoption would leave dangling:\n${registrationDetails}`);
     }
+    const report = await writeDeclarationsReport(dirname(resolve(patchesDir)), [...offending, ...registrations], args.declarationsOut);
     throw new GeneralError(`Refusing to adopt scanned files into ${patchFilename}: ${parts.join('\n')}\n` +
+        (report !== undefined ? `${formatDeclarationsReport(report).join('\n')}\n` : '') +
         formatForwardImportRemedy({
             reRunHint: 're-running the scan',
             issues: [...offending, ...registrations],

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

@@ -5,20 +5,25 @@
  * loop calls {@link reExportSinglePatchWithIndexLockRetry} per selected
  * patch.
  */
+import { join } from 'node:path';
 import { stdioIsInteractive } from '../core/destructive.js';
 import { enforceFreshFurnaceSources } from '../core/furnace-stale-export.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { listTrackedInHead } from '../core/git-file-ops.js';
 import { updatePatchAndMetadata } from '../core/patch-export.js';
+import { withoutFields } from '../core/patch-export-update.js';
 import { buildLintIgnoreChecks, lintIgnoreRule, mergeLintIgnoreIds, } from '../core/patch-lint-ignore.js';
 import { buildProjectedManifest, enforcePatchPolicy } from '../core/patch-policy.js';
 import { isGitIndexLockConflict } from '../errors/git.js';
+import { readText } from '../utils/fs.js';
 import { info, success, warn } from '../utils/logger.js';
 import { sleep } from '../utils/sleep.js';
 import { findMissingFiles, reportAdjacentUnmanagedFiles } from './re-export-adjacent.js';
 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';
 const GIT_INDEX_LOCK_RETRY_MS = 300;
 /**
  * Retries a single patch re-export exactly once when the failure is
@@ -40,6 +45,59 @@ export async function reExportSinglePatchWithIndexLockRetry(args) {
         return await reExportSinglePatch(args);
     }
 }
+/**
+ * The `--scan` branch: scans, gates the adoption on forward imports,
+ * confirms a broad scan and, under `--refuse-adjacent-unmanaged`, judges
+ * the neighbours the scan left. Undefined means the patch is not written.
+ */
+async function adoptScannedFiles(args, currentFilesAffected) {
+    const { patch, paths, manifest, options, isDryRun, config, adjacentCtx } = args;
+    const scanResult = await scanPatchFilesForReExport({
+        currentFilesAffected,
+        engineDir: paths.engine,
+        manifest,
+        patchFilename: patch.filename,
+        isDryRun,
+        ...(options.scanFiles !== undefined ? { scanFiles: options.scanFiles } : {}),
+    });
+    // Forward-import gate at adoption time (runs in dry-run too): refuse
+    // to adopt unmanaged files that import modules created by later
+    // patches, because the after-the-fact lint failure this leaves behind
+    // is the field-reported footgun. Applies to broad --scan, --scan-file,
+    // and the --scan-files bulk assignments alike.
+    await assertScanAdoptionsHaveNoForwardImports({
+        patchesDir: paths.patches,
+        engineDir: paths.engine,
+        patchFilename: patch.filename,
+        added: scanResult.added,
+        config,
+        declarationsOut: options.declarationsOut,
+    });
+    if (options.scanFiles === undefined) {
+        const proceed = await confirmBroadScanAdditions({
+            patchFilename: patch.filename,
+            added: scanResult.added,
+            isDryRun,
+            yes: options.yes === true,
+            isInteractive: stdioIsInteractive(),
+        });
+        if (!proceed)
+            return undefined;
+    }
+    if (adjacentCtx.refuseAdjacentUnmanaged) {
+        const adjacentArgs = {
+            patch,
+            paths,
+            manifest,
+            currentFilesAffected: scanResult.updated,
+            ctx: adjacentCtx,
+            afterScan: true,
+        };
+        if (await reportAdjacentUnmanagedFiles(adjacentArgs))
+            return undefined;
+    }
+    return { updated: scanResult.updated, added: scanResult.added };
+}
 async function reExportSinglePatch(args) {
     const { patch, paths, manifest, options, isDryRun, config, adjacentCtx, driftCtx, lintCtx } = args;
     const removed = new Set(options.expectRemoved ?? []);
@@ -50,41 +108,11 @@ async function reExportSinglePatch(args) {
         info(`  - ${file} (--expect-removed)`);
     // --- Scan for new/removed files ---
     if (options.scan) {
-        const scanResult = await scanPatchFilesForReExport({
-            currentFilesAffected,
-            engineDir: paths.engine,
-            manifest,
-            patchFilename: patch.filename,
-            isDryRun,
-            ...(options.scanFiles !== undefined ? { scanFiles: options.scanFiles } : {}),
-        });
-        // Forward-import gate at adoption time (runs in dry-run too): refuse
-        // to adopt unmanaged files that import modules created by later
-        // patches, because the after-the-fact lint failure this leaves behind
-        // is the field-reported footgun. Applies to broad --scan, --scan-file,
-        // and the --scan-files bulk assignments alike.
-        await assertScanAdoptionsHaveNoForwardImports({
-            patchesDir: paths.patches,
-            engineDir: paths.engine,
-            patchFilename: patch.filename,
-            added: scanResult.added,
-            config,
-        });
-        if (options.scanFiles === undefined) {
-            const isInteractive = stdioIsInteractive();
-            const proceed = await confirmBroadScanAdditions({
-                patchFilename: patch.filename,
-                added: scanResult.added,
-                isDryRun,
-                yes: options.yes === true,
-                isInteractive,
-            });
-            if (!proceed) {
-                return false;
-            }
-        }
-        currentFilesAffected = scanResult.updated;
-        adoptedFiles = scanResult.added;
+        const adopted = await adoptScannedFiles(args, currentFilesAffected);
+        if (adopted === undefined)
+            return false;
+        currentFilesAffected = adopted.updated;
+        adoptedFiles = adopted.added;
     }
     else if (options.files === undefined) {
         // When neither `--scan` nor `--files` is set and some of the manifest's
@@ -143,7 +171,17 @@ async function reExportSinglePatch(args) {
     }
     const untrackedSet = new Set(untrackedAbsent);
     const existingFiles = currentFilesAffected.filter((f) => !untrackedSet.has(f));
-    const diffContent = await getDiffForFilesAgainstHead(paths.engine, existingFiles);
+    let diffContent = await getDiffForFilesAgainstHead(paths.engine, existingFiles);
+    const selection = hunkSelectionOf(options);
+    if (selection !== undefined) {
+        diffContent = await buildHunkSelectedDiff({
+            engineDir: paths.engine,
+            selection,
+            oldBody: await readText(join(paths.patches, patch.filename)),
+            normalDiff: diffContent,
+            files: existingFiles,
+        });
+    }
     assertScanFileAdditionsHaveDiffHunks({
         diffContent,
         patchFilename: patch.filename,
@@ -173,6 +211,10 @@ async function reExportSinglePatch(args) {
         return false;
     }
     const { updates, ignoreChecks, effectiveTier, existingIgnoreSet, flagIgnoreSet } = computeReExportUpdates(patch, options, currentFilesAffected);
+    const stalePlan = planStaleRegistrationDrop(manifest, patch, currentFilesAffected);
+    if (stalePlan !== undefined)
+        reportStaleRegistrationDrop(patch.filename, stalePlan, isDryRun);
+    const unset = applyStaleRegistrationDrop(stalePlan, updates);
     enforceProjectedManifestPolicy({ config, manifest, patch, updates, options });
     // Cross-patch projection gate (runs in dry-run too): the refreshed body
     // must not introduce queue-level errors the current queue lacks, e.g. an
@@ -188,7 +230,7 @@ async function reExportSinglePatch(args) {
     // Lint against the once-per-invocation hoisted context (queue context +
     // queue-wide checkJs program + per-patch result cache) instead of
     // rebuilding ~37 s of setup for every patch in the loop.
-    const projectedMetadata = { ...patch, ...updates };
+    const projectedMetadata = withoutFields({ ...patch, ...updates }, unset);
     const lintResult = await lintReExportedPatch({
         lintCtx,
         patch,
@@ -222,6 +264,8 @@ async function reExportSinglePatch(args) {
             lintCtx,
             diffContent,
             updates,
+            unset,
+            stalePlan,
             projectedMetadata,
             existingFiles,
             lintResult,
@@ -263,7 +307,8 @@ async function commitRefreshedPatch(args) {
         filename: patch.filename,
         newContent: diffContent,
         updates,
-        onCommitted: undefined,
+        ...(args.unset.length > 0 ? { unset: args.unset } : {}),
+        onCommitted: staleRecorder(paths.patches, patch.filename, args.stalePlan),
         policyGate: {
             config,
             command: 're-export',
@@ -279,10 +324,7 @@ async function commitRefreshedPatch(args) {
     if (patchIndex !== -1) {
         const existingEntry = manifest.patches[patchIndex];
         if (existingEntry) {
-            manifest.patches[patchIndex] = {
-                ...existingEntry,
-                ...updates,
-            };
+            manifest.patches[patchIndex] = withoutFields({ ...existingEntry, ...updates }, args.unset);
         }
     }
     // A bulk run refreshes every patch. Saying "Re-exported" for one whose body
@@ -295,6 +337,24 @@ async function commitRefreshedPatch(args) {
         info(`Unchanged ${patch.filename}`);
     }
 }
+/** The history hook for a write that drops stale registrations, if any. */
+function staleRecorder(patchesDir, patchFilename, plan) {
+    if (plan === undefined)
+        return undefined;
+    return () => recordStaleRegistrationDrop(patchesDir, patchFilename, plan);
+}
+/**
+ * Folds the stale-registration drop into `updates`: the kept staged block
+ * is set, or the field is returned for unsetting when nothing is left.
+ */
+function applyStaleRegistrationDrop(plan, updates) {
+    if (plan === undefined)
+        return [];
+    if (plan.stagedDependencies === undefined)
+        return ['stagedDependencies'];
+    updates.stagedDependencies = plan.stagedDependencies;
+    return [];
+}
 /**
  * Threads the patch's own `lintIgnore` list through so the per-patch
  * suppression honoured by export/export-all is also honoured here. A

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

@@ -0,0 +1,18 @@
+import type { PatchesManifest, PatchMetadata, PatchStagedDependencies, 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[];
+    /** The staged block to write, or undefined when nothing is left. */
+    stagedDependencies: PatchStagedDependencies | undefined;
+}
+/**
+ * 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.
+ */
+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 reportStaleRegistrationDrop(patchFilename: string, plan: StaleRegistrationPlan, isDryRun: boolean): void;
+/** Records the dropped declarations as a delta, like `staged-dependency --remove`. */
+export declare function recordStaleRegistrationDrop(patchesDir: string, patchFilename: string, plan: StaleRegistrationPlan): Promise<void>;

package/dist/src/commands/re-export-stale-registrations.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Re-export prunes a staged registration the queue can no longer satisfy.
+ *
+ * A merge that deletes a file whose jar.mn line lives in another patch
+ * left the staged registration on that patch: re-export kept it, lint then
+ * warned `staged-dependency-unused`, and the stale declaration also kept
+ * the holder measuring above a just-lowered size ceiling. When no patch in
+ * the queue owns a registration's `creates` path any more, the declaration
+ * cannot be met, so the holder's own re-export drops it and says so.
+ */
+import { appendHistoryBestEffort } from '../core/history-log.js';
+import { info } from '../utils/logger.js';
+/**
+ * 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.
+ */
+export function planStaleRegistrationDrop(manifest, patch, currentFilesAffected) {
+    const registrations = patch.stagedDependencies?.registrations ?? [];
+    if (registrations.length === 0)
+        return undefined;
+    const owned = new Set(currentFilesAffected);
+    for (const entry of manifest.patches) {
+        if (entry.filename === patch.filename)
+            continue;
+        for (const file of entry.filesAffected)
+            owned.add(file);
+    }
+    const dropped = registrations.filter((registration) => !owned.has(registration.creates));
+    if (dropped.length === 0)
+        return undefined;
+    const kept = registrations.filter((registration) => owned.has(registration.creates));
+    const forwardImports = patch.stagedDependencies?.forwardImports ?? [];
+    const staged = {
+        ...(forwardImports.length > 0 ? { forwardImports } : {}),
+        ...(kept.length > 0 ? { registrations: kept } : {}),
+    };
+    return {
+        dropped,
+        stagedDependencies: Object.keys(staged).length > 0 ? staged : undefined,
+    };
+}
+/** Names each dropped registration, in both a dry run and a write. */
+export function reportStaleRegistrationDrop(patchFilename, plan, isDryRun) {
+    const verb = isDryRun ? 'would drop' : 'drops';
+    for (const registration of plan.dropped) {
+        info(`${patchFilename}: ${verb} staged registration ${registration.file} "${registration.line.trim()}": ` +
+            `no patch in the queue creates ${registration.creates} any more.`);
+    }
+}
+/** Records the dropped declarations as a delta, like `staged-dependency --remove`. */
+export async function recordStaleRegistrationDrop(patchesDir, patchFilename, plan) {
+    await appendHistoryBestEffort(patchesDir, {
+        operation: 're-export-staged-prune',
+        args: {
+            filename: patchFilename,
+            removed: plan.dropped.map((registration) => ({ kind: 'registration', ...registration })),
+        },
+        result: 'ok',
+    }, `re-export pruned stale staged registrations on ${patchFilename}`);
+}