@hominis/fireforge 0.43.1 → 0.44.1

package/dist/src/core/tree-store.js

@@ -13,7 +13,7 @@
  */
 import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { lstat, readdir, readFile, realpath, rm } from 'node:fs/promises';
+import { cp, lstat, mkdir, readdir, readFile, realpath, rm } from 'node:fs/promises';
 import { basename, join, resolve, sep } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
@@ -26,6 +26,7 @@ import { LOCK_PID_FILE, withFileLock } from './file-lock.js';
 import { git } from './git-base.js';
 import { getAllDiff } from './git-diff.js';
 import { attemptMozinfoRewrite } from './mach-build-artifacts.js';
+import { checkDocumentVersion, describeNewerDocument } from './state-file.js';
 import { cloneEntry } from './tree-cow.js';
 const TREE_MARKER_FILENAME = 'tree.json';
 const TREES_DIRNAME = 'trees';
@@ -56,16 +57,18 @@ export async function withTreeLifecycleLock(primaryRoot, operation) {
 /**
  * Validates every field of a tree marker.
  *
- * The read below checked only `schemaVersion` and `name` and asserted the
- * rest, but the unvalidated fields are consumed unguarded: `primaryRoot`
- * reaches a user-facing refusal message (`tree-guard.ts:105`), and
+ * Checking only `schemaVersion` and `name` and asserting the rest is not
+ * enough: the unvalidated fields are consumed unguarded. `primaryRoot`
+ * reaches a user-facing refusal message in `tree-guard.ts`, and
  * `engineHead`/`patchesFingerprint` feed the staleness compare, where an
  * `undefined` from a truncated marker reports every tree as stale.
  */
+/** Schema version this build writes and understands. */
+const TREE_MARKER_SCHEMA_VERSION = 1;
 function isTreeMarker(value) {
     if (!isObject(value))
         return false;
-    return (value['schemaVersion'] === 1 &&
+    return (value['schemaVersion'] === TREE_MARKER_SCHEMA_VERSION &&
         typeof value['name'] === 'string' &&
         typeof value['primaryRoot'] === 'string' &&
         typeof value['createdAt'] === 'string' &&
@@ -82,20 +85,39 @@ export function getTreeMarkerPath(root) {
 }
 /**
  * Reads the tree marker for a project root, distinguishing "not a tree" from
- * "a tree whose marker we could not read". Callers that make a safety decision
- * (the guard hook, the no-nesting refusal) must use this rather than
- * {@link readTreeMarker}.
+ * "a tree whose marker we could not read". Callers that make a safety
+ * decision (the guard hook, the no-nesting refusal) must use this rather
+ * than {@link tryReadTreeMarker}.
  *
  * Only ENOENT/ENOTDIR mean `absent`: any other probe failure (EACCES on the
  * `.fireforge` directory, EIO, …) reports `corrupt`, because "we cannot read
  * the marker" is not evidence that there is no marker — a `pathExists`
- * pre-check here classified a tree with an unreadable `.fireforge` as
- * `absent` and handed it the full mutating command set.
+ * pre-check classifies a tree with an unreadable `.fireforge` as `absent`
+ * and hands it the full mutating command set.
  */
-export async function readTreeMarkerState(root) {
+/**
+ * Naming convention for state-file readers:
+ *   - `readX(): Promise<XRead>` — the TRI-STATE read: absent, corrupt, or
+ *     valid.
+ *   - `tryReadX(): Promise<X | undefined>` — collapses absent and corrupt.
+ */
+export async function readTreeMarker(root) {
     const markerPath = getTreeMarkerPath(root);
     try {
         const raw = await readJson(markerPath);
+        // Version FIRST, and reported distinctly. Folding the schemaVersion
+        // check into `isTreeMarker` makes a marker from a NEWER FireForge read
+        // as "missing or mistypes a required field" — and `tree-guard.ts` is
+        // default-deny on corrupt, so the operator is locked out of every
+        // mutating command inside the tree by a message claiming the file is
+        // malformed when it is merely newer.
+        const version = checkDocumentVersion(raw, 'schemaVersion', TREE_MARKER_SCHEMA_VERSION);
+        if (version.kind === 'newer') {
+            return {
+                kind: 'unsupported',
+                reason: describeNewerDocument('tree marker', version.found, TREE_MARKER_SCHEMA_VERSION),
+            };
+        }
         if (!isTreeMarker(raw)) {
             verbose(`Malformed tree marker at ${markerPath}`);
             return { kind: 'corrupt', reason: 'the marker is missing or mistypes a required field' };
@@ -116,10 +138,10 @@ export async function readTreeMarkerState(root) {
  *
  * For display and best-effort paths only (`tree list` renders an unreadable
  * marker as staleness 'unknown'). Anything that decides whether a mutation may
- * proceed must call {@link readTreeMarkerState} and handle `corrupt`.
+ * proceed must call {@link readTreeMarker} and handle `corrupt`.
  */
-export async function readTreeMarker(root) {
-    const state = await readTreeMarkerState(root);
+export async function tryReadTreeMarker(root) {
+    const state = await readTreeMarker(root);
     return state.kind === 'valid' ? state.marker : undefined;
 }
 /**
@@ -131,7 +153,7 @@ export async function readTreeMarker(root) {
  * No-op outside a tree; a corrupt marker is already refused by the guard.
  */
 export async function assertObjdirMatchesTreeMarker(projectRoot, objDir) {
-    const state = await readTreeMarkerState(projectRoot);
+    const state = await readTreeMarker(projectRoot);
     if (state.kind !== 'valid' || state.marker.clonedObjdir === undefined)
         return;
     if (objDir !== state.marker.clonedObjdir) {
@@ -235,22 +257,21 @@ async function assertCloneSafeObjdir(engineDir, objDir, role) {
     }
 }
 /**
- * Materialises the tree at `treeRoot` from `primaryRoot` using
- * `capability` ('none' = plain copy, already gated on --force-copy by
- * the caller). The engine is cloned one TOP-LEVEL entry at a time so unwanted
- * `obj-*` directories are never traversed or materialised. That distinction
- * is substantial on Firefox trees: even CoW-cloning and deleting an objdir
- * touches metadata for millions of build outputs. With `withObjdir` exactly
- * that objdir is included — after {@link assertCloneSafeObjdir}
- * refuses symlinked or engine-escaping objdirs before any copying —
- * rewritten to the tree (see below), and
- * reconfigured in-tree via the caller-supplied `reconfigure` hook. A
- * fresh `.fireforge/` is created with only `state.json` (when present),
- * the last-build baseline (withObjdir only), and the tree marker.
+ * Materialises the tree at `treeRoot` from `primaryRoot` using `capability`
+ * ('none' = plain copy, already gated on --force-copy by the caller).
+ *
+ * The engine is cloned one TOP-LEVEL entry at a time so unwanted `obj-*`
+ * directories are never traversed or materialised — on a Firefox tree, even
+ * CoW-cloning and then deleting an objdir touches metadata for millions of
+ * build outputs. With `withObjdir` exactly that objdir is included (after
+ * {@link assertCloneSafeObjdir} refuses symlinked or engine-escaping objdirs
+ * before any copying), rewritten to the tree, and reconfigured in-tree via
+ * the caller-supplied `reconfigure` hook. A fresh `.fireforge/` is created
+ * with only `state.json` (when present), the last-build baseline (withObjdir
+ * only), and the tree marker.
  */
 export async function cloneTree(args) {
     const { primaryRoot, treeRoot, name, capability, createdAt, withObjdir } = args;
-    const { mkdir, cp } = await import('node:fs/promises');
     if (withObjdir) {
         // Refuse a symlinked/escaping primary objdir BEFORE any copying: the
         // clone would carry the symlink and every later write would land in
@@ -303,7 +324,7 @@ export async function cloneTree(args) {
     }
     const { engineHead, engineFingerprint, patchesFingerprint } = await computePrimaryFingerprint(primaryRoot);
     const marker = {
-        schemaVersion: 1,
+        schemaVersion: TREE_MARKER_SCHEMA_VERSION,
         name,
         primaryRoot,
         createdAt,
@@ -352,7 +373,7 @@ export async function listTrees(primaryRoot) {
         if (name.endsWith('.lock'))
             continue;
         const path = join(treesDir, name);
-        const marker = await readTreeMarker(path);
+        const marker = await tryReadTreeMarker(path);
         if (!marker) {
             entries.push({ name, path, createdAt: '(no marker)', staleness: 'unknown' });
             continue;
@@ -376,19 +397,19 @@ export async function listTrees(primaryRoot) {
  * file-lock internals.
  *
  * Liveness comes from the shared {@link isProcessAlive}, which treats EPERM
- * as alive. The local copy this replaced returned `false` for EPERM, so a
- * tree whose build lock was held by a live process running under a different
- * uid passed the guard below and was `rm -rf`'d mid-build.
+ * as alive. Returning `false` for EPERM lets a tree whose build lock is held
+ * by a live process running under a different uid pass the guard below and
+ * get `rm -rf`'d mid-build.
  *
- * The `unknown` state is not a theoretical case. `withFileLock` takes the lock
- * by creating the directory and only *then* writes the owner file, treating a
- * write failure as non-fatal — so every acquisition passes through a window in
- * which the lock is genuinely held and has no readable PID, and a read-only or
- * full filesystem leaves it that way for the lock's whole life. Reporting that
- * as `free` let `removeTree` recursively delete a tree out from under a live
- * build. `file-lock.ts` reaches the same conclusion for its own stale
- * recovery, where an unreadable PID falls back to an age-only heuristic rather
- * than assuming the lock is abandoned.
+ * The `unknown` state is not theoretical. `withFileLock` takes the lock by
+ * creating the directory and only *then* writes the owner file, treating a
+ * write failure as non-fatal — so every acquisition passes through a window
+ * in which the lock is genuinely held and has no readable PID, and a
+ * read-only or full filesystem leaves it that way for the lock's whole life.
+ * Reporting that as `free` lets `removeTree` recursively delete a tree out
+ * from under a live build. `file-lock.ts` reaches the same conclusion for
+ * its own stale recovery, where an unreadable PID falls back to an age-only
+ * heuristic rather than assuming the lock is abandoned.
  */
 async function inspectTreeLock(lockPath) {
     if (!existsSync(lockPath))
@@ -422,7 +443,11 @@ async function inspectTreeLock(lockPath) {
  */
 export async function removeTree(primaryRoot, name, options = {}) {
     assertValidTreeName(name);
-    const treesDir = getTreesDir(primaryRoot);
+    // Both sides resolved: the containment prefix has to be in the same form as
+    // the path it guards. `getTreesDir` is a `join`, so on Windows it yields a
+    // drive-less path while `resolve` below adds the drive letter — the prefix
+    // test then failed for EVERY tree and refused each removal as an escape.
+    const treesDir = resolve(getTreesDir(primaryRoot));
     const treeRoot = resolve(treesDir, name);
     if (!treeRoot.startsWith(treesDir + sep) || basename(treeRoot) !== name) {
         throw new GeneralError(`Refusing to remove "${name}": resolved path escapes the trees directory.`);

package/dist/src/core/typecheck-shim.d.ts

@@ -40,13 +40,12 @@ export declare const TEST_HARNESS_SHIM = "\n// \u2500\u2500 FireForge test-harne
 export declare const SUPPRESSED_DIAGNOSTIC_CODES: ReadonlySet<number>;
 /**
  * Undefined-free-identifier codes, split out of
- * {@link SUPPRESSED_DIAGNOSTIC_CODES}. Unconditional
- * suppression let a module reference a name with no import or declaration
- * anywhere and still typecheck with 0 errors — the failure then surfaced
- * as a runtime `ReferenceError`. Both flows now report these at a
- * configurable severity (default `'warning'`: visible without breaking
- * gates; genuine shim gaps are silenced by adding the global to
- * `extraShim`, or per-run via the `'off'` setting).
+ * {@link SUPPRESSED_DIAGNOSTIC_CODES}. Suppressing them unconditionally lets
+ * a module reference a name with no import or declaration anywhere and still
+ * typecheck with 0 errors, so the failure surfaces as a runtime
+ * `ReferenceError`. Both flows report these at a configurable severity
+ * (default `'warning'`: visible without breaking gates; genuine shim gaps
+ * are silenced by adding the global to `extraShim`, or per-run via `'off'`).
  */
 export declare const UNDEFINED_IDENTIFIER_CODES: ReadonlySet<number>;
 /** Hint appended to reported undefined-identifier diagnostics. */
@@ -61,25 +60,25 @@ export interface ComposedShim {
     extraShimAppended: boolean;
 }
 /**
- * Composes the synthetic shim source by concatenating the built-in
- * Firefox globals shim with the contents of an optional user-supplied
- * `.d.ts` file. The user file is appended verbatim — the augment
- * direction is intentional (declarations later in concat order
- * augment earlier ones), so a project that wants to refine `Services`
- * with a more specific type can do so by declaring it in the extra
- * shim, and members can be ADDED to the structured globals by merging
- * their interfaces (`interface ChromeUtilsShim { newMember(): any }` —
- * see the module doc comment). Any triple-slash
- * `/// <reference path="…">` directives inside the
- * extra shim are inlined (resolved against the extra shim's own directory)
- * so they are not silently dropped at the synthetic shim path.
+ * Composes the synthetic shim source by concatenating the built-in Firefox
+ * globals shim with the contents of an optional user-supplied `.d.ts` file.
+ * The user file is appended verbatim — the augment direction is intentional
+ * (declarations later in concat order augment earlier ones), so a project
+ * that wants to refine `Services` with a more specific type can do so in the
+ * extra shim, and members can be ADDED to the structured globals by merging
+ * their interfaces (`interface ChromeUtilsShim { newMember(): any }` — see
+ * the module doc comment). Any triple-slash `/// <reference path="…">`
+ * directives inside the extra shim are inlined (resolved against the extra
+ * shim's own directory) so they are not silently dropped at the synthetic
+ * shim path.
  *
- * Missing extra-shim files raise a clear error rather than failing
- * silently with a confusing "type not found" downstream — this is the
- * one config-driven path where a user typo in `fireforge.json`
- * produces a runtime error, so it needs to be unmistakable.
+ * Missing extra-shim files raise a clear error rather than failing silently
+ * with a confusing "type not found" downstream — this is the one
+ * config-driven path where a user typo in `fireforge.json` produces a
+ * runtime error, so it needs to be unmistakable.
  *
- * @param projectRoot - Absolute project root, used to resolve the relative shim path
+ * @param projectRoot - Absolute project root, used to resolve the relative
+ *   shim path
  * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
  */
 export declare function composeShimSource(projectRoot: string, extraShimPath: string | undefined): Promise<ComposedShim>;

package/dist/src/core/typecheck-shim.js

@@ -189,13 +189,12 @@ export const SUPPRESSED_DIAGNOSTIC_CODES = new Set([
 ]);
 /**
  * Undefined-free-identifier codes, split out of
- * {@link SUPPRESSED_DIAGNOSTIC_CODES}. Unconditional
- * suppression let a module reference a name with no import or declaration
- * anywhere and still typecheck with 0 errors — the failure then surfaced
- * as a runtime `ReferenceError`. Both flows now report these at a
- * configurable severity (default `'warning'`: visible without breaking
- * gates; genuine shim gaps are silenced by adding the global to
- * `extraShim`, or per-run via the `'off'` setting).
+ * {@link SUPPRESSED_DIAGNOSTIC_CODES}. Suppressing them unconditionally lets
+ * a module reference a name with no import or declaration anywhere and still
+ * typecheck with 0 errors, so the failure surfaces as a runtime
+ * `ReferenceError`. Both flows report these at a configurable severity
+ * (default `'warning'`: visible without breaking gates; genuine shim gaps
+ * are silenced by adding the global to `extraShim`, or per-run via `'off'`).
  */
 export const UNDEFINED_IDENTIFIER_CODES = new Set([
     2304, // Cannot find name '{0}'.
@@ -242,25 +241,25 @@ async function inlineTripleSlashReferences(source, baseDir, seen) {
     return out.join('\n');
 }
 /**
- * Composes the synthetic shim source by concatenating the built-in
- * Firefox globals shim with the contents of an optional user-supplied
- * `.d.ts` file. The user file is appended verbatim — the augment
- * direction is intentional (declarations later in concat order
- * augment earlier ones), so a project that wants to refine `Services`
- * with a more specific type can do so by declaring it in the extra
- * shim, and members can be ADDED to the structured globals by merging
- * their interfaces (`interface ChromeUtilsShim { newMember(): any }` —
- * see the module doc comment). Any triple-slash
- * `/// <reference path="…">` directives inside the
- * extra shim are inlined (resolved against the extra shim's own directory)
- * so they are not silently dropped at the synthetic shim path.
+ * Composes the synthetic shim source by concatenating the built-in Firefox
+ * globals shim with the contents of an optional user-supplied `.d.ts` file.
+ * The user file is appended verbatim — the augment direction is intentional
+ * (declarations later in concat order augment earlier ones), so a project
+ * that wants to refine `Services` with a more specific type can do so in the
+ * extra shim, and members can be ADDED to the structured globals by merging
+ * their interfaces (`interface ChromeUtilsShim { newMember(): any }` — see
+ * the module doc comment). Any triple-slash `/// <reference path="…">`
+ * directives inside the extra shim are inlined (resolved against the extra
+ * shim's own directory) so they are not silently dropped at the synthetic
+ * shim path.
  *
- * Missing extra-shim files raise a clear error rather than failing
- * silently with a confusing "type not found" downstream — this is the
- * one config-driven path where a user typo in `fireforge.json`
- * produces a runtime error, so it needs to be unmistakable.
+ * Missing extra-shim files raise a clear error rather than failing silently
+ * with a confusing "type not found" downstream — this is the one
+ * config-driven path where a user typo in `fireforge.json` produces a
+ * runtime error, so it needs to be unmistakable.
  *
- * @param projectRoot - Absolute project root, used to resolve the relative shim path
+ * @param projectRoot - Absolute project root, used to resolve the relative
+ *   shim path
  * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
  */
 export async function composeShimSource(projectRoot, extraShimPath) {

package/dist/src/core/typecheck.js

@@ -22,6 +22,7 @@ import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
 /**
  * Sentinel string surfaced as a `TypecheckIssue.message` when the
@@ -89,8 +90,8 @@ export async function runTypecheck(projectRoot, cfg) {
     // override (a path, or `null` to opt out) when present, else the shared
     // top-level extraShim. A project that narrows `lib`/`types` can opt out of
     // a Gecko-lib shim hub that another project needs, so the composed shim is
-    // no longer injected identically everywhere. Compositions are cached by the
-    // resolved extraShim path so projects sharing a shim don't recompose it.
+    // not injected identically everywhere. Compositions are cached by the
+    // resolved extraShim path so projects sharing a shim do not recompose it.
     const shimCache = new Map();
     const composeForProject = async (extraShim) => {
         const key = extraShim ?? '';
@@ -222,12 +223,12 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
         noEmit: true,
         allowJs: parsed.options.allowJs ?? true,
         checkJs: parsed.options.checkJs ?? true,
-        // No incremental sidecar, ever. A user jsconfig under `engine/` that
-        // sets `incremental` (or names a `tsBuildInfoFile`)
-        // would have this command drop a `.tsbuildinfo` inside the primary
-        // engine checkout — a second writer that invalidates a concurrent
-        // `fireforge test`'s engine fingerprint. This command emits nothing,
-        // so the sidecar buys nothing either.
+        // No incremental sidecar, ever. A user jsconfig under `engine/` that sets
+        // `incremental` (or names a `tsBuildInfoFile`) would have this command
+        // drop a `.tsbuildinfo` inside the primary engine checkout — a second
+        // writer that invalidates a concurrent `fireforge test`'s engine
+        // fingerprint. This command emits nothing, so the sidecar buys nothing
+        // either.
         incremental: false,
         // skipLibCheck is not forced; the user owns it via their jsconfig.
     };
@@ -239,7 +240,12 @@ async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource,
     // file — and never write it to disk. The CompilerHost below serves
     // it from `shimSource` for `fileExists`/`readFile`/`getSourceFile`.
     const projectDir = dirname(absConfig);
-    const shimPath = resolve(projectDir, `.fireforge-${SHIM_FILENAME}`);
+    // Forward slashes deliberately: TypeScript normalizes every `fileName` it
+    // hands a CompilerHost, on every platform. A shim path carrying Windows
+    // separators never matches those callbacks, so the shim is not served (its
+    // globals report as undefined identifiers) and its own diagnostics are not
+    // filtered out below — the pass reports failures that do not exist.
+    const shimPath = normalizePathSlashes(resolve(projectDir, `.fireforge-${SHIM_FILENAME}`));
     const rootFiles = [...parsed.fileNames, shimPath];
     const defaultHost = ts.createCompilerHost(options);
     const host = {

package/dist/src/core/wire-destroy.d.ts

@@ -5,9 +5,9 @@
  * AST-based implementation: finds onUnload()/uninit() method body and
  * inserts the destroy block at the top (LIFO ordering).
  *
- * `marker` is prefixed to the generated comment so wire-generated
- * edits carry the patch-lint `// <MARKER>:` signature
- * `lintModificationComments` looks for (eval 1 Finding #9).
+ * `marker` is prefixed to the generated comment so wire-generated edits
+ * carry the patch-lint `// <MARKER>:` signature `lintModificationComments`
+ * looks for.
  */
 export declare function addDestroyAST(content: string, expression: string, marker?: string): string;
 /**

package/dist/src/core/wire-destroy.js

@@ -9,7 +9,7 @@ import { BuildError } from '../errors/build.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { escapeRegex } from '../utils/regex.js';
 import { asEstree, detectIndent, parseScript } from './ast-utils.js';
-import { withParserFallback } from './parser-fallback.js';
+import { isInternalInvariantFailure, withParserFallback } from './parser-fallback.js';
 import { assertBraceBalancePreserved, coerceToCall, extractNameFromExpression, findMethodBody, findMethodBraceIndex, validateWireName, } from './wire-utils.js';
 const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
 const DEFAULT_MARKER = 'FIREFORGE:';
@@ -17,9 +17,9 @@ const DEFAULT_MARKER = 'FIREFORGE:';
  * AST-based implementation: finds onUnload()/uninit() method body and
  * inserts the destroy block at the top (LIFO ordering).
  *
- * `marker` is prefixed to the generated comment so wire-generated
- * edits carry the patch-lint `// <MARKER>:` signature
- * `lintModificationComments` looks for (eval 1 Finding #9).
+ * `marker` is prefixed to the generated comment so wire-generated edits
+ * carry the patch-lint `// <MARKER>:` signature `lintModificationComments`
+ * looks for.
  */
 export function addDestroyAST(content, expression, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);
@@ -110,22 +110,14 @@ export async function addDestroyToBrowserInit(engineDir, expression, marker = DE
     const content = await readText(filePath);
     // Idempotency check — look for the coerced (call) form because that is
     // what the emitter writes. Matching against the raw input would miss a
-    // previous `EvalStartup.destroy` invocation that the 0.16.0 coercion
-    // already persisted as `EvalStartup.destroy()`.
+    // bare `X.destroy` invocation that coercion already persisted as
+    // `X.destroy()`.
     const callExpression = coerceToCall(expression);
     const destroyPattern = new RegExp(`(?:^|\\W)${escapeRegex(callExpression)}\\s*;?\\s*$`, 'm');
     if (destroyPattern.test(content)) {
         return false;
     }
-    const { value, usedFallback } = withParserFallback(() => addDestroyAST(content, expression, marker), () => legacyAddDestroy(content, expression, marker), BROWSER_INIT_JS, 
-    // Rethrow only the internal-invariant GeneralErrors ("Unexpected empty
-    // …array"): those are programming bugs, and retrying the legacy scanner
-    // cannot fix a broken invariant — it just buries the stack. Everything
-    // else still falls back, which is load-bearing: the AST path raises a raw
-    // acorn SyntaxError on chrome sources acorn cannot parse (preprocessor
-    // directives), and BuildError when the file's shape is unexpected. Both
-    // are exactly what the legacy scanner is here to handle.
-    (error) => error instanceof GeneralError);
+    const { value, usedFallback } = withParserFallback(() => addDestroyAST(content, expression, marker), () => legacyAddDestroy(content, expression, marker), BROWSER_INIT_JS, isInternalInvariantFailure);
     if (usedFallback) {
         assertBraceBalancePreserved(content, value, BROWSER_INIT_JS);
     }

package/dist/src/core/wire-dom-fragment.d.ts

@@ -13,24 +13,16 @@ export declare const DEFAULT_DOM_TARGET = "browser/base/content/browser.xhtml";
  */
 export declare function addDomFragmentTokenized(content: string, includeDirective: string): string;
 /**
- * Legacy line-based implementation preserved as fallback.
- */
-export declare function legacyAddDomFragment(content: string, includeDirective: string): string;
-/**
- * Dry-run precheck for `addDomFragment`. Reads the resolved chrome
- * document and verifies it either already contains the `#include`
- * directive (the idempotent-skip case) OR offers a locatable insertion
- * point via {@link addDomFragmentTokenized} / {@link legacyAddDomFragment}.
- * Throws the same `Could not find insertion point in chrome document`
- * error the real run would throw when neither condition holds.
+ * Dry-run precheck for `addDomFragment`. Reads the resolved chrome document
+ * and verifies it either already contains the `#include` directive (the
+ * idempotent-skip case) OR offers a locatable insertion point via
+ * {@link addDomFragmentTokenized} / {@link legacyAddDomFragment}. Throws the
+ * same `Could not find insertion point in chrome document` error the real
+ * run would throw when neither condition holds.
  *
- * Motivating case (2026-04-21 eval, Finding #12): `fireforge wire ...
- * --dry-run` previewed a plausible mutation plan against
- * `tokenHostDocuments[0]`, then `fireforge wire ...` without
- * `--dry-run` threw `Could not find insertion point in chrome document`
- * on the same arguments. The real run had always called the insertion
- * helpers; dry-run did not. This helper runs the same check in the
- * preview pass so plan and execution disagree less.
+ * Without it, `wire --dry-run` previews a plausible mutation plan while the
+ * real run throws on the same arguments, because only the real run called
+ * the insertion helpers.
  */
 export declare function probeDomFragmentInsertionPoint(engineDir: string, domFilePath: string, targetPath?: string): Promise<void>;
 /**

package/dist/src/core/wire-dom-fragment.js

@@ -13,7 +13,6 @@ import { GeneralError } from '../errors/base.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { toRootRelativePath } from '../utils/paths.js';
 import { escapeRegex } from '../utils/regex.js';
-import { withParserFallback } from './parser-fallback.js';
 import { tokenizeXhtml } from './wire-utils.js';
 export const DEFAULT_DOM_TARGET = 'browser/base/content/browser.xhtml';
 /**
@@ -48,48 +47,16 @@ export function addDomFragmentTokenized(content, includeDirective) {
     return lines.join('\n');
 }
 /**
- * Legacy line-based implementation preserved as fallback.
- */
-export function legacyAddDomFragment(content, includeDirective) {
-    const lines = content.split('\n');
-    let insertIndex = -1;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (/browser-sets\.inc/.test(line)) {
-            insertIndex = i;
-            break;
-        }
-    }
-    if (insertIndex === -1) {
-        for (let i = 0; i < lines.length; i++) {
-            const line = lines[i] ?? '';
-            if (/<html:body/.test(line)) {
-                insertIndex = i + 1;
-                break;
-            }
-        }
-    }
-    if (insertIndex === -1) {
-        throw new GeneralError('Could not find insertion point in chrome document');
-    }
-    lines.splice(insertIndex, 0, includeDirective);
-    return lines.join('\n');
-}
-/**
- * Dry-run precheck for `addDomFragment`. Reads the resolved chrome
- * document and verifies it either already contains the `#include`
- * directive (the idempotent-skip case) OR offers a locatable insertion
- * point via {@link addDomFragmentTokenized} / {@link legacyAddDomFragment}.
- * Throws the same `Could not find insertion point in chrome document`
- * error the real run would throw when neither condition holds.
+ * Dry-run precheck for `addDomFragment`. Reads the resolved chrome document
+ * and verifies it either already contains the `#include` directive (the
+ * idempotent-skip case) OR offers a locatable insertion point via
+ * {@link addDomFragmentTokenized} / {@link legacyAddDomFragment}. Throws the
+ * same `Could not find insertion point in chrome document` error the real
+ * run would throw when neither condition holds.
  *
- * Motivating case (2026-04-21 eval, Finding #12): `fireforge wire ...
- * --dry-run` previewed a plausible mutation plan against
- * `tokenHostDocuments[0]`, then `fireforge wire ...` without
- * `--dry-run` threw `Could not find insertion point in chrome document`
- * on the same arguments. The real run had always called the insertion
- * helpers; dry-run did not. This helper runs the same check in the
- * preview pass so plan and execution disagree less.
+ * Without it, `wire --dry-run` previews a plausible mutation plan while the
+ * real run throws on the same arguments, because only the real run called
+ * the insertion helpers.
  */
 export async function probeDomFragmentInsertionPoint(engineDir, domFilePath, targetPath = DEFAULT_DOM_TARGET) {
     const targetAbsPath = join(engineDir, targetPath);
@@ -113,7 +80,7 @@ export async function probeDomFragmentInsertionPoint(engineDir, domFilePath, tar
     // Check the tokenised and legacy insertion paths symmetrically with
     // the real run. Either helper returning without throwing is sufficient
     // evidence that the real run can land the directive.
-    withParserFallback(() => addDomFragmentTokenized(content, includeDirective), () => legacyAddDomFragment(content, includeDirective), targetPath);
+    addDomFragmentTokenized(content, includeDirective);
 }
 /**
  * Inserts a `#include` directive for an `.inc.xhtml` file into the top-level
@@ -177,7 +144,7 @@ export async function addDomFragment(engineDir, domFilePath, targetPath = DEFAUL
         }
     }
     // Normal insertion
-    const { value } = withParserFallback(() => addDomFragmentTokenized(content, includeDirective), () => legacyAddDomFragment(content, includeDirective), targetPath);
+    const value = addDomFragmentTokenized(content, includeDirective);
     await writeText(targetAbsPath, value);
     return true;
 }

package/dist/src/core/wire-init.d.ts

@@ -8,9 +8,8 @@
  *
  * `marker` is prepended (uppercased) to the generated comment line so the
  * emitted block carries the patch-lint `// <MARKER>:` signature that
- * `lintModificationComments` looks for. Otherwise the first export after
- * `wire` trips `missing-modification-comment` on wire-generated edits —
- * exactly the eval 1 Finding #9 regression.
+ * `lintModificationComments` looks for; otherwise the first export after
+ * `wire` trips `missing-modification-comment` on wire-generated edits.
  */
 export declare function addInitAST(content: string, expression: string, after?: string, marker?: string): string;
 /**