@hominis/fireforge 0.49.1 → 0.50.0

package/dist/src/core/test-run-completeness.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The exit-0 completeness veto for `fireforge test`.
+ *
+ * `classifyHarnessRun` trusts a mach exit code of 0 once any test started.
+ * That is wrong for one shape a downstream fork hit: the browser shut down
+ * cleanly inside the 105th of 314 files ("Application shut down (without
+ * crashing) in the middle of a test!"), nothing after it ran, mach still
+ * exited 0, and the verdict read `PASS checks=7919 unexpected=1`. The
+ * truncation checks the classifier already applies to a non-zero exit with
+ * a green-looking summary never ran, because the exit code short-circuited
+ * them.
+ *
+ * So a would-be pass is re-examined here against three facts the captured
+ * output carries: a non-zero `Unexpected results:` count, the harness's
+ * mid-test shutdown line, and requested test files that never produced a
+ * start marker. Any one of them turns the run into
+ * `FAIL reason=test-failures`, and a short start count is stamped on the
+ * verdict line as `started=<n>/<m> first-unstarted=<path>`.
+ *
+ * The start-count check only runs when at least one start marker names a
+ * requested file. The suite-specific xpcshell dispatch can prove execution
+ * with a result-summary block alone and print no `TEST_START` line, and a
+ * run that never names its files cannot be counted against them.
+ */
+import { type HarnessRunVerdict } from './test-harness-crash.js';
+import type { IncompleteRunEvidence } from './test-harness-signature.js';
+/**
+ * Counts the requested test files that produced a start or skip marker.
+ * Returns undefined when nothing can be counted: no test-file-shaped
+ * request, or no start line that names any requested file.
+ *
+ * @param output - Captured mach stdout and stderr
+ * @param requestedPaths - Dispatched paths, in dispatch order
+ */
+export declare function countStartedFiles(output: string, requestedPaths: readonly string[]): {
+    started: number;
+    requested: number;
+    firstUnstarted?: string;
+} | undefined;
+/**
+ * Re-examines a passing verdict for a mach exit-0 run and fails it when
+ * the run is incomplete or reported unexpected results. Any other verdict
+ * is returned unchanged.
+ *
+ * @param verdict - The classifier's verdict
+ * @param output - Captured mach stdout and stderr
+ * @param requestedPaths - Dispatched paths, in dispatch order
+ */
+export declare function vetoIncompletePass(verdict: HarnessRunVerdict, output: string, requestedPaths: readonly string[]): HarnessRunVerdict;
+/**
+ * Operator-facing explanation for a pass {@link vetoIncompletePass}
+ * refused. Names the first file that never started, because that is
+ * where a re-run has to pick up.
+ *
+ * @param evidence - The veto's evidence
+ */
+export declare function buildIncompleteRunMessage(evidence: IncompleteRunEvidence): string;

package/dist/src/core/test-run-completeness.js

@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The exit-0 completeness veto for `fireforge test`.
+ *
+ * `classifyHarnessRun` trusts a mach exit code of 0 once any test started.
+ * That is wrong for one shape a downstream fork hit: the browser shut down
+ * cleanly inside the 105th of 314 files ("Application shut down (without
+ * crashing) in the middle of a test!"), nothing after it ran, mach still
+ * exited 0, and the verdict read `PASS checks=7919 unexpected=1`. The
+ * truncation checks the classifier already applies to a non-zero exit with
+ * a green-looking summary never ran, because the exit code short-circuited
+ * them.
+ *
+ * So a would-be pass is re-examined here against three facts the captured
+ * output carries: a non-zero `Unexpected results:` count, the harness's
+ * mid-test shutdown line, and requested test files that never produced a
+ * start marker. Any one of them turns the run into
+ * `FAIL reason=test-failures`, and a short start count is stamped on the
+ * verdict line as `started=<n>/<m> first-unstarted=<path>`.
+ *
+ * The start-count check only runs when at least one start marker names a
+ * requested file. The suite-specific xpcshell dispatch can prove execution
+ * with a result-summary block alone and print no `TEST_START` line, and a
+ * run that never names its files cannot be counted against them.
+ */
+import { SHUTDOWN_REENTRY_PATTERN, START_MARKER_PATTERN, TEST_FILE_BASENAME_PATTERN, } from './test-harness-crash.js';
+/**
+ * A skip marker naming a test (`TEST-SKIP | path`, `TEST_SKIP: path`). A
+ * manifest-skipped file is accounted for, not missing.
+ */
+const SKIP_MARKER_PATTERN = /\bTEST[-_]SKIP(?:PED)?\b[:| ]*\s*(\S+)?/;
+/** Basename of a `/`-separated path. */
+function basenameOf(path) {
+    return path.slice(path.lastIndexOf('/') + 1);
+}
+/**
+ * Counts the requested test files that produced a start or skip marker.
+ * Returns undefined when nothing can be counted: no test-file-shaped
+ * request, or no start line that names any requested file.
+ *
+ * @param output - Captured mach stdout and stderr
+ * @param requestedPaths - Dispatched paths, in dispatch order
+ */
+export function countStartedFiles(output, requestedPaths) {
+    const requested = requestedPaths.filter((path) => TEST_FILE_BASENAME_PATTERN.test(basenameOf(path)));
+    if (requested.length === 0)
+        return undefined;
+    const started = [];
+    const skipped = [];
+    for (const line of output.split(/\r?\n/)) {
+        const start = START_MARKER_PATTERN.exec(line)?.[1];
+        if (start !== undefined) {
+            started.push(start);
+            continue;
+        }
+        const skip = SKIP_MARKER_PATTERN.exec(line)?.[1];
+        if (skip !== undefined)
+            skipped.push(skip);
+    }
+    const names = (path, list) => {
+        const base = basenameOf(path);
+        return list.some((name) => name.includes(base));
+    };
+    // Counting needs a dialect that names the requested files on its start
+    // lines. When no start line names any of them, the output cannot be
+    // counted against the request at all.
+    if (!requested.some((path) => names(path, started)))
+        return undefined;
+    const unstarted = requested.filter((path) => !names(path, started) && !names(path, skipped));
+    const firstUnstarted = unstarted[0];
+    return {
+        started: requested.length - unstarted.length,
+        requested: requested.length,
+        ...(firstUnstarted !== undefined ? { firstUnstarted } : {}),
+    };
+}
+/**
+ * Re-examines a passing verdict for a mach exit-0 run and fails it when
+ * the run is incomplete or reported unexpected results. Any other verdict
+ * is returned unchanged.
+ *
+ * @param verdict - The classifier's verdict
+ * @param output - Captured mach stdout and stderr
+ * @param requestedPaths - Dispatched paths, in dispatch order
+ */
+export function vetoIncompletePass(verdict, output, requestedPaths) {
+    if (verdict.kind !== 'tests-ran-ok')
+        return verdict;
+    const shutdownLine = output
+        .split(/\r?\n/)
+        .find((line) => SHUTDOWN_REENTRY_PATTERN.test(line))
+        ?.trim();
+    const counted = countStartedFiles(output, requestedPaths);
+    const unexpected = verdict.unexpected ?? 0;
+    const truncated = counted?.firstUnstarted !== undefined;
+    if (unexpected === 0 && shutdownLine === undefined && !truncated)
+        return verdict;
+    const evidence = {
+        started: counted?.started ?? 0,
+        requested: counted?.requested ?? 0,
+        ...(counted?.firstUnstarted !== undefined ? { firstUnstarted: counted.firstUnstarted } : {}),
+        ...(shutdownLine !== undefined ? { shutdownLine } : {}),
+        ...(unexpected > 0 ? { unexpected } : {}),
+    };
+    // The pass-only annotations would misdescribe a failed run: "harness
+    // teardown noise ignored" and the green-summary override both say the
+    // run was trusted.
+    const rest = { ...verdict };
+    delete rest.greenSummaryOverride;
+    delete rest.note;
+    return {
+        ...rest,
+        kind: 'test-failures',
+        incomplete: evidence,
+        ...(shutdownLine !== undefined ? { realFailureLine: shutdownLine } : {}),
+    };
+}
+/**
+ * Operator-facing explanation for a pass {@link vetoIncompletePass}
+ * refused. Names the first file that never started, because that is
+ * where a re-run has to pick up.
+ *
+ * @param evidence - The veto's evidence
+ */
+export function buildIncompleteRunMessage(evidence) {
+    const lines = [];
+    if (evidence.firstUnstarted !== undefined) {
+        lines.push(`  - only ${evidence.started} of ${evidence.requested} requested test files started; ` +
+            `the first that never started is ${evidence.firstUnstarted}`);
+    }
+    if (evidence.shutdownLine !== undefined) {
+        lines.push(`  - the browser shut down in the middle of a test: ${evidence.shutdownLine}`);
+    }
+    if (evidence.unexpected !== undefined) {
+        lines.push(`  - the suite summary reported ${evidence.unexpected} unexpected result(s)`);
+    }
+    const rerun = evidence.firstUnstarted !== undefined
+        ? `Re-run from ${evidence.firstUnstarted} onward, or the whole selection once the engine is quiet.`
+        : 'Read the unexpected results in the output above.';
+    return ('mach exited 0, but FireForge did NOT treat the run as passed:\n\n' +
+        `${lines.join('\n')}\n\n` +
+        'A browser that quits cleanly mid-suite exits 0, and its summary then covers only the ' +
+        `files that ran. ${rerun}`);
+}

package/dist/src/core/test-stale-check.d.ts

@@ -1,4 +1,5 @@
 import type { BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
+import { type StaleExemption } from './test-stale-exempt.js';
 /** Result of the stale-build preflight probe. */
 export interface StaleBuildResult {
     /** True when at least one packageable engine file changed since the baseline. */
@@ -22,6 +23,13 @@ export interface StaleBuildResult {
      * we have nothing to compare against and a warning would mislead.
      */
     baseline: BuildBaseline | undefined;
+    /**
+     * Changed packageable paths the packaged runtime already serves (objdir
+     * symlinks to the edited source, test files restaged at dispatch), which
+     * therefore do not make the build stale. Named in the refusal and in a
+     * notice so the exemption is visible.
+     */
+    exempt?: StaleExemption[];
 }
 /**
  * Probes the engine tree for packageable changes since the last successful
@@ -79,15 +87,33 @@ export declare function findUncoveredRequestPaths(coverage: TestPackagingCoverag
  *   {@link STALE_PATHS_LIMIT}
  */
 export declare function findChangedTestManifestsForPaths(engineDir: string, baseline: BuildBaseline | undefined, uncovered: readonly string[]): Promise<string[]>;
+/** Extra evidence for {@link formatTestCoverageRefusal}. */
+export interface CoverageRefusalDetail {
+    /**
+     * Per uncovered path, the staging inputs that changed since the full
+     * build the recorded claim carries forward (what the replaced coverage
+     * affects).
+     */
+    changedInputs?: Readonly<Record<string, readonly string[]>>;
+    /** The record carries a full build's anchor forward for unchanged paths. */
+    carriesFullAnchor?: boolean;
+}
 /**
+ * Formats the refusal shown when a non-`--build` run requests paths the
+ * packaged runtime's scoped `test --build` coverage does not include. It is
+ * enforced on every such run, with or without `--allow-stale-build`. Kept
+ * separate from the matcher so tests can pin structure and copy
+ * independently (same split as {@link formatStaleBuildWarning}).
+ *
  * @param uncovered - Request paths the recorded packaging does not cover
  * @param coverage - The recorded scoped coverage claim
  * @param changedManifests - Test manifests changed since the recorded
  *   build that explain an uncovered path (from
  *   {@link findChangedTestManifestsForPaths}). Omitted or empty renders
  *   nothing
+ * @param detail - See {@link CoverageRefusalDetail}
  */
-export declare function formatTestCoverageRefusal(uncovered: string[], coverage: string[], changedManifests?: readonly string[]): string;
+export declare function formatTestCoverageRefusal(uncovered: string[], coverage: string[], changedManifests?: readonly string[], detail?: CoverageRefusalDetail): string;
 /** Result of the compiled-StaticComponents staleness probe. */
 export interface StaticComponentsStaleResult {
     /** True when at least one `components.conf` genuinely diverged from the anchor. */

package/dist/src/core/test-stale-check.js

@@ -28,7 +28,9 @@ import { normalizePathSlashes } from '../utils/paths.js';
 import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
 import { readBuildBaseline } from './build-baseline.js';
 import { hashEngineFile } from './coverage-extend.js';
+import { isTestManifestPath } from './coverage-records.js';
 import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
+import { formatStaleExemptions, partitionStaleCandidates, } from './test-stale-exempt.js';
 /** Cap on the number of changed paths rendered inline. */
 const STALE_PATHS_LIMIT = 10;
 /**
@@ -61,12 +63,15 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
     // fingerprints capture "these files had this content when the build ran".
     // A path stays stale only when its live hash diverges.
     packageable = await dropPathsMatchingFingerprints(engineDir, packageable, baseline.packageableFingerprints);
-    if (packageable.length === 0) {
-        return { stale: false, changedPaths: [], truncated: 0, baseline };
+    // Edits the runtime already serves (symlinked into the objdir, or test
+    // files `mach test` restages at dispatch) cannot make the packaging stale.
+    const { stale, exempt } = await partitionStaleCandidates(engineDir, packageable);
+    if (stale.length === 0) {
+        return { stale: false, changedPaths: [], truncated: 0, baseline, exempt };
     }
-    const head = packageable.slice(0, STALE_PATHS_LIMIT);
-    const truncated = Math.max(0, packageable.length - head.length);
-    return { stale: true, changedPaths: head, truncated, baseline };
+    const head = stale.slice(0, STALE_PATHS_LIMIT);
+    const truncated = Math.max(0, stale.length - head.length);
+    return { stale: true, changedPaths: head, truncated, baseline, exempt };
 }
 /**
  * Formats a human-readable warning body from a {@link StaleBuildResult}.
@@ -76,10 +81,15 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
 export function formatStaleBuildWarning(result) {
     const tail = result.truncated > 0 ? `, … (+${result.truncated} more)` : '';
     const list = result.changedPaths.join(', ') + tail;
+    const exempt = result.exempt ?? [];
+    const exemptLine = exempt.length > 0
+        ? `\nNot counted as stale, because the runtime already serves them: ${formatStaleExemptions(exempt)}.`
+        : '';
     return (`Engine tree has changed since the last successful fireforge build (${list}).\n` +
         'The current obj-*/dist/ bundle may not reflect those edits. If your test reads ' +
         'packaged chrome / jar.mn resources, rerun with "fireforge test --build" (or ' +
-        '"fireforge build --ui") first. Passing --build skips this check.');
+        '"fireforge build --ui") first. Passing --build skips this check.' +
+        exemptLine);
 }
 /**
  * Sentinel returned by {@link findUncoveredRequestPaths} when a full-suite
@@ -120,37 +130,6 @@ export function findUncoveredRequestPaths(coverage, requestedPaths) {
 function normalizeCoveragePath(path) {
     return normalizePathSlashes(path.trim()).replace(/\/+$/, '');
 }
-/**
- * Formats the refusal shown when a non-`--build` run requests paths the
- * packaged runtime's scoped `test --build` coverage does not include. It is
- * enforced on every such run, with or without `--allow-stale-build`. Kept
- * separate from the matcher so tests can pin structure and copy
- * independently (same split as {@link formatStaleBuildWarning}).
- */
-/**
- * Basenames of the test manifests whose entries decide what a packaged test
- * runtime stages. A manifest that gained an entry is the single most common
- * reason a run needs coverage the last build never claimed, and it is a
- * fact FireForge already holds but never said, leaving the operator to
- * rediscover it after a correct refusal.
- */
-const TEST_MANIFEST_BASENAMES = new Set([
-    'xpcshell.toml',
-    'xpcshell.ini',
-    'browser.toml',
-    'browser.ini',
-    'mochitest.toml',
-    'mochitest.ini',
-    'chrome.toml',
-    'chrome.ini',
-    'a11y.toml',
-    'a11y.ini',
-]);
-/** True for a test manifest path (by basename). */
-function isTestManifestPath(path) {
-    const base = path.slice(path.lastIndexOf('/') + 1);
-    return TEST_MANIFEST_BASENAMES.has(base);
-}
 /**
  * Test manifests changed since the recorded build that sit in (or above)
  * the directory of an uncovered request path, i.e. the manifests that
@@ -185,31 +164,35 @@ export async function findChangedTestManifestsForPaths(engineDir, baseline, unco
     return hits.slice(0, STALE_PATHS_LIMIT);
 }
 /**
+ * Formats the refusal shown when a non-`--build` run requests paths the
+ * packaged runtime's scoped `test --build` coverage does not include. It is
+ * enforced on every such run, with or without `--allow-stale-build`. Kept
+ * separate from the matcher so tests can pin structure and copy
+ * independently (same split as {@link formatStaleBuildWarning}).
+ *
  * @param uncovered - Request paths the recorded packaging does not cover
  * @param coverage - The recorded scoped coverage claim
  * @param changedManifests - Test manifests changed since the recorded
  *   build that explain an uncovered path (from
  *   {@link findChangedTestManifestsForPaths}). Omitted or empty renders
  *   nothing
+ * @param detail - See {@link CoverageRefusalDetail}
  */
-export function formatTestCoverageRefusal(uncovered, coverage, changedManifests = []) {
+export function formatTestCoverageRefusal(uncovered, coverage, changedManifests = [], detail = {}) {
     const cap = (paths) => {
         const head = paths.slice(0, STALE_PATHS_LIMIT);
         const truncated = paths.length - head.length;
         return head.join(', ') + (truncated > 0 ? `, … (+${truncated} more)` : '');
     };
     const rebuildTargets = uncovered.filter((p) => p !== FULL_SUITE_REQUEST);
-    // Name --extend-coverage here or it is undiscoverable: a scoped build
-    // replaces the claim, so under several concurrent sessions a peer's build
-    // for an unrelated path erases coverage you legitimately still hold, and
-    // the union that fixes it is a flag the operator has no reason to know
-    // exists at the moment they need it. The anchor conditions are stated
-    // because they are what decides whether it will work.
-    const extendHint = rebuildTargets.length > 0
-        ? ` Add --extend-coverage to that rebuild to UNION the new paths onto the recorded claim instead of replacing it — it holds while engine HEAD and engine/mozconfig are unchanged since the recorded build.`
+    // Per-path retention is the default, so rebuilding only the uncovered
+    // paths no longer costs anyone else's claim. Saying so is what keeps a
+    // peer from rebuilding everything "to be safe".
+    const keepHint = rebuildTargets.length > 0
+        ? ' That scoped build keeps every other recorded path whose own staging inputs (manifest directory and the fixtures its manifest names) and engine/mozconfig are unchanged.'
         : '';
     const rebuildHint = rebuildTargets.length > 0
-        ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them, or run "fireforge build" for full coverage.${extendHint}`
+        ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them (or "fireforge test --build-only ..." to package without running), or run "fireforge build" for full coverage.${keepHint}`
         : 'Run "fireforge build" (or a path-less "fireforge test --build") for full coverage first.';
     // Why this run needs new coverage, when a changed manifest explains it: a
     // manifest that gained an entry is not covered by a build claim recorded
@@ -217,10 +200,17 @@ export function formatTestCoverageRefusal(uncovered, coverage, changedManifests
     const manifestLine = changedManifests.length > 0
         ? ` This run needs coverage the recorded build never claimed because a test manifest changed since it: ${changedManifests.map((m) => `engine/${m}`).join(', ')} — a manifest that gained an entry stages new support fixtures, and a claim recorded for other paths (or another harness) does not cover them.`
         : '';
-    return (`The packaged test runtime was produced by a scoped "fireforge test --build" covering only: ${cap(coverage)}.\n` +
+    const affected = Object.entries(detail.changedInputs ?? {}).filter(([, files]) => files.length > 0);
+    const affectedLine = affected.length > 0
+        ? ` Staging inputs changed since the full build this record carries forward: ${affected.map(([path, files]) => `${path} (${cap(files)})`).join('; ')}.`
+        : '';
+    const scope = detail.carriesFullAnchor
+        ? `${cap(coverage)}, plus earlier full coverage for paths whose own staging inputs are unchanged`
+        : cap(coverage);
+    return (`The packaged test runtime was produced by a scoped "fireforge test --build" covering only: ${scope}.\n` +
         `The requested run needs ${cap(uncovered)}, which that packaging does not cover — support ` +
         'fixtures for those manifests may be missing from obj-*/_tests/, and the run can hang ' +
-        `rather than fail.${manifestLine} ${rebuildHint} ` +
+        `rather than fail.${affectedLine}${manifestLine} ${rebuildHint} ` +
         '(--allow-stale-build does not bypass this check — it accepts stale content, not missing coverage.)');
 }
 /**

package/dist/src/core/test-stale-exempt.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Edits the stale-build preflight must not count. A test file the build
+ * never packages is restaged by `mach test` at dispatch, and a file whose
+ * every objdir copy is a symlink back to the edited source is already what
+ * the runtime reads. Refusing on either made every iteration on a test (or
+ * on symlinked chrome) pay a packaging pass or reach for
+ * `--allow-stale-build`, the flag whose refusal text says not to.
+ */
+import { type InstallManifestIndex } from './objdir-install-manifests.js';
+/** A changed path the preflight does not count as stale, and why. */
+export interface StaleExemption {
+    path: string;
+    /**
+     * `symlinked`: every objdir copy is a symlink to the edited source.
+     * `test-only`: a test file the build does not package, restaged at dispatch.
+     */
+    why: 'symlinked' | 'test-only';
+}
+/** The single `obj-*` directory under the engine, or undefined when zero or several exist. */
+export declare function findSingleObjDir(engineDir: string): Promise<string | undefined>;
+/**
+ * The objdir's install-manifest index, or undefined when there is no single
+ * objdir or nothing in it is readable.
+ * @param engineDir - Absolute engine directory
+ */
+export declare function loadEngineInstallIndex(engineDir: string): Promise<InstallManifestIndex | undefined>;
+/**
+ * Splits changed packageable paths into the ones that make the packaged
+ * runtime stale and the ones it already serves. Without a readable objdir
+ * index every path stays stale, the behaviour before the exemption existed.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param paths - Changed engine-relative paths, already fingerprint-filtered
+ */
+export declare function partitionStaleCandidates(engineDir: string, paths: readonly string[]): Promise<{
+    stale: string[];
+    exempt: StaleExemption[];
+}>;
+/** Renders exemptions for a notice or refusal: `a (symlinked), b (test file)`. */
+export declare function formatStaleExemptions(exempt: readonly StaleExemption[], limit?: number): string;

package/dist/src/core/test-stale-exempt.js

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Edits the stale-build preflight must not count. A test file the build
+ * never packages is restaged by `mach test` at dispatch, and a file whose
+ * every objdir copy is a symlink back to the edited source is already what
+ * the runtime reads. Refusing on either made every iteration on a test (or
+ * on symlinked chrome) pay a packaging pass or reach for
+ * `--allow-stale-build`, the flag whose refusal text says not to.
+ */
+import { readdir } from 'node:fs/promises';
+import { isTestPath } from './build-audit-resolve.js';
+import { classifyRuntimeDelivery, loadInstallManifestIndex, } from './objdir-install-manifests.js';
+/** The single `obj-*` directory under the engine, or undefined when zero or several exist. */
+export async function findSingleObjDir(engineDir) {
+    try {
+        const entries = await readdir(engineDir, { withFileTypes: true });
+        const objDirs = entries.filter((entry) => entry.isDirectory() && entry.name.startsWith('obj-'));
+        return objDirs.length === 1 ? objDirs[0]?.name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The objdir's install-manifest index, or undefined when there is no single
+ * objdir or nothing in it is readable.
+ * @param engineDir - Absolute engine directory
+ */
+export async function loadEngineInstallIndex(engineDir) {
+    const objDir = await findSingleObjDir(engineDir);
+    return objDir === undefined ? undefined : loadInstallManifestIndex(engineDir, objDir);
+}
+/**
+ * Splits changed packageable paths into the ones that make the packaged
+ * runtime stale and the ones it already serves. Without a readable objdir
+ * index every path stays stale, the behaviour before the exemption existed.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param paths - Changed engine-relative paths, already fingerprint-filtered
+ */
+export async function partitionStaleCandidates(engineDir, paths) {
+    if (paths.length === 0)
+        return { stale: [], exempt: [] };
+    const index = await loadEngineInstallIndex(engineDir);
+    if (index === undefined)
+        return { stale: [...paths], exempt: [] };
+    const stale = [];
+    const exempt = [];
+    for (const path of paths) {
+        const delivery = await classifyRuntimeDelivery(index, engineDir, path);
+        if (delivery === 'live')
+            exempt.push({ path, why: 'symlinked' });
+        else if (delivery === 'at-dispatch' || (delivery === 'unlisted' && isTestPath(path))) {
+            exempt.push({ path, why: 'test-only' });
+        }
+        else
+            stale.push(path);
+    }
+    return { stale, exempt };
+}
+/** Renders exemptions for a notice or refusal: `a (symlinked), b (test file)`. */
+export function formatStaleExemptions(exempt, limit = 10) {
+    const head = exempt
+        .slice(0, limit)
+        .map(({ path, why }) => why === 'symlinked'
+        ? `${path} (objdir symlink to the source)`
+        : `${path} (test file, restaged at dispatch)`);
+    const extra = exempt.length - head.length;
+    return head.join(', ') + (extra > 0 ? `, … (+${extra} more)` : '');
+}

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

@@ -0,0 +1,50 @@
+/**
+ * `fireforge token lint`: structural checks over the design-token system.
+ *
+ * - `token-lockstep`: a themed override block (the dark `@media` mirror, a
+ *   `:root[variant]` block) declares only tokens the base `:root` declares.
+ *   An override with no base is a token that exists only in one theme, so
+ *   every other theme resolves it to nothing.
+ * - `token-undeclared`: a `var(--<prefix>…)` reference in the tokens CSS or
+ *   in a CSS file the patch queue touches names a token no block of the
+ *   tokens CSS declares. Same-file declarations, `furnace.json`
+ *   `tokenAllowlist` and `runtimeVariables` are exempt, matching the
+ *   `token-prefix-violation` rule's notion of a runtime channel.
+ *
+ * Built on `token-category.ts`'s base-block and comment-mask primitives, so
+ * this report and `token add` agree on which block is the base.
+ */
+/** One `token lint` finding. */
+export interface TokenLintFinding {
+    check: 'token-lockstep' | 'token-undeclared';
+    /** Engine-relative file. */
+    file: string;
+    /** 1-based line. */
+    line: number;
+    /** The custom property at fault. */
+    token: string;
+    message: string;
+}
+/** Every custom property the tokens CSS declares, in any block. */
+export declare function collectDeclaredTokenNames(lines: string[]): Set<string>;
+/**
+ * Themed override declarations of `tokenPrefix` tokens that the base
+ * `:root` block does not declare.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param tokensCssPath - Engine-relative path, for the findings
+ * @param tokenPrefix - Only tokens with this prefix are held to lockstep;
+ *   a themed block may still override platform properties
+ */
+export declare function lintTokenLockstep(lines: string[], tokensCssPath: string, tokenPrefix: string): TokenLintFinding[];
+/**
+ * `var(--<prefix>…)` references naming a token the tokens CSS never
+ * declares.
+ *
+ * @param file - Engine-relative path, for the findings
+ * @param css - The file's content
+ * @param tokenPrefix - Only references with this prefix are checked
+ * @param declared - {@link collectDeclaredTokenNames} of the tokens CSS
+ * @param exempt - `tokenAllowlist` and `runtimeVariables` names
+ */
+export declare function lintUndeclaredTokenReferences(file: string, css: string, tokenPrefix: string, declared: ReadonlySet<string>, exempt: ReadonlySet<string>): TokenLintFinding[];