@hominis/fireforge 0.35.0 → 0.37.0

package/dist/src/core/patch-export-update.js

@@ -5,7 +5,7 @@ import { pathExists, readText, writeText } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
 import { withPatchDirectoryLock } from './patch-apply.js';
 import { normalizePatchArtifact } from './patch-artifact-normalize.js';
-import { loadPatchesManifest, mutatePatchRowsInManifest } from './patch-manifest.js';
+import { loadPatchesManifestForWrite, mutatePatchRowsInManifest } from './patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy } from './patch-policy.js';
 /**
  * Updates a patch file body and its manifest row under the same patch
@@ -14,7 +14,7 @@ import { buildProjectedManifest, enforcePatchPolicy } from './patch-policy.js';
  */
 export async function updatePatchAndMetadata(patchesDir, filename, newContent, updates, onCommitted, policyGate) {
     await withPatchDirectoryLock(patchesDir, async () => {
-        const manifest = await loadPatchesManifest(patchesDir);
+        const manifest = await loadPatchesManifestForWrite(patchesDir);
         if (!manifest) {
             throw new Error('Cannot update patch metadata: patches.json is missing.');
         }
@@ -65,4 +65,3 @@ export async function updatePatchAndMetadata(patchesDir, filename, newContent, u
         }
     });
 }
-//# sourceMappingURL=patch-export-update.js.map

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

@@ -30,6 +30,8 @@ export declare function sanitizeName(name: string): string;
  * double-prefix incident) also collapses. Exported for direct testing.
  */
 export declare function stripRedundantCategoryPrefix(sanitizedName: string, category: string): string;
+/** Sanitizes a patch name and drops redundant category/full-stem prefixes. */
+export declare function patchNameSlug(name: string, category: string): string;
 /**
  * Generates the next patch filename with category.
  * @param patchesDir - Path to the patches directory
@@ -99,12 +101,6 @@ export declare function findExistingPatchForFile(patchesDir: string, filePath: s
  * @param newContent - New patch content
  */
 export declare function updatePatch(patchPath: string, newContent: string): Promise<void>;
-/**
- * Deletes a patch file and removes it from the manifest.
- * @param patchesDir - Path to the patches directory
- * @param filename - Patch filename to delete
- */
-export declare function deletePatch(patchesDir: string, filename: string): Promise<void>;
 /**
  * Fully computed plan for a pending export. Returned from
  * {@link planExport} so that `--dry-run` previews can render the full

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

@@ -1,5 +1,4 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, removeFile, writeText } from '../utils/fs.js';
@@ -8,7 +7,7 @@ import { PATCH_CATEGORIES } from '../utils/validation.js';
 import { discoverPatches, withPatchDirectoryLock } from './patch-apply.js';
 import { normalizePatchArtifact } from './patch-artifact-normalize.js';
 import { findAllPatchesForFilesWithDetails, } from './patch-export-coverage.js';
-import { addPatchToManifest, loadPatchesManifest, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest.js';
+import { addPatchToManifest, loadPatchesManifestForWrite, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest.js';
 import { allocatePolicyOrder, enforcePatchPolicy } from './patch-policy.js';
 export { findAllPatchesForFiles, findAllPatchesForFilesWithDetails, findSupersededPatches, isPatchFullyCovered, } from './patch-export-coverage.js';
 export { mutatePatchMetadata, updatePatchMetadata, } from './patch-export-metadata.js';
@@ -46,6 +45,9 @@ export function sanitizeName(name) {
         .replace(/^-+|-+$/g, '')
         .slice(0, 50);
 }
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 /**
  * Strips a leading `NNN-<category>-` prefix from a sanitized name slug.
  * Operators frequently pass the DESIRED FILENAME stem to `--name`
@@ -56,15 +58,25 @@ export function sanitizeName(name) {
  * double-prefix incident) also collapses. Exported for direct testing.
  */
 export function stripRedundantCategoryPrefix(sanitizedName, category) {
-    const prefix = new RegExp(`^\\d+-${category}-`);
+    const prefixes = [
+        new RegExp(`^\\d+-${escapeRegExp(category)}-`),
+        new RegExp(`^${escapeRegExp(category)}-`),
+    ];
     let stripped = sanitizedName;
-    while (prefix.test(stripped)) {
-        stripped = stripped.replace(prefix, '');
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const prefix of prefixes) {
+            if (prefix.test(stripped)) {
+                stripped = stripped.replace(prefix, '');
+                changed = true;
+            }
+        }
     }
     return stripped.length > 0 ? stripped : sanitizedName;
 }
-/** Sanitizes a patch name and drops a redundant `NNN-<category>-` prefix. */
-function patchNameSlug(name, category) {
+/** Sanitizes a patch name and drops redundant category/full-stem prefixes. */
+export function patchNameSlug(name, category) {
     return stripRedundantCategoryPrefix(sanitizeName(name), category);
 }
 /**
@@ -221,45 +233,6 @@ export async function findExistingPatchForFile(patchesDir, filePath) {
 export async function updatePatch(patchPath, newContent) {
     await writeText(patchPath, normalizePatchArtifact(newContent));
 }
-/**
- * Deletes a patch file and removes it from the manifest.
- * @param patchesDir - Path to the patches directory
- * @param filename - Patch filename to delete
- */
-export async function deletePatch(patchesDir, filename) {
-    await withPatchDirectoryLock(patchesDir, async () => {
-        const patchPath = join(patchesDir, filename);
-        const manifest = await loadPatchesManifest(patchesDir);
-        const updatedManifest = manifest
-            ? {
-                ...manifest,
-                patches: manifest.patches.filter((patch) => patch.filename !== filename),
-            }
-            : null;
-        // Update manifest first so interrupted deletions leave an explicit repairable
-        // extra patch file rather than silently dropping metadata for an absent file.
-        if (updatedManifest) {
-            await savePatchesManifest(patchesDir, updatedManifest);
-        }
-        if (!(await pathExists(patchPath))) {
-            return;
-        }
-        try {
-            await unlink(patchPath);
-        }
-        catch (error) {
-            if (manifest) {
-                try {
-                    await savePatchesManifest(patchesDir, manifest);
-                }
-                catch (error) {
-                    warn(`Failed to restore manifest after patch deletion error for "${filename}": ${toError(error).message}`);
-                }
-            }
-            throw error;
-        }
-    });
-}
 /**
  * Internal planning helper. Does NOT take the patch directory lock — the
  * caller must already hold it — because the two public entry points
@@ -269,7 +242,11 @@ export async function deletePatch(patchesDir, filename) {
  * instead of by parallel implementations that can drift.
  */
 async function computeExportPlanUnderLock(input) {
-    const manifestBefore = await loadPatchesManifest(input.patchesDir);
+    // ForWrite: a corrupt manifest read as null here would produce a
+    // manifestAfter containing ONLY the new patch — committing that plan
+    // wipes the queue metadata, and the rollback path would then delete
+    // patches.json entirely because manifestBefore looked absent.
+    const manifestBefore = await loadPatchesManifestForWrite(input.patchesDir);
     const policyOrder = input.config !== undefined
         ? allocatePolicyOrder(input.config, manifestBefore?.patches ?? [], input.category)
         : null;
@@ -341,4 +318,3 @@ export async function planExport(input) {
         };
     });
 }
-//# sourceMappingURL=patch-export.js.map

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

@@ -51,4 +51,3 @@ export async function getAllTargetFilesFromPatch(patchPath) {
     const content = await readText(patchPath);
     return extractAffectedFiles(content);
 }
-//# sourceMappingURL=patch-files.js.map

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

@@ -105,4 +105,3 @@ export function formatPatchNotFoundError(identifier, patches) {
     }
     return `${lead} No close match found among ${patches.length} patches in the queue. Run "fireforge patch list" to see them.`;
 }
-//# sourceMappingURL=patch-identifier-suggest.js.map

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

@@ -414,4 +414,3 @@ export async function invokePatchLintCheckJsGrouped(repoDir, patchOwnedFiles, pa
         : { strict };
     return runCheckJsGrouped(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, mode);
 }
-//# sourceMappingURL=patch-lint-checkjs.js.map

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

@@ -84,4 +84,3 @@ export function lintChromeScriptJsDocForFile(file, content, isChromeOwned, mode)
         severity: issue.severity ?? mode,
     }));
 }
-//# sourceMappingURL=patch-lint-chrome-jsdoc.js.map

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

@@ -343,6 +343,14 @@ function findMatchingStagedDependency(entry, sitePath, specifier, laterOwners) {
         laterOwners.some((owner) => owner.fullPath === dependency.creates &&
             (dependency.owner === undefined || dependency.owner === owner.filename)));
 }
+/**
+ * Later-in-apply-order predicate shared by the forward-import scan and the
+ * registration validation: strictly higher ordinal, or same ordinal with a
+ * lexicographically later filename (the apply loop's tiebreak).
+ */
+function isLaterOwner(owner, entry) {
+    return (owner.order > entry.order || (owner.order === entry.order && owner.filename > entry.filename));
+}
 /** Builds the basename → later-creators index used by the forward-import scan. */
 function buildNewFileIndex(ctx) {
     const newFileIndex = new Map();
@@ -382,8 +390,7 @@ function eachForwardImportSite(ctx, newFileIndex, visit) {
             const owners = newFileIndex.get(leaf);
             if (!owners)
                 continue;
-            const laterOwners = owners.filter((owner) => owner.order > entry.order ||
-                (owner.order === entry.order && owner.filename > entry.filename));
+            const laterOwners = owners.filter((owner) => isLaterOwner(owner, entry));
             if (laterOwners.length === 0)
                 continue;
             visit(entry, sitePath, specifier, cleaned, laterOwners);
@@ -477,9 +484,80 @@ export function lintPatchQueueForwardImports(ctx) {
                 severity: 'warning',
             });
         }
+        // Registration-kind declarations (0.37.0 item 5): a jar.mn packaging
+        // line, customElements registration, or actor registration referencing
+        // a later-created file. There is no import specifier to match — the
+        // declaration is "used" when the declared line (whitespace-trimmed)
+        // appears among the lines this patch adds to the declaring file AND
+        // its `creates` resolves to a file a later-ordered patch actually
+        // creates (with `owner`, when set, naming that patch) — mirroring
+        // findMatchingStagedDependency for the import kind.
+        for (const registration of entry.metadata?.stagedDependencies?.registrations ?? []) {
+            const failure = findStagedRegistrationFailure(entry, registration, newFileIndex);
+            if (failure === undefined)
+                continue;
+            issues.push({
+                file: registration.file,
+                check: 'staged-dependency-unused',
+                fingerprint: `staged-dependency-unused|${entry.filename}|${registration.file}|reg:${registration.line}|${registration.creates}|${registration.owner ?? ''}`,
+                message: `${entry.filename} declares a staged registration in ${registration.file} ` +
+                    `("${registration.line}") for ${registration.creates}, but ${describeRegistrationFailure(failure)} ` +
+                    'Remove the stale declaration with "fireforge patch staged-dependency --remove --kind registration" or update it to match the patch and queue.',
+                severity: 'warning',
+            });
+        }
     }
     return issues;
 }
+/**
+ * Validates one registration-kind declaration against the patch content
+ * and the queue, mirroring {@link findMatchingStagedDependency}: the
+ * declared line must be added by this patch, `creates` must exactly match
+ * a file a LATER-ordered patch creates (an earlier-only creator means the
+ * dependency is already satisfied and the declaration is stale), and
+ * `owner`, when set, must name one of those creating patches. Returns
+ * undefined when valid.
+ */
+function findStagedRegistrationFailure(entry, registration, newFileIndex) {
+    if (!isRegistrationLinePresent(entry, registration))
+        return { kind: 'line-absent' };
+    const creators = (newFileIndex.get(basename(registration.creates)) ?? []).filter((owner) => owner.fullPath === registration.creates && isLaterOwner(owner, entry));
+    if (creators.length === 0)
+        return { kind: 'creates-unresolved' };
+    if (registration.owner !== undefined &&
+        !creators.some((owner) => owner.filename === registration.owner)) {
+        return { kind: 'owner-mismatch', creators };
+    }
+    return undefined;
+}
+/** Message tail for each {@link StagedRegistrationFailure} shape. */
+function describeRegistrationFailure(failure) {
+    switch (failure.kind) {
+        case 'line-absent':
+            return 'the patch does not add that line.';
+        case 'creates-unresolved':
+            return ('no later-ordered patch creates that file — the declaration is stale, ' +
+                'or the queue order no longer stages it.');
+        case 'owner-mismatch':
+            return `that file is created by ${failure.creators.map((o) => o.filename).join(', ')}, not the declared owner.`;
+    }
+}
+/**
+ * True when the declared registration/packaging line appears (trimmed)
+ * among the lines the patch introduces in the declaring file — either as a
+ * newly-created file's content or as added lines to an existing file
+ * (where jar.mn / customElements.js / actor-registration edits land).
+ */
+function isRegistrationLinePresent(entry, registration) {
+    const declared = registration.line.trim();
+    if (declared.length === 0)
+        return false;
+    const introduced = [
+        entry.newFiles.get(registration.file),
+        entry.modifiedFileAdditions.get(registration.file),
+    ];
+    return introduced.some((content) => content !== undefined && content.split('\n').some((line) => line.trim() === declared));
+}
 /**
  * Cross-patch lint orchestrator. Runs every cross-patch rule against the
  * provided context and returns combined issues.
@@ -495,4 +573,3 @@ export function lintPatchQueueForwardImports(ctx) {
 export function lintPatchQueue(ctx) {
     return [...lintPatchQueueDuplicateCreations(ctx), ...lintPatchQueueForwardImports(ctx)];
 }
-//# sourceMappingURL=patch-lint-cross.js.map

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

@@ -169,4 +169,3 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
     }
     return issues;
 }
-//# sourceMappingURL=patch-lint-css.js.map

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

@@ -105,4 +105,3 @@ export function tagLintIssues(issues, diffFiles) {
     }
     return issues;
 }
-//# sourceMappingURL=patch-lint-diff-tag.js.map

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

@@ -6,7 +6,8 @@
  * cross-patch lint body (in `patch-lint-cross.ts`) can both depend on
  * the same diff walkers without inducing a circular import. Callers
  * should keep importing these through `patch-lint.ts` — this file is
- * an implementation detail.
+ * an implementation detail. The actual line-walking lives in
+ * `parseDiffSections` (patch-parse.ts), the codebase's single diff walker.
  */
 /**
  * Extracts new-file paths from a unified diff by scanning for `new file mode` markers.

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

@@ -7,23 +7,18 @@
  * cross-patch lint body (in `patch-lint-cross.ts`) can both depend on
  * the same diff walkers without inducing a circular import. Callers
  * should keep importing these through `patch-lint.ts` — this file is
- * an implementation detail.
+ * an implementation detail. The actual line-walking lives in
+ * `parseDiffSections` (patch-parse.ts), the codebase's single diff walker.
  */
+import { parseDiffSections } from './patch-parse.js';
 /**
  * Extracts new-file paths from a unified diff by scanning for `new file mode` markers.
  */
 export function detectNewFilesInDiff(diffContent) {
     const newFiles = new Set();
-    const lines = diffContent.split('\n');
-    let currentFile = null;
-    for (const line of lines) {
-        if (line.startsWith('diff --git')) {
-            const match = /^diff --git a\/.+ b\/(.+)$/.exec(line);
-            currentFile = match?.[1] ?? null;
-            continue;
-        }
-        if (line.startsWith('new file mode') && currentFile) {
-            newFiles.add(currentFile);
+    for (const section of parseDiffSections(diffContent)) {
+        if (section.isNewFile) {
+            newFiles.add(section.targetPath);
         }
     }
     return newFiles;
@@ -34,27 +29,18 @@ export function detectNewFilesInDiff(diffContent) {
  */
 export function extractAddedLinesPerFile(diffContent) {
     const result = new Map();
-    const lines = diffContent.split('\n');
-    let currentFile = null;
-    let inHunk = false;
-    for (const line of lines) {
-        if (line.startsWith('diff --git')) {
-            const match = /^diff --git a\/.+ b\/(.+)$/.exec(line);
-            currentFile = match?.[1] ?? null;
-            inHunk = false;
-            continue;
-        }
-        if (line.startsWith('@@')) {
-            inHunk = true;
-            continue;
-        }
-        if (inHunk && currentFile && line.startsWith('+') && !line.startsWith('+++')) {
-            let arr = result.get(currentFile);
-            if (!arr) {
-                arr = [];
-                result.set(currentFile, arr);
+    for (const section of parseDiffSections(diffContent)) {
+        for (const hunk of section.hunks) {
+            for (const line of hunk.lines) {
+                if (!line.startsWith('+'))
+                    continue;
+                let arr = result.get(section.targetPath);
+                if (!arr) {
+                    arr = [];
+                    result.set(section.targetPath, arr);
+                }
+                arr.push(line.slice(1));
             }
-            arr.push(line.slice(1));
         }
     }
     return result;
@@ -81,4 +67,3 @@ export function buildModifiedFileAdditionsFromDiff(diff) {
     }
     return result;
 }
-//# sourceMappingURL=patch-lint-diff.js.map

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

@@ -65,4 +65,3 @@ export function hasRelativeImport(content) {
     }
     return RELATIVE_IMPORT_FALLBACK_PATTERN.test(stripJsComments(content));
 }
-//# sourceMappingURL=patch-lint-imports.js.map

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

@@ -450,4 +450,3 @@ export function validateExportJsDoc(source, options) {
     }
     return issues;
 }
-//# sourceMappingURL=patch-lint-jsdoc.js.map

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

@@ -165,4 +165,3 @@ export function lintObserverTopics(strippedContent, file, binaryName) {
     }
     return issues;
 }
-//# sourceMappingURL=patch-lint-observer.js.map

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

@@ -67,4 +67,3 @@ export function resolvePatchOwnedSysMjs(currentNewFiles, patchQueueCtx) {
 export function resolvePatchOwnedChromeScripts(currentNewFiles, patchQueueCtx) {
     return resolveOwned(currentNewFiles, patchQueueCtx, (file) => file.endsWith('.js') && !file.endsWith('.sys.mjs'));
 }
-//# sourceMappingURL=patch-lint-ownership.js.map

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

@@ -5,4 +5,3 @@
  */
 export { buildPatchQueueContext, collectForwardImportEdges, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, } from './patch-lint-cross.js';
 export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
-//# sourceMappingURL=patch-lint-reexports.js.map

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

@@ -1,5 +1,5 @@
 import type { PatchLintIssue } from '../types/commands/index.js';
-import type { FireForgeConfig } from '../types/config.js';
+import type { FireForgeConfig, ProjectLicense } from '../types/config.js';
 import { type CommentStyle } from './license-headers.js';
 import { lintPatchedCss } from './patch-lint-css.js';
 export * from './patch-lint-reexports.js';
@@ -26,7 +26,42 @@ export declare function isTestFile(file: string): boolean;
  */
 export declare function commentStyleForFile(file: string): CommentStyle | null;
 /**
- * Checks new files for required license headers.
+ * Decides whether a NEW file's leading header satisfies the
+ * `missing-license-header` rule. Single owner of the acceptance policy —
+ * `lintNewFileHeaders` (the rule) and `autoFixLicenseHeaders` (the
+ * interactive export fixer) must agree, or the fixer offers to stack a
+ * second header onto a file the lint already accepts.
+ *
+ * Accepted shapes, in order:
+ *  - the project's own header for the file's comment style;
+ *  - under `browser/branding/`, ANY recognised license header in the
+ *    matching style: the setup-generated branding directory is copied
+ *    from Firefox's `unofficial` template and arrives with Mozilla
+ *    MPL-2.0 headers — legitimate for copyright purposes (the assets are
+ *    Mozilla's) even when the fork's own code is 0BSD / EUPL-1.2 /
+ *    GPL-2.0-or-later;
+ *  - on an MPL-2.0 project, any recognised header in the matching style;
+ *  - the verbatim upstream MPL-2.0 block header (`/* … *\/`, optionally
+ *    behind a leading editor-directive comment) REGARDLESS of the
+ *    project license, on any file whose comment syntax is the block form
+ *    (JS and CSS): a file copied from the Firefox tree legitimately
+ *    keeps Mozilla's header for provenance in an EUPL/GPL/0BSD project
+ *    too. 0.35.0 accepted this on JS only; field verification showed a
+ *    derived CSS file carrying the identical three-line block header
+ *    still needed a patch-level lintIgnore. Only the block form is
+ *    accepted — the `// `-style MPL header is FireForge-generated, not
+ *    upstream provenance — and `hash`-style files (FTL) stay excluded
+ *    because `/* … *\/` is not a comment there.
+ *
+ * @param file - Engine-relative path of the new file
+ * @param content - File content
+ * @param style - Comment style resolved for the file
+ * @param license - The project license
+ */
+export declare function isAcceptableNewFileHeader(file: string, content: string, style: CommentStyle, license: ProjectLicense): boolean;
+/**
+ * Checks new files for required license headers (acceptance policy in
+ * {@link isAcceptableNewFileHeader}).
  *
  * @param repoDir - Absolute path to the engine directory
  * @param newFiles - New file paths (relative to repoDir)

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

@@ -211,7 +211,52 @@ export function commentStyleForFile(file) {
 // License header lint
 // ---------------------------------------------------------------------------
 /**
- * Checks new files for required license headers.
+ * Decides whether a NEW file's leading header satisfies the
+ * `missing-license-header` rule. Single owner of the acceptance policy —
+ * `lintNewFileHeaders` (the rule) and `autoFixLicenseHeaders` (the
+ * interactive export fixer) must agree, or the fixer offers to stack a
+ * second header onto a file the lint already accepts.
+ *
+ * Accepted shapes, in order:
+ *  - the project's own header for the file's comment style;
+ *  - under `browser/branding/`, ANY recognised license header in the
+ *    matching style: the setup-generated branding directory is copied
+ *    from Firefox's `unofficial` template and arrives with Mozilla
+ *    MPL-2.0 headers — legitimate for copyright purposes (the assets are
+ *    Mozilla's) even when the fork's own code is 0BSD / EUPL-1.2 /
+ *    GPL-2.0-or-later;
+ *  - on an MPL-2.0 project, any recognised header in the matching style;
+ *  - the verbatim upstream MPL-2.0 block header (`/* … *\/`, optionally
+ *    behind a leading editor-directive comment) REGARDLESS of the
+ *    project license, on any file whose comment syntax is the block form
+ *    (JS and CSS): a file copied from the Firefox tree legitimately
+ *    keeps Mozilla's header for provenance in an EUPL/GPL/0BSD project
+ *    too. 0.35.0 accepted this on JS only; field verification showed a
+ *    derived CSS file carrying the identical three-line block header
+ *    still needed a patch-level lintIgnore. Only the block form is
+ *    accepted — the `// `-style MPL header is FireForge-generated, not
+ *    upstream provenance — and `hash`-style files (FTL) stay excluded
+ *    because `/* … *\/` is not a comment there.
+ *
+ * @param file - Engine-relative path of the new file
+ * @param content - File content
+ * @param style - Comment style resolved for the file
+ * @param license - The project license
+ */
+export function isAcceptableNewFileHeader(file, content, style, license) {
+    if (content.startsWith(getLicenseHeader(license, style)))
+        return true;
+    if (file.startsWith('browser/branding/') && hasAnyLicenseHeader(content, style))
+        return true;
+    if (license === 'MPL-2.0' && hasAnyLicenseHeader(content, style))
+        return true;
+    if ((style === 'js' || style === 'css') && hasUpstreamMplBlockHeader(content))
+        return true;
+    return false;
+}
+/**
+ * Checks new files for required license headers (acceptance policy in
+ * {@link isAcceptableNewFileHeader}).
  *
  * @param repoDir - Absolute path to the engine directory
  * @param newFiles - New file paths (relative to repoDir)
@@ -229,38 +274,7 @@ export async function lintNewFileHeaders(repoDir, newFiles, config) {
         if (!(await pathExists(filePath)))
             continue;
         const content = await readText(filePath);
-        const expectedHeader = getLicenseHeader(license, style);
-        // Auto-exempt `browser/branding/` when the file carries ANY recognised
-        // license header in the matching comment style. The setup-generated
-        // branding directory is copied from Firefox's `unofficial` template,
-        // which arrives with Mozilla MPL-2.0 headers — those are legitimate
-        // for copyright purposes (the assets are Mozilla's) even when the
-        // fork's own code is 0BSD / EUPL-1.2 / GPL-2.0-or-later. The narrower
-        // license-match rule would force operators to either rewrite the
-        // copied headers (misrepresenting authorship) or suppress the lint
-        // with `--skip-lint` (hiding real issues elsewhere).
-        if (content.startsWith(expectedHeader))
-            continue;
-        if (file.startsWith('browser/branding/') && hasAnyLicenseHeader(content, style))
-            continue;
-        // Accept the MPL-2.0 block-comment form (`/* ... */` with leading `*`)
-        // for any JS file — that is the canonical upstream Firefox header
-        // shape, and `hasAnyLicenseHeader` above also recognises it. The
-        // explicit guard mirrors the branding carve-out so operators using the
-        // standard Mozilla header on a JS file (e.g. one copied from upstream
-        // browser/base/content) do not need `--skip-lint` to land it.
-        if (license === 'MPL-2.0' && hasAnyLicenseHeader(content, style))
-            continue;
-        // Accept the verbatim upstream MPL block header on new JS files
-        // REGARDLESS of the project license: a file copied from the Firefox
-        // tree legitimately keeps Mozilla's header for provenance in an
-        // EUPL/GPL/0BSD project too. The carve-out above is gated on the
-        // project being MPL-2.0 itself, which made this documented case dead
-        // code for every other license — consumers carried repo-side audit
-        // workarounds (recorded 2026-07-04 in the Hominis FORGE.md). Only
-        // the block-comment form is accepted; the `// `-style MPL header is
-        // FireForge-generated, not upstream provenance.
-        if (style === 'js' && hasUpstreamMplBlockHeader(content))
+        if (isAcceptableNewFileHeader(file, content, style, license))
             continue;
         issues.push({
             file,
@@ -620,4 +634,3 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
     }
     return issues;
 }
-//# sourceMappingURL=patch-lint.js.map

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

@@ -27,4 +27,3 @@ export async function withPatchDirectoryLock(patchesDir, operation) {
         throw new PatchError(toError(error).message);
     });
 }
-//# sourceMappingURL=patch-lock.js.map

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

@@ -4,6 +4,7 @@
  */
 import { stat } from 'node:fs/promises';
 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';
 /**
@@ -89,6 +90,14 @@ export async function validatePatchesManifestConsistency(patchesDir) {
  *   plus the filenames that were reconstructed from generic defaults.
  */
 export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersion) {
+    // 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));
+}
+async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion) {
     const manifestState = await loadPatchesManifestState(patchesDir);
     const existingEntries = new Map();
     if (manifestState.manifest) {
@@ -162,4 +171,3 @@ function normalizeFiles(files) {
 function sameStringArray(left, right) {
     return left.length === right.length && left.every((value, index) => value === right[index]);
 }
-//# sourceMappingURL=patch-manifest-consistency.js.map

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

@@ -37,10 +37,26 @@ export interface PatchManifestRowMutationResult {
 export declare function loadPatchesManifestState(patchesDir: string): Promise<LoadedManifestState>;
 /**
  * Loads the patches manifest if it exists.
+ *
+ * READ-ONLY callers only: this collapses "absent" and "corrupt" into null.
+ * Any code path that will WRITE the manifest (or delete patch files based
+ * on its content) must use {@link loadPatchesManifestForWrite} instead —
+ * treating a corrupt manifest as empty and then saving destroys every
+ * existing patch's metadata.
+ *
  * @param patchesDir - Path to the patches directory
  * @returns PatchesManifest or null if not found
  */
 export declare function loadPatchesManifest(patchesDir: string): Promise<PatchesManifest | null>;
+/**
+ * Loads the patches manifest for a mutating operation.
+ *
+ * Returns null only when the manifest genuinely does not exist; a manifest
+ * that exists but fails to parse/validate throws
+ * {@link PatchManifestCorruptError} so the caller aborts instead of
+ * rebuilding an empty queue over the top of the corrupt file.
+ */
+export declare function loadPatchesManifestForWrite(patchesDir: string): Promise<PatchesManifest | null>;
 /**
  * Saves the patches manifest.
  * @param patchesDir - Path to the patches directory
@@ -86,8 +102,9 @@ export interface PatchRenameEntry {
     newOrder: number;
 }
 /**
- * Rewrites `stagedDependencies.forwardImports[].owner` references on one
- * patch through a rename lookup. Owners embed exact patch filenames, so any
+ * Rewrites `stagedDependencies.forwardImports[].owner` and
+ * `stagedDependencies.registrations[].owner` references on one patch
+ * through a rename lookup. Owners embed exact patch filenames, so any
  * renumber (compact, reorder, placement export, rename) that does not remap
  * them leaves dangling references that surface as false forward-import
  * errors on the next lint.