@hominis/fireforge 0.50.0 → 0.52.0

package/dist/src/commands/patch/lint-ignore.js

@@ -26,12 +26,13 @@ import { Command, Option } from 'commander';
 import { confirmDestructive } from '../../core/destructive.js';
 import { appendHistoryBestEffort } from '../../core/history-log.js';
 import { mutatePatchMetadata } from '../../core/patch-export.js';
-import { addedLintIgnoreEntries, formatLintIgnoreEntry, formatLintIgnoreList, LINT_IGNORE_CEILING_RULES, lintIgnoreRule, removeLintIgnoreRules, upsertLintIgnoreEntries, } from '../../core/patch-lint-ignore.js';
+import { addedLintIgnoreEntries, formatLintIgnoreEntry, formatLintIgnoreList, lintIgnoreRule, removeLintIgnoreRules, upsertLintIgnoreEntries, } from '../../core/patch-lint-ignore.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { addWaitLockOption, commanderArgParser, resolveWaitLockSeconds, stringListOption, } from '../../utils/options.js';
 import { parsePositiveIntegerFlag } from '../../utils/validation.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
+import { parseShare, readLintIgnoreBatch, resolveAddEntries } from './lint-ignore-from.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
 /**
  * Printed whenever `--add` lands a new check id. The waiver this command
@@ -88,37 +89,28 @@ function describeChange(before, after, mode, values) {
 }
 /**
  * Turns the mode's IDs into manifest entries, applying `--max`/`--reason`
- * to `--add`. Refuses a ceiling flag without `--add`, a `--max` without a
- * `--reason` (and the reverse), and a ceiling on a rule that carries no
- * measurement, so a waiver that could never suppress anything is not
- * written.
+ * and `<rule>=<max>` to `--add` (see `lint-ignore-from.ts`). Refuses a
+ * ceiling flag without `--add`, a ceiling without a `--reason`, and a
+ * ceiling on a rule that carries no measurement, so a waiver that could
+ * never suppress anything is not written. A `--from` add resolves later,
+ * once the target patch is known.
  */
 function resolveRequestedEntries(mode, options) {
-    const hasMax = options.max !== undefined;
-    const hasReason = options.reason !== undefined;
-    if ((hasMax || hasReason) && mode !== 'add') {
-        throw new InvalidArgumentError('--max and --reason only apply to --add.', hasMax ? '--max' : '--reason');
-    }
-    if (hasMax !== hasReason) {
-        throw new InvalidArgumentError('A lintIgnore ceiling needs both --max <n> and --reason <text>.', hasMax ? '--reason' : '--max');
+    const ceilingFlag = options.max !== undefined ? '--max' : options.share !== undefined ? '--share' : undefined;
+    if ((ceilingFlag !== undefined || options.reason !== undefined) && mode !== 'add') {
+        throw new InvalidArgumentError('--max, --reason and --share only apply to --add.', ceilingFlag ?? '--reason');
     }
     if (mode === 'remove')
         return [...(options.remove ?? [])];
     if (mode !== 'add')
         return [];
-    const ids = options.add ?? [];
-    if (options.max === undefined || options.reason === undefined)
-        return [...ids];
-    if (options.reason.trim() === '') {
-        throw new InvalidArgumentError('--reason must not be empty.', '--reason');
-    }
-    const unmeasured = ids.filter((id) => !LINT_IGNORE_CEILING_RULES.includes(id));
-    if (unmeasured.length > 0) {
-        throw new InvalidArgumentError(`--max only applies to the measured size rules (${LINT_IGNORE_CEILING_RULES.join(', ')}); ` +
-            `got ${unmeasured.join(', ')}.`, '--max');
+    if (options.from !== undefined) {
+        if ((options.add?.length ?? 0) > 0 || ceilingFlag !== undefined) {
+            throw new InvalidArgumentError('--from takes its entries from the file; it combines only with --reason (the default reason).', (options.add?.length ?? 0) > 0 ? '--add' : ceilingFlag);
+        }
+        return [];
     }
-    const { max, reason } = options;
-    return ids.map((rule) => ({ rule, max, reason }));
+    return resolveAddEntries(options.add ?? [], options);
 }
 /**
  * Runs the `patch lint-ignore` command: reads the patch's existing
@@ -135,7 +127,7 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
     // `--add foo --remove bar` are rejected: an operator who needs both
     // runs the command twice (clearer audit trail), and `--clear` plus a
     // mode is contradictory.
-    const adding = (options.add?.length ?? 0) > 0;
+    const adding = (options.add?.length ?? 0) > 0 || options.from !== undefined;
     const removing = (options.remove?.length ?? 0) > 0;
     const clearing = options.clear === true;
     const modeCount = [adding, removing, clearing].filter(Boolean).length;
@@ -143,12 +135,22 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
         throw new InvalidArgumentError('--add, --remove, and --clear are mutually exclusive. Pick one mode per invocation.', 'patch lint-ignore');
     }
     if (modeCount === 0) {
-        throw new InvalidArgumentError('Specify --add <id>, --remove <id>, or --clear.', 'patch lint-ignore');
+        throw new InvalidArgumentError('Specify --add <id>, --from <json-file>, --remove <id>, or --clear.', 'patch lint-ignore');
     }
     const mode = adding ? 'add' : removing ? 'remove' : 'clear';
-    const values = resolveRequestedEntries(mode, options);
+    let values = resolveRequestedEntries(mode, options);
     const { paths, manifest } = await requirePatchQueue(projectRoot);
     const target = requirePatchTarget(identifier, manifest.patches);
+    if (options.from !== undefined) {
+        const batch = await readLintIgnoreBatch(options.from, target.filename, options.reason);
+        if (batch.skippedForOtherPatches > 0) {
+            info(`--from: ${batch.skippedForOtherPatches} entry/entries for other patches left out.`);
+        }
+        if (batch.entries.length === 0) {
+            throw new InvalidArgumentError(`--from ${options.from} holds no lintIgnore entry for ${target.filename}.`, '--from');
+        }
+        values = batch.entries;
+    }
     // Destructive-operation contract (docs/lifecycle-invariants.md): manifest
     // metadata mutations get summary + dry-run + confirmation/--yes + history
     // uniformly. Accepting --yes without ever prompting makes the flag appear
@@ -216,12 +218,16 @@ export function registerPatchLintIgnore(parent, context) {
     const command = parent
         .command('lint-ignore <name>')
         .description('Edit PatchMetadata.lintIgnore on a single patch (no .patch body rewrite). One mode per invocation.')
-        .option('--add <check-id>', 'Lint check ID to add to the patch lintIgnore list (repeatable)', ...stringListOption())
+        .option('--add <check-id>', 'Lint check ID to add to the patch lintIgnore list (repeatable); <rule>=<max> adds a ceiling at <max>', ...stringListOption())
         .option('--remove <check-id>', 'Lint check ID to remove from the patch lintIgnore list (repeatable)', ...stringListOption())
         .option('--clear', 'Drop the lintIgnore field entirely')
         .addOption(new Option('--max <n>', 'With --add: write a size waiver with a ceiling, suppressing the rule only while its ' +
         'measurement is at most <n> (file-too-large, large-patch-lines, large-patch-files)').argParser(commanderArgParser((v) => parsePositiveIntegerFlag('--max', v))))
-        .option('--reason <text>', 'With --add --max: why the ceiling exists (required with --max)')
+        .option('--reason <text>', 'Why the ceiling exists (required with --max or <rule>=<max>; with --from: the default for entries without one)')
+        .addOption(new Option('--share <share>', 'With a large-patch-lines ceiling: bound only the "product" or "test" share of the measurement').argParser(commanderArgParser(parseShare)))
+        .option('--from <json-file>', 'Add every entry in a JSON file under one lock hold: an array of check IDs or ' +
+        '{ rule, max, reason?, share?, meta?, patch? } objects, or a "lint --per-patch --report" ' +
+        'document, whose ceilings for this patch are rebaselined to their current measurement')
         .option('--dry-run', 'Show what would change without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)');
     addWaitLockOption(command).action(withErrorHandling(async (name, options) => {
@@ -240,6 +246,10 @@ export function registerPatchLintIgnore(parent, context) {
             normalized.max = options.max;
         if (options.reason !== undefined)
             normalized.reason = options.reason;
+        if (options.share !== undefined)
+            normalized.share = options.share;
+        if (options.from !== undefined)
+            normalized.from = options.from;
         if (options.dryRun === true)
             normalized.dryRun = true;
         if (options.yes === true)

package/dist/src/commands/patch/move-files-create.js

@@ -21,11 +21,12 @@ import { enforcePatchPolicy } from '../../core/patch-policy.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { info, intro, outro, success } from '../../utils/logger.js';
 import { normalizePatchDisplayName } from '../../utils/validation.js';
+import { withDeclarationsReport } from '../declarations-report.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { resolvePlacementPlan } from '../export-flow.js';
 import { runPatchLint } from '../export-shared.js';
 import { commitPatchSplit, reportSplitStagedChanges } from './split.js';
-import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, projectSplitManifest, runProjectedSplitLint, } from './split-plan.js';
+import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, projectSplitManifest, runProjectedSplitLint, splitDeclarationRenamer, } from './split-plan.js';
 import { emptyStagedMaintenance, findOwnerRewriteHolders } from './split-staged.js';
 /**
  * Runs `patch move-files --create --order <n>`: plans the create+move as a
@@ -136,9 +137,15 @@ export async function patchMoveFilesCreateCommand(projectRoot, fromIdentifier, n
         ignoreChecks,
         patchTier: source.tier,
     });
-    const { conflicts, stagedDependencyAdditions, stagedMaintenance } = runProjectedSplitLint(plan, patchQueueCtx);
-    plan.stagedDependencyAdditions = stagedDependencyAdditions;
-    plan.stagedMaintenance = stagedMaintenance;
+    const projected = runProjectedSplitLint(plan, patchQueueCtx);
+    plan.stagedDependencyAdditions = projected.stagedDependencyAdditions;
+    plan.stagedMaintenance = projected.stagedMaintenance;
+    const conflicts = await withDeclarationsReport(projected.conflicts, {
+        projectRoot,
+        regressions: projected.regressions,
+        out: options.declarationsOut,
+        rename: splitDeclarationRenamer(plan),
+    });
     const newMetadata = buildNewPatchMetadata(plan, config);
     const decision = await confirmDestructive({
         operation: 'patch-move-files-create',

package/dist/src/commands/patch/move-files-into.js

@@ -14,7 +14,7 @@
  * reflect both patches' content, because both bodies are regenerated from
  * the worktree.
  */
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { assertConfirmationAvailable, confirmDestructive, } from '../../core/destructive.js';
 import { appendHistoryBestEffort } from '../../core/history-log.js';
 import { buildPatchQueueContext, collectForwardImportEdges, formatPatchLintIssue, lintPatchQueue, } from '../../core/patch-lint.js';
@@ -27,6 +27,7 @@ import { toError } from '../../utils/errors.js';
 import { readText, writeText } from '../../utils/fs.js';
 import { info, outro, success, warn } from '../../utils/logger.js';
 import { resolveWaitLockSeconds } from '../../utils/options.js';
+import { withDeclarationsReport } from '../declarations-report.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { runPatchLint } from '../export-shared.js';
 import { projectEntryBody } from './entry-projection.js';
@@ -91,7 +92,7 @@ function runProjectedMoveLint(plan, baseCtx) {
             reason: `move would introduce ${regressions.length} cross-patch lint error(s)`,
             details: regressions.map(formatPatchLintIssue),
         };
-    return { conflicts, stagedDependencyAdditions };
+    return { conflicts, regressions, stagedDependencyAdditions };
 }
 /**
  * Commits a confirmed move under the patch-directory lock: write both
@@ -225,8 +226,13 @@ export async function runMoveFilesInto(args) {
         ownerRewrites: findOwnerRewriteHolders(manifest?.patches ?? [], source.filename, new Set(files)),
         stagedDependencyAdditions: new Map(),
     };
-    const { conflicts, stagedDependencyAdditions } = runProjectedMoveLint(plan, patchQueueCtx);
-    plan.stagedDependencyAdditions = stagedDependencyAdditions;
+    const projected = runProjectedMoveLint(plan, patchQueueCtx);
+    plan.stagedDependencyAdditions = projected.stagedDependencyAdditions;
+    const conflicts = await withDeclarationsReport(projected.conflicts, {
+        projectRoot: dirname(resolve(patchesDir)),
+        regressions: projected.regressions,
+        out: options.declarationsOut,
+    });
     const decision = await confirmDestructive({
         operation: 'patch-move-files',
         title: `Move ${files.length} file(s) from ${source.filename} to ${target.filename}`,

package/dist/src/commands/patch/move-files.js

@@ -172,7 +172,8 @@ export function registerPatchMoveFiles(parent, context) {
         .option('--dry-run', 'Show what would happen without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
         .option('--force-unsafe', 'Bypass projected-lint refusals')
-        .option('--skip-lint', 'Skip per-patch lint of the projected bodies');
+        .option('--skip-lint', 'Skip per-patch lint of the projected bodies')
+        .option('--declarations-out <path>', 'Where a refusal writes its one --from-ready staged-declaration report (default: .fireforge/declarations/<timestamp>.json)');
     addWaitLockOption(command).action(withErrorHandling(async (from, to, options) => {
         await patchMoveFilesCommand(getProjectRoot(), from, to, {
             ...pickDefined({
@@ -185,6 +186,7 @@ export function registerPatchMoveFiles(parent, context) {
                 yes: options.yes,
                 forceUnsafe: options.forceUnsafe,
                 skipLint: options.skipLint,
+                declarationsOut: options.declarationsOut,
                 waitLock: options.waitLock,
             }),
         });

package/dist/src/commands/patch/removal-created-files.d.ts

@@ -0,0 +1,48 @@
+/**
+ * What `patch delete` and `patch retire` do to the files the removed patch
+ * claims, shared so both commands say and do the same.
+ *
+ * A file the patch modifies stays in the engine with its edits, unmanaged.
+ * A file the patch creates is different: once the patch is gone nothing
+ * owns it, so a created file still on disk turns into an unmanaged file the
+ * engine-clean gate reports. The summary names each such file (in the dry
+ * run and at the prompt), and `--delete-created` removes them as part of
+ * the confirmed operation.
+ */
+import type { PatchQueueContext } from '../../core/patch-lint.js';
+import type { PatchMetadata } from '../../types/commands/index.js';
+/** The summary lines for a removal's claimed files, and what to delete. */
+export interface ClaimedFilePlan {
+    /** One summary line per claimed file, plus a header. */
+    summary: string[];
+    /** Created files still on disk that the removal will delete. */
+    deleteOnCommit: string[];
+}
+/**
+ * Plans the claimed-file half of a removal.
+ *
+ * @param ctx - Queue context built before the removal
+ * @param target - The patch about to leave the queue
+ * @param engineDir - Engine directory
+ * @param deleteCreated - Whether `--delete-created` was passed
+ */
+export declare function planClaimedFiles(ctx: PatchQueueContext, target: PatchMetadata, engineDir: string, deleteCreated: boolean): Promise<ClaimedFilePlan>;
+/**
+ * Deletes the created files a confirmed removal planned to delete.
+ *
+ * @param engineDir - Engine directory
+ * @param files - Engine-relative paths from {@link planClaimedFiles}
+ */
+export declare function deleteCreatedFiles(engineDir: string, files: readonly string[]): Promise<void>;
+/**
+ * Runs a removal's locked commit, inside the engine-session lock as well
+ * when it will delete engine files, so no engine-mutating peer runs while
+ * created files disappear under it.
+ *
+ * @param projectRoot - Project root directory
+ * @param command - Command name for lock attribution
+ * @param plan - The claimed-file plan
+ * @param waitLockSeconds - Wait budget for the engine lock
+ * @param operation - The patch-directory-locked commit
+ */
+export declare function withCreatedFileLock(projectRoot: string, command: string, plan: ClaimedFilePlan, waitLockSeconds: number | undefined, operation: () => Promise<void>): Promise<void>;

package/dist/src/commands/patch/removal-created-files.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * What `patch delete` and `patch retire` do to the files the removed patch
+ * claims, shared so both commands say and do the same.
+ *
+ * A file the patch modifies stays in the engine with its edits, unmanaged.
+ * A file the patch creates is different: once the patch is gone nothing
+ * owns it, so a created file still on disk turns into an unmanaged file the
+ * engine-clean gate reports. The summary names each such file (in the dry
+ * run and at the prompt), and `--delete-created` removes them as part of
+ * the confirmed operation.
+ */
+import { join } from 'node:path';
+import { withEngineSessionLock } from '../../core/engine-session-lock.js';
+import { pathExists, removeFile } from '../../utils/fs.js';
+/**
+ * Plans the claimed-file half of a removal.
+ *
+ * @param ctx - Queue context built before the removal
+ * @param target - The patch about to leave the queue
+ * @param engineDir - Engine directory
+ * @param deleteCreated - Whether `--delete-created` was passed
+ */
+export async function planClaimedFiles(ctx, target, engineDir, deleteCreated) {
+    const created = ctx.entries.find((entry) => entry.filename === target.filename)?.createdFiles;
+    const summary = [`files currently claimed by this patch (${target.filesAffected.length}):`];
+    const deleteOnCommit = [];
+    let lingering = 0;
+    for (const file of target.filesAffected) {
+        if (created?.has(file) !== true) {
+            summary.push(`  ${file}  → will become unmanaged`);
+            continue;
+        }
+        if (!(await pathExists(join(engineDir, file)))) {
+            summary.push(`  ${file}  → created by this patch; already gone`);
+            continue;
+        }
+        if (deleteCreated) {
+            deleteOnCommit.push(file);
+            summary.push(`  ${file}  → created by this patch; will be deleted (--delete-created)`);
+        }
+        else {
+            lingering++;
+            summary.push(`  ${file}  → created by this patch and still on disk: will become unmanaged`);
+        }
+    }
+    if (lingering > 0) {
+        summary.push(`${lingering} created file(s) are still on disk. Delete them first, or pass ` +
+            '--delete-created to remove them with the patch; otherwise status reports them as unmanaged.');
+    }
+    return { summary, deleteOnCommit };
+}
+/**
+ * Deletes the created files a confirmed removal planned to delete.
+ *
+ * @param engineDir - Engine directory
+ * @param files - Engine-relative paths from {@link planClaimedFiles}
+ */
+export async function deleteCreatedFiles(engineDir, files) {
+    for (const file of files) {
+        await removeFile(join(engineDir, file));
+    }
+}
+/**
+ * Runs a removal's locked commit, inside the engine-session lock as well
+ * when it will delete engine files, so no engine-mutating peer runs while
+ * created files disappear under it.
+ *
+ * @param projectRoot - Project root directory
+ * @param command - Command name for lock attribution
+ * @param plan - The claimed-file plan
+ * @param waitLockSeconds - Wait budget for the engine lock
+ * @param operation - The patch-directory-locked commit
+ */
+export async function withCreatedFileLock(projectRoot, command, plan, waitLockSeconds, operation) {
+    if (plan.deleteOnCommit.length === 0) {
+        await operation();
+        return;
+    }
+    await withEngineSessionLock(projectRoot, command, operation, {
+        ...(waitLockSeconds !== undefined ? { waitLockSeconds } : {}),
+    });
+}

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

@@ -26,7 +26,7 @@ import { buildPatchQueueContext, formatPatchLintIssue, lintPatchQueue, } from '.
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from '../../core/patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy, getPatchPolicyCategories, isCategoryAllowedByConfig, } from '../../core/patch-policy.js';
-import { carryRetiredSlots } from '../../core/patch-retired.js';
+import { carryReservedSlots, carryRetiredSlots } from '../../core/patch-retired.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
@@ -116,12 +116,17 @@ async function commitRenameUnderLock(input) {
                 ...(descriptionChanging ? { description: newDescription ?? '' } : {}),
             };
         }
-        // A rename onto a retired order fills that slot.
+        // A rename onto a retired or reserved order fills that slot.
         const retired = carryRetiredSlots(fresh, fresh.patches);
         if (retired === undefined)
             delete fresh.retired;
         else
             fresh.retired = retired;
+        const reserved = carryReservedSlots(fresh, fresh.patches);
+        if (reserved === undefined)
+            delete fresh.reserved;
+        else
+            fresh.reserved = reserved;
         enforcePatchPolicy({
             config: input.config,
             manifest: buildProjectedManifest(fresh, fresh.patches),
@@ -306,11 +311,18 @@ export async function patchRenameCommand(projectRoot, identifier, options = {})
         command: 'patch rename',
         forceUnsafe: options.forceUnsafe === true,
     });
+    // A description-only edit renames nothing and moves no order, so it needs
+    // no confirmation: scripts may change a description without --yes.
+    const descriptionOnly = descriptionChanging &&
+        !filenameChanging &&
+        !nameChanging &&
+        !orderChanging &&
+        !categoryChanging;
     const decision = await confirmDestructive({
         operation: 'patch-rename',
         title: `Rename ${target.filename}`,
         summary,
-        yes: options.yes === true,
+        yes: options.yes === true || descriptionOnly,
         dryRun: isDryRun,
         conflicts: null,
     });

package/dist/src/commands/patch/reserve.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `fireforge patch reserve <order>`: holds an order number for a patch a
+ * session has agreed to export but has not exported yet.
+ *
+ * The case it exists for: under `patchPolicy.allowGaps: false`, a session
+ * cannot `export --order 571` while a peer has claimed 569 and 570 but not
+ * exported them, because the unfilled orders read as a gap. A reservation
+ * is a placeholder in `patches.json#reserved` that the gap check counts as
+ * occupied and the earliest-legal-order search counts as taken. The export
+ * that lands on the order fills it (see `core/patch-retired.ts`), and
+ * `--release` drops a reservation whose patch will not come.
+ *
+ * Metadata-only: no `.patch` file is written and no row is added, so
+ * apply, lint and rebase never see a reservation.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchReserveOptions } from '../../types/commands/index.js';
+/**
+ * Runs the `patch reserve` command.
+ *
+ * @param projectRoot - Project root directory
+ * @param order - Order number to reserve or release
+ * @param options - Command options
+ */
+export declare function patchReserveCommand(projectRoot: string, order: number, options?: PatchReserveOptions): Promise<void>;
+/**
+ * Registers the `patch reserve` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchReserve(parent: Command, context: CommandContext): void;

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

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch reserve <order>`: holds an order number for a patch a
+ * session has agreed to export but has not exported yet.
+ *
+ * The case it exists for: under `patchPolicy.allowGaps: false`, a session
+ * cannot `export --order 571` while a peer has claimed 569 and 570 but not
+ * exported them, because the unfilled orders read as a gap. A reservation
+ * is a placeholder in `patches.json#reserved` that the gap check counts as
+ * occupied and the earliest-legal-order search counts as taken. The export
+ * that lands on the order fills it (see `core/patch-retired.ts`), and
+ * `--release` drops a reservation whose patch will not come.
+ *
+ * Metadata-only: no `.patch` file is written and no row is added, so
+ * apply, lint and rebase never see a reservation.
+ */
+import { Command } from 'commander';
+import { getProjectPaths, loadConfig } from '../../core/config.js';
+import { appendHistoryBestEffort } from '../../core/history-log.js';
+import { withPatchDirectoryLock } from '../../core/patch-lock.js';
+import { loadPatchesManifestForWrite, savePatchesManifest } from '../../core/patch-manifest.js';
+import { formatPatchOrder } from '../../core/patch-parse.js';
+import { categoryRangeForOrder, categoryRangeLabel, isCategoryAllowedByConfig, } from '../../core/patch-policy.js';
+import { InvalidArgumentError } from '../../errors/base.js';
+import { info, intro, outro } from '../../utils/logger.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../utils/options.js';
+import { parsePositiveIntegerFlag } from '../../utils/validation.js';
+/**
+ * Refuses a reservation the manifest or the policy cannot hold: an order a
+ * patch, a retired slot or another reservation already takes, or one
+ * outside the category's configured ranges.
+ */
+function assertReservable(manifest, config, order, category) {
+    const label = formatPatchOrder(order);
+    const patch = manifest.patches.find((entry) => entry.order === order);
+    if (patch !== undefined) {
+        throw new InvalidArgumentError(`Order ${label} is taken by ${patch.filename}.`, '<order>');
+    }
+    if ((manifest.retired ?? []).some((slot) => slot.order === order)) {
+        throw new InvalidArgumentError(`Order ${label} is a retired slot; "fireforge export --order ${label}" fills it without a reservation.`, '<order>');
+    }
+    const held = manifest.reserved?.find((slot) => slot.order === order);
+    if (held !== undefined) {
+        throw new InvalidArgumentError(`Order ${label} is already reserved by ${held.owner} (since ${held.reservedAt}).`, '<order>');
+    }
+    const policy = config.patchPolicy;
+    if (policy !== undefined && categoryRangeForOrder(policy, category, order) === null) {
+        throw new InvalidArgumentError(`Order ${label} is outside the ${category} range (${categoryRangeLabel(policy.ranges, category)}).`, '<order>');
+    }
+}
+/**
+ * Runs the `patch reserve` command.
+ *
+ * @param projectRoot - Project root directory
+ * @param order - Order number to reserve or release
+ * @param options - Command options
+ */
+export async function patchReserveCommand(projectRoot, order, options = {}) {
+    const releasing = options.release === true;
+    const verb = releasing ? 'release' : 'reserve';
+    intro(options.dryRun ? `FireForge patch ${verb} (dry run)` : `FireForge patch ${verb}`);
+    const config = await loadConfig(projectRoot);
+    const label = formatPatchOrder(order);
+    let category;
+    let owner;
+    if (!releasing) {
+        category = options.category;
+        owner = options.owner?.trim();
+        if (category === undefined || owner === undefined || owner === '') {
+            throw new InvalidArgumentError('patch reserve requires --category and --owner (or --release to drop a reservation).', [category === undefined ? '--category' : '', owner ? '' : '--owner']
+                .filter(Boolean)
+                .join(', '));
+        }
+        if (!isCategoryAllowedByConfig(config, category)) {
+            throw new InvalidArgumentError(`Unknown patch category "${category}".`, '--category');
+        }
+    }
+    else if (options.category !== undefined || options.owner !== undefined) {
+        throw new InvalidArgumentError('--release takes only the order; --category and --owner apply when reserving.', '--release');
+    }
+    const { patches: patchesDir } = getProjectPaths(projectRoot);
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const manifest = (await loadPatchesManifestForWrite(patchesDir)) ?? {
+            version: 1,
+            patches: [],
+        };
+        const reserved = manifest.reserved ?? [];
+        let slot;
+        let next;
+        if (releasing) {
+            const held = reserved.find((entry) => entry.order === order);
+            if (held === undefined) {
+                throw new InvalidArgumentError(`Order ${label} is not reserved.`, '<order>');
+            }
+            slot = held;
+            next = reserved.filter((entry) => entry.order !== order);
+        }
+        else {
+            assertReservable(manifest, config, order, category);
+            slot = {
+                order,
+                category: category,
+                owner: owner,
+                reservedAt: new Date().toISOString(),
+                ...(options.reason !== undefined ? { reason: options.reason } : {}),
+            };
+            next = [...reserved, slot].sort((a, b) => a.order - b.order);
+        }
+        const summary = releasing
+            ? `release order ${label} (reserved by ${slot.owner})`
+            : `reserve order ${label} for ${slot.owner} (category: ${slot.category})`;
+        if (options.dryRun === true) {
+            info(`[dry-run] ${summary}`);
+            return;
+        }
+        if (next.length > 0)
+            manifest.reserved = next;
+        else
+            delete manifest.reserved;
+        await savePatchesManifest(patchesDir, manifest);
+        await appendHistoryBestEffort(patchesDir, {
+            operation: releasing ? 'patch-reserve-release' : 'patch-reserve',
+            args: { ...slot },
+            result: 'ok',
+        }, `patch ${verb} committed (${label})`);
+        info(releasing
+            ? `Released order ${label}.`
+            : `Reserved order ${label} for ${slot.owner}; "fireforge export --order ${label}" fills it.`);
+    }, { waitLockSeconds: resolveWaitLockSeconds(options.waitLock), command: `patch ${verb}` });
+    outro(options.dryRun ? 'Dry run complete — no changes made' : `Patch ${verb} complete`);
+}
+/**
+ * Registers the `patch reserve` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchReserve(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    const command = parent
+        .command('reserve <order>')
+        .description('Hold an order number for a patch not exported yet, so patchPolicy.allowGaps: false ' +
+        'sees no gap; the export that takes the order fills it (metadata only)')
+        .option('--category <category>', 'Category the reserved patch will carry')
+        .option('--owner <label>', 'Who holds the reservation (a session label or planned filename)')
+        .option('--reason <text>', 'Rationale recorded on the reserved slot')
+        .option('--release', 'Drop the reservation at <order> instead of creating one')
+        .option('--dry-run', 'Show what would change without writing');
+    addWaitLockOption(command).action(withErrorHandling(async (rawOrder, options) => {
+        await patchReserveCommand(getProjectRoot(), parsePositiveIntegerFlag('<order>', rawOrder), pickDefined(options));
+    }));
+}