@hominis/fireforge 0.52.0 → 0.53.0

package/dist/src/core/negative-control-compiled.d.ts

@@ -6,15 +6,25 @@
  * objdir links to. A C++ (or Rust, IDL, …) source edited at that point is
  * never compiled: the run tests the unmutated binary and reports
  * `control=missed`, which reads as a test that cannot fail. Such a target
- * is now refused without `--build`, and with `--build` the control is
+ * is refused without `--build`, and with `--build` the control is
  * applied before the build so the binary under test carries it. That build
  * is a full `mach build`: the pre-test build is otherwise `mach build
- * faster`, which compiles nothing, so the control still missed.
+ * faster`, which compiles nothing, so the control would still miss.
  */
+/**
+ * Whether an engine-relative path has a compiled-source extension: a file
+ * the build compiles or code-generates into the binary. This is the
+ * extension test only. {@link findCompiledControlTargets} additionally
+ * drops non-header files an install manifest ships as-is.
+ *
+ * @param path - Engine-relative path
+ */
+export declare function isCompiledSourcePath(path: string): boolean;
 /**
  * The engine-relative targets that reach the runtime only through a
  * compile: a compiled-source extension and no install-manifest entry that
- * ships the file itself.
+ * ships the file itself. Headers are always compiled, even when an
+ * `EXPORTS` manifest installs them into `dist/include`.
  *
  * @param engineDir - Absolute engine directory
  * @param enginePaths - The control's engine-relative targets

package/dist/src/core/negative-control-compiled.js

@@ -7,10 +7,10 @@
  * objdir links to. A C++ (or Rust, IDL, …) source edited at that point is
  * never compiled: the run tests the unmutated binary and reports
  * `control=missed`, which reads as a test that cannot fail. Such a target
- * is now refused without `--build`, and with `--build` the control is
+ * is refused without `--build`, and with `--build` the control is
  * applied before the build so the binary under test carries it. That build
  * is a full `mach build`: the pre-test build is otherwise `mach build
- * faster`, which compiles nothing, so the control still missed.
+ * faster`, which compiles nothing, so the control would still miss.
  */
 import { extname } from 'node:path';
 import { classifyRuntimeDelivery } from './objdir-install-manifests.js';
@@ -34,24 +34,46 @@ const COMPILED_EXTENSIONS = new Set([
     '.yaml',
     '.yml',
 ]);
+/**
+ * Header extensions. An `EXPORTS` install manifest names many headers (it
+ * copies them into `dist/include`), but that copy only feeds other
+ * compiles: the runtime never reads a header, so a header edit reaches the
+ * binary through a compile whatever the manifests say.
+ */
+const HEADER_EXTENSIONS = new Set(['.h', '.hh', '.hpp', '.ipdlh']);
+/**
+ * Whether an engine-relative path has a compiled-source extension: a file
+ * the build compiles or code-generates into the binary. This is the
+ * extension test only. {@link findCompiledControlTargets} additionally
+ * drops non-header files an install manifest ships as-is.
+ *
+ * @param path - Engine-relative path
+ */
+export function isCompiledSourcePath(path) {
+    return COMPILED_EXTENSIONS.has(extname(path));
+}
 /**
  * The engine-relative targets that reach the runtime only through a
  * compile: a compiled-source extension and no install-manifest entry that
- * ships the file itself.
+ * ships the file itself. Headers are always compiled, even when an
+ * `EXPORTS` manifest installs them into `dist/include`.
  *
  * @param engineDir - Absolute engine directory
  * @param enginePaths - The control's engine-relative targets
  */
 export async function findCompiledControlTargets(engineDir, enginePaths) {
-    const candidates = enginePaths.filter((path) => COMPILED_EXTENSIONS.has(extname(path)));
+    const candidates = enginePaths.filter(isCompiledSourcePath);
     if (candidates.length === 0)
         return [];
+    if (candidates.every((path) => HEADER_EXTENSIONS.has(extname(path))))
+        return candidates;
     const index = await loadEngineInstallIndex(engineDir);
     if (index === undefined)
         return candidates;
     const compiled = [];
     for (const path of candidates) {
-        if ((await classifyRuntimeDelivery(index, engineDir, path)) === 'unlisted') {
+        if (HEADER_EXTENSIONS.has(extname(path)) ||
+            (await classifyRuntimeDelivery(index, engineDir, path)) === 'unlisted') {
             compiled.push(path);
         }
     }

package/dist/src/core/parser-fallback.d.ts

@@ -13,12 +13,12 @@ export declare function consumeParserFallbackEvents(): ParserFallbackEvent[];
  * The `rethrowIf` predicate every AST-primary caller wants.
  *
  * Rethrows internal-invariant `GeneralError`s ("Unexpected empty …array"):
- * those are programming bugs, and retrying the legacy scanner cannot fix a
+ * those are programming bugs, and retrying the fallback scanner cannot fix a
  * broken invariant, it just buries the stack. Everything else still falls
  * back, which matters: the AST path raises a raw acorn SyntaxError
  * on chrome sources acorn cannot parse (preprocessor directives), and
  * BuildError when the file's shape is unexpected. Both are exactly what the
- * legacy scanner is here to handle.
+ * fallback scanner is here to handle.
  *
  * @param error - The error the primary parser threw
  * @returns True when the error must propagate instead of falling back
@@ -33,15 +33,15 @@ export interface ParserResult<T> {
     fallbackReason?: string;
 }
 /**
- * Wraps a primary (AST/tokenizer) parser with a legacy (regex/line-based)
+ * Wraps a primary (AST/tokenizer) parser with a regex/line-based
  * fallback. If the primary throws, a warning is logged and the fallback is
  * used instead.
  *
  * Returns a {@link ParserResult} so callers (and tests) can detect which
  * code path was taken and surface it in logs or assertions.
  *
- * @param primary - The modern parser implementation
- * @param fallback - The legacy fallback implementation
+ * @param primary - The primary parser implementation
+ * @param fallback - The regex/line-based fallback implementation
  * @param context - File/context name used in the warning message
  * @param rethrowIf - Optional predicate. If it returns true for the caught
  *   error the error is re-thrown instead of falling back (useful for

package/dist/src/core/parser-fallback.js

@@ -18,12 +18,12 @@ export function consumeParserFallbackEvents() {
  * The `rethrowIf` predicate every AST-primary caller wants.
  *
  * Rethrows internal-invariant `GeneralError`s ("Unexpected empty …array"):
- * those are programming bugs, and retrying the legacy scanner cannot fix a
+ * those are programming bugs, and retrying the fallback scanner cannot fix a
  * broken invariant, it just buries the stack. Everything else still falls
  * back, which matters: the AST path raises a raw acorn SyntaxError
  * on chrome sources acorn cannot parse (preprocessor directives), and
  * BuildError when the file's shape is unexpected. Both are exactly what the
- * legacy scanner is here to handle.
+ * fallback scanner is here to handle.
  *
  * @param error - The error the primary parser threw
  * @returns True when the error must propagate instead of falling back
@@ -32,15 +32,15 @@ export function isInternalInvariantFailure(error) {
     return error instanceof GeneralError;
 }
 /**
- * Wraps a primary (AST/tokenizer) parser with a legacy (regex/line-based)
+ * Wraps a primary (AST/tokenizer) parser with a regex/line-based
  * fallback. If the primary throws, a warning is logged and the fallback is
  * used instead.
  *
  * Returns a {@link ParserResult} so callers (and tests) can detect which
  * code path was taken and surface it in logs or assertions.
  *
- * @param primary - The modern parser implementation
- * @param fallback - The legacy fallback implementation
+ * @param primary - The primary parser implementation
+ * @param fallback - The regex/line-based fallback implementation
  * @param context - File/context name used in the warning message
  * @param rethrowIf - Optional predicate. If it returns true for the caught
  *   error the error is re-thrown instead of falling back (useful for

package/dist/src/core/patch-identifier-suggest.d.ts

@@ -18,3 +18,9 @@ import type { PatchMetadata } from '../types/commands/index.js';
  * `InvalidArgumentError` body, never the full queue enumeration.
  */
 export declare function formatPatchNotFoundError(identifier: string, patches: readonly PatchMetadata[]): string;
+/**
+ * The nearest-match half of {@link formatPatchNotFoundError}: the closest
+ * accepted identifiers and the queue size, never the full queue. For
+ * callers that word their own lead, such as the `--patches` subset.
+ */
+export declare function formatPatchSuggestions(identifier: string, patches: readonly PatchMetadata[]): string;

package/dist/src/core/patch-identifier-suggest.js

@@ -118,11 +118,18 @@ function rankSuggestions(identifier, candidates) {
  * `InvalidArgumentError` body, never the full queue enumeration.
  */
 export function formatPatchNotFoundError(identifier, patches) {
-    const accepted = collectAcceptedIdentifiers(patches);
-    const suggestions = rankSuggestions(identifier, accepted);
     const lead = `Patch "${identifier}" not found. Accepted identifiers: ordinal (e.g. 2), filename (e.g. 002-ui-foo.patch), or manifest name (e.g. ui-foo).`;
+    return `${lead} ${formatPatchSuggestions(identifier, patches)}`;
+}
+/**
+ * The nearest-match half of {@link formatPatchNotFoundError}: the closest
+ * accepted identifiers and the queue size, never the full queue. For
+ * callers that word their own lead, such as the `--patches` subset.
+ */
+export function formatPatchSuggestions(identifier, patches) {
+    const suggestions = rankSuggestions(identifier, collectAcceptedIdentifiers(patches));
     if (suggestions.length > 0) {
-        return `${lead} Did you mean: ${suggestions.join(', ')}? (${patches.length} patches in queue — run "fireforge patch list" for the full list.)`;
+        return `Did you mean: ${suggestions.join(', ')}? (${patches.length} patches in queue — run "fireforge patch list" for the full list.)`;
     }
-    return `${lead} No close match found among ${patches.length} patches in the queue. Run "fireforge patch list" to see them.`;
+    return `No close match found among ${patches.length} patches in the queue. Run "fireforge patch list" to see them.`;
 }

package/dist/src/core/patch-lint-checkjs.d.ts

@@ -9,7 +9,7 @@
  *
  * Separated from `patch-lint.ts` to keep both files within the
  * project's per-file line budget. The shim itself and the suppressed
- * diagnostic code list now live in `typecheck-shim.ts` and are shared
+ * diagnostic code list live in `typecheck-shim.ts` and are shared
  * with the whole-project `fireforge typecheck` command, keeping a
  * single source of truth for the Firefox-globals coverage.
  * `patchLint.checkJsStrict` only tightens `strict` / `noImplicitAny`

package/dist/src/core/patch-lint-checkjs.js

@@ -10,7 +10,7 @@
  *
  * Separated from `patch-lint.ts` to keep both files within the
  * project's per-file line budget. The shim itself and the suppressed
- * diagnostic code list now live in `typecheck-shim.ts` and are shared
+ * diagnostic code list live in `typecheck-shim.ts` and are shared
  * with the whole-project `fireforge typecheck` command, keeping a
  * single source of truth for the Firefox-globals coverage.
  * `patchLint.checkJsStrict` only tightens `strict` / `noImplicitAny`

package/dist/src/core/patch-lint-css.js

@@ -65,7 +65,7 @@ const RAW_COLOR_IGNORE_MARKER = 'fireforge-ignore: raw-color-value';
  * comment spanning the context/added boundary suppresses its hex, then
  * only the patch's added line numbers are scanned. Returns undefined
  * when any added line number falls outside the on-disk file (patch not
- * applied / drifted). The caller then falls back to the legacy
+ * applied / drifted). The caller then falls back to the
  * joined-added-lines scan rather than misattributing lines.
  */
 function buildAddedLinesScanSource(rawCss, addedNumbers) {
@@ -100,7 +100,7 @@ function checkRawColorValues(input) {
         suppressedContent = buildAddedLinesScanSource(rawCss, addedNumbers);
     }
     if (suppressedContent === undefined) {
-        // Legacy scan: full file (no diff), or the joined added lines when
+        // Fallback scan: full file (no diff), or the joined added lines when
         // the diff and on-disk file disagree. Waiver lines are filtered
         // against the pre-strip text so the CSS comment marker is present.
         const sourceForSuppression = addedLinesByFile

package/dist/src/core/patch-lint-file-size.d.ts

@@ -6,13 +6,11 @@
  * `patch-lint.ts` from `config-validate.ts` for a constant would draw an
  * import edge (and a cycle) between the rule bodies and config parsing.
  *
- * On the vocabulary: the bands were `notice` / `warning` / `error` with the
- * middle one described as a "soft limit". That description is false under
- * the posture FireForge itself recommends for a release gate,
- * `--max-warnings 0`, where a warning is a hard failure, so a file at 751
- * lines failed a gate with a message calling 750 soft. The message below
- * says what the band is (a warning) and what a zero-warning gate does with
- * it, and the thresholds are now tunable, so a project whose file-size
+ * On the vocabulary: the bands are `notice` / `warning` / `error`, and the
+ * middle one is not a "soft limit". Under the posture FireForge itself
+ * recommends for a release gate, `--max-warnings 0`, a warning is a hard
+ * failure. The message below therefore says what the band is (a warning)
+ * and what a zero-warning gate does with it, and the thresholds are tunable, so a project whose file-size
  * policy differs has a dial instead of an argument. The notice band is the
  * design target: advisory, and its message says so rather than borrowing
  * the warning band's gate sentence.

package/dist/src/core/patch-lint-file-size.js

@@ -7,13 +7,11 @@
  * `patch-lint.ts` from `config-validate.ts` for a constant would draw an
  * import edge (and a cycle) between the rule bodies and config parsing.
  *
- * On the vocabulary: the bands were `notice` / `warning` / `error` with the
- * middle one described as a "soft limit". That description is false under
- * the posture FireForge itself recommends for a release gate,
- * `--max-warnings 0`, where a warning is a hard failure, so a file at 751
- * lines failed a gate with a message calling 750 soft. The message below
- * says what the band is (a warning) and what a zero-warning gate does with
- * it, and the thresholds are now tunable, so a project whose file-size
+ * On the vocabulary: the bands are `notice` / `warning` / `error`, and the
+ * middle one is not a "soft limit". Under the posture FireForge itself
+ * recommends for a release gate, `--max-warnings 0`, a warning is a hard
+ * failure. The message below therefore says what the band is (a warning)
+ * and what a zero-warning gate does with it, and the thresholds are tunable, so a project whose file-size
  * policy differs has a dial instead of an argument. The notice band is the
  * design target: advisory, and its message says so rather than borrowing
  * the warning band's gate sentence.

package/dist/src/core/patch-lint-ignore.d.ts

@@ -3,9 +3,9 @@
  *
  * An entry is either a bare check ID, which suppresses that rule at any
  * size, or a ceiling `{ rule, max, reason }`, which suppresses a size rule
- * only while its measurement is at or below `max`. The bare form let a
- * waived file grow without bound: nothing re-examined the waiver once it
- * was written, so a 950-line file waived at review time was still waived at
+ * only while its measurement is at or below `max`. The bare form lets a
+ * waived file grow without bound: nothing re-examines the waiver once it
+ * is written, so a 950-line file waived at review time is still waived at
  * 2,000 lines. The ceiling makes growth past the reviewed size fire again,
  * and lets a gate say when the waiver is no longer needed at all.
  *

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

@@ -4,9 +4,9 @@
  *
  * An entry is either a bare check ID, which suppresses that rule at any
  * size, or a ceiling `{ rule, max, reason }`, which suppresses a size rule
- * only while its measurement is at or below `max`. The bare form let a
- * waived file grow without bound: nothing re-examined the waiver once it
- * was written, so a 950-line file waived at review time was still waived at
+ * only while its measurement is at or below `max`. The bare form lets a
+ * waived file grow without bound: nothing re-examines the waiver once it
+ * is written, so a 950-line file waived at review time is still waived at
  * 2,000 lines. The ceiling makes growth past the reviewed size fire again,
  * and lets a gate say when the waiver is no longer needed at all.
  *

package/dist/src/core/patch-lint-prettier.d.ts

@@ -1,14 +1,12 @@
 /**
  * Optional Prettier pass over patch-owned `.sys.mjs` modules.
  *
- * Until 0.45.0 no tier of the chain ran Prettier on `.sys.mjs` at all, so
- * module formatting drift was caught by nothing and survived to a human
- * reviewer. Worse, the obvious manual check was misleading in the same
- * direction: a fork's root `.prettierignore` typically excludes `engine/`,
+ * Without this pass no tier of the chain runs Prettier on `.sys.mjs`, so
+ * module formatting drift survives to a human reviewer. The obvious manual
+ * check is misleading in the same direction: a fork's root `.prettierignore` typically excludes `engine/`,
  * so `prettier --check --config engine/.prettierrc.js <engine files>` run
  * from the repo root reports "all files use Prettier code style" for files
- * that fail the identical check run from inside `engine/`. A root-level
- * spot-check falsely refuted a correct reviewer finding on exactly this.
+ * that fail the identical check run from inside `engine/`.
  *
  * This pass therefore runs prettier with `cwd` set to the engine directory,
  * so the engine's own `.prettierrc*` and `.prettierignore` resolve the way

package/dist/src/core/patch-lint-prettier.js

@@ -2,14 +2,12 @@
 /**
  * Optional Prettier pass over patch-owned `.sys.mjs` modules.
  *
- * Until 0.45.0 no tier of the chain ran Prettier on `.sys.mjs` at all, so
- * module formatting drift was caught by nothing and survived to a human
- * reviewer. Worse, the obvious manual check was misleading in the same
- * direction: a fork's root `.prettierignore` typically excludes `engine/`,
+ * Without this pass no tier of the chain runs Prettier on `.sys.mjs`, so
+ * module formatting drift survives to a human reviewer. The obvious manual
+ * check is misleading in the same direction: a fork's root `.prettierignore` typically excludes `engine/`,
  * so `prettier --check --config engine/.prettierrc.js <engine files>` run
  * from the repo root reports "all files use Prettier code style" for files
- * that fail the identical check run from inside `engine/`. A root-level
- * spot-check falsely refuted a correct reviewer finding on exactly this.
+ * that fail the identical check run from inside `engine/`.
  *
  * This pass therefore runs prettier with `cwd` set to the engine directory,
  * so the engine's own `.prettierrc*` and `.prettierignore` resolve the way

package/dist/src/core/patch-lint-projection.d.ts

@@ -8,7 +8,7 @@ import type { PatchLintIssue } from '../types/commands/index.js';
  * whose message text can drift between otherwise-equivalent runs (for
  * example because the message embeds later-owner filenames or positional
  * detail). Falling back to the full tuple keeps the helper conservative
- * for older/non-fingerprinted rules: if their message changes, we would
+ * for non-fingerprinted rules: if their message changes, we would
  * rather surface a potential regression than silently swallow it.
  *
  * Consumption order within the projected list is stable (the input

package/dist/src/core/patch-lint-projection.js

@@ -7,7 +7,7 @@
  * whose message text can drift between otherwise-equivalent runs (for
  * example because the message embeds later-owner filenames or positional
  * detail). Falling back to the full tuple keeps the helper conservative
- * for older/non-fingerprinted rules: if their message changes, we would
+ * for non-fingerprinted rules: if their message changes, we would
  * rather surface a potential regression than silently swallow it.
  *
  * Consumption order within the projected list is stable (the input

package/dist/src/core/patch-lint-queue-types.d.ts

@@ -3,8 +3,8 @@
  *
  * A leaf module by design: it imports nothing, so the individual rule
  * modules can describe the slice of `PatchQueueContext` they read without
- * importing `patch-lint-cross.ts` (which imports them back). Previously each
- * rule re-declared its own private `{ entries }` interface. Sharing them here
+ * importing `patch-lint-cross.ts` (which imports them back). Sharing them
+ * here instead of re-declaring a private `{ entries }` interface per rule
  * keeps the dependency edge one-way and `dpdm` clean while stating the shape
  * once.
  */

package/dist/src/core/patch-lint-queue-types.js

@@ -4,8 +4,8 @@
  *
  * A leaf module by design: it imports nothing, so the individual rule
  * modules can describe the slice of `PatchQueueContext` they read without
- * importing `patch-lint-cross.ts` (which imports them back). Previously each
- * rule re-declared its own private `{ entries }` interface. Sharing them here
+ * importing `patch-lint-cross.ts` (which imports them back). Sharing them
+ * here instead of re-declaring a private `{ entries }` interface per rule
  * keeps the dependency edge one-way and `dpdm` clean while stating the shape
  * once.
  */

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

@@ -20,7 +20,7 @@ export declare function validatePatchesManifestConsistency(patchesDir: string):
  *
  * 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
+ * whole-manifest rebuild for it puts
  * an operator one keystroke from rewriting every row in the manifest to
  * correct one list.
  */
@@ -80,7 +80,7 @@ export interface RebuildPatchesManifestOptions extends PatchDirectoryLockOptions
  * 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
+ * @param fallbackSourceEsrVersion - source version to use for recovered entries that carry none
  * @param options - Lock options plus `allowMetadataLoss` / `dryRun`
  * @returns {@link RebuildPatchesManifestResult}: the rebuilt manifest, the
  *   filenames that were reconstructed from generic defaults, and the rows

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

@@ -87,7 +87,7 @@ export async function validatePatchesManifestConsistency(patchesDir) {
  *
  * 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
+ * whole-manifest rebuild for it puts
  * an operator one keystroke from rewriting every row in the manifest to
  * correct one list.
  */
@@ -115,7 +115,7 @@ export function recommendManifestRepair(issues) {
  * 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
+ * @param fallbackSourceEsrVersion - source version to use for recovered entries that carry none
  * @param options - Lock options plus `allowMetadataLoss` / `dryRun`
  * @returns {@link RebuildPatchesManifestResult}: the rebuilt manifest, the
  *   filenames that were reconstructed from generic defaults, and the rows

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

@@ -65,10 +65,14 @@ export declare function loadPatchesManifestForWrite(patchesDir: string): Promise
  */
 export declare function savePatchesManifest(patchesDir: string, manifest: PatchesManifest): Promise<void>;
 /**
- * Mutates selected manifest rows while preserving the raw JSON shape of every
+ * Mutates selected manifest rows while preserving the raw JSON fields of every
  * untouched row. This avoids serializing reader-only fallback fields, such as
  * `sourceVersion` derived from legacy `sourceEsrVersion`, into unrelated patch
  * entries during partial metadata updates.
+ *
+ * Every row's keys (and the manifest's own) are written in canonical order,
+ * not only the changed rows', so the working copy matches what `patch stage`
+ * and full saves write and no commit flips untouched rows' key order.
  */
 export declare function mutatePatchRowsInManifest(patchesDir: string, filenames: readonly string[], mutator: (existing: PatchMetadata, rawExisting: Readonly<JsonObject>) => PatchManifestRowMutation | null): Promise<PatchManifestRowMutationResult[] | null>;
 /**

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

@@ -19,7 +19,7 @@ import { pathExistsStrict, readJson, removeFile, writeJson } from '../utils/fs.j
 import { warn } from '../utils/logger.js';
 import { isArray, isObject } from '../utils/validation.js';
 import { assertPatchDirectoryLockHeld } from './patch-lock.js';
-import { canonicalizeManifest, canonicalizePatchRow } from './patch-manifest-key-order.js';
+import { canonicalizeManifest } from './patch-manifest-key-order.js';
 import { validatePatchesManifest } from './patch-manifest-validate.js';
 import { manifestWithRetiredSlots } from './patch-retired.js';
 /** Filename for the patches manifest */
@@ -90,10 +90,14 @@ export async function savePatchesManifest(patchesDir, manifest) {
     await writeJson(manifestPath, canonicalizeManifest(manifest));
 }
 /**
- * Mutates selected manifest rows while preserving the raw JSON shape of every
+ * Mutates selected manifest rows while preserving the raw JSON fields of every
  * untouched row. This avoids serializing reader-only fallback fields, such as
  * `sourceVersion` derived from legacy `sourceEsrVersion`, into unrelated patch
  * entries during partial metadata updates.
+ *
+ * Every row's keys (and the manifest's own) are written in canonical order,
+ * not only the changed rows', so the working copy matches what `patch stage`
+ * and full saves write and no commit flips untouched rows' key order.
  */
 export async function mutatePatchRowsInManifest(patchesDir, filenames, mutator) {
     const manifestPath = join(patchesDir, PATCHES_MANIFEST);
@@ -140,16 +144,14 @@ export async function mutatePatchRowsInManifest(patchesDir, filenames, mutator)
     }
     if (changedIndexes.length === 0)
         return [];
-    // Only the rows this call changed are put in canonical order, so a key
-    // it sets lands where every other writer puts it; untouched rows keep
-    // their raw shape.
-    for (const index of changedIndexes) {
-        rawPatches[index] = canonicalizePatchRow(rawPatches[index]);
-    }
-    const nextRawManifest = {
+    // Every row is put in canonical key order, not only the changed ones:
+    // `patch stage` and full saves canonicalize the whole manifest, so a
+    // row left in any other order flips back and forth between the
+    // working copy and the index. Reordering keys adds no field.
+    const nextRawManifest = canonicalizeManifest({
         ...rawManifest,
         patches: rawPatches,
-    };
+    });
     const afterManifest = validatePatchesManifest(nextRawManifest);
     await writeJson(manifestPath, nextRawManifest);
     return changedIndexes.map((index) => ({

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

@@ -1,9 +1,8 @@
 /**
  * The one key order every `patches.json` writer uses for a patch row and
- * for the manifest itself. Writers used to disagree: `export` spread
- * `sourceProduct` before `sourceVersion` while a full-manifest save put it
- * after `filesAffected`, so a no-op rewrite left a key-order-only hunk in
- * the manifest.
+ * for the manifest itself, so that every writer (`export`, full-manifest
+ * saves, `patch stage`) agrees and a no-op rewrite leaves no key-order-only
+ * hunk in the manifest.
  */
 /**
  * Returns a copy of a patch row with its keys in canonical order.

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

@@ -1,10 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * The one key order every `patches.json` writer uses for a patch row and
- * for the manifest itself. Writers used to disagree: `export` spread
- * `sourceProduct` before `sourceVersion` while a full-manifest save put it
- * after `filesAffected`, so a no-op rewrite left a key-order-only hunk in
- * the manifest.
+ * for the manifest itself, so that every writer (`export`, full-manifest
+ * saves, `patch stage`) agrees and a no-op rewrite leaves no key-order-only
+ * hunk in the manifest.
  */
 /** Patch-row keys in the order of the `PatchMetadata` interface. */
 const PATCH_ROW_KEY_ORDER = [

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

@@ -34,10 +34,10 @@ export declare function extractOrder(filename: string): number;
  * The write-side counterpart to {@link extractOrder}. That one answers
  * `Infinity` for a prefix-less filename, which sorts such a patch last and
  * is the right answer for a read: an unparseable name should not crash a
- * status listing. Persisting `Infinity` (or the `0` some call sites used to
- * fall back to) is a different matter: it puts an order in the manifest
+ * status listing. Persisting `Infinity` (or a fallback `0`) is a different
+ * matter: it puts an order in the manifest
  * that no filename on disk agrees with, and the queue then applies in an
- * order the operator cannot see. Callers here have always just built or
+ * order the operator cannot see. Callers here have just built or
  * looked up a real prefixed filename, so absence is a bug, not input.
  *
  * @param filename - Patch filename carrying a numeric order prefix

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

@@ -56,10 +56,10 @@ export function extractOrder(filename) {
  * The write-side counterpart to {@link extractOrder}. That one answers
  * `Infinity` for a prefix-less filename, which sorts such a patch last and
  * is the right answer for a read: an unparseable name should not crash a
- * status listing. Persisting `Infinity` (or the `0` some call sites used to
- * fall back to) is a different matter: it puts an order in the manifest
+ * status listing. Persisting `Infinity` (or a fallback `0`) is a different
+ * matter: it puts an order in the manifest
  * that no filename on disk agrees with, and the queue then applies in an
- * order the operator cannot see. Callers here have always just built or
+ * order the operator cannot see. Callers here have just built or
  * looked up a real prefixed filename, so absence is a bug, not input.
  *
  * @param filename - Patch filename carrying a numeric order prefix

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

@@ -42,7 +42,7 @@ export interface PatchPolicyEnforcementInput {
 }
 /** Returns valid categories for prompts and CLI validation under the config. */
 export declare function getPatchPolicyCategories(config: FireForgeConfig): string[];
-/** Checks whether a category is accepted by legacy defaults or the policy ranges. */
+/** Checks whether a category is accepted by the built-in defaults or the policy ranges. */
 export declare function isCategoryAllowedByConfig(config: FireForgeConfig, category: string): boolean;
 /**
  * Human-readable label for a category's configured ranges, e.g. `300-399`.

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

@@ -28,7 +28,7 @@ export function getPatchPolicyCategories(config) {
         return [...PATCH_CATEGORIES];
     return Array.from(new Set(cfg.ranges.map((range) => range.category))).sort((a, b) => a.localeCompare(b));
 }
-/** Checks whether a category is accepted by legacy defaults or the policy ranges. */
+/** Checks whether a category is accepted by the built-in defaults or the policy ranges. */
 export function isCategoryAllowedByConfig(config, category) {
     if (!/^[a-z][a-z0-9-]*$/.test(category))
         return false;

package/dist/src/core/patch-source-metadata.d.ts

@@ -2,5 +2,5 @@ import type { PatchMetadata } from '../types/commands/index.js';
 import type { FirefoxConfig } from '../types/config.js';
 /** Metadata fields stamped on new or refreshed patch entries. */
 export declare function buildPatchSourceMetadata(firefox: Pick<FirefoxConfig, 'product' | 'version'>): Pick<PatchMetadata, 'sourceEsrVersion' | 'sourceProduct' | 'sourceVersion'>;
-/** Backward-compatible source version reader for legacy manifests. */
+/** Source version reader that also accepts rows carrying only `sourceEsrVersion`. */
 export declare function getPatchSourceVersion(patch: Pick<PatchMetadata, 'sourceEsrVersion' | 'sourceVersion'>): string;

package/dist/src/core/patch-source-metadata.js

@@ -6,7 +6,7 @@ export function buildPatchSourceMetadata(firefox) {
         sourceVersion: firefox.version,
     };
 }
-/** Backward-compatible source version reader for legacy manifests. */
+/** Source version reader that also accepts rows carrying only `sourceEsrVersion`. */
 export function getPatchSourceVersion(patch) {
     return patch.sourceVersion ?? patch.sourceEsrVersion;
 }

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

@@ -3,12 +3,14 @@ import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js'
  * Resolves a `--patches <name…>` subset against the manifest, matching each
  * requested name tolerantly (exact filename, filename ± `.patch`, the bare
  * order number, the manifest `name` field, or the slug). Accepts repeated
- * values and comma lists. Throws listing the available patches when a
+ * values and lists separated by commas or whitespace, so a list passed as
+ * one shell word (`--patches "$P"` under zsh) still splits. Throws when a
  * requested name matches none, so a typo fails loud rather than silently
- * judging nothing.
+ * judging nothing; the refusal names that name and its nearest matches,
+ * not the whole queue.
  *
  * @param manifest - The loaded patch manifest
- * @param requested - Raw `--patches` values (each may be a comma list)
+ * @param requested - Raw `--patches` values (each may be a comma or whitespace list)
  * @param refusalHint - Sentence inserted into the no-match refusal, naming
  *   what the caller's flag selects
  * @returns The matching manifest rows, de-duplicated, in request order