@hominis/fireforge 0.46.0 → 0.46.1

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

@@ -5,9 +5,9 @@
  * per-file LOC budget.
  *
  * Every helper here degrades gracefully: if the locale jar.mn is missing or
- * the FTL tree is non-standard, apply logs an ADVISORY `stepError`
+ * the FTL tree is non-standard, apply logs an advisory `stepError`
  * (`advisory: true`) rather than aborting the whole command. Advisory step
- * errors are reported as warnings and never trigger rollback — a missing
+ * errors are reported as warnings and never trigger rollback: a missing
  * jar.mn on a fork without a locale package must not block a working
  * `.mjs`/`.css` from shipping.
  */
@@ -44,12 +44,12 @@ function resolveSharedFtlPruneTarget(name, ftlDir) {
  *
  * A `localized: true` widget that opts into a feature-scoped `sharedFtl`
  * bundle (its strings live under `browser/...` and load via
- * `insertFTLIfNeeded`) must NOT carry a per-widget
+ * `insertFTLIfNeeded`) must not carry a per-widget
  * `locale/@AB_CD@/<chromeSubPath>/<name>.ftl` line. Such a line points at a
  * `.ftl` that does not exist, so `mach build` fails hard (`Cannot find
  * <chromeSubPath>/<name>.ftl`) and blocks every build.
  *
- * The pruned line is the per-widget toolkit entry only; the shared bundle's
+ * The pruned line is the per-widget toolkit entry only. The shared bundle's
  * own line (a different chrome sub-path / base name) is never matched, so
  * pruning one widget cannot orphan the shared bundle. Idempotent: when no
  * dangling entry exists the file is left untouched (no journal churn).
@@ -120,8 +120,8 @@ export async function describeSharedFtlPrune(ctx, config) {
  * in the locale jar.mn.
  *
  * Failure modes (missing jar.mn, regex write error) are captured as
- * stepErrors rather than thrown — a well-formed `.mjs`/`.css` must never be
- * blocked by a broken locale path.
+ * stepErrors rather than thrown, since a well-formed `.mjs`/`.css` must
+ * never be blocked by a broken locale path.
  */
 export async function applyCustomFtlFile(ctx, affectedPaths, stepErrors, rollbackJournal) {
     const { engineDir, name, componentDir, ftlDir } = ctx;
@@ -134,7 +134,7 @@ export async function applyCustomFtlFile(ctx, affectedPaths, stepErrors, rollbac
         await snapshotFile(rollbackJournal, ftlDest);
     }
     await copyFile(ftlSrc, ftlDest);
-    // Sibling pushes on this list are POSIX literals (`localeJarRel`); keep
+    // Sibling pushes on this list are POSIX literals (`localeJarRel`). Keep
     // the computed one in the same spelling.
     affectedPaths.push(normalizePathSlashes(relative(engineDir, ftlDest)));
     const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
@@ -185,7 +185,7 @@ export function describeLocaleFtlJarMnRegistration(name, ftlDir, ftlFile) {
 }
 /**
  * Drops the locale jar.mn entry for `fileName` when it's a `.ftl` whose
- * source workspace file has been deleted. Idempotent — absent entries are a
+ * source workspace file has been deleted. Idempotent: absent entries are a
  * no-op. Early-returns for `sharedFtl` components: the shared bundle is
  * owned elsewhere, and dropping its jar.mn line on our component's delete
  * would orphan every other participant.

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

@@ -3,7 +3,7 @@ import { type RollbackJournal } from './furnace-rollback.js';
 /**
  * Filter deciding which files in an override workspace directory are candidates
  * for copying into the engine. Exported so `furnace remove` can invert apply
- * using the exact same file set — the "files to restore" set is defined as the
+ * using the same file set: the "files to restore" set is defined as the
  * inverse of the "files apply would have written" set.
  */
 export declare function isOverrideCopyCandidate(entryName: string, type: OverrideComponentConfig['type']): boolean;
@@ -16,14 +16,14 @@ export declare function getOverrideEngineTargetPath(engineDir: string, config: O
  * Behaviour matches the per-file branch of `restoreOverrideEngineFiles` in
  * `furnace remove`: snapshot first, then either `git restore` (if the file
  * exists in HEAD) or hard-delete (if the override introduced the file). The
- * caller MUST guarantee `engineDir` is a git repository — this helper does
+ * caller must guarantee `engineDir` is a git repository. This helper does
  * not re-check, because both `furnace remove` and `furnace apply` already
  * own the precondition check at their entry points and re-checking on every
  * file would balloon git invocations.
  *
  * Returns the action taken so the caller can produce accurate user-facing
  * counts (`restored` vs `removed`). `noop` means the file was neither in HEAD
- * nor on disk, which can happen when the engine was reset out-of-band — the
+ * nor on disk, which can happen when the engine was reset out-of-band. The
  * caller should treat that as a successful no-op rather than an error.
  */
 export declare function restoreOverrideFileToBaseline(engineDir: string, enginePath: string, journal: RollbackJournal): Promise<'restored' | 'removed' | 'noop'>;
@@ -32,14 +32,14 @@ export declare function computeComponentChecksums(componentDir: string): Promise
 /**
  * Removes engine copies of files that the developer has deleted from a custom
  * component's workspace since the last apply. `.ftl` files live under the
- * shared Fluent tree (`engine/${FTL_DIR}`); everything else lives under
+ * shared Fluent tree (`engine/${FTL_DIR}`). Everything else lives under
  * `engine/${config.targetPath}`. Snapshots each removal into the journal so a
  * mid-apply failure can roll the engine back to its pre-undeploy state. Files
  * that are already missing from the engine are silently no-op (the engine
- * may have been reset out-of-band — refusing here would surface a confusing
- * error in a recovery path).
+ * may have been reset out-of-band, and refusing here would surface a
+ * confusing error in a recovery path).
  *
- * Does **not** touch jar.mn or customElements.js: registration churn is the
+ * Does not touch jar.mn or customElements.js: registration churn is the
  * caller's responsibility, since it must coordinate with the new file list
  * computed by the regular apply step that follows.
  */
@@ -51,9 +51,9 @@ export declare function undeployCustomFiles(engineDir: string, config: CustomCom
  * HEAD if it was a Firefox baseline file or hard-deletes it if the override
  * had introduced it.
  *
- * Requires `engineDir` to be a git repository — overrides cannot be inverted
+ * Requires `engineDir` to be a git repository: overrides cannot be inverted
  * without git HEAD as the source of truth. The caller is expected to have
- * already validated this precondition for the apply path; we re-check here
+ * already validated this precondition for the apply path. We re-check here
  * so unit tests that exercise this helper directly cannot accidentally
  * silent-fail on a non-git fixture.
  */

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

@@ -21,7 +21,7 @@ import { fileExistsInHead, restoreTrackedPath } from './git-file-ops.js';
 /**
  * Filter deciding which files in an override workspace directory are candidates
  * for copying into the engine. Exported so `furnace remove` can invert apply
- * using the exact same file set — the "files to restore" set is defined as the
+ * using the same file set: the "files to restore" set is defined as the
  * inverse of the "files apply would have written" set.
  */
 export function isOverrideCopyCandidate(entryName, type) {
@@ -46,18 +46,18 @@ export function getOverrideEngineTargetPath(engineDir, config, fileName, ftlDir)
  * Behaviour matches the per-file branch of `restoreOverrideEngineFiles` in
  * `furnace remove`: snapshot first, then either `git restore` (if the file
  * exists in HEAD) or hard-delete (if the override introduced the file). The
- * caller MUST guarantee `engineDir` is a git repository — this helper does
+ * caller must guarantee `engineDir` is a git repository. This helper does
  * not re-check, because both `furnace remove` and `furnace apply` already
  * own the precondition check at their entry points and re-checking on every
  * file would balloon git invocations.
  *
  * Returns the action taken so the caller can produce accurate user-facing
  * counts (`restored` vs `removed`). `noop` means the file was neither in HEAD
- * nor on disk, which can happen when the engine was reset out-of-band — the
+ * nor on disk, which can happen when the engine was reset out-of-band. The
  * caller should treat that as a successful no-op rather than an error.
  */
 export async function restoreOverrideFileToBaseline(engineDir, enginePath, journal) {
-    // Engine-relative paths are IDENTIFIERS here, not filesystem arguments:
+    // Engine-relative paths are identifiers here, not filesystem arguments:
     // they are handed to git, recorded in furnace state, and compared against
     // the POSIX paths furnace.json and jar.mn already carry. `relative()`
     // returns backslashes on Windows, so without this the same file has two
@@ -66,8 +66,8 @@ export async function restoreOverrideFileToBaseline(engineDir, enginePath, journ
     // Snapshot before mutation so a later rollback can undo both restoration
     // (writes whatever content we removed back) and deletion (recreates the
     // file). Snapshotting a missing path records `{ existed: false }`, which
-    // restoreFile turns into a delete — exactly the inverse of "we just
-    // wrote a file here", which is correct for the noop case too.
+    // restoreFile turns into a delete, the inverse of "we just wrote a file
+    // here", which is correct for the noop case too.
     await snapshotFile(journal, enginePath);
     if (await fileExistsInHead(engineDir, relPath)) {
         await restoreTrackedPath(engineDir, relPath);
@@ -88,7 +88,7 @@ export async function computeComponentChecksums(componentDir) {
             continue;
         if (entry.name === 'override.json')
             continue;
-        // The three extensions a component can deploy; anything else in the
+        // The three extensions a component can deploy. Anything else in the
         // workspace directory is not part of the component's checksum identity.
         const { name: entryName } = entry;
         if (!entryName.endsWith('.mjs') && !entryName.endsWith('.css') && !entryName.endsWith('.ftl'))
@@ -102,14 +102,14 @@ export async function computeComponentChecksums(componentDir) {
 /**
  * Removes engine copies of files that the developer has deleted from a custom
  * component's workspace since the last apply. `.ftl` files live under the
- * shared Fluent tree (`engine/${FTL_DIR}`); everything else lives under
+ * shared Fluent tree (`engine/${FTL_DIR}`). Everything else lives under
  * `engine/${config.targetPath}`. Snapshots each removal into the journal so a
  * mid-apply failure can roll the engine back to its pre-undeploy state. Files
  * that are already missing from the engine are silently no-op (the engine
- * may have been reset out-of-band — refusing here would surface a confusing
- * error in a recovery path).
+ * may have been reset out-of-band, and refusing here would surface a
+ * confusing error in a recovery path).
  *
- * Does **not** touch jar.mn or customElements.js: registration churn is the
+ * Does not touch jar.mn or customElements.js: registration churn is the
  * caller's responsibility, since it must coordinate with the new file list
  * computed by the regular apply step that follows.
  */
@@ -127,7 +127,7 @@ export async function undeployCustomFiles(engineDir, config, deletedFiles, ftlDi
             removed.push(normalizePathSlashes(relative(engineDir, enginePath)));
         }
         // When an `.ftl` is deleted from the workspace the corresponding locale
-        // jar.mn entry must also be dropped — otherwise the chrome URI points at
+        // jar.mn entry must also be dropped. Otherwise the chrome URI points at
         // a missing file and runtime Fluent resolution breaks silently.
         // `removeCustomFtlJarMnEntry` early-returns for `sharedFtl` components
         // (the shared bundle is owned elsewhere).
@@ -142,9 +142,9 @@ export async function undeployCustomFiles(engineDir, config, deletedFiles, ftlDi
  * HEAD if it was a Firefox baseline file or hard-deletes it if the override
  * had introduced it.
  *
- * Requires `engineDir` to be a git repository — overrides cannot be inverted
+ * Requires `engineDir` to be a git repository: overrides cannot be inverted
  * without git HEAD as the source of truth. The caller is expected to have
- * already validated this precondition for the apply path; we re-check here
+ * already validated this precondition for the apply path. We re-check here
  * so unit tests that exercise this helper directly cannot accidentally
  * silent-fail on a non-git fixture.
  */
@@ -158,11 +158,11 @@ export async function undeployOverrideFiles(engineDir, config, deletedFiles, ftl
     if (!(await isGitRepository(engineDir))) {
         throw new FurnaceError('Cannot undeploy override files: engine is not a git repository. Run "fireforge download" to initialise it.');
     }
-    // Note: we deliberately do not re-filter `deletedFiles` through
+    // Note: we do not re-filter `deletedFiles` through
     // `isOverrideCopyCandidate(fileName, config.type)`. A file recorded in
     // `previous` was already a valid copy candidate when it was deployed, and
     // re-filtering would block cleanup if the override type later flipped
-    // from `full` to `css-only` — exactly the case we need cleanup for.
+    // from `full` to `css-only`, which is the case we need cleanup for.
     const restored = [];
     const removed = [];
     for (const fileName of deletedFiles) {
@@ -228,7 +228,7 @@ export async function hasOverrideEngineDrift(ctx, config, cachedEngineChecksums)
                 return true;
             }
             if (cachedHash)
-                continue; // Hash match — skip full source comparison
+                continue; // Hash match, skip full source comparison
         }
         // Slow path: byte-compare engine content against workspace source
         const srcContent = normalizeForChecksum(await readText(join(componentDir, entry.name)));
@@ -259,7 +259,7 @@ export async function hasCustomEngineDrift(ctx, config) {
     // Registration drift: only check jar.mn entries for the file types that
     // actually exist in source. jarMn{Mjs,Css} are substring checks, so a
     // component with only .mjs (no .css) should not be flagged when jarMnCss
-    // is false — that is the expected post-apply state, not drift.
+    // is false. That is the expected post-apply state, not drift.
     const entries = await readdir(componentDir, { withFileTypes: true, encoding: 'utf8' });
     let hasMjs = false;
     let hasCss = false;
@@ -311,16 +311,16 @@ export async function applyCustomComponent(ctx, config, dryRun = false, rollback
     // must complete before any copy (they read the original content), but
     // independent files can be processed concurrently.
     const filesToCopy = entries.filter((entry) => isRegularFile(entry) && (entry.name.endsWith('.mjs') || entry.name.endsWith('.css')));
-    // Snapshot phase (serial — journal is not concurrent-safe for the same path)
+    // Snapshot phase (serial: journal is not concurrent-safe for the same path)
     for (const entry of filesToCopy) {
         const dest = join(targetDir, entry.name);
         if (rollbackJournal) {
             await snapshotFile(rollbackJournal, dest);
         }
     }
-    // Copy phase (parallel — independent file writes to different paths).
+    // Copy phase (parallel: independent file writes to different paths).
     // CSS files carrying @fireforge-include directives are written as their
-    // fragment-expanded form; the workspace source keeps only the directive,
+    // fragment-expanded form. The workspace source keeps only the directive,
     // so shared CSS stays single-sourced.
     const sharedDir = join(componentDir, '..', '..', SHARED_FRAGMENTS_DIR);
     await Promise.all(filesToCopy.map(async (entry) => {

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

@@ -52,7 +52,7 @@ export function logApplyResult(result, isDryRun) {
         }
     }
     // Patch-owned overwrite warnings print on every non-dry-run
-    // outcome — including the rolled-back branch, where the overwrite
+    // outcome, including the rolled-back branch, where the overwrite
     // happened before the rollback restored it and the operator still needs
     // to know the deployed copy was momentarily replaced.
     if (!isDryRun && result.warnings !== undefined) {

package/dist/src/core/furnace-apply-overwrite-warn.d.ts

@@ -1,18 +1,18 @@
 /**
  * Patch-owned overwrite warnings for `furnace apply`.
  *
- * For Furnace-managed components, apply OVERWRITES the deployed engine
+ * For Furnace-managed components, apply overwrites the deployed engine
  * copies with the `components/` sources. A fix made directly in `engine/` and
- * exported into a patch — but never back-ported to the component source — is
+ * exported into a patch (but never back-ported to the component source) is
  * silently undone by the next apply, and a plain drift line reads like
- * "someone's uncommitted work". This module detects that exact case BEFORE
- * the copy (deployed bytes differ from the component source AND the file is
+ * "someone's uncommitted work". This module detects that case before
+ * the copy (deployed bytes differ from the component source and the file is
  * patch-owned) and produces a per-file warning naming the file, the owning
  * patch, and the consequence.
  *
- * The per-file byte comparison already exists —
+ * The per-file byte comparison already exists:
  * `checkRegistrationConsistency` for custom components (fragment- and
- * ftl-aware) and the copy-candidate walk for overrides — so this module only
+ * ftl-aware) and the copy-candidate walk for overrides. This module only
  * surfaces what was previously computed and thrown away.
  */
 import type { CustomComponentConfig, OverrideComponentConfig } from '../types/furnace.js';
@@ -26,7 +26,7 @@ export interface PatchOwnedOverwriteWarning {
 }
 /**
  * Loads the file → owning-patch map for the overwrite warning.
- * A missing or unreadable patches manifest degrades to an empty map — the
+ * A missing or unreadable patches manifest degrades to an empty map. The
  * warning is advisory and must never block an apply.
  */
 export declare function loadPatchClaimsForApply(root: string): Promise<ReadonlyMap<string, readonly string[]>>;
@@ -55,8 +55,8 @@ export type PatchOwnedOverwriteProbe = {
 };
 /**
  * Finds deployed files this component's apply is about to overwrite whose
- * engine bytes differ from the component source AND that are patch-owned.
- * Probe failures degrade to a verbose line and an empty list — the apply
+ * engine bytes differ from the component source and that are patch-owned.
+ * Probe failures degrade to a verbose line and an empty list. The apply
  * itself must not fail because the warning probe could not run.
  */
 export declare function findPatchOwnedOverwrites(args: PatchOwnedOverwriteProbe): Promise<PatchOwnedOverwriteWarning[]>;

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

@@ -2,18 +2,18 @@
 /**
  * Patch-owned overwrite warnings for `furnace apply`.
  *
- * For Furnace-managed components, apply OVERWRITES the deployed engine
+ * For Furnace-managed components, apply overwrites the deployed engine
  * copies with the `components/` sources. A fix made directly in `engine/` and
- * exported into a patch — but never back-ported to the component source — is
+ * exported into a patch (but never back-ported to the component source) is
  * silently undone by the next apply, and a plain drift line reads like
- * "someone's uncommitted work". This module detects that exact case BEFORE
- * the copy (deployed bytes differ from the component source AND the file is
+ * "someone's uncommitted work". This module detects that case before
+ * the copy (deployed bytes differ from the component source and the file is
  * patch-owned) and produces a per-file warning naming the file, the owning
  * patch, and the consequence.
  *
- * The per-file byte comparison already exists —
+ * The per-file byte comparison already exists:
  * `checkRegistrationConsistency` for custom components (fragment- and
- * ftl-aware) and the copy-candidate walk for overrides — so this module only
+ * ftl-aware) and the copy-candidate walk for overrides. This module only
  * surfaces what was previously computed and thrown away.
  */
 import { readdir } from 'node:fs/promises';
@@ -31,7 +31,7 @@ import { loadPatchesManifest } from './patch-manifest.js';
 import { buildPatchClaims } from './status-classify.js';
 /**
  * Loads the file → owning-patch map for the overwrite warning.
- * A missing or unreadable patches manifest degrades to an empty map — the
+ * A missing or unreadable patches manifest degrades to an empty map. The
  * warning is advisory and must never block an apply.
  */
 export async function loadPatchClaimsForApply(root) {
@@ -104,8 +104,8 @@ async function findOverrideOverwrites(args) {
 }
 /**
  * Finds deployed files this component's apply is about to overwrite whose
- * engine bytes differ from the component source AND that are patch-owned.
- * Probe failures degrade to a verbose line and an empty list — the apply
+ * engine bytes differ from the component source and that are patch-owned.
+ * Probe failures degrade to a verbose line and an empty list. The apply
  * itself must not fail because the warning probe could not run.
  */
 export async function findPatchOwnedOverwrites(args) {

package/dist/src/core/furnace-apply-undeploy-actions.d.ts

@@ -1,7 +1,7 @@
 /**
  * Dry-run action builders for files deleted from a component workspace since
  * the last apply. Split out of `furnace-apply.ts` to stay under the per-file
- * line budget; the real undeploy paths stay in `furnace-apply-helpers.ts`.
+ * line budget. The real undeploy paths stay in `furnace-apply-helpers.ts`.
  */
 import type { CustomComponentConfig, DryRunAction, OverrideComponentConfig } from '../types/furnace.js';
 /** Plans the engine-restore actions for deleted override workspace files. */

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

@@ -2,7 +2,7 @@
 /**
  * Dry-run action builders for files deleted from a component workspace since
  * the last apply. Split out of `furnace-apply.ts` to stay under the per-file
- * line budget; the real undeploy paths stay in `furnace-apply-helpers.ts`.
+ * line budget. The real undeploy paths stay in `furnace-apply-helpers.ts`.
  */
 import { join } from 'node:path';
 import { getOverrideEngineTargetPath } from './furnace-apply-helpers.js';

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

@@ -8,8 +8,8 @@ export { computeComponentChecksums, prefixChecksums } from './furnace-apply-help
  * Named so consumers can refer to the shape directly instead of going
  * through `Awaited<ReturnType<typeof applyAllComponents>>`.
  *
- * `actions` is populated only on a dry run; `rollbackJournal` only when
- * `persistState: false` hands journal ownership back to the caller.
+ * `actions` is populated only on a dry run. `rollbackJournal` is set only
+ * when `persistState: false` hands journal ownership back to the caller.
  */
 export type ApplyAllComponentsResult = ApplyResult & {
     actions?: DryRunAction[];
@@ -44,6 +44,6 @@ export declare function applyAllComponents(root: string, dryRun?: boolean, optio
 }): Promise<ApplyAllComponentsResult>; /**
  * Shared context threaded through the batch apply loops. Bundles the state
  * both loops mutate (result/actions/checksums) with the immutable run
- * parameters; the 12–13 positional parameters this replaced let call sites
+ * parameters. The 12-13 positional parameters this replaced let call sites
  * drift and made every new parameter a two-signature change.
  */

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

@@ -23,8 +23,8 @@ export { computeComponentChecksums, prefixChecksums } from './furnace-apply-help
 /**
  * Records one component's checksums into the run-wide accumulator, under the
  * flattened `type/name/file` keys the state file stores. A Map keeps the
- * accumulation explicit — the previous `Object.assign` merges read as if they
- * replaced the accumulator rather than adding to it.
+ * accumulation explicit. The previous `Object.assign` merges read as if
+ * they replaced the accumulator rather than adding to it.
  */
 function recordComponentChecksums(accumulator, checksums, type, name) {
     for (const [key, value] of Object.entries(prefixChecksums(checksums, type, name))) {
@@ -59,8 +59,8 @@ async function applyOverrideBatch(ctx) {
             const changed = await hasComponentChanged(componentDir, previous, currentChecksums);
             if (!changed) {
                 // Fast path holds only if the engine still reflects what we deployed.
-                // reset/download/manual edits can silently erase engine files; the
-                // checksum record alone cannot detect that.
+                // reset/download/manual edits can silently erase engine files, and
+                // the checksum record alone cannot detect that.
                 const cachedEngine = extractComponentChecksums(state.engineChecksums, 'override', name);
                 const drifted = await hasOverrideEngineDrift({ engineDir, componentDir, ftlDir }, overrideConfig, cachedEngine);
                 if (!drifted) {
@@ -86,9 +86,9 @@ async function applyOverrideBatch(ctx) {
                 filesAffectedTotal.push(...restored, ...removed);
             }
             if (!dryRun) {
-                // Runs unconditionally — including when the component source
-                // changed — because the lost-work case is precisely a deployed
-                // engine edit that the incoming copy is about to replace.
+                // Runs unconditionally, including when the component source
+                // changed, because the lost-work case is a deployed engine edit
+                // that the incoming copy is about to replace.
                 recordOverwriteWarnings(result, await findPatchOwnedOverwrites({
                     type: 'override',
                     engineDir,
@@ -121,7 +121,7 @@ async function applyOverrideBatch(ctx) {
  * After undeploying deleted files, the in-engine jar.mn and
  * customElements.js still carry entries for the removed files. Re-sync them
  * by removing all of `name`'s jar.mn entries and re-adding only those that
- * still exist in the workspace; if the .mjs itself was deleted, also drop
+ * still exist in the workspace. If the .mjs itself was deleted, also drop
  * the customElements.js registration. Snapshots are taken under the same
  * journal so the undo path is symmetric with apply.
  */
@@ -141,13 +141,14 @@ async function reconcileCustomRegistrationAfterUndeploy(args) {
     await removeJarMnEntries(engineDir, name);
     const liveJarFiles = Object.keys(currentChecksums).filter((f) => f.endsWith('.mjs') || f.endsWith('.css'));
     if (liveJarFiles.length > 0) {
-        // applyCustomComponent has already added live entries; the remove above
-        // dropped them too, so re-add now to leave jar.mn in the correct state.
+        // applyCustomComponent has already added live entries, and the remove
+        // above dropped them too, so re-add now to leave jar.mn in the correct
+        // state.
         await addJarMnEntries(engineDir, name, liveJarFiles);
     }
     filesAffected.push(JAR_MN);
     // If the .mjs file itself was deleted, the customElements registration
-    // must go too — otherwise we leave a dangling import in the Pattern B
+    // must go too. Otherwise we leave a dangling import in the Pattern B
     // block that fails at runtime.
     if (deletedFiles.includes(`${name}.mjs`)) {
         if (rollbackJournal) {
@@ -245,9 +246,9 @@ async function applyCustomBatch(ctx, root, markerComment) {
                 filesAffectedTotal.push(...removed);
             }
             if (!dryRun) {
-                // Runs unconditionally — the `changed === true` path used to skip
-                // drift detection entirely, which is exactly when a deployed
-                // engine-only fix gets silently replaced (J6).
+                // Runs unconditionally. The `changed === true` path used to skip
+                // drift detection entirely, which is when a deployed engine-only
+                // fix gets silently replaced (J6).
                 recordOverwriteWarnings(result, await findPatchOwnedOverwrites({
                     type: 'custom',
                     root,
@@ -279,9 +280,9 @@ async function applyCustomBatch(ctx, root, markerComment) {
                 filesAffected: filesAffectedTotal,
                 ...(stepErrors.length > 0 ? { stepErrors } : {}),
             });
-            // Only store checksums when the component applied without BLOCKING
+            // 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 —
+            // the next run. Advisory errors (FTL degradation) still persist, since
             // re-applying cannot fix a fork that has no locale jar.mn.
             if (!dryRun && blockingStepErrors(stepErrors).length === 0) {
                 recordComponentChecksums(newChecksums, currentChecksums, 'custom', name);
@@ -328,7 +329,7 @@ export async function applyAllComponents(root, dryRun = false, options) {
     // When `markerComment` is unset in fireforge.json, default it to
     // `binaryName.toUpperCase()` so the furnace-emitted edits to upstream
     // files (e.g. customElements.js) carry a marker that satisfies
-    // `lintModificationComments` — that rule keys on
+    // `lintModificationComments`. That rule keys on
     // `${binaryName.toUpperCase()}:`. An explicit `markerComment` still wins.
     const forgeConfig = await loadConfig(root).catch(() => undefined);
     const markerComment = resolveFurnaceMarkerComment(forgeConfig);
@@ -338,7 +339,7 @@ export async function applyAllComponents(root, dryRun = false, options) {
         operationContext.registerJournal(rollbackJournal);
     }
     // Everything below this line can write to the engine. A real apply that
-    // reached it without a journal would have no way back — neither the
+    // reached it without a journal would have no way back: neither the
     // lifecycle wrapper's throw path nor the signal handler can restore what
     // was never captured. `operationContext` is legitimately absent for the
     // few callers that drive apply outside the wrapper, so the invariant is on
@@ -361,7 +362,7 @@ export async function applyAllComponents(root, dryRun = false, options) {
         }
     }
     // Patch-claim map for the overwrite warning: loaded once per
-    // apply. A missing/unreadable manifest degrades to an empty map — the
+    // apply. A missing/unreadable manifest degrades to an empty map. The
     // warning is advisory and must never block the apply.
     const patchClaims = await loadPatchClaimsForApply(root);
     const batchContext = {
@@ -390,7 +391,7 @@ export async function applyAllComponents(root, dryRun = false, options) {
     if (!dryRun && !hasApplyStepErrors && result.errors.length === 0) {
         await runPostApplyConsistencyChecks(root, config, result, ftlDir);
     }
-    // Recompute AFTER the consistency checks: they MUTATE entry.stepErrors
+    // 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 lets those failures
     // skip rollback and persist checksums for a component known to be
@@ -442,6 +443,6 @@ export async function applyAllComponents(root, dryRun = false, options) {
 } /**
  * Shared context threaded through the batch apply loops. Bundles the state
  * both loops mutate (result/actions/checksums) with the immutable run
- * parameters; the 12–13 positional parameters this replaced let call sites
+ * parameters. The 12-13 positional parameters this replaced let call sites
  * drift and made every new parameter a two-signature change.
  */

package/dist/src/core/furnace-checksum-utils.d.ts

@@ -3,10 +3,10 @@ export declare function extractComponentChecksums(allChecksums: Record<string, s
 /** Prefixes component checksums so they can be stored in the flattened state format. */
 export declare function prefixChecksums(checksums: Record<string, string>, type: string, name: string): Record<string, string>;
 /**
- * Returns the filenames present in `previous` that are absent from `current`
- * — i.e. files we know we deployed last time but the workspace has since
- * deleted. The order of returned names is intentionally stable
- * (sorted alphabetically) so test snapshots and CLI output are deterministic.
+ * Returns the filenames present in `previous` that are absent from
+ * `current`, i.e. files we know we deployed last time but the workspace has
+ * since deleted. The order of returned names is stable (sorted
+ * alphabetically) so test snapshots and CLI output are deterministic.
  */
 export declare function diffDeletedFiles(previous: Record<string, string>, current: Record<string, string>): string[];
 /**
@@ -15,7 +15,7 @@ export declare function diffDeletedFiles(previous: Record<string, string>, curre
  * Strips a leading BOM and folds CRLF to LF, so a file that differs from its
  * deployed copy only by line endings or a byte-order mark is not reported as
  * drift. Every comparison that decides "has this component changed?" must
- * use it — otherwise `furnace status` and `furnace validate` can disagree
+ * use it. Otherwise `furnace status` and `furnace validate` can disagree
  * with `apply`'s skip fast-path about the same pair of files on a CRLF
  * checkout.
  *

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

@@ -22,10 +22,10 @@ export function prefixChecksums(checksums, type, name) {
     return result;
 }
 /**
- * Returns the filenames present in `previous` that are absent from `current`
- * — i.e. files we know we deployed last time but the workspace has since
- * deleted. The order of returned names is intentionally stable
- * (sorted alphabetically) so test snapshots and CLI output are deterministic.
+ * Returns the filenames present in `previous` that are absent from
+ * `current`, i.e. files we know we deployed last time but the workspace has
+ * since deleted. The order of returned names is stable (sorted
+ * alphabetically) so test snapshots and CLI output are deterministic.
  */
 export function diffDeletedFiles(previous, current) {
     const deleted = [];
@@ -42,7 +42,7 @@ export function diffDeletedFiles(previous, current) {
  * Strips a leading BOM and folds CRLF to LF, so a file that differs from its
  * deployed copy only by line endings or a byte-order mark is not reported as
  * drift. Every comparison that decides "has this component changed?" must
- * use it — otherwise `furnace status` and `furnace validate` can disagree
+ * use it. Otherwise `furnace status` and `furnace validate` can disagree
  * with `apply`'s skip fast-path about the same pair of files on a CRLF
  * checkout.
  *

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

@@ -1,7 +1,7 @@
 /**
  * Parser for the `custom` entries in furnace.json. Extracted from
  * `furnace-config.ts` so the main config module stays under the
- * per-file LOC budget — the custom-component schema has grown to
+ * per-file LOC budget. The custom-component schema has grown to
  * carry opt-in fields (`composes`, `keyboardCovered`, `sharedFtl`) that
  * each add their own validation branch.
  */

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

@@ -2,7 +2,7 @@
 /**
  * Parser for the `custom` entries in furnace.json. Extracted from
  * `furnace-config.ts` so the main config module stays under the
- * per-file LOC budget — the custom-component schema has grown to
+ * per-file LOC budget. The custom-component schema has grown to
  * carry opt-in fields (`composes`, `keyboardCovered`, `sharedFtl`) that
  * each add their own validation branch.
  */
@@ -65,7 +65,7 @@ export function parseCustomConfig(data, name) {
             ? { composes: parseStringArray(data['composes'], `${name}.composes`) }
             : {}),
         ...(data['keyboardCovered'] === true ? { keyboardCovered: true } : {}),
-        // Explicit `kind: "element"` is the default; normalize it away so the
+        // Explicit `kind: "element"` is the default. Normalize it away so the
         // stored config carries the field only when it changes behavior.
         ...(data['kind'] === 'library' ? { kind: 'library' } : {}),
         ...(sharedFtl !== undefined ? { sharedFtl } : {}),

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

@@ -60,7 +60,7 @@ function orderComponentMapLikeExisting(existing, next) {
 export function orderFurnaceConfigForWrite(existing, config) {
     // FurnaceConfig is plain parsed-JSON data, but as an interface it carries
     // no index signature, so the compiler cannot verify the JsonObject
-    // contract structurally — hence the double assertion. This is the one
+    // contract structurally, hence the double assertion. This is the one
     // place a typed furnace config re-enters the raw-document world.
     // eslint-disable-next-line no-restricted-syntax -- see above
     const next = config;

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

@@ -6,12 +6,12 @@
 /**
  * Validates a `tokenHostDocuments` raw value. Each entry must be a non-empty
  * relative path contained in the engine tree. Throws `FurnaceError` on
- * violation; does nothing for `undefined` (field is optional).
+ * violation. Does nothing for `undefined` (field is optional).
  */
 export declare function validateTokenHostDocuments(raw: unknown): void;
 /**
  * Validates a `runtimeVariables` raw value. Each entry must start with `--`
- * (it is a CSS custom property name). Throws `FurnaceError` on violation;
- * does nothing for `undefined` (field is optional).
+ * (it is a CSS custom property name). Throws `FurnaceError` on violation.
+ * Does nothing for `undefined` (field is optional).
  */
 export declare function validateRuntimeVariables(raw: unknown): void;