@hominis/fireforge 0.41.0 → 0.43.0

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

@@ -7,15 +7,25 @@ import { getPackageVersion } from '../utils/package-root.js';
 import { getFurnacePaths } from './furnace-config.js';
 import { git } from './git-base.js';
 import { collectNewFileCreatorsByPath } from './patch-lint.js';
-// Schema 2 (FORGE G10): entries additionally carry the lintIgnore-suppressed
+// Schema 2: entries additionally carry the lintIgnore-suppressed
 // issues and the measured non-binary line count, so a warm run can report
 // waived size measurements identically to a cold one (the F5-class hazard:
 // a cache hit must never surface LESS than a fresh lint).
-// Schema 3 (FORGE H2): the key additionally content-hashes the
+// Schema 3: the key additionally content-hashes the
 // `patchLint.checkJsTestShim` file exactly as `checkJsExtraShim`'s already
 // was — before this, editing the test shim in place replayed every cached
 // verdict (the same warm-run-reports-less-than-cold hazard class).
-export const LINT_CACHE_SCHEMA_VERSION = 3;
+// Schema 4: each entry RECORDS the lint-ignore waiver set that
+// produced it, and a lookup whose effective waiver set differs is refused
+// even when the key matches. The key already hashes `patch.lintIgnore`, so
+// this is belt-and-braces on purpose: a waiver change is the one mutation
+// that makes a replayed verdict actively WRONG (an operator writes a
+// waiver, re-runs, and is shown the finding they just waived — or worse,
+// a pre-waiver verdict replayed under a post-waiver key), and the class
+// must not depend on every future key input staying complete. Bumping the
+// schema also discards every pre-4 entry, which is itself the cure for a
+// cache that already holds a mismatched verdict.
+export const LINT_CACHE_SCHEMA_VERSION = 4;
 const LINT_IMPLEMENTATION_VERSION = 1;
 const LINT_CACHE_DIRNAME = 'lint-cache';
 const PER_PATCH_CACHE_FILENAME = 'per-patch-v1.json';
@@ -108,7 +118,7 @@ export async function buildPerPatchLintCacheKey(input) {
         : { path: shimPath, hash: await fileHash(resolve(input.projectRoot, shimPath)) };
     // Both shims feed compiled checkJs programs, so both are content-hashed —
     // the config block alone only carries their PATHS, and an in-place edit
-    // must invalidate the programs it feeds (FORGE H2).
+    // must invalidate the programs it feeds.
     const [extraShim, testShim] = await Promise.all([
         shimHashOf(input.config.patchLint?.checkJsExtraShim),
         shimHashOf(input.config.patchLint?.checkJsTestShim),
@@ -118,7 +128,7 @@ export async function buildPerPatchLintCacheKey(input) {
         engineHeadSha: input.engineHeadSha ?? null,
         lintImplementationVersion: LINT_IMPLEMENTATION_VERSION,
         // Deliberately the PLAIN semver, not the +g<sha> build identity
-        // (FORGE K2): identity churns every commit at the same version and
+        //: identity churns every commit at the same version and
         // would invalidate the cache for no correctness gain.
         packageVersion: input.packageVersion ?? getPackageVersion(),
         patchFile: await fileHash(join(input.patchesDir, input.patch.filename)),
@@ -144,6 +154,8 @@ function isCacheEntry(value) {
         Array.isArray(entry.issues) &&
         Array.isArray(entry.suppressed) &&
         typeof entry.lineCount === 'number' &&
+        Array.isArray(entry.lintIgnore) &&
+        entry.lintIgnore.every((id) => typeof id === 'string') &&
         typeof entry.updatedAt === 'string');
 }
 /** Loads the per-patch lint cache, treating missing or invalid files as empty. */
@@ -187,11 +199,25 @@ export async function savePerPatchLintCache(projectRoot, cache) {
 export async function clearPerPatchLintCache(projectRoot) {
     await writeJson(getPerPatchLintCachePath(projectRoot), createEmptyPerPatchLintCache());
 }
-/** Returns the cached lint payload for a patch when the stored key still matches. */
-export function getCachedPerPatchLintIssues(cache, patchFilename, key) {
+/** Canonical (sorted, de-duplicated) form of a waiver set for comparison. */
+function normalizeLintIgnoreSet(lintIgnore) {
+    return [...new Set(lintIgnore ?? [])].sort((a, b) => a.localeCompare(b));
+}
+/**
+ * Returns the cached lint payload for a patch when the stored key still
+ * matches AND the entry was computed under the same lint-ignore waiver set
+ *. A waiver change makes a replayed verdict actively wrong, so
+ * the waiver set is compared explicitly rather than trusted to the key.
+ */
+export function getCachedPerPatchLintIssues(cache, patchFilename, key, lintIgnore) {
     const entry = cache.entries[patchFilename];
     if (!entry || entry.key !== key)
         return undefined;
+    const expected = normalizeLintIgnoreSet(lintIgnore);
+    const stored = normalizeLintIgnoreSet(entry.lintIgnore);
+    if (expected.length !== stored.length || expected.some((id, i) => id !== stored[i])) {
+        return undefined;
+    }
     return {
         issues: entry.issues.map((issue) => ({ ...issue })),
         suppressed: entry.suppressed.map((issue) => ({ ...issue })),
@@ -199,13 +225,14 @@ export function getCachedPerPatchLintIssues(cache, patchFilename, key) {
     };
 }
 /** Stores the per-patch lint payload after a successful lint calculation. */
-export function setCachedPerPatchLintIssues(cache, patchFilename, key, issues, suppressed, lineCount) {
+export function setCachedPerPatchLintIssues(cache, patchFilename, key, issues, suppressed, lineCount, lintIgnore) {
     cache.entries[patchFilename] = {
         key,
         patchFilename,
         issues: issues.map((issue) => ({ ...issue })),
         suppressed: suppressed.map((issue) => ({ ...issue })),
         lineCount,
+        lintIgnore: normalizeLintIgnoreSet(lintIgnore),
         updatedAt: new Date().toISOString(),
     };
 }

package/dist/src/core/mach-known-noise-filter.d.ts

@@ -27,6 +27,27 @@
  *   - The hold buffer is bounded; on overflow the block is flushed verbatim
  *     and the filter returns to pass-through, so output is never lost.
  */
+/**
+ * True when CAPTURED output carries the documented mozsystemmonitor
+ * teardown traceback.
+ *
+ * The echo filter above only affects what a human sees. The CLASSIFIER
+ * reads the raw capture, and it needs the same recognition to tell "the
+ * suite finished clean and then upstream fell over at shutdown" from "the
+ * suite did not finish". Deliberately the same two-signal test the echo
+ * filter applies — a novel attribute or a traceback from anywhere but
+ * `resourcemonitor.py` is NOT this incident and must keep failing the run.
+ *
+ * The shutdown-marker precondition the echo filter adds is intentionally
+ * omitted: the whole point at the classification layer is the case where
+ * the teardown crash prevented the shutdown marker from printing.
+ *
+ * Pure; exported for the classifier and for direct unit testing.
+ *
+ * @param output - Raw captured stdout/stderr
+ * @returns True when the recognized teardown traceback is present
+ */
+export declare function hasKnownTeardownNoise(output: string): boolean;
 /**
  * Shared across the stdout and stderr filter instances of ONE mach run:
  * SUITE_END typically arrives on stdout while the teardown traceback lands

package/dist/src/core/mach-known-noise-filter.js

@@ -49,6 +49,29 @@ const SHUTDOWN_MARKER_PATTERN = /\bSUITE_END\b/;
 function isRecognizedTeardownNoise(block) {
     return (KNOWN_TEARDOWN_ATTRIBUTE_ERROR_PATTERN.test(block) && RESOURCEMONITOR_FRAME_PATTERN.test(block));
 }
+/**
+ * True when CAPTURED output carries the documented mozsystemmonitor
+ * teardown traceback.
+ *
+ * The echo filter above only affects what a human sees. The CLASSIFIER
+ * reads the raw capture, and it needs the same recognition to tell "the
+ * suite finished clean and then upstream fell over at shutdown" from "the
+ * suite did not finish". Deliberately the same two-signal test the echo
+ * filter applies — a novel attribute or a traceback from anywhere but
+ * `resourcemonitor.py` is NOT this incident and must keep failing the run.
+ *
+ * The shutdown-marker precondition the echo filter adds is intentionally
+ * omitted: the whole point at the classification layer is the case where
+ * the teardown crash prevented the shutdown marker from printing.
+ *
+ * Pure; exported for the classifier and for direct unit testing.
+ *
+ * @param output - Raw captured stdout/stderr
+ * @returns True when the recognized teardown traceback is present
+ */
+export function hasKnownTeardownNoise(output) {
+    return isRecognizedTeardownNoise(output);
+}
 /** Fresh per-run context — hand the same instance to both stream filters. */
 export function createTeardownNoiseContext() {
     return { shutdownSeen: false };

package/dist/src/core/mach-mozconfig.js

@@ -1,9 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { MozconfigError } from '../errors/build.js';
-import { pathExists, readText, writeText } from '../utils/fs.js';
+import { pathExists, readText, writeTextIfChanged } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
 import { getPlatform } from '../utils/platform.js';
-import { BrandingMozconfigMismatchError } from './branding.js';
+import { BrandingMozconfigMismatchError, splitAppId } from './branding.js';
 /**
  * Replaces template variables in a string.
  * @param content - Content with ${variable} placeholders
@@ -95,6 +96,14 @@ export async function generateMozconfig(configsDir, engineDir, config) {
         binaryName: config.binaryName,
     };
     let content = '';
+    // Bundle identity: branding configure.sh carries only the LEAF of appId
+    // (see splitAppId in branding.ts — upstream composes the mac bundle id as
+    // <distribution-id>.<MOZ_MACBUNDLE_ID>); the prefix travels here so the
+    // two halves can never drift apart.
+    const { distributionId } = splitAppId(config.appId);
+    content +=
+        `# FireForge identity (generated from fireforge.json appId)\n` +
+            `ac_add_options --with-distribution-id=${distributionId}\n\n`;
     // Read common config if it exists
     if (await pathExists(commonPath)) {
         const commonContent = await readText(commonPath);
@@ -106,7 +115,16 @@ export async function generateMozconfig(configsDir, engineDir, config) {
     }
     const platformContent = await readText(platformPath);
     content += `# Platform configuration (${platform})\n${replaceVariables(platformContent, variables)}`;
-    await writeText(outputPath, content);
+    // Write-if-changed: `mozconfig` is a mach CONFIGURE INPUT, so
+    // its mtime — not its content — is what `config.status` compares against.
+    // Rewriting a byte-identical file on every build-capable invocation made
+    // mach re-run `configure` plus backend regeneration ("Backend config
+    // changed; N files touched") on EVERY run, each run re-arming the next.
+    // Only touch the file when the rendered content actually differs.
+    const wrote = await writeTextIfChanged(outputPath, content);
+    if (!wrote) {
+        verbose(`mozconfig already up to date (content unchanged): ${outputPath}`);
+    }
     // Preflight: the mozconfig we just wrote must reference the branding
     // directory FireForge actually set up. Catching the drift here (after the
     // write, before anything consumes mozconfig) keeps `generateMozconfig`

package/dist/src/core/module-resolution-preflight.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Engine-aware resolution preflight for queue-owned system modules.
+ *
+ * An `.sys.mjs` that a packaged module imports but whose `EXTRA_JS_MODULES`
+ * registration never landed kills every xpcshell suite
+ * with `xpcshell return code: -11` and ZERO output — no import error, no
+ * stack, nothing. The 0.41.0 `unregistered-system-module` check catches
+ * this class, but only in one shape: a module NEWLY CREATED by a patch in
+ * the projected queue. The class recurred through the other shape — three
+ * modules imported from an ALREADY-EXISTING module before their moz.build
+ * lines landed — and cost a full rebuild cycle before anyone recognised it.
+ *
+ * This preflight closes that gap by asking the question against the ENGINE
+ * rather than against a projected diff: for every `resource:///modules/…`
+ * specifier imported by any queue-owned module, does the module it names
+ * exist, and is it registered in a moz.build that covers it?
+ *
+ * Scope is the queue-owned file set on purpose. A specifier that resolves
+ * to no owned file is an UPSTREAM Firefox module, which FireForge does not
+ * police and cannot cheaply enumerate; policing only what the fork owns is
+ * both the actionable set and the one that produced every recorded
+ * incident.
+ */
+/** Why a queue-owned module import does not resolve to a packaged module. */
+export type UnresolvedModuleReason = 'missing-file' | 'unregistered';
+/** One unresolvable or unregistered system-module import. */
+export interface UnresolvedModuleImport {
+    /** Engine-relative path of the module the specifier names. */
+    module: string;
+    /** The `resource://` specifier as written. */
+    specifier: string;
+    /** Engine-relative paths of the files that import it, sorted. */
+    importers: string[];
+    reason: UnresolvedModuleReason;
+}
+/**
+ * Resolves every `resource://` system-module import made by the
+ * queue-owned files and reports the ones a packaged browser could not
+ * load.
+ *
+ * @param engineDir - Path to the engine checkout
+ * @param ownedFiles - Engine-relative paths the patch queue owns
+ * @returns Findings sorted by module path; empty when everything resolves
+ */
+export declare function findUnresolvedSystemModuleImports(engineDir: string, ownedFiles: readonly string[]): Promise<UnresolvedModuleImport[]>;
+/**
+ * Renders findings as operator-facing lines, naming the unregistered or
+ * unresolvable module, so the failure is a sentence instead of a bare
+ * `-11`.
+ */
+export declare function formatUnresolvedSystemModuleImports(findings: readonly UnresolvedModuleImport[]): string[];

package/dist/src/core/module-resolution-preflight.js

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Engine-aware resolution preflight for queue-owned system modules.
+ *
+ * An `.sys.mjs` that a packaged module imports but whose `EXTRA_JS_MODULES`
+ * registration never landed kills every xpcshell suite
+ * with `xpcshell return code: -11` and ZERO output — no import error, no
+ * stack, nothing. The 0.41.0 `unregistered-system-module` check catches
+ * this class, but only in one shape: a module NEWLY CREATED by a patch in
+ * the projected queue. The class recurred through the other shape — three
+ * modules imported from an ALREADY-EXISTING module before their moz.build
+ * lines landed — and cost a full rebuild cycle before anyone recognised it.
+ *
+ * This preflight closes that gap by asking the question against the ENGINE
+ * rather than against a projected diff: for every `resource:///modules/…`
+ * specifier imported by any queue-owned module, does the module it names
+ * exist, and is it registered in a moz.build that covers it?
+ *
+ * Scope is the queue-owned file set on purpose. A specifier that resolves
+ * to no owned file is an UPSTREAM Firefox module, which FireForge does not
+ * police and cannot cheaply enumerate; policing only what the fork owns is
+ * both the actionable set and the one that produced every recorded
+ * incident.
+ */
+import { dirname, join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { escapeRegex } from '../utils/regex.js';
+import { extractResourceModuleSpecifiers, moduleSourceSuffix, } from './patch-lint-module-registration.js';
+/** Extensions whose contents are scanned for resource-module imports. */
+const IMPORTABLE_EXTENSIONS = ['.mjs', '.sys.mjs', '.js', '.jsm'];
+/**
+ * Reads a file, returning undefined (with a verbose note) rather than
+ * throwing: a preflight must not fail a command over one unreadable path.
+ */
+async function readIfPresent(path) {
+    try {
+        if (!(await pathExists(path)))
+            return undefined;
+        return await readText(path);
+    }
+    catch (error) {
+        verbose(`Module resolution preflight: could not read ${path} — ${toError(error).message}`);
+        return undefined;
+    }
+}
+/**
+ * True when some `moz.build` at or above `moduleRelPath`'s directory (up
+ * to, and including, the engine root) mentions the module's basename.
+ *
+ * Walking ancestors — rather than checking only the sibling `moz.build` —
+ * matches how Mozilla's build system actually works: a module list may sit
+ * in a parent directory's `moz.build` with a path-qualified entry. The
+ * check is a quoted-basename match for the same reason the queue-level
+ * rule uses one: parsing moz.build's Python is not worth it for a
+ * preflight, and a quoted basename has no meaningful false-positive shape.
+ */
+async function isRegisteredInAncestorMozBuild(engineDir, moduleRelPath, mozBuildCache) {
+    const leaf = moduleRelPath.slice(moduleRelPath.lastIndexOf('/') + 1);
+    // The entry may be the bare basename (`"Foo.sys.mjs"`, sibling
+    // moz.build) or path-qualified relative to the moz.build that declares
+    // it (`"sub/Foo.sys.mjs"`, ancestor moz.build). Both are the same
+    // registration; anchor on the closing quote and require a path boundary
+    // so `NotFoo.sys.mjs` cannot satisfy `Foo.sys.mjs`.
+    const quotedLeaf = new RegExp(`["'](?:[^"']*/)?${escapeRegex(leaf)}["']`);
+    let dir = dirname(moduleRelPath);
+    for (;;) {
+        const key = dir === '.' ? '' : dir;
+        if (!mozBuildCache.has(key)) {
+            mozBuildCache.set(key, await readIfPresent(join(engineDir, key, 'moz.build')));
+        }
+        const content = mozBuildCache.get(key);
+        if (content !== undefined && quotedLeaf.test(content))
+            return true;
+        if (dir === '.' || dir === '' || dir === '/')
+            return false;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+}
+/**
+ * Resolves every `resource://` system-module import made by the
+ * queue-owned files and reports the ones a packaged browser could not
+ * load.
+ *
+ * @param engineDir - Path to the engine checkout
+ * @param ownedFiles - Engine-relative paths the patch queue owns
+ * @returns Findings sorted by module path; empty when everything resolves
+ */
+export async function findUnresolvedSystemModuleImports(engineDir, ownedFiles) {
+    const owned = [...new Set(ownedFiles)];
+    /** specifier → importing owned files. */
+    const importersBySpecifier = new Map();
+    for (const file of owned) {
+        if (!IMPORTABLE_EXTENSIONS.some((extension) => file.endsWith(extension)))
+            continue;
+        const content = await readIfPresent(join(engineDir, file));
+        if (content === undefined)
+            continue;
+        for (const specifier of extractResourceModuleSpecifiers(content)) {
+            const importers = importersBySpecifier.get(specifier) ?? new Set();
+            importers.add(file);
+            importersBySpecifier.set(specifier, importers);
+        }
+    }
+    const mozBuildCache = new Map();
+    const findings = [];
+    for (const [specifier, importers] of importersBySpecifier) {
+        const suffix = moduleSourceSuffix(specifier);
+        if (suffix === undefined)
+            continue;
+        // Only fork-owned targets are policed; anything else is upstream.
+        const target = owned.find((file) => file.endsWith(suffix));
+        if (target === undefined)
+            continue;
+        const sortedImporters = [...importers].sort((a, b) => a.localeCompare(b));
+        if (!(await pathExists(join(engineDir, target)))) {
+            findings.push({
+                module: target,
+                specifier,
+                importers: sortedImporters,
+                reason: 'missing-file',
+            });
+            continue;
+        }
+        if (!(await isRegisteredInAncestorMozBuild(engineDir, target, mozBuildCache))) {
+            findings.push({
+                module: target,
+                specifier,
+                importers: sortedImporters,
+                reason: 'unregistered',
+            });
+        }
+    }
+    // Deterministic order regardless of Map iteration or owned-file order.
+    return findings.sort((a, b) => a.module.localeCompare(b.module) || a.specifier.localeCompare(b.specifier));
+}
+/**
+ * Renders findings as operator-facing lines, naming the unregistered or
+ * unresolvable module, so the failure is a sentence instead of a bare
+ * `-11`.
+ */
+export function formatUnresolvedSystemModuleImports(findings) {
+    return findings.map((finding) => finding.reason === 'missing-file'
+        ? `${finding.module}: imported as ${finding.specifier} by ${finding.importers.join(', ')}, ` +
+            'but the file does not exist in engine/. A packaged browser cannot load it; xpcshell ' +
+            'dies on SIGSEGV with no output.'
+        : `${finding.module}: imported as ${finding.specifier} by ${finding.importers.join(', ')}, ` +
+            'but no moz.build at or above its directory registers it. Add it to EXTRA_JS_MODULES ' +
+            '(or the appropriate namespaced module list) — until then a packaged browser cannot ' +
+            'load it and xpcshell dies on SIGSEGV with no output.');
+}

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

@@ -8,6 +8,7 @@ import { discoverPatches, withPatchDirectoryLock } from './patch-apply.js';
 import { normalizePatchArtifact } from './patch-artifact-normalize.js';
 import { findAllPatchesForFilesWithDetails, } from './patch-export-coverage.js';
 import { addPatchToManifest, loadPatchesManifestForWrite, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest.js';
+import { requirePatchOrder } from './patch-parse.js';
 import { allocatePolicyOrder, enforcePatchPolicy } from './patch-policy.js';
 export { findAllPatchesForFiles, findAllPatchesForFilesWithDetails, findSupersededPatches, isPatchFullyCovered, } from './patch-export-coverage.js';
 import { escapeRegex } from '../utils/regex.js';
@@ -264,7 +265,7 @@ async function computeExportPlanUnderLock(input) {
     const patchPath = join(input.patchesDir, patchFilename);
     const metadata = {
         filename: patchFilename,
-        order: parseInt(patchFilename.split('-')[0] ?? '0', 10),
+        order: requirePatchOrder(patchFilename),
         category: input.category,
         name: input.name,
         description: input.description,

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

@@ -18,6 +18,11 @@
  */
 /** Maximum Levenshtein distance accepted as a "did you mean" suggestion. */
 const SUGGESTION_DISTANCE_THRESHOLD = 3;
+/**
+ * Shortest side accepted for a prefix relation. Below this a prefix match
+ * is noise: a one-character ordinal prefixes almost anything.
+ */
+const MIN_PREFIX_MATCH_LENGTH = 4;
 /** Maximum number of suggestions to surface in the error message. */
 const SUGGESTION_LIMIT = 3;
 /**
@@ -83,10 +88,31 @@ function collectAcceptedIdentifiers(patches) {
  * candidate whose distance exceeds {@link SUGGESTION_DISTANCE_THRESHOLD}.
  */
 function rankSuggestions(identifier, candidates) {
+    const needle = identifier.toLowerCase();
     return candidates
-        .map((candidate) => ({ candidate, distance: levenshtein(identifier, candidate) }))
-        .filter((entry) => entry.distance <= SUGGESTION_DISTANCE_THRESHOLD)
-        .sort((a, b) => a.distance - b.distance || a.candidate.localeCompare(b.candidate))
+        .map((candidate) => {
+        const lower = candidate.toLowerCase();
+        // Prefix relation in EITHER direction is a stronger signal than edit
+        // distance and is not bounded by it: a partial ordinal or
+        // an abbreviated slug ("ui-foo" for "002-ui-foo.patch") is many edits
+        // away from the full identifier yet is obviously the intended target.
+        // `lower.startsWith(needle)`: the operator typed an abbreviation of
+        // a real identifier. The reverse relation is only meaningful when
+        // the candidate is substantial — otherwise the single-character
+        // ordinal "9" would "match" every input starting with a 9.
+        const prefixMatch = needle.length >= MIN_PREFIX_MATCH_LENGTH &&
+            (lower.startsWith(needle) ||
+                (lower.length >= MIN_PREFIX_MATCH_LENGTH && needle.startsWith(lower)));
+        return {
+            candidate,
+            prefixMatch,
+            distance: levenshtein(identifier, candidate),
+        };
+    })
+        .filter((entry) => entry.prefixMatch || entry.distance <= SUGGESTION_DISTANCE_THRESHOLD)
+        .sort((a, b) => Number(b.prefixMatch) - Number(a.prefixMatch) ||
+        a.distance - b.distance ||
+        a.candidate.localeCompare(b.candidate))
         .slice(0, SUGGESTION_LIMIT)
         .map((entry) => entry.candidate);
 }

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

@@ -32,7 +32,7 @@ export interface CheckJsMode {
     compilerOptions?: PatchLintCheckJsCompilerOptions;
     /**
      * How to report undefined free identifiers (TS2304/TS2552). Default
-     * 'warning' — see `patchLint.undefinedIdentifiers` (FORGE F12).
+     * 'warning' — see `patchLint.undefinedIdentifiers`.
      */
     undefinedIdentifiers?: PatchLintSeverityGate;
 }
@@ -68,7 +68,7 @@ export interface GroupedCheckJsResult {
  *   against the real owning sources while unrelated owned files are never
  *   parsed. `.mjs` files are module-scoped, so a root's diagnostics are
  *   identical whether other owned files are roots or mere resolution
- *   targets (pinned by the rootScope parity test — FORGE J1c).
+ * targets (pinned by the rootScope parity test).
  * @returns Diagnostics grouped per owning file plus run-level errors
  */
 export declare function runCheckJsGrouped(repoDir: string, resolutionOwned: Set<string>, extraShimPath?: string, projectRoot?: string, mode?: CheckJsMode, builtinShimSuffix?: string, rootScope?: ReadonlySet<string>): Promise<GroupedCheckJsResult>;
@@ -102,7 +102,7 @@ export declare function runCheckJs(repoDir: string, patchOwnedFiles: Set<string>
  */
 export declare function invokePatchLintCheckJs(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, reportScope?: ReadonlySet<string>): Promise<PatchLintIssue[]>;
 /**
- * Runs the checkJs pass over patch-owned test `.js` files (FORGE G5,
+ * Runs the checkJs pass over patch-owned test `.js` files (
  * `patchLint.checkJsTestFiles`). Each test file gets its OWN small
  * program — mochitest scripts share top-level scope only with their
  * directory's `head*.js` helpers, so one multi-script program would emit
@@ -131,7 +131,7 @@ export declare function runCheckJsTestFilesGrouped(repoDir: string, testFiles: S
  * @param patchLint - The resolved `patchLint` config block
  * @param projectRoot - FireForge project root for shim resolution
  * @param rootScope - Optional subset of files to use as program roots
- *   (`--patches`); resolution still spans the whole queue (FORGE J1c)
+ * (`--patches`); resolution still spans the whole queue
  */
 export declare function invokePatchLintCheckJsGrouped(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, rootScope?: ReadonlySet<string>): Promise<GroupedCheckJsResult>;
 /**
@@ -141,7 +141,7 @@ export declare function invokePatchLintCheckJsGrouped(repoDir: string, patchOwne
  * when `checkJsTestFiles` is on). The built program itself never
  * contributes globals (see {@link runCheckJsGrouped}), so a warm
  * all-cache-hit run can satisfy the "warm never reports less than cold"
- * invariant (FORGE F5) with this probe instead of building the whole
+ * invariant with this probe instead of building the whole
  * TypeScript program. Issue objects are byte-identical to the build
  * path's, deduplicated by message like {@link runCheckJsTestFilesGrouped}.
  */

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

@@ -154,7 +154,7 @@ function createPathsResolver(ts, paths, baseDir, fileExists, onResolved) {
  *   against the real owning sources while unrelated owned files are never
  *   parsed. `.mjs` files are module-scoped, so a root's diagnostics are
  *   identical whether other owned files are roots or mere resolution
- *   targets (pinned by the rootScope parity test — FORGE J1c).
+ * targets (pinned by the rootScope parity test).
  * @returns Diagnostics grouped per owning file plus run-level errors
  */
 export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath, projectRoot, mode, builtinShimSuffix, rootScope) {
@@ -206,7 +206,7 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
     let shimSource;
     try {
         const composed = await composeShimSource(projectRoot ?? repoDir, extraShimPath);
-        // The suffix (e.g. the loose test-harness baseline, FORGE G5) goes
+        // The suffix (e.g. the loose test-harness baseline) goes
         // AFTER the consumer's extra shim: TypeScript resolves conflicting
         // `declare var` redeclarations to the FIRST declaration, so a typed
         // consumer declaration must precede the loose fallback to win.
@@ -420,7 +420,7 @@ export async function invokePatchLintCheckJs(repoDir, patchOwnedFiles, patchLint
     return runCheckJs(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, modeFromPatchLintConfig(patchLint), reportScope);
 }
 /**
- * Runs the checkJs pass over patch-owned test `.js` files (FORGE G5,
+ * Runs the checkJs pass over patch-owned test `.js` files (
  * `patchLint.checkJsTestFiles`). Each test file gets its OWN small
  * program — mochitest scripts share top-level scope only with their
  * directory's `head*.js` helpers, so one multi-script program would emit
@@ -446,7 +446,7 @@ export async function runCheckJsTestFilesGrouped(repoDir, testFiles, patchLint,
     for (const file of files) {
         // Under a rootScope only the scoped files get their own program, but
         // head.js helper discovery still spans the full owned set so a scoped
-        // test keeps its cross-patch harness globals (FORGE J1c).
+        // test keeps its cross-patch harness globals.
         if (rootScope !== undefined && !rootScope.has(file))
             continue;
         const dir = file.slice(0, file.lastIndexOf('/') + 1);
@@ -498,7 +498,7 @@ function modeFromPatchLintConfig(patchLint) {
  * @param patchLint - The resolved `patchLint` config block
  * @param projectRoot - FireForge project root for shim resolution
  * @param rootScope - Optional subset of files to use as program roots
- *   (`--patches`); resolution still spans the whole queue (FORGE J1c)
+ * (`--patches`); resolution still spans the whole queue
  */
 export async function invokePatchLintCheckJsGrouped(repoDir, patchOwnedFiles, patchLint, projectRoot, rootScope) {
     return runCheckJsGrouped(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, modeFromPatchLintConfig(patchLint), undefined, rootScope);
@@ -510,7 +510,7 @@ export async function invokePatchLintCheckJsGrouped(repoDir, patchOwnedFiles, pa
  * when `checkJsTestFiles` is on). The built program itself never
  * contributes globals (see {@link runCheckJsGrouped}), so a warm
  * all-cache-hit run can satisfy the "warm never reports less than cold"
- * invariant (FORGE F5) with this probe instead of building the whole
+ * invariant with this probe instead of building the whole
  * TypeScript program. Issue objects are byte-identical to the build
  * path's, deduplicated by message like {@link runCheckJsTestFilesGrouped}.
  */

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

@@ -3,7 +3,7 @@
  * `patch-lint-cross.ts` (at the per-file line budget). Re-exported from
  * there so callers keep importing from `patch-lint.ts` unchanged.
  *
- * Memoised per context object (FORGE J1): ownership resolution and
+ * Memoised per context object: ownership resolution and
  * cache-key fingerprints call this 2-3× per linted patch, and each call
  * used to re-run `detectNewFilesInDiff` over EVERY queue entry's diff.
  * Keyed weakly so a discarded context frees its map; a caller that

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

@@ -4,7 +4,7 @@
  * `patch-lint-cross.ts` (at the per-file line budget). Re-exported from
  * there so callers keep importing from `patch-lint.ts` unchanged.
  *
- * Memoised per context object (FORGE J1): ownership resolution and
+ * Memoised per context object: ownership resolution and
  * cache-key fingerprints call this 2-3× per linted patch, and each call
  * used to re-run `detectNewFilesInDiff` over EVERY queue entry's diff.
  * Keyed weakly so a discarded context frees its map; a caller that

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

@@ -62,7 +62,7 @@ export interface PatchQueueContext {
      * Optional patchPolicy config. When present, the forward-import rule
      * validates its "Closest legal ordinal" suggestion against the importing
      * patch's category range and suppresses it when no legal ordinal exists
-     * (FORGE F14). Absent = current behavior (hint always printed).
+     *. Absent = current behavior (hint always printed).
      */
     patchPolicy?: PatchPolicyConfig;
 }

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

@@ -85,7 +85,7 @@ export async function buildPatchQueueContext(patchesDir, config) {
 }
 // The creators map (split out of `lintPatchQueueDuplicateCreations` so
 // `status --ownership` can consume the structured data) lives in
-// `patch-lint-creators.ts` with its per-context memoisation (FORGE J1);
+// `patch-lint-creators.ts` with its per-context memoisation;
 // re-exported here so callers keep importing from `patch-lint.ts`.
 export { collectNewFileCreatorsByPath, invalidateNewFileCreatorsCache, } from './patch-lint-creators.js';
 /**
@@ -276,7 +276,7 @@ export function extractImportSpecifiersWithLines(source) {
  * `modifiedFileAdditions`: a patch that inserts one property into an
  * existing getter object never carries the `defineESModuleGetters(` opener
  * in its added lines, so the balanced-brace walk in
- * {@link extractImportSpecifiersWithLines} cannot see it (FORGE F3). The
+ * {@link extractImportSpecifiersWithLines} cannot see it. The
  * URL-scheme restriction keeps ordinary object literals
  * (`label: "Foo.sys.mjs"`) out; the leaf-extension filter downstream does
  * the rest.
@@ -474,7 +474,7 @@ export function lintPatchQueueForwardImports(ctx) {
         // when the only fix is reordering. When patchPolicy is available and
         // that ordinal falls outside the importing patch's category range,
         // `patch reorder` would refuse it — suppress the hint and point at
-        // the staged-dependency remedy instead (FORGE F14).
+        // the staged-dependency remedy instead.
         const suggestedOrder = Math.max(...laterOwners.map((o) => o.order)) + 1;
         const category = entry.metadata?.category ?? /^\d+-([a-z]+)-/.exec(entry.filename)?.[1];
         let ordinalHint = `Closest legal ordinal that satisfies this dependency: ${suggestedOrder}.`;
@@ -487,7 +487,7 @@ export function lintPatchQueueForwardImports(ctx) {
                     'creating patch(es); declaring the staged dependency is the recommended remedy.';
         }
         // The exact per-owner invocation turns the refusal into a paste-and-run
-        // remedy instead of a flag-discovery exercise (FORGE F3).
+        // remedy instead of a flag-discovery exercise.
         const stagedCommands = laterOwners
             .map((o) => `fireforge patch staged-dependency ${entry.filename} --add ` +
             `--file ${sitePath} --specifier "${specifier}" ` +