@hominis/fireforge 0.49.2 → 0.50.0

package/dist/src/core/file-lock.js

@@ -1,14 +1,16 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { randomUUID } from 'node:crypto';
-import { mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { mkdir, rename, rm, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
 import { LockContentionError } from '../errors/base.js';
-import { getNodeErrorCode, isProcessAlive, toError } from '../utils/errors.js';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
 import { ensureDir } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
 import { sleep } from '../utils/sleep.js';
 import { isLockOwnerAlive, LOCK_PID_FILE, readLockOwner, writeLockOwner, } from './file-lock-owner.js';
+import { readLockQueue, registerWaiter, } from './file-lock-queue.js';
 export { LOCK_PID_FILE };
+export { formatLockQueuePosition } from './file-lock-queue.js';
 const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
 const DEFAULT_LOCK_POLL_MS = 50;
 const DEFAULT_STALE_LOCK_MS = 5 * 60_000;
@@ -30,46 +32,6 @@ const WAIT_PROBE_INTERVAL_MS = 5_000;
 export function createSiblingLockPath(filePath, suffix = '.fireforge.lock') {
     return `${filePath}${suffix}`;
 }
-/** Sibling directory in which waiters advertise themselves. */
-function lockWaitersDir(lockPath) {
-    return `${lockPath}.waiters`;
-}
-/** Parsed waiter-file name: `<startedAtMs>-<pid>-<uuid>`. */
-function parseWaiterFileName(name) {
-    const match = /^(\d+)-(\d+)-/.exec(name);
-    const startedAt = match?.[1];
-    const pid = match?.[2];
-    if (startedAt === undefined || pid === undefined)
-        return undefined;
-    return { startedAt: Number.parseInt(startedAt, 10), pid: Number.parseInt(pid, 10) };
-}
-/**
- * Reads the live waiter queue around `lockPath`, dropping entries whose
- * process is gone (a killed waiter must not inflate the depth forever).
- *
- * Advisory and fail-open: an unreadable registry reports an empty queue
- * rather than failing whatever asked.
- *
- * @param lockPath - The lock directory whose queue to inspect
- * @param selfStartedAt - This process's wait start, to compute `ahead`
- */
-export async function readLockQueue(lockPath, selfStartedAt) {
-    let names;
-    try {
-        names = await readdir(lockWaitersDir(lockPath));
-    }
-    catch {
-        return { depth: 0, ahead: 0 };
-    }
-    const live = names
-        .map(parseWaiterFileName)
-        .filter((entry) => entry !== undefined)
-        .filter((entry) => isProcessAlive(entry.pid));
-    const ahead = selfStartedAt === undefined
-        ? 0
-        : live.filter((entry) => entry.startedAt < selfStartedAt).length;
-    return { depth: live.length, ahead };
-}
 /**
  * Inspects a lock without acquiring it. Read-only and fail-open: a missing
  * lock is reported as free, never as an error.
@@ -92,29 +54,6 @@ export async function readLockStatus(lockPath) {
         : undefined;
     return { held: true, holder, heldForMs, queueDepth: queue.depth };
 }
-/**
- * Registers this process in the lock's waiter queue. Returns a
- * deregistration function that is always safe to call (including when
- * registration itself failed).
- */
-async function registerWaiter(lockPath, startedAt) {
-    const dir = lockWaitersDir(lockPath);
-    const file = join(dir, `${startedAt}-${process.pid}-${randomUUID()}`);
-    try {
-        await ensureDir(dir);
-        await writeFile(file, `${process.pid}\n`, 'utf-8');
-    }
-    catch (error) {
-        // Advisory only. Never fail a lock acquisition over the queue display.
-        verbose(`Could not register lock waiter for ${lockPath}: ${toError(error).message}`);
-        return async () => {
-            /* nothing to remove */
-        };
-    }
-    return async () => {
-        await rm(file, { force: true });
-    };
-}
 /**
  * Reads the contended lock's owner and queue in one go. One probe per cycle
  * serves both the progress line and the deadline extension, so the two can
@@ -122,12 +61,12 @@ async function registerWaiter(lockPath, startedAt) {
  * degrades to `holder: undefined`, since a diagnostic must never break the
  * wait loop.
  */
-async function probeWaitState(lockPath, startedAt) {
+async function probeWaitState(lockPath, self) {
     const owner = await readLockOwner(lockPath);
     const holder = owner.present
         ? { pid: owner.pid, alive: isLockOwnerAlive(owner), metadata: owner.metadata }
         : undefined;
-    return { holder, queue: await readLockQueue(lockPath, startedAt) };
+    return { holder, queue: await readLockQueue(lockPath, self) };
 }
 /**
  * Reaps a lock directory believed to be stale, safely against concurrent
@@ -345,16 +284,24 @@ function formatQueuePositionReached(queue) {
  * caller asked for it. Split out of the wait loop so the loop stays a
  * readable state machine.
  */
-async function runWaitProbe(lockPath, startedAt, timeoutMs, options) {
-    const { holder, queue } = await probeWaitState(lockPath, startedAt);
+async function runWaitProbe(lockPath, self, timeoutMs, options) {
+    const { holder, queue } = await probeWaitState(lockPath, self);
     options.onWaitProgress?.({
-        waitedMs: Date.now() - startedAt,
+        waitedMs: Date.now() - self.startedAt,
         timeoutMs,
         holder,
         queue,
     });
     return { queue };
 }
+/**
+ * Whether it is this waiter's turn to contend for the lock: no live waiter
+ * arrived before it. Ties and dead or stalled tickets are settled by
+ * {@link readLockQueue}, so every waiter agrees on who is at the head.
+ */
+async function isWaiterTurn(lockPath, startedAt, waiter) {
+    return (await readLockQueue(lockPath, { startedAt, ticket: waiter.ticket })).ahead === 0;
+}
 /**
  * Lock directories this process currently holds.
  *
@@ -404,8 +351,14 @@ export async function withFileLock(lockPath, operation, options = {}) {
     let lastProbeAt = startedAt;
     /** Best (lowest) queue position seen so far. Used to detect an advance. */
     let bestAhead;
-    /** Set on first contention so an uncontended acquire costs nothing. */
-    let deregisterWaiter;
+    /**
+     * This waiter's ticket in the queue. Taken on first contention, or up
+     * front when others are already queued, so an uncontended acquire never
+     * writes one.
+     */
+    let waiter;
+    /** The last `EEXIST`, carried as the cause of a timeout refusal. */
+    let contention;
     // One cadence drives both the progress line and the deadline extension.
     // Either feature alone is enough to want the probe. Neither is worth a
     // second timer.
@@ -414,83 +367,97 @@ export async function withFileLock(lockPath, operation, options = {}) {
         extend !== undefined;
     await ensureDir(dirname(lockPath));
     try {
+        // Arrival order: a newcomer that finds others already queued takes a
+        // ticket behind them instead of racing them for the next free moment.
+        // Without this a fresh command could take the lock in the gap between
+        // the holder's release and the head waiter's next poll.
+        if ((await readLockQueue(lockPath)).depth > 0) {
+            waiter = await registerWaiter(lockPath, startedAt);
+        }
         for (;;) {
-            try {
-                await mkdir(lockPath);
-                break;
-            }
-            catch (error) {
-                if (getNodeErrorCode(error) !== 'EEXIST') {
-                    throw error;
+            // Only the head of the queue contends for the lock. A waiter without
+            // a ticket (no contention seen yet, or a registry that could not be
+            // written) contends as every waiter did before tickets existed.
+            if (waiter?.ticket === undefined || (await isWaiterTurn(lockPath, startedAt, waiter))) {
+                try {
+                    await mkdir(lockPath);
+                    break;
                 }
-                // Advertise this waiter so the queue is visible to the wait output
-                // and to `fireforge status --lock`. Registered lazily:
-                // an uncontended acquisition never touches the registry.
-                deregisterWaiter ??= await registerWaiter(lockPath, startedAt);
-                if (lastStaleProbeAt === undefined || Date.now() - lastStaleProbeAt >= staleReprobeMs) {
-                    lastStaleProbeAt = Date.now();
-                    if (await removeIfStaleLock(lockPath, staleMs, options.onStaleLockMessage)) {
-                        continue;
+                catch (error) {
+                    if (getNodeErrorCode(error) !== 'EEXIST') {
+                        throw error;
                     }
+                    contention = error;
                 }
-                // The probe runs before the deadline check, so a due progress line is
-                // written before the refusal that follows it, never lost to it. On a
-                // slow host (a cold Windows CI runner) the first iteration alone, with
-                // its waiter registration and stale probe, can outlast a short budget;
-                // checked the other way round, the wait timed out having reported
-                // nothing, and an advance that probe would have seen could not extend
-                // the deadline it was about to miss.
-                if (probeWanted && Date.now() - lastProbeAt >= probeIntervalMs) {
-                    lastProbeAt = Date.now();
-                    // Report the budget that is currently in force, not the one
-                    // originally requested: once an extension has been granted, the
-                    // requested figure is stale, and a progress line that keeps
-                    // quoting it reads as a timeout that does not fire.
-                    const probe = await runWaitProbe(lockPath, startedAt, deadline - startedAt, options);
-                    // An advance (someone ahead of us took their turn and finished)
-                    // buys a fresh budget, because the wait is working. Only a queue
-                    // that stops moving starves, which is the case the timeout is for.
-                    //
-                    // The first observation is a seed, never an advance. `bestAhead`
-                    // used to start `undefined`, so the opening probe always satisfied
-                    // this test and handed out a free full budget: a `--wait-lock 300`
-                    // run outlived its 300 s even against a queue that never moved
-                    // once, which is the "it does not reliably give up after N
-                    // seconds" behaviour a downstream fork reported.
-                    if (hardDeadline !== undefined) {
-                        if (bestAhead === undefined) {
-                            bestAhead = probe.queue.ahead;
-                        }
-                        else if (probe.queue.ahead < bestAhead) {
-                            bestAhead = probe.queue.ahead;
-                            deadline = Math.min(Date.now() + timeoutMs, hardDeadline);
-                            options.onWaitExtended?.({
-                                ahead: probe.queue.ahead,
-                                budgetMs: deadline - startedAt,
-                            });
-                        }
-                    }
-                }
-                if (Date.now() >= deadline) {
-                    // The queue is read here, not carried over from the last progress
-                    // probe: the position the wait reached is the one number that says
-                    // whether a larger budget would have helped, and it must not depend
-                    // on a probe having happened to land inside the budget. We are still
-                    // registered at this point. `deregisterWaiter` runs in the `finally`
-                    // below, which is only entered once this refusal has been built.
-                    throw await buildLockTimeoutError(lockPath, options.onTimeoutMessage, error, await readLockQueue(lockPath, startedAt));
+            }
+            // Take a ticket so the queue is visible to the wait output and to
+            // `fireforge status --lock`, and so the grant follows arrival order.
+            waiter ??= await registerWaiter(lockPath, startedAt);
+            await waiter.heartbeat();
+            const self = { startedAt, ticket: waiter.ticket };
+            if (lastStaleProbeAt === undefined || Date.now() - lastStaleProbeAt >= staleReprobeMs) {
+                lastStaleProbeAt = Date.now();
+                if (await removeIfStaleLock(lockPath, staleMs, options.onStaleLockMessage)) {
+                    continue;
                 }
-                await sleep(currentPollMs);
-                if (options.pollMaxMs !== undefined) {
-                    currentPollMs = Math.min(currentPollMs * 2, options.pollMaxMs);
+            }
+            // The probe runs before the deadline check, so a due progress line is
+            // written before the refusal that follows it, never lost to it. On a
+            // slow host (a cold Windows CI runner) the first iteration alone, with
+            // its waiter registration and stale probe, can outlast a short budget;
+            // checked the other way round, the wait timed out having reported
+            // nothing, and an advance that probe would have seen could not extend
+            // the deadline it was about to miss.
+            if (probeWanted && Date.now() - lastProbeAt >= probeIntervalMs) {
+                lastProbeAt = Date.now();
+                // Report the budget that is currently in force, not the one
+                // originally requested: once an extension has been granted, the
+                // requested figure is stale, and a progress line that keeps
+                // quoting it reads as a timeout that does not fire.
+                const probe = await runWaitProbe(lockPath, self, deadline - startedAt, options);
+                // An advance (someone ahead of us took their turn and finished)
+                // buys a fresh budget, because the wait is working. Only a queue
+                // that stops moving starves, which is the case the timeout is for.
+                //
+                // The first observation is a seed, never an advance. `bestAhead`
+                // used to start `undefined`, so the opening probe always satisfied
+                // this test and handed out a free full budget: a `--wait-lock 300`
+                // run outlived its 300 s even against a queue that never moved
+                // once, which is the "it does not reliably give up after N
+                // seconds" behaviour a downstream fork reported.
+                if (hardDeadline !== undefined) {
+                    if (bestAhead === undefined) {
+                        bestAhead = probe.queue.ahead;
+                    }
+                    else if (probe.queue.ahead < bestAhead) {
+                        bestAhead = probe.queue.ahead;
+                        deadline = Math.min(Date.now() + timeoutMs, hardDeadline);
+                        options.onWaitExtended?.({
+                            ahead: probe.queue.ahead,
+                            budgetMs: deadline - startedAt,
+                        });
+                    }
                 }
             }
+            if (Date.now() >= deadline) {
+                // The queue is read here, not carried over from the last progress
+                // probe: the position the wait reached is the one number that says
+                // whether a larger budget would have helped, and it must not depend
+                // on a probe having happened to land inside the budget. We are still
+                // registered at this point. The ticket is returned in the `finally`
+                // below, which is only entered once this refusal has been built.
+                throw await buildLockTimeoutError(lockPath, options.onTimeoutMessage, contention, await readLockQueue(lockPath, self));
+            }
+            await sleep(currentPollMs);
+            if (options.pollMaxMs !== undefined) {
+                currentPollMs = Math.min(currentPollMs * 2, options.pollMaxMs);
+            }
         }
     }
     finally {
         // Leaving the queue happens the moment we stop waiting, whether we
         // acquired the lock or timed out.
-        await deregisterWaiter?.();
+        await waiter?.deregister();
     }
     // Stamp ownership (PID + per-acquisition token + acquisition time) into
     // the lock directory so stale-lock recovery can check liveness and release

package/dist/src/core/furnace-apply-output.d.ts

@@ -2,6 +2,16 @@ import type { ApplyResult, DryRunAction } from '../types/furnace.js';
 type ApplyResultWithActions = ApplyResult & {
     actions?: DryRunAction[];
 };
+/**
+ * The reason breakdown appended to a "skipped N" summary, e.g.
+ * ` (2 already current)`, so `Applied 0, skipped 1` says whether the
+ * component was already current or skipped for another reason without
+ * diffing the deployed files by hand. Empty when nothing was skipped.
+ *
+ * @param skipped - `result.skipped` from applyAllComponents
+ * @returns The parenthesised breakdown with a leading space, or ''
+ */
+export declare function formatSkipBreakdown(skipped: ApplyResult['skipped']): string;
 /**
  * Prints a standard summary of an apply result for both normal and dry-run flows.
  *

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

@@ -1,4 +1,34 @@
 import { error, info, success, warn } from '../utils/logger.js';
+/** Summary label and per-component explanation for each skip kind. */
+const SKIP_KIND_TEXT = {
+    'already-current': {
+        label: 'already current',
+        detail: 'already current: source unchanged since the last recorded apply (from any session) and the engine copy matches it',
+    },
+};
+/** The per-component line text for one skip. */
+function describeSkip(skipped) {
+    return skipped.kind !== undefined ? SKIP_KIND_TEXT[skipped.kind].detail : skipped.reason;
+}
+/**
+ * The reason breakdown appended to a "skipped N" summary, e.g.
+ * ` (2 already current)`, so `Applied 0, skipped 1` says whether the
+ * component was already current or skipped for another reason without
+ * diffing the deployed files by hand. Empty when nothing was skipped.
+ *
+ * @param skipped - `result.skipped` from applyAllComponents
+ * @returns The parenthesised breakdown with a leading space, or ''
+ */
+export function formatSkipBreakdown(skipped) {
+    if (skipped.length === 0)
+        return '';
+    const counts = new Map();
+    for (const entry of skipped) {
+        const label = entry.kind !== undefined ? SKIP_KIND_TEXT[entry.kind].label : entry.reason;
+        counts.set(label, (counts.get(label) ?? 0) + 1);
+    }
+    return ` (${[...counts].map(([label, count]) => `${count} ${label}`).join(', ')})`;
+}
 /**
  * Prints a standard summary of an apply result for both normal and dry-run flows.
  *
@@ -40,7 +70,7 @@ export function logApplyResult(result, isDryRun) {
             success(`${applied.name} (${applied.type}) → ${applied.filesAffected.length} files`);
         }
         for (const skipped of result.skipped) {
-            info(`${skipped.name} — ${skipped.reason}`);
+            info(`${skipped.name} — ${describeSkip(skipped)}`);
         }
         for (const applied of result.applied) {
             if (applied.stepErrors && applied.stepErrors.length > 0) {

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

@@ -39,6 +39,16 @@ function addMissingComponentError(result, name, directoryPath) {
         error: `Component directory not found: ${directoryPath}`,
     });
 }
+/**
+ * The skip both batch loops record when a component's source is unchanged
+ * since the last recorded apply and its engine copy still matches. `reason`
+ * keeps its long-standing text for API consumers; `kind` lets summaries
+ * name it.
+ */
+const ALREADY_CURRENT_SKIP = {
+    reason: 'No changes since last apply',
+    kind: 'already-current',
+};
 async function applyOverrideBatch(ctx) {
     const { config, furnacePaths, state, engineDir, ftlDir, dryRun } = ctx;
     const { result, allActions, newChecksums, rollbackJournal, componentName } = ctx;
@@ -66,7 +76,7 @@ async function applyOverrideBatch(ctx) {
                 const cachedEngine = extractComponentChecksums(state.engineChecksums, 'override', name);
                 const drifted = await hasOverrideEngineDrift({ engineDir, componentDir, ftlDir }, overrideConfig, cachedEngine);
                 if (!drifted) {
-                    result.skipped.push({ name, reason: 'No changes since last apply' });
+                    result.skipped.push({ name, ...ALREADY_CURRENT_SKIP });
                     recordComponentChecksums(newChecksums, previous, 'override', name);
                     continue;
                 }
@@ -226,7 +236,7 @@ async function applyCustomBatch(ctx, root, markerComment) {
                 // re-apply even though the workspace is unchanged.
                 const drifted = await hasCustomEngineDrift({ root, name, componentDir, ftlDir }, customConfig);
                 if (!drifted) {
-                    result.skipped.push({ name, reason: 'No changes since last apply' });
+                    result.skipped.push({ name, ...ALREADY_CURRENT_SKIP });
                     recordComponentChecksums(newChecksums, previous, 'custom', name);
                     continue;
                 }

package/dist/src/core/furnace-composed-source.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The Furnace-composed form of a component source, and the questions that
+ * need it.
+ *
+ * `furnace apply` does not copy every source verbatim: a stylesheet with
+ * `@fireforge-include` directives is deployed with each fragment body from
+ * `components/shared/` inlined between the directive and its
+ * `@fireforge-end-include` marker. Anything that compares a deployed engine
+ * file with its source has to compare against that composed form, or a
+ * freshly deployed widget reads as a large difference it is not:
+ *
+ *  - the unexported-drift belt (`build`/`test --refuse-unexported-drift`),
+ *    which must not refuse to overwrite a deployed file with the very bytes
+ *    it already holds;
+ *  - `furnace diff`, which must show what the next apply would change.
+ */
+import type { FurnaceConfig } from '../types/furnace.js';
+/**
+ * Composes one component source into the bytes apply deploys: a stylesheet
+ * carrying include directives is fragment-expanded, anything else is
+ * returned as is.
+ *
+ * @param content - Workspace source content
+ * @param fileName - Source file name (only `.css` is ever expanded)
+ * @param sharedDir - Absolute path of `components/shared/`
+ * @returns The composed content
+ * @throws FurnaceError when an included fragment is missing or nested
+ */
+export declare function composeComponentSource(content: string, fileName: string, sharedDir: string): Promise<string>;
+/** The workspace source apply deploys to one engine path. */
+export interface FurnaceDeployedSource {
+    type: 'custom' | 'override';
+    component: string;
+    /** Source file name inside the component directory. */
+    fileName: string;
+    /** Absolute path of the workspace source. */
+    sourcePath: string;
+}
+/**
+ * Maps every engine-relative path `furnace apply` writes to the workspace
+ * source it writes there: custom `.mjs`/`.css` into `targetPath`, a custom
+ * component's own `.ftl` into the Fluent tree (never for `sharedFtl`), and
+ * each override copy candidate onto its engine target.
+ *
+ * @param root - Project root
+ * @param config - Loaded furnace.json
+ * @returns Engine-relative path (POSIX) → deployed source
+ */
+export declare function mapDeployedComponentSources(root: string, config: FurnaceConfig): Promise<Map<string, FurnaceDeployedSource>>;
+/**
+ * Why a deployed engine file is safe to overwrite from its component
+ * source even though no patch body or baseline explains it:
+ *
+ * - `composed-source`: it already equals the Furnace-composed current
+ *   source, so the overwrite writes the same bytes;
+ * - `fragment-refresh`: it differs from the composed source only inside
+ *   Furnace-generated fragment expansions (a fragment changed since it was
+ *   deployed), so the overwrite only refreshes generated text;
+ * - `previous-deploy`: it is exactly the content Furnace's last recorded
+ *   apply deployed (the source has moved on since), so the overwrite loses
+ *   nothing that was not already a component source.
+ */
+export type DeployedSourceMatch = 'composed-source' | 'fragment-refresh' | 'previous-deploy';
+/**
+ * For each engine-relative path, decides whether its current engine content
+ * is a Furnace deployment of its component source (see
+ * {@link DeployedSourceMatch}). Paths with no component source, an
+ * unreadable engine copy, or content explained by none of the matches are
+ * absent from the result.
+ *
+ * @param root - Project root
+ * @param engineDir - Absolute engine directory
+ * @param files - Engine-relative paths to classify
+ * @returns Engine-relative path → match, for the matching paths only
+ */
+export declare function matchDeployedComponentFiles(root: string, engineDir: string, files: readonly string[]): Promise<Map<string, DeployedSourceMatch>>;

package/dist/src/core/furnace-composed-source.js

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The Furnace-composed form of a component source, and the questions that
+ * need it.
+ *
+ * `furnace apply` does not copy every source verbatim: a stylesheet with
+ * `@fireforge-include` directives is deployed with each fragment body from
+ * `components/shared/` inlined between the directive and its
+ * `@fireforge-end-include` marker. Anything that compares a deployed engine
+ * file with its source has to compare against that composed form, or a
+ * freshly deployed widget reads as a large difference it is not:
+ *
+ *  - the unexported-drift belt (`build`/`test --refuse-unexported-drift`),
+ *    which must not refuse to overwrite a deployed file with the very bytes
+ *    it already holds;
+ *  - `furnace diff`, which must show what the next apply would change.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { sha256Hex } from '../utils/hash.js';
+import { normalizePathSlashes } from '../utils/paths.js';
+import { isOverrideCopyCandidate } from './furnace-apply-helpers.js';
+import { extractComponentChecksums, normalizeForChecksum } from './furnace-checksum-utils.js';
+import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
+import { resolveFtlDir } from './furnace-constants.js';
+import { expandCssFragments, listFragmentIncludes, stripExpandedFragments, } from './furnace-css-fragments.js';
+import { isRegularFile } from './furnace-dir-entry.js';
+/**
+ * Composes one component source into the bytes apply deploys: a stylesheet
+ * carrying include directives is fragment-expanded, anything else is
+ * returned as is.
+ *
+ * @param content - Workspace source content
+ * @param fileName - Source file name (only `.css` is ever expanded)
+ * @param sharedDir - Absolute path of `components/shared/`
+ * @returns The composed content
+ * @throws FurnaceError when an included fragment is missing or nested
+ */
+export async function composeComponentSource(content, fileName, sharedDir) {
+    if (!fileName.endsWith('.css') || listFragmentIncludes(content).length === 0)
+        return content;
+    return (await expandCssFragments(content, sharedDir)).expanded;
+}
+/**
+ * Maps every engine-relative path `furnace apply` writes to the workspace
+ * source it writes there: custom `.mjs`/`.css` into `targetPath`, a custom
+ * component's own `.ftl` into the Fluent tree (never for `sharedFtl`), and
+ * each override copy candidate onto its engine target.
+ *
+ * @param root - Project root
+ * @param config - Loaded furnace.json
+ * @returns Engine-relative path (POSIX) → deployed source
+ */
+export async function mapDeployedComponentSources(root, config) {
+    const furnacePaths = getFurnacePaths(root);
+    const ftlDir = resolveFtlDir(config.ftlBasePath);
+    const sources = new Map();
+    for (const [component, custom] of Object.entries(config.custom)) {
+        const componentDir = join(furnacePaths.customDir, component);
+        for (const fileName of await listSourceFiles(componentDir)) {
+            let engineRel;
+            if (fileName.endsWith('.mjs') || fileName.endsWith('.css')) {
+                engineRel = normalizePathSlashes(join(custom.targetPath, fileName));
+            }
+            else if (fileName === `${component}.ftl` && custom.localized && !custom.sharedFtl) {
+                engineRel = normalizePathSlashes(join(ftlDir, fileName));
+            }
+            if (engineRel === undefined)
+                continue;
+            sources.set(engineRel, {
+                type: 'custom',
+                component,
+                fileName,
+                sourcePath: join(componentDir, fileName),
+            });
+        }
+    }
+    for (const [component, override] of Object.entries(config.overrides)) {
+        const componentDir = join(furnacePaths.overridesDir, component);
+        for (const fileName of await listSourceFiles(componentDir)) {
+            if (!isOverrideCopyCandidate(fileName, override.type))
+                continue;
+            // Same target rule as `getOverrideEngineTargetPath`, engine-relative.
+            const base = fileName.endsWith('.ftl') ? ftlDir : override.basePath;
+            sources.set(normalizePathSlashes(join(base, fileName)), {
+                type: 'override',
+                component,
+                fileName,
+                sourcePath: join(componentDir, fileName),
+            });
+        }
+    }
+    return sources;
+}
+async function listSourceFiles(componentDir) {
+    if (!(await pathExists(componentDir)))
+        return [];
+    const entries = await readdir(componentDir, { withFileTypes: true, encoding: 'utf8' });
+    return entries.filter((entry) => isRegularFile(entry)).map((entry) => entry.name);
+}
+/**
+ * Classifies one deployed engine file against its component source.
+ *
+ * @returns The match, or undefined when the engine copy is explained by
+ *   none of them (a real, unrecorded engine edit)
+ */
+async function matchDeployedSource(engineContent, source, sharedDir, appliedChecksums) {
+    const sourceContent = await readText(source.sourcePath);
+    const engine = normalizeForChecksum(engineContent);
+    let composed;
+    try {
+        composed = await composeComponentSource(sourceContent, source.fileName, sharedDir);
+    }
+    catch {
+        // A missing fragment: no composed form exists. The other two
+        // comparisons below still apply.
+    }
+    if (composed !== undefined && normalizeForChecksum(composed) === engine) {
+        return 'composed-source';
+    }
+    const strippedEngine = stripExpandedFragments(engine);
+    if (listFragmentIncludes(sourceContent).length > 0 &&
+        strippedEngine === stripExpandedFragments(normalizeForChecksum(sourceContent))) {
+        return 'fragment-refresh';
+    }
+    const recorded = extractComponentChecksums(appliedChecksums, source.type, source.component)[source.fileName];
+    // Apply records the checksum of the (unexpanded) source it deployed, so
+    // an engine copy with its expansions collapsed hashes to that value
+    // exactly when it is that deployment.
+    if (recorded !== undefined && sha256Hex(strippedEngine) === recorded) {
+        return 'previous-deploy';
+    }
+    return undefined;
+}
+/**
+ * For each engine-relative path, decides whether its current engine content
+ * is a Furnace deployment of its component source (see
+ * {@link DeployedSourceMatch}). Paths with no component source, an
+ * unreadable engine copy, or content explained by none of the matches are
+ * absent from the result.
+ *
+ * @param root - Project root
+ * @param engineDir - Absolute engine directory
+ * @param files - Engine-relative paths to classify
+ * @returns Engine-relative path → match, for the matching paths only
+ */
+export async function matchDeployedComponentFiles(root, engineDir, files) {
+    const matches = new Map();
+    if (files.length === 0 || !(await furnaceConfigExists(root)))
+        return matches;
+    const sources = await mapDeployedComponentSources(root, await loadFurnaceConfig(root));
+    const { sharedDir } = getFurnacePaths(root);
+    const { appliedChecksums } = await loadFurnaceState(root);
+    for (const file of files) {
+        const source = sources.get(file);
+        if (source === undefined)
+            continue;
+        const enginePath = join(engineDir, file);
+        if (!(await pathExists(enginePath)))
+            continue;
+        const match = await matchDeployedSource(await readText(enginePath), source, sharedDir, appliedChecksums);
+        if (match !== undefined)
+            matches.set(file, match);
+    }
+    return matches;
+}