@hominis/fireforge 0.49.1 → 0.50.0

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

@@ -22,9 +22,11 @@ import { assertConfirmationAvailable, confirmDestructive } from '../../core/dest
 import { appendHistoryBestEffort } from '../../core/history-log.js';
 import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { buildPatchQueueContext } from '../../core/patch-lint.js';
+import { buildLintIgnoreChecks } from '../../core/patch-lint-ignore.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, savePatchesManifest, validatePatchesManifest, } from '../../core/patch-manifest.js';
 import { enforcePatchPolicy } from '../../core/patch-policy.js';
+import { manifestWithRetiredSlots } from '../../core/patch-retired.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { readText, removeFile, writeText } from '../../utils/fs.js';
@@ -34,7 +36,32 @@ import { normalizePatchDisplayName, parsePositiveIntegerFlag } from '../../utils
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { placementPlansEqual, resolvePlacementPlan } from '../export-flow.js';
 import { runPatchLint } from '../export-shared.js';
-import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, findOwnerRewriteHolders, mergeStagedForwardImports, projectSplitManifest, rewriteSplitOwners, runProjectedSplitLint, } from './split-plan.js';
+import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, mergeStagedForwardImports, projectSplitManifest, runProjectedSplitLint, } 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
+ * when it touched none so unaffected records keep their old shape.
+ */
+function stagedMaintenanceHistory(plan) {
+    const { relocated, dropped } = plan.stagedMaintenance;
+    const relocatedCount = (relocated.forwardImports?.length ?? 0) + (relocated.registrations?.length ?? 0);
+    return {
+        ...(relocatedCount > 0 ? { relocatedDeclarations: relocated } : {}),
+        ...(dropped.length > 0 ? { droppedDeclarations: dropped } : {}),
+    };
+}
+/**
+ * Prints the owner rewrites and the declarations the move re-homed or
+ * dropped, after a committed split or `move-files --create`.
+ */
+export function reportSplitStagedChanges(plan) {
+    if (plan.ownerRewrites.length > 0) {
+        info(`Re-pointed staged-dependency owners in: ${plan.ownerRewrites.join(', ')}`);
+    }
+    for (const line of describeStagedMaintenance(plan.stagedMaintenance, plan.source.filename, plan.placement.newFilename)) {
+        info(line);
+    }
+}
 /**
  * Commits a confirmed split under the patch directory lock: renumber →
  * write new patch body → write shrunken source body → single manifest
@@ -84,13 +111,17 @@ export async function commitPatchSplit(patchesDir, plan, newMetadata, options, c
                 if (decls?.length) {
                     withOwners = mergeStagedForwardImports(withOwners, decls);
                 }
+                withOwners = withoutDroppedDeclarations(withOwners, plan.stagedMaintenance.dropped);
                 if (patch.filename !== effectiveSourceFilename)
                     return withOwners;
-                return { ...withOwners, filesAffected: plan.remainingFiles };
+                return {
+                    ...withoutRelocatedDeclarations(withOwners, movedSet),
+                    filesAffected: plan.remainingFiles,
+                };
             });
             updatedPatches.push(newMetadata);
             updatedPatches.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
-            const updated = validatePatchesManifest({ ...fresh, patches: updatedPatches });
+            const updated = validatePatchesManifest(manifestWithRetiredSlots(fresh, updatedPatches));
             await savePatchesManifest(patchesDir, updated);
             await appendHistoryBestEffort(patchesDir, {
                 operation: 'patch-split',
@@ -100,6 +131,7 @@ export async function commitPatchSplit(patchesDir, plan, newMetadata, options, c
                     order: plan.placement.insertionOrder,
                     files: plan.movedFiles,
                     ownerRewrites: plan.ownerRewrites,
+                    ...stagedMaintenanceHistory(plan),
                     renames: [...plan.placement.renameMap.entries()].map(([from, entry]) => ({
                         from,
                         to: entry.newFilename,
@@ -212,16 +244,27 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         name: displayName,
         description: options.description ?? '',
         ownerRewrites: findOwnerRewriteHolders(manifest.patches, source.filename, movedSet),
-        // Populated by runProjectedSplitLint below (forward edges into the new patch).
+        // Populated by runProjectedSplitLint below (forward edges into the new
+        // patch, and the declarations the move re-homes or makes unused).
         stagedDependencyAdditions: new Map(),
+        stagedMaintenance: emptyStagedMaintenance(),
     };
+    // Policy first: the projected manifest (orders, ranges, the gap rule)
+    // does not depend on the lint below, so a refused --order fails before
+    // the per-patch and projected lint passes instead of after them.
+    enforcePatchPolicy({
+        config,
+        manifest: projectSplitManifest(manifest, plan, buildNewPatchMetadata(plan, config)),
+        command: 'patch split',
+        forceUnsafe: options.forceUnsafe === true,
+    });
     // Per-patch lint both projected bodies, threading the source patch's
     // tier/lintIgnore so an intentional-advisory patch can still split.
     // The whole-queue context (built once, with the config for committed-gate
     // parity) resolves cross-patch imports and sibling head.js harness roots
     // instead of linting each projected body blind.
     const patchQueueCtx = await buildPatchQueueContext(paths.patches, config);
-    const ignoreChecks = source.lintIgnore ? new Set(source.lintIgnore) : undefined;
+    const ignoreChecks = buildLintIgnoreChecks(source.lintIgnore);
     await runPatchLint({
         engineDir: paths.engine,
         filesAffected: remainingFiles,
@@ -242,15 +285,10 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         ignoreChecks,
         patchTier: source.tier,
     });
-    const { conflicts, stagedDependencyAdditions } = runProjectedSplitLint(plan, patchQueueCtx);
+    const { conflicts, stagedDependencyAdditions, stagedMaintenance } = runProjectedSplitLint(plan, patchQueueCtx);
     plan.stagedDependencyAdditions = stagedDependencyAdditions;
+    plan.stagedMaintenance = stagedMaintenance;
     const newMetadata = buildNewPatchMetadata(plan, config);
-    enforcePatchPolicy({
-        config,
-        manifest: projectSplitManifest(manifest, plan, newMetadata),
-        command: 'patch split',
-        forceUnsafe: options.forceUnsafe === true,
-    });
     const decision = await confirmDestructive({
         operation: 'patch-split',
         title: `Split ${plan.movedFiles.length} file(s) out of ${source.filename} into ${placement.newFilename}`,
@@ -264,9 +302,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         return;
     await commitPatchSplit(paths.patches, plan, newMetadata, options, config);
     success(`Split ${source.filename}: ${placement.newFilename} now owns ${plan.movedFiles.length} file(s)`);
-    if (plan.ownerRewrites.length > 0) {
-        info(`Re-pointed staged-dependency owners in: ${plan.ownerRewrites.join(', ')}`);
-    }
+    reportSplitStagedChanges(plan);
     outro('Split complete');
 }
 /**

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

@@ -0,0 +1,48 @@
+/**
+ * Batch input and history delta for `patch staged-dependency`.
+ *
+ * `--from <json-file>` lets one `--add` call declare many edges under one
+ * lock hold. Turning on `patchLint.forwardRegistration: "extended"` on a real
+ * queue surfaced hundreds of undeclared registrations, each printed with its
+ * own command, and one call per edge was the only way to declare them. The
+ * file is either a `lint --per-patch --report` JSON (its findings carry the
+ * `stagedDeclarations` that discharge them) or a plain array of
+ * declarations.
+ *
+ * The history record of every call holds only the delta (`added` /
+ * `removed`). Recording the patch's whole list before and after grew the
+ * log quadratically with the list: 849 single-edge calls took one consumer's
+ * log from 36 MB to 184 MB.
+ */
+import type { PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration } from '../../types/commands/index.js';
+/** Declarations read from a `--from` file for one target patch. */
+export interface StagedDependencyBatch {
+    forwardImports: PatchStagedForwardImport[];
+    registrations: PatchStagedRegistration[];
+    /** Entries naming a different patch, left out. */
+    skippedForOtherPatches: number;
+}
+/**
+ * Reads the declarations a `--from` file supplies for `targetFilename`.
+ *
+ * Every entry takes `file`, `creates`, optional `owner` and `reason`, and
+ * either `specifier` (an import) or `line` (a registration); `kind` may
+ * name the shape explicitly. An entry with a `patch` field naming another
+ * patch is skipped and counted, so one report can be applied patch by
+ * patch. `defaultReason` (the `--reason` flag) fills entries without one.
+ *
+ * @param path - The JSON file
+ * @param targetFilename - Filename of the patch being edited
+ * @param defaultReason - Reason for entries that carry none
+ */
+export declare function readStagedDependencyBatch(path: string, targetFilename: string, defaultReason?: string): Promise<StagedDependencyBatch>;
+/**
+ * The history delta between two committed `stagedDependencies` values:
+ * the declarations the call added and the ones it removed. Each side is
+ * omitted when empty. Older log records carry `before`/`after` instead;
+ * a reader should accept either.
+ */
+export declare function stagedDependencyDelta(before: PatchStagedDependencies | undefined, after: PatchStagedDependencies | undefined): {
+    added?: PatchStagedDependencies;
+    removed?: PatchStagedDependencies;
+};

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

@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Batch input and history delta for `patch staged-dependency`.
+ *
+ * `--from <json-file>` lets one `--add` call declare many edges under one
+ * lock hold. Turning on `patchLint.forwardRegistration: "extended"` on a real
+ * queue surfaced hundreds of undeclared registrations, each printed with its
+ * own command, and one call per edge was the only way to declare them. The
+ * file is either a `lint --per-patch --report` JSON (its findings carry the
+ * `stagedDeclarations` that discharge them) or a plain array of
+ * declarations.
+ *
+ * The history record of every call holds only the delta (`added` /
+ * `removed`). Recording the patch's whole list before and after grew the
+ * log quadratically with the list: 849 single-edge calls took one consumer's
+ * log from 36 MB to 184 MB.
+ */
+import { InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { readJson } from '../../utils/fs.js';
+import { isArray, isObject } from '../../utils/validation.js';
+function optionalString(record, key, label) {
+    const value = record[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new InvalidArgumentError(`${label}.${key} must be a non-empty string.`, '--from');
+    }
+    return value;
+}
+function requiredString(record, key, label) {
+    const value = optionalString(record, key, label);
+    if (value === undefined) {
+        throw new InvalidArgumentError(`${label} is missing "${key}".`, '--from');
+    }
+    return value;
+}
+/**
+ * Collects the declaration records a parsed file holds: a lint report's
+ * `stagedDeclarations` (from `queueIssues` and every patch's `issues`), or
+ * the elements of a plain array.
+ */
+function collectRecords(data) {
+    if (isArray(data)) {
+        return data.map((entry, index) => {
+            if (!isObject(entry)) {
+                throw new InvalidArgumentError(`--from entry [${index}] must be an object.`, '--from');
+            }
+            return { record: entry, label: `--from entry [${index}]` };
+        });
+    }
+    if (!isObject(data)) {
+        throw new InvalidArgumentError('--from must hold a JSON array of declarations or a "lint --per-patch --report" document.', '--from');
+    }
+    const issues = [];
+    if (isArray(data['queueIssues']))
+        issues.push(...data['queueIssues']);
+    if (isArray(data['patches'])) {
+        for (const patch of data['patches']) {
+            if (isObject(patch) && isArray(patch['issues']))
+                issues.push(...patch['issues']);
+        }
+    }
+    const records = [];
+    for (const issue of issues) {
+        if (!isObject(issue) || !isArray(issue['stagedDeclarations']))
+            continue;
+        for (const declaration of issue['stagedDeclarations']) {
+            if (isObject(declaration)) {
+                records.push({
+                    record: declaration,
+                    label: `stagedDeclarations of [${String(issue['check'])}] ${String(issue['file'])}`,
+                });
+            }
+        }
+    }
+    return records;
+}
+/**
+ * Reads the declarations a `--from` file supplies for `targetFilename`.
+ *
+ * Every entry takes `file`, `creates`, optional `owner` and `reason`, and
+ * either `specifier` (an import) or `line` (a registration); `kind` may
+ * name the shape explicitly. An entry with a `patch` field naming another
+ * patch is skipped and counted, so one report can be applied patch by
+ * patch. `defaultReason` (the `--reason` flag) fills entries without one.
+ *
+ * @param path - The JSON file
+ * @param targetFilename - Filename of the patch being edited
+ * @param defaultReason - Reason for entries that carry none
+ */
+export async function readStagedDependencyBatch(path, targetFilename, defaultReason) {
+    let data;
+    try {
+        data = await readJson(path);
+    }
+    catch (error) {
+        throw new InvalidArgumentError(`--from ${path} could not be read as JSON: ${toError(error).message}`, '--from');
+    }
+    const batch = {
+        forwardImports: [],
+        registrations: [],
+        skippedForOtherPatches: 0,
+    };
+    for (const { record, label } of collectRecords(data)) {
+        const patch = optionalString(record, 'patch', label);
+        if (patch !== undefined && patch !== targetFilename) {
+            batch.skippedForOtherPatches += 1;
+            continue;
+        }
+        const specifier = optionalString(record, 'specifier', label);
+        const line = optionalString(record, 'line', label);
+        const kind = record['kind'] ?? (line !== undefined ? 'registration' : 'import');
+        if (kind !== 'import' && kind !== 'registration') {
+            throw new InvalidArgumentError(`${label}.kind must be "import" or "registration".`, '--from');
+        }
+        const file = requiredString(record, 'file', label);
+        const creates = requiredString(record, 'creates', label);
+        const owner = optionalString(record, 'owner', label);
+        const reason = optionalString(record, 'reason', label) ?? defaultReason;
+        const extras = {
+            ...(owner !== undefined ? { owner } : {}),
+            ...(reason !== undefined ? { reason } : {}),
+        };
+        if (kind === 'import') {
+            if (specifier === undefined || line !== undefined) {
+                throw new InvalidArgumentError(`${label} is an import declaration and needs "specifier" (not "line").`, '--from');
+            }
+            batch.forwardImports.push({ file, specifier, creates, ...extras });
+        }
+        else {
+            if (line === undefined || specifier !== undefined) {
+                throw new InvalidArgumentError(`${label} is a registration declaration and needs "line" (not "specifier").`, '--from');
+            }
+            batch.registrations.push({ file, line, creates, ...extras });
+        }
+    }
+    return batch;
+}
+function entryKey(entry) {
+    return JSON.stringify(entry);
+}
+function difference(left, right) {
+    const keys = new Set((right ?? []).map(entryKey));
+    return (left ?? []).filter((entry) => !keys.has(entryKey(entry)));
+}
+function nonEmpty(staged) {
+    const forwardImports = staged.forwardImports ?? [];
+    const registrations = staged.registrations ?? [];
+    if (forwardImports.length === 0 && registrations.length === 0)
+        return undefined;
+    return {
+        ...(forwardImports.length > 0 ? { forwardImports } : {}),
+        ...(registrations.length > 0 ? { registrations } : {}),
+    };
+}
+/**
+ * The history delta between two committed `stagedDependencies` values:
+ * the declarations the call added and the ones it removed. Each side is
+ * omitted when empty. Older log records carry `before`/`after` instead;
+ * a reader should accept either.
+ */
+export function stagedDependencyDelta(before, after) {
+    const added = nonEmpty({
+        forwardImports: difference(after?.forwardImports, before?.forwardImports),
+        registrations: difference(after?.registrations, before?.registrations),
+    });
+    const removed = nonEmpty({
+        forwardImports: difference(before?.forwardImports, after?.forwardImports),
+        registrations: difference(before?.registrations, after?.registrations),
+    });
+    return {
+        ...(added !== undefined ? { added } : {}),
+        ...(removed !== undefined ? { removed } : {}),
+    };
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Kind-neutral views and list operations over staged-dependency
+ * declarations, shared by `patch staged-dependency` and its `--from` batch
+ * path. Split out of `staged-dependency.ts` for the per-file line budget.
+ */
+import type { PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration } from '../../types/commands/index.js';
+/** The command's mutation mode. */
+export type StagedDependencyMode = 'add' | 'remove' | 'clear';
+/** The declaration shape (`--kind`). */
+export type StagedDependencyKind = 'import' | 'registration';
+/**
+ * One staged-dependency entry of either kind. The `matcher` field is the
+ * kind-specific middle term: the import specifier for import entries, the
+ * registration line for registration entries. Key/removal/label logic is
+ * shared across kinds through this shape.
+ */
+export interface StagedEntryView {
+    file: string;
+    matcher: string;
+    creates: string;
+    owner?: string;
+    reason?: string;
+}
+/** View of an import declaration. */
+export declare function importView(dependency: PatchStagedForwardImport): StagedEntryView;
+/** View of a registration declaration. */
+export declare function registrationView(dependency: PatchStagedRegistration): StagedEntryView;
+/** One-line operator label for a declaration. */
+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.
+ */
+export declare function applyMode<T>(existing: readonly T[], mode: StagedDependencyMode, target: StagedEntryView | undefined, toView: (entry: T) => StagedEntryView, addition: T | undefined): T[];
+/** Number of declarations of both kinds. */
+export declare function countStagedEntries(staged: PatchStagedDependencies | undefined): number;

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

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Kind-neutral views and list operations over staged-dependency
+ * declarations, shared by `patch staged-dependency` and its `--from` batch
+ * path. Split out of `staged-dependency.ts` for the per-file line budget.
+ */
+/** View of an import declaration. */
+export function importView(dependency) {
+    return { ...dependency, matcher: dependency.specifier };
+}
+/** View of a registration declaration. */
+export function registrationView(dependency) {
+    return { ...dependency, matcher: dependency.line };
+}
+function dependencyKey(view) {
+    return [view.file, view.matcher, view.creates, view.owner ?? ''].join('\0');
+}
+/** One-line operator label for a declaration. */
+export function dependencyLabel(kind, view) {
+    const owner = view.owner ? ` owner=${view.owner}` : '';
+    const reason = view.reason ? ` reason="${view.reason}"` : '';
+    if (kind === 'import') {
+        return `${view.file} imports "${view.matcher}" from ${view.creates}${owner}${reason}`;
+    }
+    return `${view.file} registers "${view.matcher}" for ${view.creates}${owner}${reason}`;
+}
+function matchesTarget(view, target) {
+    return (view.file === target.file &&
+        view.matcher === target.matcher &&
+        view.creates === target.creates &&
+        (target.owner === undefined || view.owner === target.owner));
+}
+/**
+ * Applies one add/remove/clear to a declaration list: `add` appends unless
+ * an entry with the same file, matcher, creates and owner exists.
+ */
+export function applyMode(existing, mode, target, toView, addition) {
+    if (mode === 'clear')
+        return [];
+    if (!target)
+        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)
+        return [...existing];
+    return [...existing, addition];
+}
+/** Number of declarations of both kinds. */
+export function countStagedEntries(staged) {
+    return (staged?.forwardImports?.length ?? 0) + (staged?.registrations?.length ?? 0);
+}

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

@@ -0,0 +1,14 @@
+/**
+ * `patch staged-dependency --add --from <json-file>`: adds every
+ * declaration a file supplies for one patch in a single manifest update
+ * under one lock hold. The file format and the history delta live in
+ * `staged-dependency-batch.ts`.
+ */
+import type { PatchStagedDependencyOptions } from '../../types/commands/index.js';
+import { type StagedDependencyMode } from './staged-dependency-entries.js';
+/**
+ * `--add --from <json-file>`: every declaration the file supplies for the
+ * target patch, validated up front and written in one manifest update
+ * under one lock hold, with one delta history record.
+ */
+export declare function runBatchAdd(projectRoot: string, identifier: string, mode: StagedDependencyMode, options: PatchStagedDependencyOptions): Promise<void>;

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

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `patch staged-dependency --add --from <json-file>`: adds every
+ * declaration a file supplies for one patch in a single manifest update
+ * under one lock hold. The file format and the history delta live in
+ * `staged-dependency-batch.ts`.
+ */
+import { appendHistoryBestEffort } from '../../core/history-log.js';
+import { mutatePatchMetadata } from '../../core/patch-export.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+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 { validateStagedDependencyAdd } from './staged-dependency-validate.js';
+/** Flags that describe one declaration and so cannot combine with `--from`. */
+const SINGLE_DECLARATION_FLAGS = [
+    ['--kind', 'kind'],
+    ['--file', 'file'],
+    ['--specifier', 'specifier'],
+    ['--line', 'line'],
+    ['--creates', 'creates'],
+    ['--owner', 'owner'],
+];
+/** Adds every `--from` declaration not already present, keyed like a single `--add`. */
+function mergeBatch(staged, batch) {
+    let forwardImports = [...(staged?.forwardImports ?? [])];
+    for (const entry of batch.forwardImports) {
+        forwardImports = applyMode(forwardImports, 'add', importView(entry), importView, entry);
+    }
+    let registrations = [...(staged?.registrations ?? [])];
+    for (const entry of batch.registrations) {
+        registrations = applyMode(registrations, 'add', registrationView(entry), registrationView, entry);
+    }
+    return {
+        ...(forwardImports.length > 0 ? { forwardImports } : {}),
+        ...(registrations.length > 0 ? { registrations } : {}),
+    };
+}
+/**
+ * `--add --from <json-file>`: every declaration the file supplies for the
+ * target patch, validated up front and written in one manifest update
+ * under one lock hold, with one delta history record.
+ */
+export async function runBatchAdd(projectRoot, identifier, mode, options) {
+    const from = options.from ?? '';
+    if (mode !== 'add') {
+        throw new InvalidArgumentError('--from only applies to --add.', '--from');
+    }
+    const clashing = SINGLE_DECLARATION_FLAGS.filter(([, key]) => options[key] !== undefined);
+    if (clashing.length > 0) {
+        throw new InvalidArgumentError(`--from supplies the declarations itself; drop ${clashing.map(([flag]) => flag).join(', ')}.`, '--from');
+    }
+    const { paths, manifest } = await requirePatchQueue(projectRoot);
+    const targetPatch = requirePatchTarget(identifier, manifest.patches);
+    const batch = await readStagedDependencyBatch(from, targetPatch.filename, options.reason);
+    for (const entry of [...batch.forwardImports, ...batch.registrations]) {
+        validateStagedDependencyAdd(entry, manifest.patches);
+    }
+    const supplied = batch.forwardImports.length + batch.registrations.length;
+    if (batch.skippedForOtherPatches > 0) {
+        info(`Skipped ${batch.skippedForOtherPatches} declaration(s) in ${from} that name another patch.`);
+    }
+    if (supplied === 0) {
+        info(`${from} holds no declarations for ${targetPatch.filename}; nothing to add.`);
+        outro('Patch staged-dependency complete');
+        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)`
+            : '');
+    if (options.dryRun === true) {
+        info(`[dry-run] ${targetPatch.filename}: ${describe(countStagedEntries(existing), projectedCount)}.`);
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    const result = await mutatePatchMetadata(paths.patches, targetPatch.filename, (current) => {
+        const after = mergeBatch(current.stagedDependencies, batch);
+        if (countStagedEntries(after) === 0)
+            return { unset: ['stagedDependencies'] };
+        return { set: { stagedDependencies: after } };
+    }, {
+        waitLockSeconds: resolveWaitLockSeconds(options.waitLock),
+        command: 'patch staged-dependency',
+    });
+    if (!result) {
+        throw new GeneralError(`Patch ${targetPatch.filename} disappeared from the manifest during the update. Re-run after investigating.`);
+    }
+    const before = result.before.stagedDependencies;
+    const after = result.after.stagedDependencies;
+    info(`${targetPatch.filename}: ${describe(countStagedEntries(before), countStagedEntries(after))}.`);
+    await appendHistoryBestEffort(paths.patches, {
+        operation: 'patch-staged-dependency',
+        args: {
+            filename: targetPatch.filename,
+            mode,
+            from,
+            ...stagedDependencyDelta(before, after),
+        },
+        ...(options.yes === true ? { yes: true } : {}),
+        result: 'ok',
+    }, `patch staged-dependency committed (${targetPatch.filename})`);
+    outro('Patch staged-dependency complete');
+}