@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -5,16 +5,18 @@ import { stripJsComments } from '../utils/regex.js';
 import { containsUpstreamLicenseText, getLicenseHeader, hasAnyLicenseHeader, hasAnyLicenseHeaderAnyStyle, hasUpstreamMplBlockHeader, } from './license-headers.js';
 import { invokePatchLintCheckJs, runCheckJsTestFilesGrouped } from './patch-lint-checkjs.js';
 import { lintChromeScriptJsDocForFile } from './patch-lint-chrome-jsdoc.js';
+import { countCodeLines, countRawLines } from './patch-lint-code-lines.js';
 import { lintPatchedCss } from './patch-lint-css.js';
 import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-diff.js';
-import { AGGREGATE_PATCH_FILE } from './patch-lint-diff-tag.js';
 import { formatFileTooLargeMessage, resolveFileSizeThresholds } from './patch-lint-file-size.js';
+import { partitionLintIgnoredIssues } from './patch-lint-ignore.js';
 import { hasRelativeImport } from './patch-lint-imports.js';
 import { validateExportJsDoc } from './patch-lint-jsdoc.js';
 import { lintMozBuildSortedLists } from './patch-lint-mozbuild.js';
 import { lintObserverTopics } from './patch-lint-observer.js';
-import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs, resolvePatchOwnedTestScripts, } from './patch-lint-ownership.js';
+import { resolvableModulesForTests, resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs, resolvePatchOwnedTestScripts, } from './patch-lint-ownership.js';
 import { invokePatchLintPrettier } from './patch-lint-prettier.js';
+import { isTestFile, lintPatchSize, measurePatchSize, } from './patch-lint-size.js';
 // ---------------------------------------------------------------------------
 // Cross-patch lint re-exports
 // ---------------------------------------------------------------------------
@@ -30,23 +32,12 @@ export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patc
 // split as the other rule families). Re-export the imported binding so
 // callers and tests keep importing `lintPatchedCss` from this module.
 export { lintPatchedCss };
+// Same split for the patch-size rules and their measurement.
+export { countNonBinaryDiffLines, getPatchSizeThresholds, isTestFile, lintPatchSize, measurePatchSize, resolvePatchSizeTier, } from './patch-lint-size.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 const JS_EXTENSIONS = ['.js', '.mjs', '.jsm'];
-/**
- * Counts the lines of `content` the way `wc -l` reports them: a trailing
- * newline terminates the last line rather than starting an empty extra one.
- * A naive `split('\n').length` over-counts by one for any content ending in
- * `\n` (the common case), making the size rules fire one line early against
- * the operator's own `wc -l` measurement.
- */
-function countContentLines(content) {
-    const lines = content.split('\n');
-    if (lines[lines.length - 1] === '')
-        lines.pop();
-    return lines.length;
-}
 /**
  * Canonical `[check] file: message` rendering of a patch-lint issue. It is
  * the one string shape every reporter and refusal message uses, so operators
@@ -55,133 +46,6 @@ function countContentLines(content) {
 export function formatPatchLintIssue(issue) {
     return `[${issue.check}] ${issue.file}: ${issue.message}`;
 }
-/**
- * Counts the total lines in a unified diff and the number of non-binary
- * text lines, so binary hunks do not inflate patch size checks.
- *
- * Line counting agrees with `wc -l`: a trailing newline does not add a
- * phantom empty line to either `total` or the binary-hunk accounting.
- *
- * @param diffContent - Raw unified diff string
- * @returns Object with `total` line count and `textLines` (total minus binary hunk lines)
- */
-export function countNonBinaryDiffLines(diffContent) {
-    const lines = diffContent.split('\n');
-    if (lines[lines.length - 1] === '')
-        lines.pop();
-    const total = lines.length;
-    let binaryLines = 0;
-    let inBinaryHunk = false;
-    for (const line of lines) {
-        if (line === 'GIT binary patch' || line.startsWith('GIT binary patch')) {
-            inBinaryHunk = true;
-        }
-        else if (line.startsWith('diff --git ')) {
-            inBinaryHunk = false;
-        }
-        if (inBinaryHunk) {
-            binaryLines++;
-        }
-    }
-    return { total, textLines: total - binaryLines };
-}
-const PATCH_LINE_THRESHOLDS = {
-    general: { notice: 800, warning: 1500, error: 3000 },
-    test: { notice: 1500, warning: 3000, error: 6000 },
-    /**
-     * Branding patches have a legitimate reason to be large: they include
-     * every locale's `brand.ftl`, copied upstream CSS/PNG assets, and the
-     * fork-specific `configure.sh` / `brand.properties` under a single
-     * `browser/branding/<name>/` subtree.
-     *
-     * Calibrated against a fresh-fork branding export, which lands around
-     * 15-16k lines (localized brand.ftl across many locales + SVG path data +
-     * copied upstream CSS). That is the minimum branding diff, so it must
-     * surface as a soft `notice` rather than a `warning`: the warning band
-     * sits above it with ~13% headroom, and the error band at roughly 2× the
-     * baseline, where non-branding work is probably bundled in.
-     *
-     * Permissive thresholds are safe because the *gate* into this tier is
-     * narrow: auto-detect requires every file under `browser/branding/` plus a
-     * tight registration allowlist, or an explicit `PatchMetadata.tier:
-     * "branding"` opt-in. A non-branding patch cannot accidentally land here.
-     */
-    branding: { notice: 8000, warning: 18000, error: 30000 },
-};
-/**
- * File-count thresholds for the `large-patch-files` rule, mirroring the tier
- * shape of {@link PATCH_LINE_THRESHOLDS}. A single warning-only threshold
- * per tier is intentional: file count expresses scope, not blast radius,
- * and there is no error band that would block export.
- *
- * The branding tier sits well above the typical floor because branding
- * patches inherently span many files: PNG/ICO icon assets in 7+ sizes, MSIX
- * manifests, channel-specific configs, locale `.ftl` files, Windows/macOS
- * launcher resources. A fresh-fork branding bundle is around 56 files, so 60
- * leaves headroom for additional channels/locales while still firing on a
- * genuinely bloated patch.
- *
- * Test tier matches general because a test-only patch rarely touches many
- * files (a single regression test usually adds 1-3 fixtures). The elevation
- * in {@link PATCH_LINE_THRESHOLDS.test} addresses big table-driven test
- * bodies, not file fan-out.
- */
-const PATCH_FILES_THRESHOLDS = {
-    general: 5,
-    test: 5,
-    branding: 60,
-};
-/**
- * Shared remedy sentence for the over-budget findings. Both places an
- * operator stands when a patch outgrows its budget must name the sanctioned
- * one-transaction way out, or they reach for the wrong tools first. One
- * constant, four emission sites, so the wording cannot drift.
- */
-const SPLIT_HINT = 'Consider splitting into smaller, focused patches — ' +
-    '"fireforge patch move-files <from> <to> --file <path> --create --order <n>" ' +
-    'moves files into a new patch in one transaction.';
-/**
- * Fixed allowlist of non-branding sibling paths that real-world Firefox
- * branding patches legitimately need to touch to register the new branding
- * flavor with the top-level configure. A predicate requiring every file to
- * live under `browser/branding/` drops a branding patch that also touches
- * `browser/moz.configure` (the canonical registration point) into the
- * general lint tier.
- *
- * Narrow on purpose: add entries only when a genuine branding patch
- * cannot be expressed without a specific registration sibling. Pinned
- * against ESR 140.x conventions at time of writing.
- */
-const BRANDING_REGISTRATION_FILES = new Set([
-    'browser/moz.configure',
-    'browser/confvars.sh',
-]);
-/**
- * Returns true when a patch qualifies for the branding threshold tier:
- * every file lives either under `browser/branding/` or in the narrow
- * registration allowlist, and the patch contains at least one file
- * under `browser/branding/` (guard against a config-only patch
- * accidentally qualifying as branding).
- *
- * Used by `lintPatchSize` to pick the branding threshold tier. The
- * explicit `tier: "branding"` field on `PatchMetadata` bypasses this
- * heuristic and forces the branding tier directly.
- */
-function isBrandingOnlyPatch(files) {
-    if (files.length === 0)
-        return false;
-    let hasBrandingFile = false;
-    for (const file of files) {
-        if (file.startsWith('browser/branding/')) {
-            hasBrandingFile = true;
-            continue;
-        }
-        if (BRANDING_REGISTRATION_FILES.has(file))
-            continue;
-        return false;
-    }
-    return hasBrandingFile;
-}
 /**
  * Returns true if the filename looks like a JS/MJS/JSM file.
  * Handles `.sys.mjs` as well.
@@ -207,15 +71,57 @@ export function filesMeasuredByFileTooLarge(patchText) {
     return measuredByFileTooLarge(detectNewFilesInDiff(patchText));
 }
 /**
- * Returns true if the file path looks like a test file.
- * Matches paths containing `/test/` or filenames starting with
- * `browser_`, `test_`, or `xpcshell_` (all `.js`).
+ * The `file-too-large` rule for one measured file, in the configured
+ * `patchLint.fileSizeMetric`. Under `"code"`, a file acorn cannot tokenize
+ * is measured in raw lines (the upper bound) and a `file-size-unparsed`
+ * notice names it, so the fallback is visible instead of silently lenient.
  */
-export function isTestFile(file) {
-    if (file.includes('/test/'))
-        return true;
-    const basename = file.split('/').pop() ?? '';
-    return /^(?:browser_|test_|xpcshell_).*\.js$/.test(basename);
+function lintFileSize(file, content, config) {
+    const issues = [];
+    let lineCount = countRawLines(content);
+    let unit = 'lines';
+    if (config.patchLint?.fileSizeMetric === 'code') {
+        const counted = countCodeLines(content);
+        if (counted.parsed) {
+            lineCount = counted.lines;
+            unit = 'code lines';
+        }
+        else {
+            issues.push({
+                file,
+                check: 'file-size-unparsed',
+                message: `Could not parse the file as a module or a script, so file-too-large counted its ` +
+                    `${lineCount} raw lines (the upper bound) instead of code lines.`,
+                severity: 'notice',
+            });
+        }
+    }
+    const isTest = isTestFile(file);
+    const thresholds = resolveFileSizeThresholds(config.patchLint?.fileSizeThresholds, isTest);
+    const band = lineCount > thresholds.error
+        ? 'error'
+        : lineCount > thresholds.warning
+            ? 'warning'
+            : lineCount > thresholds.notice
+                ? 'notice'
+                : undefined;
+    if (band !== undefined) {
+        issues.push({
+            file,
+            check: 'file-too-large',
+            message: formatFileTooLargeMessage({
+                label: isTest ? 'Test file' : 'New file',
+                lineCount,
+                unit,
+                thresholds,
+                band,
+                verb: isTest ? 'splitting' : 'decomposing',
+            }),
+            severity: band,
+            measurement: lineCount,
+        });
+    }
+    return issues;
 }
 /**
  * Narrower scope than `isTestFile`: only browser-chrome test files
@@ -424,26 +330,7 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
         }
         // 2. File size check (new JS files only; see filesMeasuredByFileTooLarge)
         if (sizeMeasured.has(file)) {
-            const lineCount = countContentLines(content);
-            const isTest = isTestFile(file);
-            const thresholds = resolveFileSizeThresholds(config.patchLint?.fileSizeThresholds, isTest);
-            const label = isTest ? 'Test file' : 'New file';
-            const verb = isTest ? 'splitting' : 'decomposing';
-            const band = lineCount > thresholds.error
-                ? 'error'
-                : lineCount > thresholds.warning
-                    ? 'warning'
-                    : lineCount > thresholds.notice
-                        ? 'notice'
-                        : undefined;
-            if (band !== undefined) {
-                issues.push({
-                    file,
-                    check: 'file-too-large',
-                    message: formatFileTooLargeMessage({ label, lineCount, thresholds, band, verb }),
-                    severity: band,
-                });
-            }
+            issues.push(...lintFileSize(file, content, config));
         }
         // 3. JSDoc on exports (patch-owned .sys.mjs files)
         const isOwned = patchOwnedFiles ? patchOwnedFiles.has(file) : isNew;
@@ -522,114 +409,6 @@ export function lintModificationComments(diffContent, config) {
     }
     return issues;
 }
-/**
- * Decides which `large-patch-lines` threshold tier applies to a patch.
- * Exported so `runPatchLint` and the per-patch `lint` command can
- * surface the tier choice to the operator *without* depending on
- * `lintPatchSize`'s internal return shape. The rule itself stays a
- * pure issues-array API, and the decision is computed separately for
- * the sole purpose of reporting.
- *
- * Precedence: test > branding (explicit) > branding (auto) > general.
- * The test tier beats branding because a table-driven regression test
- * is legitimately large independent of whether the patch also claims
- * branding shape, and the test-tier thresholds are already more
- * permissive than branding, so "tests beat branding" is the
- * defensive-for-tests choice.
- */
-export function resolvePatchSizeTier(filesAffected, patchTier) {
-    const allTests = filesAffected.length > 0 && filesAffected.every(isTestFile);
-    if (allTests)
-        return { tier: 'test' };
-    if (patchTier === 'branding')
-        return { tier: 'branding', source: 'explicit' };
-    if (isBrandingOnlyPatch(filesAffected))
-        return { tier: 'branding', source: 'auto' };
-    return { tier: 'general' };
-}
-/**
- * Read-only view of the size thresholds a tier enforces.
- * Public-API companion to {@link resolvePatchSizeTier} /
- * {@link countNonBinaryDiffLines} so consumers can build waiver-freshness
- * checks against the same numbers `large-patch-lines` /
- * `large-patch-files` fire on instead of mirroring them.
- */
-export function getPatchSizeThresholds(tier) {
-    return {
-        lines: { ...PATCH_LINE_THRESHOLDS[tier] },
-        maxFiles: PATCH_FILES_THRESHOLDS[tier],
-    };
-}
-/**
- * Checks patch size and emits advisory warnings.
- *
- * @param filesAffected - Files touched by the patch
- * @param lineCount - Non-binary line count of the unified diff
- * @param patchTier - Optional explicit tier override declared on
- *   `PatchMetadata.tier`. When `"branding"`, forces the branding
- *   thresholds regardless of `filesAffected`. Tests still win over
- *   branding (precedence `test > branding > general`) because the
- *   test-tier thresholds are already more permissive and an all-tests
- *   patch that is also branding-shaped is vanishingly rare.
- */
-export function lintPatchSize(filesAffected, lineCount, patchTier) {
-    const issues = [];
-    // Tier selection: test > branding > general. Tests keep their elevated
-    // thresholds because a big regression test is legitimate (table-driven
-    // harnesses run into the thousands of lines). Branding patches get their
-    // own tier so a first export of setup-generated branding does not fire the
-    // general hard limit. See `PATCH_LINE_THRESHOLDS.branding` and
-    // `PATCH_FILES_THRESHOLDS.branding` above. An explicit `patchTier` opt-in
-    // forces branding even when `isBrandingOnlyPatch` cannot reach the patch's
-    // actual shape (a branding patch that also touches a non-allowlisted
-    // sibling like a vendor-specific icon resource). Both checks read off the
-    // same decision so the file-count and line-count rules cannot disagree
-    // about which tier applies.
-    const decision = resolvePatchSizeTier(filesAffected, patchTier);
-    const fileThreshold = decision.tier === 'test'
-        ? PATCH_FILES_THRESHOLDS.test
-        : decision.tier === 'branding'
-            ? PATCH_FILES_THRESHOLDS.branding
-            : PATCH_FILES_THRESHOLDS.general;
-    const lineThresholds = decision.tier === 'test'
-        ? PATCH_LINE_THRESHOLDS.test
-        : decision.tier === 'branding'
-            ? PATCH_LINE_THRESHOLDS.branding
-            : PATCH_LINE_THRESHOLDS.general;
-    if (filesAffected.length > fileThreshold) {
-        issues.push({
-            file: AGGREGATE_PATCH_FILE,
-            check: 'large-patch-files',
-            message: `Patch affects ${filesAffected.length} files (recommended: ≤${fileThreshold}). ${SPLIT_HINT}`,
-            severity: 'warning',
-        });
-    }
-    if (lineCount > lineThresholds.error) {
-        issues.push({
-            file: AGGREGATE_PATCH_FILE,
-            check: 'large-patch-lines',
-            message: `Patch is ${lineCount} lines (hard limit: ${lineThresholds.error}). ${SPLIT_HINT}`,
-            severity: 'error',
-        });
-    }
-    else if (lineCount > lineThresholds.warning) {
-        issues.push({
-            file: AGGREGATE_PATCH_FILE,
-            check: 'large-patch-lines',
-            message: `Patch is ${lineCount} lines (soft limit: ${lineThresholds.warning}, hard limit: ${lineThresholds.error}). ${SPLIT_HINT}`,
-            severity: 'warning',
-        });
-    }
-    else if (lineCount > lineThresholds.notice) {
-        issues.push({
-            file: AGGREGATE_PATCH_FILE,
-            check: 'large-patch-lines',
-            message: `Patch is ${lineCount} lines (soft limit: ${lineThresholds.warning}, hard limit: ${lineThresholds.error}). ${SPLIT_HINT}`,
-            severity: 'notice',
-        });
-    }
-    return issues;
-}
 // ---------------------------------------------------------------------------
 // Modified file header lint
 // ---------------------------------------------------------------------------
@@ -683,7 +462,6 @@ export async function lintModifiedFileHeaders(repoDir, affectedFiles, newFiles)
 export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, options) {
     const { patchQueueCtx, ignoreChecks, patchTier } = options ?? {};
     const newFiles = detectNewFilesInDiff(diffContent);
-    const { textLines: lineCount } = countNonBinaryDiffLines(diffContent);
     const patchOwnedFiles = resolvePatchOwnedSysMjs(newFiles, patchQueueCtx);
     const patchOwnedChromeScripts = resolvePatchOwnedChromeScripts(newFiles, patchQueueCtx);
     const [cssIssues, headerIssues, jsIssues, modifiedHeaderIssues, mozBuildIssues] = await Promise.all([
@@ -696,7 +474,8 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
     const modCommentIssues = lintModificationComments(diffContent, config);
     const sizeIssues = options?.skipPatchSize
         ? []
-        : lintPatchSize(affectedFiles, lineCount, patchTier);
+        : lintPatchSize(affectedFiles, options?.patchSizeMeasurement ??
+            (await measurePatchSize(repoDir, diffContent, affectedFiles, config)), patchTier, config);
     const issues = [
         ...sizeIssues,
         ...cssIssues,
@@ -716,7 +495,7 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         // Export-time twin of per-patch lint's test-file pass, so
         // export/re-export and `lint --per-patch` agree on the checked surface.
         if (config.patchLint.checkJsTestFiles === true) {
-            const testGrouped = await runCheckJsTestFilesGrouped(repoDir, resolvePatchOwnedTestScripts(newFiles, patchQueueCtx), config.patchLint, dirname(repoDir));
+            const testGrouped = await runCheckJsTestFilesGrouped(repoDir, resolvePatchOwnedTestScripts(newFiles, patchQueueCtx), config.patchLint, dirname(repoDir), undefined, patchQueueCtx ? resolvableModulesForTests(patchQueueCtx) : undefined);
             issues.push(...testGrouped.global);
             for (const [rel, list] of testGrouped.byFile) {
                 if (options?.checkJsReportScope && !options.checkJsReportScope.has(rel))
@@ -740,12 +519,11 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
     // reclassify severities: an ignored error simply drops, mirroring how
     // inline `fireforge-ignore: <check>` markers work in the CSS and
     // forward-import rules.
-    if (ignoreChecks && ignoreChecks.size > 0) {
-        const suppressed = issues.filter((issue) => ignoreChecks.has(issue.check));
-        if (suppressed.length > 0) {
-            options?.onSuppressed?.(suppressed);
-        }
-        return issues.filter((issue) => !ignoreChecks.has(issue.check));
+    // A ceiling entry (see `patch-lint-ignore.ts`) drops a size finding only
+    // while its measurement stays at or below the ceiling.
+    const { kept, suppressed } = partitionLintIgnoredIssues(issues, ignoreChecks);
+    if (suppressed.length > 0) {
+        options?.onSuppressed?.(suppressed);
     }
-    return issues;
+    return kept;
 }

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

@@ -8,20 +8,21 @@ import { PatchError } from '../errors/patch.js';
 import { assert } from '../utils/assert.js';
 import { toError } from '../utils/errors.js';
 import { info } from '../utils/logger.js';
-import { readLockStatus, withFileLock } from './file-lock.js';
+import { formatLockQueuePosition, readLockStatus, withFileLock } from './file-lock.js';
 const PATCH_DIRECTORY_LOCK = '.fireforge-patches.lock';
 /**
  * Formats the periodic operator-facing waiting line printed while
  * `--wait-lock` polls a contended patch directory lock. Mirrors the engine
  * session lock's progress line so operators read one shape for both locks.
  */
-function formatWaitProgressLine(waitedMs, timeoutMs, holder) {
+function formatWaitProgressLine(waitedMs, timeoutMs, holder, queue) {
     const progress = `${Math.round(waitedMs / 1000)}s of up to ${Math.round(timeoutMs / 1000)}s`;
+    const position = formatLockQueuePosition(queue);
     if (holder === undefined) {
-        return `Waiting for the FireForge patch directory lock — ${progress}.`;
+        return `Waiting for the FireForge patch directory lock — ${progress}.${position}`;
     }
     const details = holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '';
-    return `Waiting for the FireForge patch directory lock held by PID ${holder.pid}${details} — ${progress}.`;
+    return `Waiting for the FireForge patch directory lock held by PID ${holder.pid}${details} — ${progress}.${position}`;
 }
 /**
  * Asserts that this process is inside {@link withPatchDirectoryLock} for the
@@ -80,8 +81,8 @@ export async function withPatchDirectoryLock(patchesDir, operation, options = {}
                 pollMs: 100,
                 pollMaxMs: 2000,
                 waitProgressMs: 5000,
-                onWaitProgress: ({ waitedMs, timeoutMs, holder }) => {
-                    info(formatWaitProgressLine(waitedMs, timeoutMs, holder));
+                onWaitProgress: ({ waitedMs, timeoutMs, holder, queue }) => {
+                    info(formatWaitProgressLine(waitedMs, timeoutMs, holder, queue));
                 },
             }
             : {}),

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

@@ -8,6 +8,7 @@ import { discoverPatches, getAllTargetFilesFromPatch } from './patch-files.js';
 import { withPatchDirectoryLock } from './patch-lock.js';
 import { loadPatchesManifestState, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest-io.js';
 import { inferPatchMetadataFromFilename } from './patch-manifest-validate.js';
+import { manifestWithRetiredSlots } from './patch-retired.js';
 /**
  * Validates that patches.json and the patch directory describe the same patch set.
  * @param patchesDir - Path to the patches directory
@@ -216,16 +217,16 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
         };
         // 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?.lintIgnore !== undefined) {
+            rebuilt.lintIgnore = existing.lintIgnore.map((entry) => typeof entry === 'string' ? entry : { ...entry });
+        }
         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,
-    };
+    // Retired slots have no patch file to recover them from, so they ride
+    // along from the loaded manifest like the per-row fields above.
+    const rebuiltManifest = manifestWithRetiredSlots(manifestState.manifest, 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, since the file is the
     // source of truth, but dropping rows without naming them is

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

@@ -7,7 +7,7 @@
  * inconsistent manifests.
  */
 import { FireForgeError } from '../errors/base.js';
-import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
+import type { PatchesManifest, PatchMetadata, PatchRetiredSlot } from '../types/commands/index.js';
 import type { JsonObject } from '../types/json.js';
 /** Filename for the patches manifest */
 export declare const PATCHES_MANIFEST = "patches.json";
@@ -89,10 +89,11 @@ export declare function addPatchToManifest(patchesDir: string, metadata: PatchMe
  *
  * @param patchesDir - Path to the patches directory
  * @param filename - Filename of the patch to remove from the manifest
+ * @param retiredSlot - Optional placeholder to record for the removed order
  * @returns True when the manifest was written (i.e. an entry was removed),
  *   false when no matching entry existed
  */
-export declare function removePatchFromManifest(patchesDir: string, filename: string): Promise<boolean>;
+export declare function removePatchFromManifest(patchesDir: string, filename: string, retiredSlot?: PatchRetiredSlot): Promise<boolean>;
 /**
  * A single rename step in a {@link renumberPatchesInManifest} plan.
  */
@@ -188,5 +189,7 @@ export declare class PatchDeleteRollbackError extends FireForgeError {
  *
  * @param patchesDir - Path to the patches directory
  * @param filename - Patch filename to delete
+ * @param retiredSlot - When set (`patch retire`), the placeholder written in
+ *   the same manifest update that removes the row
  */
-export declare function removePatchFileAndManifest(patchesDir: string, filename: string): Promise<void>;
+export declare function removePatchFileAndManifest(patchesDir: string, filename: string, retiredSlot?: PatchRetiredSlot): Promise<void>;

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

@@ -19,7 +19,9 @@ 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 { validatePatchesManifest } from './patch-manifest-validate.js';
+import { manifestWithRetiredSlots } from './patch-retired.js';
 /** Filename for the patches manifest */
 export const PATCHES_MANIFEST = 'patches.json';
 /**
@@ -85,7 +87,7 @@ export async function loadPatchesManifestForWrite(patchesDir) {
  */
 export async function savePatchesManifest(patchesDir, manifest) {
     const manifestPath = join(patchesDir, PATCHES_MANIFEST);
-    await writeJson(manifestPath, manifest);
+    await writeJson(manifestPath, canonicalizeManifest(manifest));
 }
 /**
  * Mutates selected manifest rows while preserving the raw JSON shape of every
@@ -138,6 +140,12 @@ 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 = {
         ...rawManifest,
         patches: rawPatches,
@@ -171,7 +179,8 @@ export async function addPatchToManifest(patchesDir, metadata, removeFilenames)
     // Add new entry and sort by order
     manifest.patches.push(metadata);
     manifest.patches.sort((a, b) => a.order - b.order);
-    await savePatchesManifest(patchesDir, manifest);
+    // A patch landing on a retired order fills that slot.
+    await savePatchesManifest(patchesDir, manifestWithRetiredSlots(manifest, manifest.patches));
 }
 /**
  * Removes a single patch entry from the manifest by filename. Leaves the
@@ -184,10 +193,11 @@ export async function addPatchToManifest(patchesDir, metadata, removeFilenames)
  *
  * @param patchesDir - Path to the patches directory
  * @param filename - Filename of the patch to remove from the manifest
+ * @param retiredSlot - Optional placeholder to record for the removed order
  * @returns True when the manifest was written (i.e. an entry was removed),
  *   false when no matching entry existed
  */
-export async function removePatchFromManifest(patchesDir, filename) {
+export async function removePatchFromManifest(patchesDir, filename, retiredSlot) {
     const manifest = await loadPatchesManifestForWrite(patchesDir);
     if (!manifest)
         return false;
@@ -196,6 +206,14 @@ export async function removePatchFromManifest(patchesDir, filename) {
     if (manifest.patches.length === originalLength) {
         return false;
     }
+    if (retiredSlot !== undefined) {
+        // `patch retire`: the row leaves and its order stays spent, in the
+        // same write, so no reader ever sees the gap in between.
+        manifest.retired = [
+            ...(manifest.retired ?? []).filter((slot) => slot.order !== retiredSlot.order),
+            retiredSlot,
+        ].sort((a, b) => a.order - b.order);
+    }
     await savePatchesManifest(patchesDir, manifest);
     return true;
 }
@@ -436,10 +454,8 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
         // try, so a violation unwinds through the Phase 3 rollback that puts the
         // filenames back.
         assertRenumberedOrderIsWellFormed(updatedPatches);
-        await savePatchesManifest(patchesDir, {
-            ...manifest,
-            patches: updatedPatches,
-        });
+        // A patch renumbered onto a retired order fills that slot.
+        await savePatchesManifest(patchesDir, manifestWithRetiredSlots(manifest, updatedPatches));
     }
     catch (error) {
         // Phase 3 rollback: reverse every completed rename. The manifest
@@ -504,14 +520,16 @@ export class PatchDeleteRollbackError extends FireForgeError {
  *
  * @param patchesDir - Path to the patches directory
  * @param filename - Patch filename to delete
+ * @param retiredSlot - When set (`patch retire`), the placeholder written in
+ *   the same manifest update that removes the row
  */
-export async function removePatchFileAndManifest(patchesDir, filename) {
+export async function removePatchFileAndManifest(patchesDir, filename, retiredSlot) {
     await assertPatchDirectoryLockHeld(patchesDir, 'deleting a patch and its manifest row');
     const patchPath = join(patchesDir, filename);
     // ForWrite: deleting the patch file while a corrupt manifest still
     // references it would strand the queue. Abort on corruption instead.
     const originalManifest = await loadPatchesManifestForWrite(patchesDir);
-    const removedFromManifest = await removePatchFromManifest(patchesDir, filename);
+    const removedFromManifest = await removePatchFromManifest(patchesDir, filename, retiredSlot);
     try {
         if (await pathExistsStrict(patchPath)) {
             await removeFile(patchPath);

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

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+/**
+ * Returns a copy of a patch row with its keys in canonical order.
+ *
+ * @param row - A `PatchMetadata` row, typed or raw
+ * @returns The same fields in canonical key order
+ */
+export declare function canonicalizePatchRow<T extends object>(row: T): T;
+/**
+ * Returns a copy of a manifest with its top-level keys and every row in
+ * canonical order.
+ *
+ * @param manifest - A `PatchesManifest`, typed or raw
+ * @returns The manifest in canonical key order
+ */
+export declare function canonicalizeManifest<T extends {
+    patches: readonly object[];
+}>(manifest: T): T;