@hominis/fireforge 0.34.2 → 0.36.0

package/dist/src/core/furnace-apply.js

@@ -13,6 +13,7 @@ import { resolveFurnaceMarkerComment } from './furnace-marker.js';
 import { recordFurnaceRollbackFailure } from './furnace-operation.js';
 import { addJarMnEntries, removeCustomElementRegistration, removeJarMnEntries, } from './furnace-registration.js';
 import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotFile, } from './furnace-rollback.js';
+import { blockingStepErrors, hasBlockingStepErrors } from './furnace-step-errors.js';
 import { runPostApplyConsistencyChecks } from './furnace-validate-registration.js';
 export { computeComponentChecksums, extractComponentChecksums, hasComponentChanged, hasCustomEngineDrift, hasOverrideEngineDrift, prefixChecksums, } from './furnace-apply-helpers.js';
 function addMissingComponentError(result, name, directoryPath) {
@@ -29,7 +30,9 @@ function buildOverrideUndeployActions(name, config, engineDir, deletedFiles, ftl
         description: `Restore engine/${fileName.endsWith('.ftl') ? `${ftlDir}/${fileName}` : `${config.basePath}/${fileName}`} to Firefox baseline`,
     }));
 }
-async function applyOverrideBatch(config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName) {
+async function applyOverrideBatch(ctx) {
+    const { config, furnacePaths, state, engineDir, ftlDir, dryRun } = ctx;
+    const { result, allActions, newChecksums, rollbackJournal, componentName } = ctx;
     const overrideEntries = Object.entries(config.overrides).filter(([name]) => !componentName || name === componentName);
     const totalOverrides = overrideEntries.length;
     let overrideIndex = 0;
@@ -162,7 +165,9 @@ async function reconcileCustomRegistrationAfterUndeploy(engineDir, name, config,
         filesAffected.push(CUSTOM_ELEMENTS_JS);
     }
 }
-async function applyCustomBatch(root, config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName, markerComment) {
+async function applyCustomBatch(ctx, root, markerComment) {
+    const { config, furnacePaths, state, engineDir, ftlDir, dryRun } = ctx;
+    const { result, allActions, newChecksums, rollbackJournal, componentName } = ctx;
     const allKnown = new Set([
         ...config.stock,
         ...Object.keys(config.overrides),
@@ -251,7 +256,7 @@ async function applyCustomBatch(root, config, furnacePaths, state, engineDir, ft
             if (dryRun && actions) {
                 allActions.push(...actions);
             }
-            if (!dryRun && deletedFiles.length > 0 && stepErrors.length === 0) {
+            if (!dryRun && deletedFiles.length > 0 && blockingStepErrors(stepErrors).length === 0) {
                 await reconcileCustomRegistrationAfterUndeploy(engineDir, name, customConfig, deletedFiles, currentChecksums, rollbackJournal, filesAffectedTotal);
             }
             filesAffectedTotal.push(...filesAffected);
@@ -261,9 +266,11 @@ async function applyCustomBatch(root, config, furnacePaths, state, engineDir, ft
                 filesAffected: filesAffectedTotal,
                 ...(stepErrors.length > 0 ? { stepErrors } : {}),
             });
-            // Only store checksums when the component applied without step errors,
-            // so that partially failed components are re-applied on the next run.
-            if (!dryRun && stepErrors.length === 0) {
+            // Only store checksums when the component applied without BLOCKING
+            // step errors, so that partially failed components are re-applied on
+            // the next run. Advisory errors (FTL degradation) still persist —
+            // re-applying cannot fix a fork that has no locale jar.mn.
+            if (!dryRun && blockingStepErrors(stepErrors).length === 0) {
                 Object.assign(newChecksums, prefixChecksums(currentChecksums, 'custom', name));
             }
         }
@@ -338,16 +345,38 @@ export async function applyAllComponents(root, dryRun = false, options) {
             throw new FurnaceError(`Component "${componentName}" not found in furnace.json. Run "fireforge furnace list" to see registered components.`, componentName);
         }
     }
-    await applyOverrideBatch(config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName);
-    await applyCustomBatch(root, config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName, markerComment);
-    // Check for any partial failures (step errors on applied components).
-    const hasStepErrors = result.applied.some((entry) => 'stepErrors' in entry && entry.stepErrors.length > 0);
+    const batchContext = {
+        config,
+        furnacePaths,
+        state,
+        engineDir,
+        ftlDir,
+        dryRun,
+        result,
+        allActions,
+        newChecksums,
+        rollbackJournal,
+        componentName,
+    };
+    await applyOverrideBatch(batchContext);
+    await applyCustomBatch(batchContext, root, markerComment);
+    // Check for any partial failures (blocking step errors on applied
+    // components). Advisory step errors (e.g. FTL degradation) are warnings
+    // and never gate rollback.
+    const hasApplyStepErrors = result.applied.some((entry) => hasBlockingStepErrors(entry));
     // Orphaned components are implicitly cleaned up: newChecksums only
     // contains entries for components that still exist in furnace.json,
     // and it fully replaces state.appliedChecksums below.
-    if (!dryRun && !hasStepErrors && result.errors.length === 0) {
+    if (!dryRun && !hasApplyStepErrors && result.errors.length === 0) {
         await runPostApplyConsistencyChecks(root, config, result, ftlDir);
     }
+    // Recompute AFTER the consistency checks: they MUTATE entry.stepErrors
+    // when the applied output is inconsistent (e.g. a jar.mn entry that
+    // silently mis-landed). Reading the pre-check snapshot meant those
+    // failures skipped rollback and persisted checksums for a component
+    // known to be inconsistent — while the CLI simultaneously reported
+    // "failed to apply cleanly".
+    const hasStepErrors = result.applied.some((entry) => hasBlockingStepErrors(entry));
     // --- Rollback on failure, persist on success (skip for dry-run) ---
     if (!dryRun) {
         if (result.errors.length > 0 || hasStepErrors) {
@@ -386,5 +415,10 @@ export async function applyAllComponents(root, dryRun = false, options) {
         result.actions = allActions;
     }
     return result;
-}
-//# sourceMappingURL=furnace-apply.js.map
+} /**
+ * Shared context threaded through the batch apply loops. Bundles the state
+ * both loops mutate (result/actions/checksums) with the immutable run
+ * parameters — the previous 12–13 positional parameters let call sites
+ * drift (the named-apply state-wipe bug) and made every new parameter a
+ * two-signature change.
+ */

package/dist/src/core/furnace-checksum-utils.js

@@ -36,4 +36,3 @@ export function diffDeletedFiles(previous, current) {
     }
     return deleted.sort();
 }
-//# sourceMappingURL=furnace-checksum-utils.js.map

package/dist/src/core/furnace-config-array-utils.js

@@ -24,4 +24,3 @@ export function parseStringArray(value, fieldName) {
     }
     return items;
 }
-//# sourceMappingURL=furnace-config-array-utils.js.map

package/dist/src/core/furnace-config-custom.js

@@ -61,4 +61,3 @@ export function parseCustomConfig(data, name) {
         ...(sharedFtl !== undefined ? { sharedFtl } : {}),
     };
 }
-//# sourceMappingURL=furnace-config-custom.js.map

package/dist/src/core/furnace-config-order.js

@@ -83,4 +83,3 @@ export function orderFurnaceConfigForWrite(existing, config) {
     }
     return ordered;
 }
-//# sourceMappingURL=furnace-config-order.js.map

package/dist/src/core/furnace-config-tokens.js

@@ -40,4 +40,3 @@ export function validateRuntimeVariables(raw) {
         }
     }
 }
-//# sourceMappingURL=furnace-config-tokens.js.map

package/dist/src/core/furnace-config-validate.js

@@ -130,4 +130,3 @@ export function applyOptionalFurnaceFields(migrated, config) {
         config.scanPaths = paths;
     }
 }
-//# sourceMappingURL=furnace-config-validate.js.map

package/dist/src/core/furnace-config.d.ts

@@ -46,6 +46,17 @@ export declare function validateFurnaceConfig(data: unknown): FurnaceConfig;
  * @throws Error if config doesn't exist or is invalid
  */
 export declare function loadFurnaceConfig(root: string): Promise<FurnaceConfig>;
+/**
+ * Clears applied furnace state while preserving `pendingRepair`.
+ *
+ * Used whenever the engine baseline is replaced or reset (download --force,
+ * reset, rebase, rebase --abort): every applied checksum describes content
+ * that no longer exists, but pendingRepair tracks authoring-side rollback
+ * issues in the component WORKSPACE and must survive an engine refresh.
+ * No-ops when the state file does not exist. Centralized because the same
+ * reset logic had drifted into four separate command files.
+ */
+export declare function clearAppliedFurnaceState(root: string): Promise<void>;
 /**
  * Writes a furnace configuration to furnace.json.
  * @param root - Root directory of the project

package/dist/src/core/furnace-config.js

@@ -122,6 +122,25 @@ export function validateFurnaceConfig(data) {
     detectComposesCycles(custom);
     // Validate that every composes reference points to a known component.
     validateComposesReferences(stock, overrides, custom);
+    // Warn when two custom components share a targetPath. Nothing technically
+    // prevents co-location, but per-component removal and orphan detection
+    // both reason about "files this component deployed into its directory" —
+    // shared directories make those judgements ambiguous, and historically a
+    // shared targetPath meant `furnace remove` of one component deleted the
+    // other's deployed files.
+    const targetPathOwners = new Map();
+    for (const [name, custom_] of Object.entries(custom)) {
+        const owners = targetPathOwners.get(custom_.targetPath) ?? [];
+        owners.push(name);
+        targetPathOwners.set(custom_.targetPath, owners);
+    }
+    for (const [targetPath, owners] of targetPathOwners) {
+        if (owners.length > 1) {
+            warn(`furnace.json: custom components ${owners.join(', ')} share targetPath "${targetPath}". ` +
+                'Give each component its own directory — shared directories make per-component ' +
+                'removal and drift detection ambiguous.');
+        }
+    }
     const config = {
         version: CURRENT_CONFIG_VERSION,
         componentPrefix: migrated['componentPrefix'],
@@ -308,6 +327,24 @@ export async function loadFurnaceConfig(root) {
         throw new FurnaceError(`Invalid furnace.json at ${paths.furnaceConfig}: ${toError(error).message}`);
     }
 }
+/**
+ * Clears applied furnace state while preserving `pendingRepair`.
+ *
+ * Used whenever the engine baseline is replaced or reset (download --force,
+ * reset, rebase, rebase --abort): every applied checksum describes content
+ * that no longer exists, but pendingRepair tracks authoring-side rollback
+ * issues in the component WORKSPACE and must survive an engine refresh.
+ * No-ops when the state file does not exist. Centralized because the same
+ * reset logic had drifted into four separate command files.
+ */
+export async function clearAppliedFurnaceState(root) {
+    const paths = getFurnacePaths(root);
+    if (!(await pathExists(paths.furnaceState)))
+        return;
+    await updateFurnaceState(root, (current) => ({
+        ...(current.pendingRepair ? { pendingRepair: current.pendingRepair } : {}),
+    }));
+}
 /**
  * Writes a furnace configuration to furnace.json.
  * @param root - Root directory of the project
@@ -500,4 +537,3 @@ export async function collectFurnaceManagedPrefixes(root) {
     prefixes.add(FURNACE_STORYBOOK_STORIES_PREFIX);
     return prefixes;
 }
-//# sourceMappingURL=furnace-config.js.map

package/dist/src/core/furnace-constants.js

@@ -87,4 +87,3 @@ export function stripComponentPrefix(tagName, componentPrefix) {
     }
     return tagName;
 }
-//# sourceMappingURL=furnace-constants.js.map

package/dist/src/core/furnace-css-fragments.js

@@ -240,4 +240,3 @@ export async function validateCssFragments(componentDir, tagName, sharedDir, eng
     }
     return issues;
 }
-//# sourceMappingURL=furnace-css-fragments.js.map

package/dist/src/core/furnace-graph-utils.js

@@ -91,4 +91,3 @@ export function topologicalSortCustom(custom) {
     }
     return sorted;
 }
-//# sourceMappingURL=furnace-graph-utils.js.map

package/dist/src/core/furnace-jsconfig.d.ts

@@ -38,9 +38,8 @@ export interface JsconfigSyncResult {
  * writing.
  *
  * The consumer owns the jsconfig file: a missing file is an error with
- * guidance rather than a silent scaffold, and JSONC (comments/trailing
- * commas) is unsupported for the managed file — `readJson` is a strict
- * JSON parser, so the error message says so explicitly.
+ * guidance rather than a silent scaffold. JSONC comments and trailing commas
+ * are preserved; Furnace edits only `compilerOptions.paths`.
  *
  * @param root - Project root directory
  * @param config - Loaded Furnace configuration (must carry `typecheckJsconfig`)

package/dist/src/core/furnace-jsconfig.js

@@ -22,8 +22,9 @@
  */
 import { readdir } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';
+import { applyEdits, modify, parse } from 'jsonc-parser';
 import { FurnaceError } from '../errors/furnace.js';
-import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { pathExists, readText, writeTextIfChanged } from '../utils/fs.js';
 import { info } from '../utils/logger.js';
 import { normalizePathSlashes } from '../utils/paths.js';
 import { getFurnacePaths } from './furnace-config.js';
@@ -89,9 +90,8 @@ function isManagedEntry(key, value, jsconfigDir, customDir) {
  * writing.
  *
  * The consumer owns the jsconfig file: a missing file is an error with
- * guidance rather than a silent scaffold, and JSONC (comments/trailing
- * commas) is unsupported for the managed file — `readJson` is a strict
- * JSON parser, so the error message says so explicitly.
+ * guidance rather than a silent scaffold. JSONC comments and trailing commas
+ * are preserved; Furnace edits only `compilerOptions.paths`.
  *
  * @param root - Project root directory
  * @param config - Loaded Furnace configuration (must carry `typecheckJsconfig`)
@@ -109,19 +109,31 @@ export async function syncFurnaceJsconfigPaths(root, config, options) {
             `"compilerOptions.paths" entries under ${CHROME_ELEMENTS_URL_PREFIX}*), ` +
             'or remove the setting.');
     }
+    const jsconfigText = await readText(jsconfigAbs);
+    const parseErrors = [];
     let jsconfig;
     try {
-        jsconfig = await readJson(jsconfigAbs);
+        jsconfig = parse(jsconfigText, parseErrors, {
+            allowTrailingComma: true,
+            disallowComments: false,
+        });
     }
     catch (error) {
-        throw new FurnaceError(`Could not parse ${jsconfigRel} as JSON: ${error instanceof Error ? error.message : String(error)}. ` +
-            'Furnace manages paths entries only in plain-JSON jsconfig files — JSONC comments ' +
-            'and trailing commas are not supported for the managed file.');
+        throw new FurnaceError(`Could not parse ${jsconfigRel} as JSONC: ${error instanceof Error ? error.message : String(error)}.`);
     }
+    if (parseErrors.length > 0 ||
+        typeof jsconfig !== 'object' ||
+        jsconfig === null ||
+        Array.isArray(jsconfig)) {
+        throw new FurnaceError(`Could not parse ${jsconfigRel} as JSONC: expected an object jsconfig file.`);
+    }
+    const jsconfigObject = jsconfig;
     const furnacePaths = getFurnacePaths(root);
     const desired = await computeDesiredChromePathEntries(config, furnacePaths.customDir, jsconfigAbs);
     const jsconfigDir = dirname(jsconfigAbs);
-    const currentPaths = { ...(jsconfig.compilerOptions?.paths ?? {}) };
+    const currentPaths = {
+        ...(jsconfigObject.compilerOptions?.paths ?? {}),
+    };
     const nextPaths = {};
     // Preserve every unmanaged entry verbatim; prune managed entries that are
     // no longer desired; update managed entries whose target moved.
@@ -156,14 +168,10 @@ export async function syncFurnaceJsconfigPaths(root, config, options) {
     result.changed = result.added.length > 0 || result.updated.length > 0 || result.pruned.length > 0;
     if (!result.changed || options?.dryRun === true)
         return result;
-    const nextJsconfig = {
-        ...jsconfig,
-        compilerOptions: {
-            ...(jsconfig.compilerOptions ?? {}),
-            paths: nextPaths,
-        },
-    };
-    await writeJson(jsconfigAbs, nextJsconfig);
+    const edits = modify(jsconfigText, ['compilerOptions', 'paths'], nextPaths, {
+        formattingOptions: { insertSpaces: true, tabSize: 2, eol: '\n' },
+    });
+    await writeTextIfChanged(jsconfigAbs, applyEdits(jsconfigText, edits));
     return result;
 }
 /**
@@ -188,4 +196,3 @@ export async function reportJsconfigPathsSync(root, config, dryRun) {
     info(`${dryRun ? '[dry-run] Would update' : 'Updated'} ${config.typecheckJsconfig} chrome-module paths: ` +
         `+${sync.added.length} added, ~${sync.updated.length} updated, -${sync.pruned.length} pruned`);
 }
-//# sourceMappingURL=furnace-jsconfig.js.map

package/dist/src/core/furnace-marker.js

@@ -20,4 +20,3 @@ export function resolveFurnaceMarkerComment(forgeConfig) {
         return forgeConfig.binaryName.toUpperCase();
     return undefined;
 }
-//# sourceMappingURL=furnace-marker.js.map

package/dist/src/core/furnace-operation.js

@@ -252,4 +252,3 @@ export function __resetFurnaceOperationStateForTests() {
     nextOperationToken = 1;
     signalRollbackInFlight = false;
 }
-//# sourceMappingURL=furnace-operation.js.map

package/dist/src/core/furnace-refresh.js

@@ -126,4 +126,3 @@ export async function refreshOverrideFile(engineDir, overridePath, engineRelPath
     }
     return { fileName, status: 'merged' };
 }
-//# sourceMappingURL=furnace-refresh.js.map

package/dist/src/core/furnace-registration-ast.d.ts

@@ -2,6 +2,20 @@
  * AST-based custom element registration updates for customElements.js.
  * Removal logic is in furnace-registration-remove.ts.
  */
+/**
+ * Returns true when `content` already contains a registration for `tagName`.
+ *
+ * Tolerates trailing line comments (e.g. a project marker like `// MYBROWSER:`)
+ * that an operator may have appended to entries written by a previous apply.
+ * Without this, a re-apply would insert a duplicate entry, and the second
+ * `setElementCreationCallback` at window-load would throw `NotSupportedError`.
+ *
+ * Matches any of:
+ *   1. `setElementCreationCallback("tag"` / `setElementCreationCallback('tag'`
+ *   2. Single-line array entry: `["tag", "..."]` — column 0 only, comments allowed after
+ *   3. Multi-line array entry: `"tag",` on its own line, optional trailing `//` comment
+ */
+export declare function isTagAlreadyRegistered(content: string, tagName: string): boolean;
 /**
  * Options that shape the lines `addCustomElementRegistration` writes into
  * `customElements.js`. Kept optional so existing call sites keep working.

package/dist/src/core/furnace-registration-ast.js

@@ -26,7 +26,7 @@ import { validateRegistrationPlacement, validateTagName } from './furnace-regist
  *   2. Single-line array entry: `["tag", "..."]` — column 0 only, comments allowed after
  *   3. Multi-line array entry: `"tag",` on its own line, optional trailing `//` comment
  */
-function isTagAlreadyRegistered(content, tagName) {
+export function isTagAlreadyRegistered(content, tagName) {
     const escaped = escapeRegex(tagName);
     if (content.includes(`setElementCreationCallback("${tagName}"`) ||
         content.includes(`setElementCreationCallback('${tagName}'`)) {
@@ -403,4 +403,3 @@ export async function validateCustomElementRegistration(engineDir, tagName, modu
         addRegistrationRegexFallback(content, tagName, modulePath, isESModule);
     }
 }
-//# sourceMappingURL=furnace-registration-ast.js.map

package/dist/src/core/furnace-registration-remove.js

@@ -220,4 +220,3 @@ export async function removeCustomElementRegistration(engineDir, tagName) {
         await writeText(filePath, next);
     }
 }
-//# sourceMappingURL=furnace-registration-remove.js.map

package/dist/src/core/furnace-registration-validate.js

@@ -4,7 +4,7 @@
  * Used after both AST and legacy code paths to avoid duplicating logic.
  */
 import { FurnaceError } from '../errors/furnace.js';
-import { stripJsComments } from '../utils/regex.js';
+import { escapeRegex, stripJsComments } from '../utils/regex.js';
 /**
  * Regex for valid custom element tag names. A valid name is lowercase, starts
  * with a letter, and contains one or more hyphen-separated groups where each
@@ -88,7 +88,3 @@ function isTagInArrayConsumedInsideDOMContentLoaded(content, domContentLoadedIdx
     }
     return false;
 }
-function escapeRegex(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-//# sourceMappingURL=furnace-registration-validate.js.map

package/dist/src/core/furnace-registration.js

@@ -324,4 +324,3 @@ export async function validateJarMnInsertionForFiles(engineDir, tagName, files)
         throw new FurnaceError('Could not find a content/global/ section in jar.mn for element entries. The file may be malformed.', tagName);
     }
 }
-//# sourceMappingURL=furnace-registration.js.map

package/dist/src/core/furnace-rollback.js

@@ -134,4 +134,3 @@ export async function restoreRollbackJournalOrThrow(journal, context) {
         throw new FurnaceError(`${context}; automatic rollback failed: ${message}`);
     }
 }
-//# sourceMappingURL=furnace-rollback.js.map

package/dist/src/core/furnace-scanner.js

@@ -237,4 +237,3 @@ export async function isComponentInEngine(engineDir, tagName) {
     const componentDir = join(engineDir, WIDGETS_DIR, tagName);
     return pathExists(componentDir);
 }
-//# sourceMappingURL=furnace-scanner.js.map

package/dist/src/core/furnace-staleness.js

@@ -55,4 +55,3 @@ export async function warnIfFurnaceStale(projectRoot) {
         verbose('Furnace staleness check skipped due to an error.');
     }
 }
-//# sourceMappingURL=furnace-staleness.js.map

package/dist/src/core/furnace-state-persist.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Single-component furnace state persistence.
+ *
+ * There are exactly two sanctioned ways checksums land in
+ * furnace-state.json:
+ *
+ *  1. The BATCH path inside `applyAllComponents` (persistState: true),
+ *     which replaces `appliedChecksums` wholesale — correct only when the
+ *     run covered every component.
+ *  2. The per-component MERGE in this module, which rewrites only the
+ *     `<type>/<name>/…` keys of the component that was applied.
+ *
+ * Every targeted (named) apply/deploy MUST use path 2 with
+ * `persistState: false`. Routing a named run through the batch path wipes
+ * every other component's checksum state: the batch loops filter to the
+ * named component, so the wholesale replace persists a state file
+ * containing only that component. Downstream, `diffDeletedFiles` and
+ * `findOrphanedEngineFiles` both key on `appliedChecksums`, so the wiped
+ * components' stale engine files become undetectable by apply AND by
+ * `furnace validate` (2026-07-05 review, finding F1 — `furnace apply
+ * <name>` had exactly this bug while `furnace deploy <name>` documented
+ * and avoided it).
+ */
+import { type applyAllComponents } from './furnace-apply.js';
+import { type getFurnacePaths } from './furnace-config.js';
+type ApplyAllResult = Awaited<ReturnType<typeof applyAllComponents>>;
+/**
+ * Counts applied entries that carry at least one BLOCKING step error
+ * (advisory step errors are warnings and never fail a run).
+ */
+export declare function getStepFailureCount(result: ApplyAllResult): number;
+/**
+ * Decides whether a single-component apply/deploy completed cleanly enough
+ * to persist its checksums into furnace-state.json.
+ *
+ * Named runs are atomic: if any apply step fails, the rollback journal
+ * restores the engine to its pre-run state and this helper returns `false`
+ * so state is not touched. The conditions must stay in lock-step with the
+ * rollback trigger in `applyAllComponents` — both read step errors, so a
+ * future refactor cannot drift them apart and accidentally persist partial
+ * state.
+ */
+export declare function shouldPersistSingleComponentState(result: ApplyAllResult, isDryRun: boolean): boolean;
+/**
+ * Validates and narrows the applied entry a named run should persist.
+ *
+ * Guards against future refactors that might reorder or misroute the
+ * applied[] array: a named run persists state under a single component
+ * name, so the first applied entry MUST be that component. Persisting a
+ * different component's checksums would cause the next status/apply run to
+ * mis-report health for both components involved.
+ *
+ * @param commandLabel - Human label for error messages ("Deploy", "Apply")
+ */
+export declare function getPersistableAppliedEntry(commandLabel: string, name: string, appliedEntry: ApplyAllResult['applied'][number] | undefined): {
+    name: string;
+    type: 'override' | 'custom';
+};
+/**
+ * Persists checksum state for a successfully applied named component by
+ * MERGING its `<type>/<name>/…` keys into the existing state — never
+ * replacing the whole map.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param appliedEntry - Applied component descriptor
+ * @param furnacePaths - Resolved Furnace workspace paths
+ */
+export declare function persistSingleComponentState(projectRoot: string, appliedEntry: {
+    name: string;
+    type: 'override' | 'custom';
+}, furnacePaths: ReturnType<typeof getFurnacePaths>): Promise<void>;
+export {};

package/dist/src/core/furnace-state-persist.js

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Single-component furnace state persistence.
+ *
+ * There are exactly two sanctioned ways checksums land in
+ * furnace-state.json:
+ *
+ *  1. The BATCH path inside `applyAllComponents` (persistState: true),
+ *     which replaces `appliedChecksums` wholesale — correct only when the
+ *     run covered every component.
+ *  2. The per-component MERGE in this module, which rewrites only the
+ *     `<type>/<name>/…` keys of the component that was applied.
+ *
+ * Every targeted (named) apply/deploy MUST use path 2 with
+ * `persistState: false`. Routing a named run through the batch path wipes
+ * every other component's checksum state: the batch loops filter to the
+ * named component, so the wholesale replace persists a state file
+ * containing only that component. Downstream, `diffDeletedFiles` and
+ * `findOrphanedEngineFiles` both key on `appliedChecksums`, so the wiped
+ * components' stale engine files become undetectable by apply AND by
+ * `furnace validate` (2026-07-05 review, finding F1 — `furnace apply
+ * <name>` had exactly this bug while `furnace deploy <name>` documented
+ * and avoided it).
+ */
+import { join } from 'node:path';
+import { FurnaceError } from '../errors/furnace.js';
+import { computeComponentChecksums, prefixChecksums, } from './furnace-apply.js';
+import { updateFurnaceState } from './furnace-config.js';
+import { countEntriesWithBlockingStepErrors } from './furnace-step-errors.js';
+/**
+ * Counts applied entries that carry at least one BLOCKING step error
+ * (advisory step errors are warnings and never fail a run).
+ */
+export function getStepFailureCount(result) {
+    return countEntriesWithBlockingStepErrors(result.applied);
+}
+/**
+ * Decides whether a single-component apply/deploy completed cleanly enough
+ * to persist its checksums into furnace-state.json.
+ *
+ * Named runs are atomic: if any apply step fails, the rollback journal
+ * restores the engine to its pre-run state and this helper returns `false`
+ * so state is not touched. The conditions must stay in lock-step with the
+ * rollback trigger in `applyAllComponents` — both read step errors, so a
+ * future refactor cannot drift them apart and accidentally persist partial
+ * state.
+ */
+export function shouldPersistSingleComponentState(result, isDryRun) {
+    if (isDryRun)
+        return false;
+    if (result.errors.length > 0)
+        return false;
+    if (getStepFailureCount(result) > 0)
+        return false;
+    return result.applied.length > 0;
+}
+/**
+ * Validates and narrows the applied entry a named run should persist.
+ *
+ * Guards against future refactors that might reorder or misroute the
+ * applied[] array: a named run persists state under a single component
+ * name, so the first applied entry MUST be that component. Persisting a
+ * different component's checksums would cause the next status/apply run to
+ * mis-report health for both components involved.
+ *
+ * @param commandLabel - Human label for error messages ("Deploy", "Apply")
+ */
+export function getPersistableAppliedEntry(commandLabel, name, appliedEntry) {
+    if (!appliedEntry) {
+        throw new FurnaceError(`${commandLabel} for "${name}" finished without producing an applied component entry; ` +
+            `furnace state was not modified. Run "fireforge doctor --repair-furnace" to ` +
+            `reconcile state, then retry. If this persists, file a bug with the ` +
+            `output of "fireforge doctor".`);
+    }
+    if (appliedEntry.type !== 'override' && appliedEntry.type !== 'custom') {
+        throw new FurnaceError(`${commandLabel} for "${name}" returned an unsupported component type "${appliedEntry.type}"; ` +
+            `furnace state was not modified. Run "fireforge doctor --repair-furnace" to reconcile, ` +
+            `then verify the component with "fireforge furnace validate" before retrying.`);
+    }
+    if (appliedEntry.name !== name) {
+        throw new FurnaceError(`${commandLabel} for "${name}" returned an applied entry for a different component ` +
+            `("${appliedEntry.name}"); refusing to persist mismatched state. ` +
+            `Run "fireforge doctor --repair-furnace" to reconcile, then retry.`);
+    }
+    return {
+        name: appliedEntry.name,
+        type: appliedEntry.type,
+    };
+}
+/**
+ * Persists checksum state for a successfully applied named component by
+ * MERGING its `<type>/<name>/…` keys into the existing state — never
+ * replacing the whole map.
+ *
+ * @param projectRoot - Root directory of the project
+ * @param appliedEntry - Applied component descriptor
+ * @param furnacePaths - Resolved Furnace workspace paths
+ */
+export async function persistSingleComponentState(projectRoot, appliedEntry, furnacePaths) {
+    const componentDir = appliedEntry.type === 'override'
+        ? join(furnacePaths.overridesDir, appliedEntry.name)
+        : join(furnacePaths.customDir, appliedEntry.name);
+    const checksums = await computeComponentChecksums(componentDir);
+    const prefixed = prefixChecksums(checksums, appliedEntry.type, appliedEntry.name);
+    const componentPrefix = `${appliedEntry.type}/${appliedEntry.name}/`;
+    await updateFurnaceState(projectRoot, (current) => ({
+        ...current,
+        appliedChecksums: {
+            ...Object.fromEntries(Object.entries(current.appliedChecksums ?? {}).filter(([key]) => !key.startsWith(componentPrefix))),
+            ...prefixed,
+        },
+        engineChecksums: {
+            ...Object.fromEntries(Object.entries(current.engineChecksums ?? {}).filter(([key]) => !key.startsWith(componentPrefix))),
+            ...prefixed,
+        },
+        lastApply: new Date().toISOString(),
+    }));
+}