@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,21 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Marker-comment resolution shared between furnace apply and deploy.
- *
- * When `markerComment` is unset in fireforge.json, fall back to
- * `binaryName.toUpperCase()` so the patch-lint rule
- * `lintModificationComments` (which keys on `${binaryName.toUpperCase()}:`)
- * accepts furnace-emitted edits on the next `lint`/`export` round-trip. The
- * helper tolerates the undefined-config case (a project that has not run
- * `fireforge setup` yet) and the missing-binaryName case (test fixtures that
- * mock `loadConfig` with a partial shape).
- */
-export function resolveFurnaceMarkerComment(forgeConfig) {
-    if (!forgeConfig)
-        return undefined;
-    if (forgeConfig.markerComment !== undefined)
-        return forgeConfig.markerComment;
-    if (forgeConfig.binaryName)
-        return forgeConfig.binaryName.toUpperCase();
-    return undefined;
-}

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

@@ -1,195 +0,0 @@
-import type { FurnacePendingRepairOperation } from '../types/furnace.js';
-import { type RollbackJournal } from './furnace-rollback.js';
-/**
- * The signal names the lifecycle wrapper knows how to react to. Spelled out
- * as a literal union (rather than `NodeJS.Signals`) so the public type
- * surface does not depend on the NodeJS global namespace. Consumers of
- * FireForge's published scoped npm package may compile against tsconfigs
- * that omit `@types/node`.
- */
-export type FurnaceShutdownSignal = 'SIGINT' | 'SIGTERM';
-/**
- * Context handed to a furnace mutation body so it can register the in-flight
- * rollback journal with the lifecycle wrapper. The wrapper uses the registered
- * journal to perform rollback when the process receives SIGINT/SIGTERM mid-run.
- */
-export interface FurnaceOperationContext {
-    /**
-     * Registers the rollback journal for the current operation. Must be called
-     * once the body has constructed its journal so the signal handler can find
-     * it. Calling more than once replaces the prior reference (this is fine for
-     * commands that build the journal lazily).
-     */
-    registerJournal(journal: RollbackJournal): void;
-    /**
-     * Registers an extra cleanup callback to run during signal-driven teardown
-     * in addition to the journal restore. Used by `furnace preview` to make
-     * sure `cleanStories` runs even when the user hits Ctrl+C mid-run. The
-     * callback should be best-effort and idempotent: cleanup errors are
-     * collected, not re-thrown.
-     */
-    registerCleanup(cleanup: () => Promise<void>): void;
-    /**
-     * Declares that the body has already restored its own journal, so the
-     * wrapper's throw-path rollback must not restore it a second time.
-     *
-     * Bodies that catch-and-restore on their own (the `furnace/*` command
-     * bodies, `furnace-apply`) call this from their catch block after the
-     * restore, then re-throw. Without it the wrapper would restore the same
-     * journal again on the way out. That is harmless for the file writes,
-     * which are rename-based and converge, but it would race a second
-     * `pendingRepair` write against the state-file lock.
-     */
-    markRolledBack(): void;
-}
-/** Options for `runFurnaceMutation`. */
-export interface RunFurnaceMutationOptions {
-    /**
-     * If true, skip lock acquisition and signal-handler installation entirely.
-     * Used by dry-run paths where no engine mutation occurs.
-     *
-     * Note: a dry-run can overlap with a real mutation because it does not
-     * acquire the lock. This is safe because dry-runs only read. However, a
-     * dry-run that starts before a real mutation and finishes after it may
-     * observe partially-written engine state. Accept this trade-off so that
-     * concurrent dry-runs never block each other or a real apply.
-     */
-    dryRun?: boolean;
-    /**
-     * Override the default 30 s furnace-lock timeout.
-     *
-     * Set from the caller's resolved `--wait-lock` budget, so one flag governs
-     * both locks a furnace mutation takes. Before that it was declared and
-     * never passed: `furnace deploy --wait-lock 1800` waited 1800 s for the
-     * engine session lock and then met `.fireforge/furnace.lock` with a fixed
-     * 30 s, which is the worst shape a budget can have: it pays the whole
-     * wait and still refuses. Every furnace leaf that takes this lock threads
-     * its `--wait-lock` here. When absent, {@link sessionWaitLockMs} supplies
-     * the session-wide budget (`FIREFORGE_WAIT_LOCK`).
-     */
-    lockTimeoutMs?: number;
-    /**
-     * If true, skip the pendingRepair pre-flight check. Used by `doctor
-     * --repair-furnace` which must be able to mutate the engine even when a
-     * pendingRepair marker is set.
-     */
-    skipPendingRepairCheck?: boolean;
-}
-/**
- * Converts a resolved `--wait-lock` budget in seconds into the
- * {@link RunFurnaceMutationOptions} slice that applies it to the furnace
- * lock. Undefined in, empty out, so the caller can spread it
- * unconditionally without assigning `undefined` under
- * `exactOptionalPropertyTypes`.
- *
- * A helper rather than three inline spreads: the seconds-to-milliseconds
- * conversion is exactly the kind of thing that gets copied once correctly
- * and once with the factor dropped.
- *
- * @param waitLockSeconds - Resolved budget in seconds, or undefined
- * @returns `{ lockTimeoutMs }`, or `{}` when no budget applies
- */
-export declare function waitLockMutationOptions(waitLockSeconds: number | undefined): Pick<RunFurnaceMutationOptions, 'lockTimeoutMs'>;
-/**
- * Returns true while a signal-driven rollback is in progress. The bin entry
- * point uses this as a re-entrancy guard so a user mashing Ctrl+C cannot
- * trigger a second rollback that races the first. Exposed for the bin shim
- * (and the test suite). Production callers should not need it.
- */
-export declare function isSignalRollbackInFlight(): boolean;
-/**
- * Rolls back every in-flight furnace operation and writes a pendingRepair
- * marker for each. Each cleanup callback and journal restore is bounded by a
- * timeout so a stuck I/O operation cannot hang the process indefinitely.
- */
-export declare function rollbackActiveOperationsForSignal(signal: FurnaceShutdownSignal): Promise<void>;
-/**
- * Resolves the path of the lock directory used to serialize furnace mutations
- * for a given project root. Exposed for tests. Production callers should not
- * touch this directly.
- */
-export declare function getFurnaceLockPath(root: string): string;
-/**
- * Completes the rollback for a mutation body that owns its journal end to
- * end, then rethrows. Never returns normally.
- *
- * Shaped as a catch-body handler rather than a `withJournalRollback(body)`
- * wrapper on purpose: the eight calling bodies differ in early returns and
- * in what they close over, and converting them to callbacks would
- * restructure control flow through the engine's rollback path for a
- * cosmetic gain.
- *
- * The ordering is the part worth centralising: `markRolledBack()` must run
- * before the restore, so a restore that itself fails does not leave the
- * lifecycle wrapper replaying the same journal on the way out. The
- * original error is rethrown unless the rollback is what failed: the
- * operator needs to know what went wrong, and separately whether the engine
- * could be put back.
- *
- * @param ctx - The furnace operation context from `runFurnaceMutation`
- * @param journal - Rollback journal this body populated
- * @param error - The error the body threw
- * @param options - Project root, pending-repair tag, and message fragments
- * @returns Never, because it always throws
- */
-export declare function completeJournalRollback(ctx: FurnaceOperationContext, journal: RollbackJournal, error: unknown, options: {
-    projectRoot: string;
-    operation: FurnacePendingRepairOperation;
-    /** Prefix for the restore failure, e.g. `Failed to override component "x"`. */
-    failureMessage: string;
-    /** Subject recorded on the pending-repair marker, e.g. `component "x"`. */
-    subject: string;
-}): Promise<never>;
-/**
- * Forcibly removes the furnace lock directory for every active operation.
- *
- * The bin-layer signal handler calls `process.exit` after rollback, which
- * short-circuits Node's normal unwinding, so `withFileLock`'s `finally { rm
- * }` never runs and the lock directory survives the process. The next
- * FireForge command then has to either wait out the staleness window or
- * have the operator remove the lock manually. This sweeper runs inside
- * the signal-handler pipeline before `process.exit`, so the lock is gone
- * by the time the next command starts.
- *
- * Errors are logged and swallowed: we do not want a slow I/O failure at
- * shutdown to prevent the process from exiting. The doctor-side stale
- * lock check (`src/commands/doctor-furnace.ts`) is the backup path for
- * any lock that escapes this sweep.
- */
-export declare function forceReleaseFurnaceLocksForActiveOperations(): Promise<void>;
-/**
- * Runs a furnace-mutating body under the apply-wide lock and registers it
- * with the process-wide SIGINT/SIGTERM rollback pathway. The lock prevents
- * two `furnace apply`/`deploy`/`create`/etc. runs from racing on the engine
- * working copy. The CLI entrypoint's global signal handlers consult this
- * registry and invoke rollback (writing a `pendingRepair` marker when needed)
- * if the user hits Ctrl+C mid-run.
- *
- * Dry-run callers should pass `options.dryRun = true` so the wrapper skips
- * the lock entirely (concurrent dry-runs are safe and shouldn't block each
- * other).
- *
- * The body receives a {@link FurnaceOperationContext}. It must call
- * `ctx.registerJournal(journal)` once it has constructed its rollback journal.
- * Bodies that don't manage a journal directly (e.g. apply, which delegates to
- * `applyAllComponents`) can pass an internal callback through.
- */
-export declare function runFurnaceMutation<T>(root: string, kind: FurnacePendingRepairOperation, body: (ctx: FurnaceOperationContext) => Promise<T>, options?: RunFurnaceMutationOptions): Promise<T>;
-/**
- * Persists an `apply-rollback` (or other operation-kind) `pendingRepair`
- * marker on behalf of a caller that detected a rollback failure outside the
- * signal-handler path (e.g. apply's own catch-around-restore). Exposed so
- * `furnace-apply.ts` can write the marker without taking on a dependency on
- * the lifecycle wrapper's internals.
- */
-export declare function recordFurnaceRollbackFailure(root: string, operation: FurnacePendingRepairOperation, reason: string): Promise<void>;
-/**
- * Test-only helper: tears down the module-scoped state. Vitest workers may
- * reuse the module across tests, so the test suite must call this between
- * cases that exercise the signal pathway. Not exported from the package
- * entry point.
- *
- * @internal Exported only so tests can reach it. Not part of the public
- * surface.
- */
-export declare function __resetFurnaceOperationStateForTests(): void;

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

@@ -1,444 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
-import { FurnaceError } from '../errors/furnace.js';
-import { assert } from '../utils/assert.js';
-import { toError } from '../utils/errors.js';
-import { verbose, warn } from '../utils/logger.js';
-import { sessionWaitLockMs } from '../utils/options.js';
-import { FIREFORGE_DIR } from './config-paths.js';
-import { readLockStatus, releaseLockIfOwned, withFileLock } from './file-lock.js';
-import { loadFurnaceState, updateFurnaceState } from './furnace-config.js';
-import { restoreRollbackJournal, restoreRollbackJournalOrThrow, } from './furnace-rollback.js';
-/** Sidecar lock filename used to serialize concurrent furnace mutations. */
-const FURNACE_LOCK_FILENAME = 'furnace.lock';
-/**
- * Converts a resolved `--wait-lock` budget in seconds into the
- * {@link RunFurnaceMutationOptions} slice that applies it to the furnace
- * lock. Undefined in, empty out, so the caller can spread it
- * unconditionally without assigning `undefined` under
- * `exactOptionalPropertyTypes`.
- *
- * A helper rather than three inline spreads: the seconds-to-milliseconds
- * conversion is exactly the kind of thing that gets copied once correctly
- * and once with the factor dropped.
- *
- * @param waitLockSeconds - Resolved budget in seconds, or undefined
- * @returns `{ lockTimeoutMs }`, or `{}` when no budget applies
- */
-export function waitLockMutationOptions(waitLockSeconds) {
-    return waitLockSeconds === undefined ? {} : { lockTimeoutMs: waitLockSeconds * 1000 };
-}
-/**
- * Claims the rollback for one operation, or reports that another path
- * already has it.
- *
- * Must stay synchronous and must be called before the caller's first
- * await. That is what makes the claim atomic against the signal handler.
- *
- * @param operation - The in-flight operation to claim
- * @returns True when the caller now owns the rollback
- */
-function claimRollback(operation) {
-    if (operation.rollbackState !== undefined) {
-        return false;
-    }
-    operation.rollbackState = 'in-flight';
-    return true;
-}
-const activeOperations = new Map();
-let nextOperationToken = 1;
-let signalRollbackInFlight = false;
-/**
- * Returns true while a signal-driven rollback is in progress. The bin entry
- * point uses this as a re-entrancy guard so a user mashing Ctrl+C cannot
- * trigger a second rollback that races the first. Exposed for the bin shim
- * (and the test suite). Production callers should not need it.
- */
-export function isSignalRollbackInFlight() {
-    return signalRollbackInFlight;
-}
-/**
- * Rolls back every in-flight furnace operation and writes a pendingRepair
- * marker for each. The bin entry point installs SIGINT/SIGTERM handlers that
- * call this and then exit. Calling it directly from inside the library would
- * violate the "process.exit only in bin" invariant. The function is also
- * exposed under this name so the test suite can exercise the teardown path
- * without going through `process.emit` / `process.exit`.
- */
-/** Maximum time (ms) the signal-driven rollback may take per operation. */
-const SIGNAL_ROLLBACK_TIMEOUT_MS = 15_000;
-/** Races a promise against a deadline, rejecting with a timeout error if the deadline expires. */
-function withTimeout(promise, ms, label) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            reject(new Error(`${label} timed out after ${ms}ms`));
-        }, ms);
-        promise.then((value) => {
-            clearTimeout(timer);
-            resolve(value);
-        }, (error) => {
-            clearTimeout(timer);
-            reject(error instanceof Error ? error : new Error(String(error)));
-        });
-    });
-}
-/**
- * Rolls back every in-flight furnace operation and writes a pendingRepair
- * marker for each. Each cleanup callback and journal restore is bounded by a
- * timeout so a stuck I/O operation cannot hang the process indefinitely.
- */
-export async function rollbackActiveOperationsForSignal(signal) {
-    // Snapshot the active operations so we don't race with `runFurnaceMutation`
-    // clearing slots during normal completion. Filter completed bodies so a
-    // body sitting in its finally-block cleanup window is not counted as live
-    // work. Counting it would mis-trigger the rollback banner for plain
-    // `fireforge run` (which never registers a mutation but can receive
-    // SIGTERM).
-    const snapshot = [...activeOperations.values()].filter((op) => !op.completed);
-    if (snapshot.length === 0) {
-        // Nothing to roll back. Stay silent so commands that never mutated (run,
-        // watch, test, doctor) don't print an alarming "rolling back mutations"
-        // line on Ctrl+C / SIGTERM. Leave `signalRollbackInFlight` false so a
-        // subsequent registrant can still trigger the full path.
-        return;
-    }
-    signalRollbackInFlight = true;
-    warn(`Received ${signal}; rolling back in-flight furnace mutations…`);
-    for (const op of snapshot) {
-        // The body may already be rolling back on its own throw path. Claim the
-        // operation (or skip it) before the first await so the two paths cannot
-        // both restore the same journal.
-        if (!claimRollback(op)) {
-            verbose(`Rollback for ${op.kind} already in progress; leaving it to the throw path.`);
-            continue;
-        }
-        const cleanupErrors = [];
-        // Run extra cleanup callbacks first (e.g. preview's cleanStories), so the
-        // engine is in its tidiest possible shape before the journal restore
-        // writes the original file contents back over the top.
-        for (const cleanup of op.cleanups) {
-            try {
-                await withTimeout(cleanup(), SIGNAL_ROLLBACK_TIMEOUT_MS, 'Cleanup callback');
-            }
-            catch (error) {
-                cleanupErrors.push(toError(error).message);
-            }
-        }
-        if (!op.journal) {
-            // The body had not yet handed us a journal, so there is nothing to
-            // roll back. We still write a marker because the body may have started
-            // mutating the engine before reaching the registerJournal call.
-            const cleanupSuffix = cleanupErrors.length > 0 ? `; cleanup errors: ${cleanupErrors.join('; ')}` : '';
-            await persistPendingRepair(op.root, op.kind, `interrupted by ${signal} before any state was captured${cleanupSuffix}`).catch((error) => {
-                warn(`Could not persist pending-repair marker: ${toError(error).message}`);
-            });
-            continue;
-        }
-        let rollbackError;
-        try {
-            await withTimeout(restoreRollbackJournal(op.journal), SIGNAL_ROLLBACK_TIMEOUT_MS, 'Rollback journal restore');
-        }
-        catch (error) {
-            rollbackError = toError(error).message;
-        }
-        op.rollbackState = 'done';
-        // A clean signal-driven rollback is not itself a repairable problem:
-        // preview/apply/deploy/remove were interrupted, but the engine was restored
-        // successfully and the next `doctor` run should remain green. Persist a
-        // pending-repair marker only when rollback was incomplete or uncertain.
-        if (rollbackError || cleanupErrors.length > 0) {
-            const reasonParts = [`interrupted by ${signal}`];
-            if (rollbackError) {
-                reasonParts.push(`automatic rollback failed: ${rollbackError}`);
-            }
-            else {
-                reasonParts.push('automatic rollback succeeded');
-            }
-            if (cleanupErrors.length > 0) {
-                reasonParts.push(`cleanup errors: ${cleanupErrors.join('; ')}`);
-            }
-            await persistPendingRepair(op.root, op.kind, reasonParts.join('; ')).catch((error) => {
-                warn(`Could not persist pending-repair marker: ${toError(error).message}`);
-            });
-        }
-    }
-}
-/**
- * Rolls back one operation whose body threw, mirroring the signal path.
- *
- * Never throws: the body's own error is what the operator needs to see, so
- * a rollback failure becomes a `pendingRepair` marker plus a warning
- * rather than replacing it. Skips entirely when the body already restored
- * its own journal and said so via `ctx.markRolledBack()`.
- *
- * @param operation - The in-flight operation whose body threw
- */
-async function rollbackOperationForThrow(operation) {
-    if (!claimRollback(operation)) {
-        return;
-    }
-    const cleanupErrors = [];
-    // Cleanups before the journal restore, for the same reason the signal path
-    // does it in that order: the restore writes original contents back, and it
-    // should do so over the tidiest possible tree.
-    for (const cleanup of operation.cleanups) {
-        try {
-            await withTimeout(cleanup(), SIGNAL_ROLLBACK_TIMEOUT_MS, 'Cleanup callback');
-        }
-        catch (error) {
-            cleanupErrors.push(toError(error).message);
-        }
-    }
-    if (!operation.journal) {
-        // Nothing was captured, so there is nothing to restore. Unlike the signal
-        // path we do not write a pendingRepair marker here: a body that threw
-        // before registering a journal is overwhelmingly a refusal raised during
-        // pre-flight (a validation failure, a missing file), and marking the root
-        // as needing repair would block every later furnace mutation behind a
-        // `doctor --repair-furnace` that has nothing to reconcile. Bodies that
-        // genuinely mutate before registering a journal are the ones the
-        // journal-before-mutation assertions catch.
-        operation.rollbackState = 'done';
-        if (cleanupErrors.length > 0) {
-            warn(`Cleanup after a failed ${operation.kind} reported: ${cleanupErrors.join('; ')}`);
-        }
-        return;
-    }
-    let rollbackError;
-    try {
-        await withTimeout(restoreRollbackJournal(operation.journal), SIGNAL_ROLLBACK_TIMEOUT_MS, 'Rollback journal restore');
-    }
-    catch (error) {
-        rollbackError = toError(error).message;
-    }
-    operation.rollbackState = 'done';
-    if (!rollbackError && cleanupErrors.length === 0) {
-        verbose(`Rolled back ${operation.kind} after a failure; engine restored.`);
-        return;
-    }
-    const reasonParts = [`${operation.kind} failed`];
-    if (rollbackError) {
-        reasonParts.push(`automatic rollback failed: ${rollbackError}`);
-        warn(`Automatic rollback after a failed ${operation.kind} did not complete: ${rollbackError}. ` +
-            'Run "fireforge doctor --repair-furnace" to reconcile.');
-    }
-    else {
-        reasonParts.push('automatic rollback succeeded');
-    }
-    if (cleanupErrors.length > 0) {
-        reasonParts.push(`cleanup errors: ${cleanupErrors.join('; ')}`);
-    }
-    await persistPendingRepair(operation.root, operation.kind, reasonParts.join('; ')).catch((error) => {
-        warn(`Could not persist pending-repair marker: ${toError(error).message}`);
-    });
-}
-async function persistPendingRepair(root, operation, reason) {
-    await updateFurnaceState(root, (state) => ({
-        ...state,
-        pendingRepair: {
-            operation,
-            timestamp: new Date().toISOString(),
-            reason,
-        },
-    }));
-}
-/**
- * Resolves the path of the lock directory used to serialize furnace mutations
- * for a given project root. Exposed for tests. Production callers should not
- * touch this directly.
- */
-export function getFurnaceLockPath(root) {
-    return join(root, FIREFORGE_DIR, FURNACE_LOCK_FILENAME);
-}
-/**
- * Completes the rollback for a mutation body that owns its journal end to
- * end, then rethrows. Never returns normally.
- *
- * Shaped as a catch-body handler rather than a `withJournalRollback(body)`
- * wrapper on purpose: the eight calling bodies differ in early returns and
- * in what they close over, and converting them to callbacks would
- * restructure control flow through the engine's rollback path for a
- * cosmetic gain.
- *
- * The ordering is the part worth centralising: `markRolledBack()` must run
- * before the restore, so a restore that itself fails does not leave the
- * lifecycle wrapper replaying the same journal on the way out. The
- * original error is rethrown unless the rollback is what failed: the
- * operator needs to know what went wrong, and separately whether the engine
- * could be put back.
- *
- * @param ctx - The furnace operation context from `runFurnaceMutation`
- * @param journal - Rollback journal this body populated
- * @param error - The error the body threw
- * @param options - Project root, pending-repair tag, and message fragments
- * @returns Never, because it always throws
- */
-export async function completeJournalRollback(ctx, journal, error, options) {
-    // This body owns its rollback end to end, so tell the lifecycle wrapper
-    // not to restore the same journal again on the way out.
-    ctx.markRolledBack();
-    try {
-        await restoreRollbackJournalOrThrow(journal, options.failureMessage);
-    }
-    catch (rollbackError) {
-        await recordFurnaceRollbackFailure(options.projectRoot, options.operation, `${options.subject}: ${toError(rollbackError).message}`);
-        throw rollbackError;
-    }
-    throw error;
-}
-/**
- * Forcibly removes the furnace lock directory for every active operation.
- *
- * The bin-layer signal handler calls `process.exit` after rollback, which
- * short-circuits Node's normal unwinding, so `withFileLock`'s `finally { rm
- * }` never runs and the lock directory survives the process. The next
- * FireForge command then has to either wait out the staleness window or
- * have the operator remove the lock manually. This sweeper runs inside
- * the signal-handler pipeline before `process.exit`, so the lock is gone
- * by the time the next command starts.
- *
- * Errors are logged and swallowed: we do not want a slow I/O failure at
- * shutdown to prevent the process from exiting. The doctor-side stale
- * lock check (`src/commands/doctor-furnace.ts`) is the backup path for
- * any lock that escapes this sweep.
- */
-export async function forceReleaseFurnaceLocksForActiveOperations() {
-    const paths = new Set([...activeOperations.values()].map((op) => getFurnaceLockPath(op.root)));
-    for (const lockPath of paths) {
-        // Ownership-checked, like every other release path. A bare `rm` would
-        // delete a lock a different process had acquired in the window between
-        // our operation dying and this sweep running. That is the exact race
-        // `releaseLock`'s PID verification closes, and the sweeper has no
-        // acquisition token to check.
-        const removed = await releaseLockIfOwned(lockPath);
-        verbose(removed
-            ? `Removed furnace lock at ${lockPath} during signal teardown`
-            : `Left furnace lock at ${lockPath} in place during signal teardown: it is not owned by this process`);
-    }
-}
-/**
- * Runs a furnace-mutating body under the apply-wide lock and registers it
- * with the process-wide SIGINT/SIGTERM rollback pathway. The lock prevents
- * two `furnace apply`/`deploy`/`create`/etc. runs from racing on the engine
- * working copy. The CLI entrypoint's global signal handlers consult this
- * registry and invoke rollback (writing a `pendingRepair` marker when needed)
- * if the user hits Ctrl+C mid-run.
- *
- * Dry-run callers should pass `options.dryRun = true` so the wrapper skips
- * the lock entirely (concurrent dry-runs are safe and shouldn't block each
- * other).
- *
- * The body receives a {@link FurnaceOperationContext}. It must call
- * `ctx.registerJournal(journal)` once it has constructed its rollback journal.
- * Bodies that don't manage a journal directly (e.g. apply, which delegates to
- * `applyAllComponents`) can pass an internal callback through.
- */
-export async function runFurnaceMutation(root, kind, body, options = {}) {
-    if (options.dryRun) {
-        // Dry-run: no lock, no signal handler, no journal registration. The body
-        // is still given a no-op context so callers can use the same shape.
-        return body({
-            registerJournal: () => undefined,
-            registerCleanup: () => undefined,
-            markRolledBack: () => undefined,
-        });
-    }
-    // Pre-flight: refuse to mutate when a previous operation left the engine in
-    // a partially-rolled-back state. The user must run `fireforge doctor
-    // --repair-furnace` to reconcile before any new mutations can proceed.
-    if (!options.skipPendingRepairCheck) {
-        const state = await loadFurnaceState(root);
-        if (state.pendingRepair) {
-            throw new FurnaceError(`A previous "${state.pendingRepair.operation}" left the engine in an inconsistent state ` +
-                `(${state.pendingRepair.reason}). Run "fireforge doctor --repair-furnace" to reconcile ` +
-                'before running further furnace mutations.');
-        }
-    }
-    const token = nextOperationToken++;
-    const operation = { root, kind, cleanups: [] };
-    const lockPath = getFurnaceLockPath(root);
-    // An explicit budget wins. Otherwise the session-wide one applies. Naming
-    // the lock in the refusal matters: a mutation takes two, and a message
-    // that says only "timed out" sends the operator to raise a budget that
-    // was already large enough for the other lock.
-    const timeoutMs = options.lockTimeoutMs ?? sessionWaitLockMs();
-    const lockOptions = {
-        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-        onTimeoutMessage: `Timed out waiting for the FURNACE lock at ${lockPath} ` +
-            `(this is the second of the two locks a furnace mutation takes; the first is the engine session lock). ` +
-            'Another fireforge furnace command may be running. ' +
-            'Raise the budget with --wait-lock <seconds> or FIREFORGE_WAIT_LOCK, which governs both. ' +
-            'If no other process is running, remove the stale lock directory and retry.',
-        onStaleLockMessage: (ageMs) => `Removing stale furnace lock (age: ${Math.round(ageMs / 1000)}s). ` +
-            'A previous fireforge process may have crashed.',
-    };
-    return withFileLock(lockPath, async () => {
-        // Everything the body does from here is serialized only by the furnace
-        // lock, so confirm we are actually inside it before registering as a
-        // live mutation. The owner record is best-effort in `withFileLock`
-        // (a live holder can legitimately have no readable PID), so the PID
-        // half only tightens the check when a record is present. Asserting on
-        // its existence would fire on a lock we really do hold.
-        const lockStatus = await readLockStatus(lockPath);
-        assert(lockStatus.held, 'furnace lock held before the mutation body runs');
-        assert(lockStatus.holder === undefined || lockStatus.holder.pid === process.pid, () => `furnace lock is owned by this process ` +
-            `(held by PID ${lockStatus.holder?.pid}, we are ${process.pid})`);
-        activeOperations.set(token, operation);
-        try {
-            return await body({
-                registerJournal: (journal) => {
-                    operation.journal = journal;
-                },
-                registerCleanup: (cleanup) => {
-                    operation.cleanups.push(cleanup);
-                },
-                markRolledBack: () => {
-                    operation.rollbackState = 'done';
-                },
-            });
-        }
-        catch (error) {
-            // A thrown error leaves the engine mutated exactly as a signal does,
-            // so it gets the same treatment. A bare finally here would
-            // deregister the operation and mark it completed, removing it from
-            // the signal handler's view too, so a body that threw outside its
-            // own catch (notably anywhere in `applyAllComponents` outside its
-            // two per-component try blocks) would leave the checkout torn with
-            // no marker.
-            //
-            // This runs inside the withFileLock callback, so the furnace lock is
-            // still held for the duration of the restore: a competing process
-            // cannot start mutating half-way through it.
-            await rollbackOperationForThrow(operation);
-            throw error;
-        }
-        finally {
-            operation.completed = true;
-            activeOperations.delete(token);
-        }
-    }, lockOptions);
-}
-/**
- * Persists an `apply-rollback` (or other operation-kind) `pendingRepair`
- * marker on behalf of a caller that detected a rollback failure outside the
- * signal-handler path (e.g. apply's own catch-around-restore). Exposed so
- * `furnace-apply.ts` can write the marker without taking on a dependency on
- * the lifecycle wrapper's internals.
- */
-export async function recordFurnaceRollbackFailure(root, operation, reason) {
-    await persistPendingRepair(root, operation, reason);
-}
-/**
- * Test-only helper: tears down the module-scoped state. Vitest workers may
- * reuse the module across tests, so the test suite must call this between
- * cases that exercise the signal pathway. Not exported from the package
- * entry point.
- *
- * @internal Exported only so tests can reach it. Not part of the public
- * surface.
- */
-export function __resetFurnaceOperationStateForTests() {
-    activeOperations.clear();
-    nextOperationToken = 1;
-    signalRollbackInFlight = false;
-}