@hominis/fireforge 0.43.1 → 0.44.1

package/dist/src/core/patch-manifest-consistency.js

@@ -3,6 +3,7 @@
  * Manifest consistency checks and rebuild/recovery operations.
  */
 import { stat } from 'node:fs/promises';
+import { GeneralError } from '../errors/base.js';
 import { discoverPatches, getAllTargetFilesFromPatch } from './patch-files.js';
 import { withPatchDirectoryLock } from './patch-lock.js';
 import { loadPatchesManifestState, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest-io.js';
@@ -59,8 +60,8 @@ export async function validatePatchesManifestConsistency(patchesDir) {
             });
             continue;
         }
-        const declaredFiles = normalizeFiles(metadata.filesAffected);
-        const actualFiles = normalizeFiles(await getAllTargetFilesFromPatch(patch.path));
+        const declaredFiles = normalizeAffectedFiles(metadata.filesAffected);
+        const actualFiles = normalizeAffectedFiles(await getAllTargetFilesFromPatch(patch.path));
         if (!sameStringArray(declaredFiles, actualFiles)) {
             issues.push({
                 code: 'files-affected-mismatch',
@@ -80,26 +81,78 @@ export async function validatePatchesManifestConsistency(patchesDir) {
     }
     return issues;
 }
+/**
+ * Recovery hint for an unrepaired consistency failure.
+ *
+ * Drift that is only in `filesAffected` is a derived value disagreeing with
+ * the diff it describes, and the narrow repair fixes exactly that. Naming the
+ * whole-manifest rebuild for it — as this hint used to, unconditionally — puts
+ * an operator one keystroke from rewriting every row in the manifest to
+ * correct one list.
+ */
+export function recommendManifestRepair(issues) {
+    const filesAffectedOnly = issues.length > 0 && issues.every((issue) => issue.code === 'files-affected-mismatch');
+    return filesAffectedOnly
+        ? 'Run "fireforge doctor --repair-files-affected" to recompute filesAffected from the patch ' +
+            'bodies (add --dry-run to preview). It rewrites only the drifted lists and leaves every ' +
+            'other manifest field untouched.'
+        : 'Run "fireforge doctor --repair-patches-manifest" to rebuild patches.json from the patch ' +
+            'files (add --dry-run to preview). Only filesAffected and order are recomputed; every ' +
+            'other field on an existing entry is preserved.';
+}
 /**
  * Rebuilds patches.json from the patch files currently present on disk.
- * Existing metadata is preserved when possible; missing entries are recovered
- * from filename structure, patch contents, and file mtimes.
+ *
+ * This is a MERGE, not a from-scratch rebuild: only `filesAffected` and
+ * `order` are recomputed from the patch files, and every other field on an
+ * existing entry is carried forward untouched. Entries with no pre-existing
+ * metadata are recovered from filename structure, patch contents, and file
+ * mtimes.
+ *
+ * Refuses when patches.json exists but cannot be parsed, because that is the
+ * one case where nothing can be carried forward and the "merge" silently
+ * becomes a whole-manifest reinvention. Pass `allowMetadataLoss` to accept it.
+ *
  * @param patchesDir - Path to the patches directory
  * @param fallbackSourceEsrVersion - source version to use for recovered legacy entries
- * @returns {@link RebuildPatchesManifestResult} — the persisted manifest
- *   plus the filenames that were reconstructed from generic defaults.
+ * @param options - Lock options plus `allowMetadataLoss` / `dryRun`
+ * @returns {@link RebuildPatchesManifestResult} — the rebuilt manifest, the
+ *   filenames that were reconstructed from generic defaults, and the rows
+ *   dropped because their patch file is gone.
  */
-export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersion) {
+export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersion, options = {}) {
     // The whole read → discover → rebuild → save cycle runs under the shared
     // patch-directory lock (invariant 2, docs/lifecycle-invariants.md):
-    // manifest writes serialize on this lock, and a repair racing a
-    // concurrent export/reorder used to be able to clobber the other
-    // writer's manifest. Not reentrant — callers must not already hold it.
-    return withPatchDirectoryLock(patchesDir, () => rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion));
+    // manifest writes serialize on this lock, so without it a repair racing a
+    // concurrent export/reorder can clobber the other writer's manifest. Not
+    // reentrant — callers must not already hold it.
+    //
+    // A dry run takes the lock too: it reads the same manifest and patch bodies
+    // a real run would, and a projection computed against a queue being
+    // rewritten underneath is worth less than no projection at all.
+    return withPatchDirectoryLock(patchesDir, () => rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion, options), options);
 }
-async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion) {
+async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion, options) {
     const manifestState = await loadPatchesManifestState(patchesDir);
     const existingEntries = new Map();
+    // An unparseable manifest yields `manifest: null`, which the merge below
+    // cannot distinguish from "no manifest at all" — every entry would be
+    // treated as new and every descriptive field reinvented. `filesAffected`
+    // is the only field a .patch body can yield; `stagedDependencies`,
+    // `lintIgnore`, `tier`, `description`, `category`, `createdAt` and the
+    // source version cannot be reconstructed from a diff at all. Refuse rather
+    // than write that, since the write is what makes it unrecoverable on a
+    // queue that is not under version control.
+    if (manifestState.exists && manifestState.parseError && options.allowMetadataLoss !== true) {
+        throw new GeneralError(`Refusing to rebuild ${PATCHES_MANIFEST}: it exists but could not be parsed ` +
+            `(${manifestState.parseError.message}). None of its metadata can be carried ` +
+            'forward, so every entry would be rebuilt with an invented description, an ' +
+            'mtime-based createdAt and an inferred category, and any stagedDependencies, ' +
+            'lintIgnore or tier declarations would be lost — a patch body carries none of ' +
+            'them.\n' +
+            `Fix the JSON in ${PATCHES_MANIFEST} (restore it from version control if you ` +
+            'can) and re-run, or pass --allow-metadata-loss to accept the reinvention.');
+    }
     if (manifestState.manifest) {
         for (const entry of manifestState.manifest.patches) {
             existingEntries.set(entry.filename, entry);
@@ -113,13 +166,12 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
     }, 0);
     let nextRecoveredOrder = highestFiniteOrder + 1;
     // Prefetch the two independent per-patch reads concurrently. This runs
-    // while the patch-directory lock is held, and it was two serialised awaits
-    // per patch across the whole queue — 58 round-trips on a 29-patch queue.
-    // The fold below stays sequential because `nextRecoveredOrder` is
-    // loop-carried: parallelising the assignment would scramble the recovered
-    // ordinals.
+    // while the patch-directory lock is held, and as two serialised awaits per
+    // patch it costs 58 round-trips on a 29-patch queue. The fold below stays
+    // sequential because `nextRecoveredOrder` is loop-carried: parallelising
+    // the assignment would scramble the recovered ordinals.
     const prefetched = await Promise.all(patches.map(async (patch) => ({
-        filesAffected: normalizeFiles(await getAllTargetFilesFromPatch(patch.path)),
+        filesAffected: normalizeAffectedFiles(await getAllTargetFilesFromPatch(patch.path)),
         patchStats: await stat(patch.path),
     })));
     for (const [index, patch] of patches.entries()) {
@@ -131,26 +183,27 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
         const inferred = inferPatchMetadataFromFilename(patch.filename);
         const recoveredOrder = Number.isFinite(patch.order) ? patch.order : nextRecoveredOrder++;
         if (!existing) {
-            // Track every filename that had no pre-existing manifest entry
-            // so callers can warn the operator per-patch. A missing entry
-            // means every descriptive field (`description`, `createdAt`,
-            // `category`) was invented rather than preserved. FireForge
-            // patch files carry no header metadata that could carry a
-            // human description forward, so full fidelity is impossible —
-            // visibility is the best we can offer. 2026-04-21 eval
-            // (Finding #17) tripped over silent overwrites of useful
-            // human-written descriptions during a recovery run.
+            // Track every filename that had no pre-existing manifest entry so
+            // callers can warn the operator per-patch. A missing entry means every
+            // descriptive field (`description`, `createdAt`, `category`) was
+            // invented rather than preserved, and FireForge patch files carry no
+            // header metadata that could carry a human description forward — so
+            // visibility is the best available, and silent overwrites of
+            // human-written descriptions during a recovery run are the failure to
+            // avoid.
             recoveredFilenames.push(patch.filename);
         }
-        // Preserve optional fields the operator declared on the existing
-        // entry — `lintIgnore` (per-patch lint suppression) and `tier`
-        // (explicit branding-threshold override). Without this, a
-        // `doctor --repair-patches-manifest` run silently strips both
-        // fields from every entry that had them, and the next `lint`
-        // or `re-export` pass fires rules the operator had intentionally
-        // quieted. Mirrors how other descriptive fields fall back to
-        // existing values when the entry is known.
+        // The rebuild OWNS exactly two fields — `filesAffected` (recomputed from
+        // the patch body) and `order` (from the filename ordinal). Everything
+        // else on an existing entry is carried forward by the spread, so a field
+        // a .patch cannot express — `stagedDependencies`, `lintIgnore`, `tier`,
+        // and whatever is added to PatchMetadata next — survives a repair by
+        // construction rather than by someone remembering to list it here. It was
+        // an enumerated literal until `stagedDependencies` was dropped from every
+        // entry that had one, which is the failure this shape prevents from
+        // recurring.
         const rebuilt = {
+            ...(existing ?? {}),
             filename: patch.filename,
             order: recoveredOrder,
             category: existing?.category ?? inferred.category,
@@ -160,24 +213,42 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
             createdAt: existing?.createdAt ?? new Date(patchStats.mtimeMs).toISOString(),
             sourceEsrVersion: existing?.sourceEsrVersion ?? fallbackSourceEsrVersion,
             sourceVersion: existing?.sourceVersion ?? existing?.sourceEsrVersion ?? fallbackSourceEsrVersion,
-            ...(existing?.sourceProduct !== undefined ? { sourceProduct: existing.sourceProduct } : {}),
             filesAffected,
         };
+        // Copy the arrays rather than aliasing the loaded manifest's, so a caller
+        // mutating the rebuilt entry cannot reach back into `manifestState`.
         if (existing?.lintIgnore !== undefined)
             rebuilt.lintIgnore = [...existing.lintIgnore];
-        if (existing?.tier !== undefined)
-            rebuilt.tier = existing.tier;
         rebuiltPatches.push(rebuilt);
+        existingEntries.delete(patch.filename);
     }
     rebuiltPatches.sort((left, right) => left.order - right.order || left.filename.localeCompare(right.filename));
     const rebuiltManifest = {
         version: 1,
         patches: rebuiltPatches,
     };
+    // Whatever is left in the map had a manifest row but no patch file, so the
+    // rebuild drops it. That is the correct outcome — the file is the source of
+    // truth — but dropping rows without naming them is indistinguishable from
+    // never having had them.
+    const droppedFilenames = [...existingEntries.keys()].sort((left, right) => left.localeCompare(right));
+    if (options.dryRun === true) {
+        return {
+            manifest: rebuiltManifest,
+            recoveredFilenames,
+            droppedFilenames,
+            written: false,
+        };
+    }
     await savePatchesManifest(patchesDir, rebuiltManifest);
-    return { manifest: rebuiltManifest, recoveredFilenames };
+    return { manifest: rebuiltManifest, recoveredFilenames, droppedFilenames, written: true };
 }
-function normalizeFiles(files) {
+/**
+ * Canonical form of a `filesAffected` list: deduplicated and sorted, so a
+ * comparison between a declared list and one extracted from a patch body is
+ * about membership rather than ordering.
+ */
+export function normalizeAffectedFiles(files) {
     return Array.from(new Set(files)).sort((left, right) => left.localeCompare(right));
 }
 function sameStringArray(left, right) {

package/dist/src/core/patch-manifest-files-affected.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Narrow repair for `filesAffected` — the one manifest field a `.patch` body
+ * can actually yield.
+ *
+ * A `files-affected-mismatch` is pure derived-value drift: the manifest's list
+ * disagrees with the diff it describes, and the diff is right by definition.
+ * Rebuilding the whole manifest to fix it is a much larger operation than the
+ * failure calls for, so this repair recomputes one field on the drifted rows
+ * and leaves every other row byte-identical.
+ */
+import type { PatchDirectoryLockOptions } from './patch-lock.js';
+/** One row whose `filesAffected` list disagreed with its patch body. */
+export interface FilesAffectedRepair {
+    /** Patch filename. */
+    filename: string;
+    /** The list the manifest declared, normalized for comparison. */
+    before: string[];
+    /** The list the patch body actually targets. */
+    after: string[];
+}
+/** Summary of a {@link repairPatchesFilesAffected} run. */
+export interface RepairFilesAffectedResult {
+    /** Rows that drifted and were (or would be) corrected. */
+    repairs: FilesAffectedRepair[];
+    /** Requested filenames with no manifest row, or no patch file on disk. */
+    skippedFilenames: string[];
+    /** False when the run was a dry run and patches.json was left untouched. */
+    written: boolean;
+}
+/** Options for {@link repairPatchesFilesAffected}. */
+export interface RepairFilesAffectedOptions extends PatchDirectoryLockOptions {
+    /** Compute the corrections without writing them. */
+    dryRun?: boolean;
+}
+/**
+ * Recomputes `filesAffected` from the patch body for the named patches.
+ *
+ * @param patchesDir - Path to the patches directory
+ * @param filenames - Patch filenames to repair
+ * @param options - Lock options plus `dryRun`
+ * @returns The corrections applied (or projected) and the filenames skipped
+ */
+export declare function repairPatchesFilesAffected(patchesDir: string, filenames: readonly string[], options?: RepairFilesAffectedOptions): Promise<RepairFilesAffectedResult>;

package/dist/src/core/patch-manifest-files-affected.js

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Narrow repair for `filesAffected` — the one manifest field a `.patch` body
+ * can actually yield.
+ *
+ * A `files-affected-mismatch` is pure derived-value drift: the manifest's list
+ * disagrees with the diff it describes, and the diff is right by definition.
+ * Rebuilding the whole manifest to fix it is a much larger operation than the
+ * failure calls for, so this repair recomputes one field on the drifted rows
+ * and leaves every other row byte-identical.
+ */
+import { GeneralError } from '../errors/base.js';
+import { discoverPatches, getAllTargetFilesFromPatch } from './patch-files.js';
+import { withPatchDirectoryLock } from './patch-lock.js';
+import { normalizeAffectedFiles } from './patch-manifest-consistency.js';
+import { loadPatchesManifestForWrite, mutatePatchRowsInManifest, PATCHES_MANIFEST, } from './patch-manifest-io.js';
+/**
+ * Recomputes `filesAffected` from the patch body for the named patches.
+ *
+ * @param patchesDir - Path to the patches directory
+ * @param filenames - Patch filenames to repair
+ * @param options - Lock options plus `dryRun`
+ * @returns The corrections applied (or projected) and the filenames skipped
+ */
+export async function repairPatchesFilesAffected(patchesDir, filenames, options = {}) {
+    // Same lock contract as the full rebuild (invariant 2,
+    // docs/lifecycle-invariants.md): a manifest write serializes on the
+    // patch-directory lock, and a dry run reads under it so its projection
+    // cannot be computed against a queue being rewritten underneath.
+    return withPatchDirectoryLock(patchesDir, () => repairPatchesFilesAffectedUnderLock(patchesDir, filenames, options), options);
+}
+async function repairPatchesFilesAffectedUnderLock(patchesDir, filenames, options) {
+    // ForWrite: a corrupt manifest must abort here rather than be treated as
+    // empty. This repair exists precisely so that a one-field drift never
+    // reaches a whole-manifest rewrite, and silently writing over unparseable
+    // metadata would be a larger version of what it avoids.
+    const manifest = await loadPatchesManifestForWrite(patchesDir);
+    if (!manifest) {
+        throw new GeneralError(`Cannot repair filesAffected: ${PATCHES_MANIFEST} does not exist in ${patchesDir}.`);
+    }
+    const patchPathByFilename = new Map((await discoverPatches(patchesDir)).map((patch) => [patch.filename, patch.path]));
+    const rowByFilename = new Map(manifest.patches.map((entry) => [entry.filename, entry]));
+    const repairs = [];
+    const skippedFilenames = [];
+    for (const filename of new Set(filenames)) {
+        const patchPath = patchPathByFilename.get(filename);
+        const row = rowByFilename.get(filename);
+        if (patchPath === undefined || !row) {
+            // A missing patch file or a missing row is a different consistency
+            // issue with a different remedy; this repair reports it rather than
+            // inventing a row or deleting one.
+            skippedFilenames.push(filename);
+            continue;
+        }
+        const before = normalizeAffectedFiles(row.filesAffected);
+        const after = normalizeAffectedFiles(await getAllTargetFilesFromPatch(patchPath));
+        if (sameFiles(before, after))
+            continue;
+        repairs.push({ filename, before, after });
+    }
+    skippedFilenames.sort((left, right) => left.localeCompare(right));
+    if (repairs.length === 0 || options.dryRun === true) {
+        return { repairs, skippedFilenames, written: false };
+    }
+    const correctedByFilename = new Map(repairs.map((repair) => [repair.filename, repair.after]));
+    // Row-scoped mutation, so every untouched entry keeps its exact JSON shape —
+    // no re-sorted `filesAffected` lists and no reader-only fallback fields
+    // serialized into rows this repair has no business touching.
+    await mutatePatchRowsInManifest(patchesDir, [...correctedByFilename.keys()], (existing) => {
+        const corrected = correctedByFilename.get(existing.filename);
+        return corrected ? { set: { filesAffected: corrected } } : null;
+    });
+    return { repairs, skippedFilenames, written: true };
+}
+function sameFiles(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}

package/dist/src/core/patch-manifest-io.js

@@ -12,7 +12,7 @@ import { rename } from 'node:fs/promises';
 import { join } from 'node:path';
 import { FireForgeError } from '../errors/base.js';
 import { ExitCode } from '../errors/codes.js';
-import { PatchManifestCorruptError } from '../errors/patch.js';
+import { PatchError, PatchManifestCorruptError } from '../errors/patch.js';
 import { assert } from '../utils/assert.js';
 import { toError } from '../utils/errors.js';
 import { pathExistsStrict, readJson, removeFile, writeJson } from '../utils/fs.js';
@@ -315,7 +315,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
     await assertPatchDirectoryLockHeld(patchesDir, 'renumbering the patch manifest');
     const manifest = await loadPatchesManifestForWrite(patchesDir);
     if (!manifest) {
-        throw new Error('Cannot renumber patches: patches.json is missing.');
+        throw new PatchError('Cannot renumber patches: patches.json is missing.');
     }
     // Phase 1: rename each old filename to a unique temp staging name so the
     // later rename to the final target cannot collide with another entry
@@ -326,7 +326,7 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
         for (const [oldFilename, entry] of renameMap) {
             const oldPath = join(patchesDir, oldFilename);
             if (!(await pathExistsStrict(oldPath))) {
-                throw new Error(`Cannot renumber: patch file is missing on disk: ${oldFilename}`);
+                throw new PatchError(`Cannot renumber: patch file is missing on disk: ${oldFilename}`, oldFilename);
             }
             const stagedName = `.fireforge-renumber-${stagingId}-${oldFilename}`;
             const stagedPath = join(patchesDir, stagedName);
@@ -354,18 +354,16 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
             const { staged, toEntry } = stagedEntry;
             const targetPath = join(patchesDir, toEntry.newFilename);
             if (await pathExistsStrict(targetPath)) {
-                throw new Error(`Cannot renumber: target patch filename already exists on disk: ${toEntry.newFilename}`);
+                throw new PatchError(`Cannot renumber: target patch filename already exists on disk: ${toEntry.newFilename}`, toEntry.newFilename);
             }
             await rename(join(patchesDir, staged), targetPath);
-            // Postcondition assert: confirm the target actually exists on
-            // disk before we mark the rename complete. A silent rename
-            // failure would leave the manifest and the filesystem
-            // disagreeing — exactly what the eval 1 Finding #7 report
-            // described: manifest rewrote to new filenames while the old
-            // files stayed on disk. If the assert ever fires, the Phase 2
-            // rollback will undo prior moves before re-throwing.
+            // Postcondition assert: confirm the target actually exists on disk
+            // before marking the rename complete. A silent rename failure leaves
+            // the manifest and the filesystem disagreeing — manifest rewritten to
+            // new filenames while the old files stay on disk. If the assert fires,
+            // the Phase 2 rollback undoes prior moves before re-throwing.
             if (!(await pathExistsStrict(targetPath))) {
-                throw new Error(`Rename postcondition failed: expected ${toEntry.newFilename} to exist after rename, but it was not found on disk.`);
+                throw new PatchError(`Rename postcondition failed: expected ${toEntry.newFilename} to exist after rename, but it was not found on disk.`, toEntry.newFilename);
             }
             completedFinalRenames.push(stagedEntry);
         }
@@ -525,12 +523,10 @@ export async function removePatchFileAndManifest(patchesDir, filename) {
                 await savePatchesManifest(patchesDir, originalManifest);
             }
             catch (rollbackError) {
-                // Compound failure: both the delete and the rollback failed,
-                // so the directory is in a known-inconsistent state. Throw a
-                // dedicated error type that carries both causes so the
-                // operator's log shows the complete picture instead of the
-                // original delete error with a warning about the rollback
-                // buried in stderr.
+                // Compound failure: both the delete and the rollback failed, so the
+                // directory is in a known-inconsistent state. A dedicated error type
+                // carrying both causes shows the complete picture instead of the
+                // original delete error with a rollback warning buried in stderr.
                 throw new PatchDeleteRollbackError(filename, deleteError, toError(rollbackError));
             }
         }

package/dist/src/core/patch-manifest-resolve.d.ts

@@ -7,18 +7,15 @@ import type { PatchMetadata } from '../types/commands/index.js';
  *      matches `PatchMetadata.filename`.
  *   3. A filename without the `.patch` suffix — the command appends it
  *      before matching (e.g. `002-ui-foo`).
- *   4. The manifest `name` field (e.g. `eval-furnace-token-override`) —
- *      matches `PatchMetadata.name`. This is the short logical handle
- *      the export workflow stamps onto the patch and the natural
- *      identifier an operator keeps in their notes. 2026-04-21 eval
- *      (Finding #6): `patch reorder`/`delete` rejected the `name`
- *      even though the CLI help said `<name>`, forcing the operator
- *      to copy the full filename from `patches.json` before every
- *      queue mutation.
+ *   4. The manifest `name` field (e.g. `furnace-token-override`) — the short
+ *      logical handle the export workflow stamps onto the patch and the
+ *      natural identifier an operator keeps in their notes. The CLI help
+ *      says `<name>`, so rejecting it forces the operator to copy the full
+ *      filename out of `patches.json` before every queue mutation.
  *
- * Resolution order is strict: numeric ordinals first, then filename
- * lookup (with + without `.patch` suffix), then name-field lookup.
- * The filename lookup beats the name lookup when the two happen to
- * collide so legacy scripts that pass filenames keep working.
+ * Resolution order is strict: numeric ordinals first, then filename lookup
+ * (with and without the `.patch` suffix), then name-field lookup. The
+ * filename lookup beats the name lookup when the two collide, so scripts
+ * that pass filenames keep working.
  */
 export declare function resolvePatchIdentifier(identifier: string, patches: PatchMetadata[]): PatchMetadata | null;

package/dist/src/core/patch-manifest-resolve.js

@@ -6,19 +6,16 @@
  *      matches `PatchMetadata.filename`.
  *   3. A filename without the `.patch` suffix — the command appends it
  *      before matching (e.g. `002-ui-foo`).
- *   4. The manifest `name` field (e.g. `eval-furnace-token-override`) —
- *      matches `PatchMetadata.name`. This is the short logical handle
- *      the export workflow stamps onto the patch and the natural
- *      identifier an operator keeps in their notes. 2026-04-21 eval
- *      (Finding #6): `patch reorder`/`delete` rejected the `name`
- *      even though the CLI help said `<name>`, forcing the operator
- *      to copy the full filename from `patches.json` before every
- *      queue mutation.
+ *   4. The manifest `name` field (e.g. `furnace-token-override`) — the short
+ *      logical handle the export workflow stamps onto the patch and the
+ *      natural identifier an operator keeps in their notes. The CLI help
+ *      says `<name>`, so rejecting it forces the operator to copy the full
+ *      filename out of `patches.json` before every queue mutation.
  *
- * Resolution order is strict: numeric ordinals first, then filename
- * lookup (with + without `.patch` suffix), then name-field lookup.
- * The filename lookup beats the name lookup when the two happen to
- * collide so legacy scripts that pass filenames keep working.
+ * Resolution order is strict: numeric ordinals first, then filename lookup
+ * (with and without the `.patch` suffix), then name-field lookup. The
+ * filename lookup beats the name lookup when the two collide, so scripts
+ * that pass filenames keep working.
  */
 export function resolvePatchIdentifier(identifier, patches) {
     if (/^\d+$/.test(identifier)) {

package/dist/src/core/patch-manifest-validate.d.ts

@@ -2,7 +2,12 @@
  * Schema validation for patches.json manifest data.
  */
 import type { PatchCategory, PatchesManifest } from '../types/commands/index.js';
-/** Validates raw patches.json data and returns the typed manifest shape. */
+/**
+ * Validates raw patches.json data and returns the typed manifest shape.
+ *
+ * @param data - Parsed patches.json content
+ * @returns The validated manifest
+ */
 export declare function validatePatchesManifest(data: unknown): PatchesManifest;
 /**
  * Infers patch metadata from a filename pattern.

package/dist/src/core/patch-manifest-validate.js

@@ -4,6 +4,7 @@
  */
 import { parseObject } from '../utils/parse.js';
 import { isArray, isObject, isValidFirefoxProduct, isValidFirefoxVersion, PATCH_CATEGORIES, } from '../utils/validation.js';
+import { checkDocumentVersion, describeNewerDocument } from './state-file.js';
 function parseForwardImports(data, label) {
     if (!isArray(data)) {
         throw new Error(`${label} must be an array`);
@@ -91,16 +92,13 @@ function validatePatchMetadata(data, index) {
         throw new Error(`patches[${index}].sourceEsrVersion must be a valid Firefox version string`);
     }
     const filesAffected = rec.stringArray('filesAffected');
-    // Optional fields. These were silently stripped before the 0.17.0
-    // branding-tier work reached in and audited the loader — the 0.16.0
-    // `lintIgnore` escape hatch demonstrably round-tripped only through
-    // test fixtures that mocked `loadPatchesManifest` directly. Real
-    // operator edits to `patches.json` were dropped on every subsequent
-    // load, so any patch that relied on `lintIgnore` to suppress a
-    // specific lint rule was quietly re-tripped the next time the
-    // manifest validated. Preserve both the pre-existing `lintIgnore`
-    // and the new `tier` field here so future-added optional fields
-    // have a ready template to follow.
+    // Optional fields. These are easy to strip silently — an escape hatch
+    // that round-trips only through test fixtures mocking
+    // `loadPatchesManifest` looks fine while real operator edits to
+    // `patches.json` are dropped on every load, so a patch relying on
+    // `lintIgnore` to suppress a rule is quietly re-tripped the next time the
+    // manifest validates. Preserve both `lintIgnore` and `tier` here; future
+    // optional fields follow the same template.
     const lintIgnore = rec.optionalStringArray('lintIgnore');
     const rawTier = rec.raw('tier');
     let tier;
@@ -133,13 +131,27 @@ function validatePatchMetadata(data, index) {
     }
     return result;
 }
-/** Validates raw patches.json data and returns the typed manifest shape. */
+/** Manifest schema version this build writes and understands. */
+const PATCHES_MANIFEST_VERSION = 1;
+/**
+ * Validates raw patches.json data and returns the typed manifest shape.
+ *
+ * @param data - Parsed patches.json content
+ * @returns The validated manifest
+ */
 export function validatePatchesManifest(data) {
     if (!isObject(data)) {
         throw new Error('patches.json must be a JSON object');
     }
-    if (data['version'] !== 1) {
-        throw new Error('patches.json version must be 1');
+    // A manifest from a NEWER FireForge is not corrupt. The bare "version must
+    // be 1" this replaced sent the operator looking for damage in a file that
+    // only needed a newer build to read it.
+    const version = checkDocumentVersion(data, 'version', PATCHES_MANIFEST_VERSION);
+    if (version.kind === 'newer') {
+        throw new Error(describeNewerDocument('patches manifest', version.found, PATCHES_MANIFEST_VERSION));
+    }
+    if (version.kind !== 'current') {
+        throw new Error(`patches.json version must be ${PATCHES_MANIFEST_VERSION}`);
     }
     if (!isArray(data['patches'])) {
         throw new Error('patches.json field "patches" must be an array');

package/dist/src/core/patch-manifest.d.ts

@@ -4,7 +4,8 @@
  * Callers should continue to import from this module; the internal split
  * is an implementation detail.
  */
-export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
+export { type PatchManifestConsistencyIssue, rebuildPatchesManifest, recommendManifestRepair, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
+export { type FilesAffectedRepair, repairPatchesFilesAffected, } from './patch-manifest-files-affected.js';
 export { addPatchToManifest, loadPatchesManifest, loadPatchesManifestForWrite, mutatePatchRowsInManifest, PATCHES_MANIFEST, type PatchRenameEntry, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
 export { checkVersionCompatibility, findPatchesAffectingFile, getClaimedFiles, stampPatchVersions, validatePatchIntegrity, } from './patch-manifest-query.js';
 export { resolvePatchIdentifier } from './patch-manifest-resolve.js';

package/dist/src/core/patch-manifest.js

@@ -5,7 +5,8 @@
  * Callers should continue to import from this module; the internal split
  * is an implementation detail.
  */
-export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
+export { rebuildPatchesManifest, recommendManifestRepair, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
+export { repairPatchesFilesAffected, } from './patch-manifest-files-affected.js';
 export { addPatchToManifest, loadPatchesManifest, loadPatchesManifestForWrite, mutatePatchRowsInManifest, PATCHES_MANIFEST, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
 export { checkVersionCompatibility, findPatchesAffectingFile, getClaimedFiles, stampPatchVersions, validatePatchIntegrity, } from './patch-manifest-query.js';
 export { resolvePatchIdentifier } from './patch-manifest-resolve.js';