@hominis/fireforge 0.51.0 → 0.53.0

package/dist/src/core/token-manager.js

@@ -17,7 +17,7 @@ import { findVariantBlockDeclaration, insertVariantDeclaration, validateVariantS
  *
  * Derived from {@link TOKEN_MODES} so the runtime allowlist and the type
  * cannot drift: adding a member here without updating the list (or the
- * reverse) is no longer possible, because there is only one list.
+ * reverse) is impossible, because there is only one list.
  */
 export const TOKEN_MODES = ['auto', 'static', 'override'];
 /** Narrows an arbitrary string to a {@link TokenMode}. */
@@ -109,12 +109,10 @@ function normalizeVariantOption(options) {
  * Narrows {@link AddTokenOptions.category} for the base-declaration path,
  * which cannot proceed without one.
  *
- * `--category` used to be unconditionally required, including under
- * `--variant`, where the declaration is routed into a `:root<selector>`
- * block and the category names nothing about where the token lands. The
- * requirement existed so the argument would not be silently discarded,
- * a fair goal that produced a mandatory argument describing nothing. Under
- * a variant it is now optional. Everywhere else this states the reason
+ * `--category` is optional under `--variant`, where the declaration is
+ * routed into a `:root<selector>` block and the category names nothing
+ * about where the token lands, so requiring it there would make a
+ * mandatory argument describing nothing. Everywhere else this states the reason
  * rather than leaving commander to print a bare "required option not
  * specified".
  *

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

@@ -28,12 +28,12 @@ export type VariantValidation = {
  * Boolean-attribute fragments are returned unchanged.
  *
  * Structure is decided by {@link rootAttributeSelector}, the matcher's own
- * parse, rather than by a second regex. 0.44.2 widened
- * the matcher to consume consecutive `[…]` groups and stop at a pseudo-class
- * tail, and the validator did not move with it, so
- * `:root[data-skin="humanist"]:not([data-private])` was a block the tool
- * could find but would not let you name. Running both halves off one parse
- * is what stops them drifting apart again. Character-level safety stays a
+ * parse, rather than by a second regex. The matcher consumes consecutive
+ * `[…]` groups and stops at a pseudo-class tail, and a separate validator
+ * that does not follow it leaves blocks such as
+ * `:root[data-skin="humanist"]:not([data-private])` findable but
+ * unnameable. Running both halves off one parse keeps them from drifting
+ * apart. Character-level safety stays a
  * separate, per-group check, because the matcher finds bracket boundaries
  * and validates no characters at all.
  *

package/dist/src/core/token-variant.js

@@ -68,12 +68,12 @@ function normalizeAttributeFragment(group) {
  * Boolean-attribute fragments are returned unchanged.
  *
  * Structure is decided by {@link rootAttributeSelector}, the matcher's own
- * parse, rather than by a second regex. 0.44.2 widened
- * the matcher to consume consecutive `[…]` groups and stop at a pseudo-class
- * tail, and the validator did not move with it, so
- * `:root[data-skin="humanist"]:not([data-private])` was a block the tool
- * could find but would not let you name. Running both halves off one parse
- * is what stops them drifting apart again. Character-level safety stays a
+ * parse, rather than by a second regex. The matcher consumes consecutive
+ * `[…]` groups and stops at a pseudo-class tail, and a separate validator
+ * that does not follow it leaves blocks such as
+ * `:root[data-skin="humanist"]:not([data-private])` findable but
+ * unnameable. Running both halves off one parse keeps them from drifting
+ * apart. Character-level safety stays a
  * separate, per-group check, because the matcher finds bracket boundaries
  * and validates no characters at all.
  *
@@ -194,7 +194,7 @@ function findVariantBlock(lines, variant) {
         if (selector === undefined || canonicalSelector(selector.attributes) !== want)
             continue;
         // An unqualified request still matches a qualified block: that is the
-        // 0.44.2 behaviour `variantBlockQualifier` exists to report, since
+        // behaviour `variantBlockQualifier` exists to report, since
         // silently skipping the block is the worse failure. A request that names
         // a qualifier, though, means it, so it must match.
         if (wantQualifier !== '' && canonicalSelector(selector.qualifier) !== wantQualifier)

package/dist/src/core/typecheck-shim.d.ts

@@ -82,7 +82,8 @@ export interface ComposedShim {
  *   shim path
  * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
  * @param options - `litTypes` appends {@link LIT_TYPES_SHIM} after the
- *   built-in shim (before the extra shim, which can still merge into it)
+ *   built-in shim (before the extra shim, which can still merge into it),
+ *   and {@link LOOSE_LIT_SHIM} otherwise
  */
 export declare function composeShimSource(projectRoot: string, extraShimPath: string | undefined, options?: {
     litTypes?: boolean | undefined;

package/dist/src/core/typecheck-shim.js

@@ -291,12 +291,17 @@ export const UNDEFINED_IDENTIFIER_CODES = new Set([
 ]);
 /**
  * Typed Lit, opt-in through `typecheck.litTypes`. Declares the two chrome
- * modules widgets import Lit from, so they no longer fall to the
+ * modules widgets import Lit from, so they do not fall to the
  * `chrome:*` wildcard as `any`: `LitElement` (with `ReactiveElement`'s
  * lifecycle) and `MozLitElement` carry closed member lists, so a misspelt
  * member of a widget host is TS2339, as `Cu` is in the built-in shim.
- * Template helpers and directives stay loose. A project shim can merge
- * members into `LitElementShimMembers`; a project whose jsconfig `paths`
+ * Template helpers and directives stay loose. The global
+ * `MozLitElementWith<Extra>` types a widget's query getters and
+ * `static properties` members: the widget casts its `MozLitElement` import
+ * to it before extending ({@link LOOSE_LIT_SHIM} keeps it `any` without
+ * typed Lit). A project
+ * shim can merge members into `LitElementShimMembers`; a project whose
+ * jsconfig `paths`
  * maps these URLs to the real sources gets those instead, since a resolved
  * file wins over an ambient module.
  */
@@ -399,6 +404,24 @@ declare module 'chrome://global/content/lit-utils.mjs' {
   export const SelectControlBaseElement: any;
   export const SelectControlItemMixin: any;
 }
+// MozLitElement with instance members Extra: what a widget casts its base
+// to for the getters static queries installs (and properties it declares
+// only in static properties). A class field would redefine a query getter
+// and throw, and a constructor declaration reads it before renderRoot.
+type MozLitElementWith<Extra> = Pick<
+  typeof import('chrome://global/content/lit-utils.mjs').MozLitElement,
+  keyof typeof import('chrome://global/content/lit-utils.mjs').MozLitElement
+> &
+  (new () => import('chrome://global/content/lit-utils.mjs').MozLitElement & Extra);
+`;
+/**
+ * Without typed Lit, `MozLitElementWith<Extra>` is `any`, as the base it
+ * casts is: the same widget source checks under per-patch checkJs and a
+ * project typecheck that leaves `litTypes` off.
+ */
+const LOOSE_LIT_SHIM = `
+// FireForge loose Lit (typecheck.litTypes off): see typecheck-shim.ts.
+type MozLitElementWith<Extra> = any;
 `;
 /** Hint appended to reported undefined-identifier diagnostics. */
 export const UNDEFINED_IDENTIFIER_HINT = '(undefined identifier — import or declare it, add the global to the extra shim, ' +
@@ -462,10 +485,11 @@ async function inlineTripleSlashReferences(source, baseDir, seen) {
  *   shim path
  * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
  * @param options - `litTypes` appends {@link LIT_TYPES_SHIM} after the
- *   built-in shim (before the extra shim, which can still merge into it)
+ *   built-in shim (before the extra shim, which can still merge into it),
+ *   and {@link LOOSE_LIT_SHIM} otherwise
  */
 export async function composeShimSource(projectRoot, extraShimPath, options = {}) {
-    const base = options.litTypes === true ? `${FIREFOX_GLOBALS_SHIM}\n${LIT_TYPES_SHIM}` : FIREFOX_GLOBALS_SHIM;
+    const base = `${FIREFOX_GLOBALS_SHIM}\n${options.litTypes === true ? LIT_TYPES_SHIM : LOOSE_LIT_SHIM}`;
     if (!extraShimPath) {
         return { source: base, extraShimAppended: false };
     }

package/dist/src/core/wire-destroy.d.ts

@@ -11,7 +11,7 @@
  */
 export declare function addDestroyAST(content: string, expression: string, marker?: string): string;
 /**
- * Legacy regex/line-based implementation preserved as fallback.
+ * Regex/line-based fallback implementation.
  */
 export declare function legacyAddDestroy(content: string, expression: string, marker?: string): string;
 /**

package/dist/src/core/wire-destroy.js

@@ -65,7 +65,7 @@ export function addDestroyAST(content, expression, marker = DEFAULT_MARKER) {
     return ms.toString();
 }
 /**
- * Legacy regex/line-based implementation preserved as fallback.
+ * Regex/line-based fallback implementation.
  */
 export function legacyAddDestroy(content, expression, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);

package/dist/src/core/wire-dom-fragment.js

@@ -66,7 +66,7 @@ export async function probeDomFragmentInsertionPoint(engineDir, domFilePath, tar
         // dry-run is allowed to proceed too.
         return;
     }
-    // Check the tokenised and legacy insertion paths symmetrically with
+    // Check the tokenised and line-based insertion paths symmetrically with
     // the real run. Either helper returning without throwing is sufficient
     // evidence that the real run can land the directive.
     addDomFragmentTokenized(content, includeDirective);

package/dist/src/core/wire-init.d.ts

@@ -13,7 +13,7 @@
  */
 export declare function addInitAST(content: string, expression: string, after?: string, marker?: string): string;
 /**
- * Legacy regex/line-based implementation preserved as fallback.
+ * Regex/line-based fallback implementation.
  */
 export declare function legacyAddInit(content: string, expression: string, after?: string, marker?: string): string;
 /**

package/dist/src/core/wire-init.js

@@ -112,7 +112,7 @@ export function addInitAST(content, expression, after, marker = DEFAULT_MARKER)
     return ms.toString();
 }
 /**
- * Legacy regex/line-based implementation preserved as fallback.
+ * Regex/line-based fallback implementation.
  */
 export function legacyAddInit(content, expression, after, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);

package/dist/src/core/wire-subscript.d.ts

@@ -10,7 +10,7 @@
  */
 export declare function addSubscriptAST(content: string, name: string, marker?: string): string;
 /**
- * Legacy regex/line-based implementation preserved as fallback.
+ * Regex/line-based fallback implementation.
  */
 export declare function legacyAddSubscript(content: string, name: string, marker?: string): string;
 /**

package/dist/src/core/wire-subscript.js

@@ -73,7 +73,7 @@ export function addSubscriptAST(content, name, marker = DEFAULT_MARKER) {
     return ms.toString();
 }
 /**
- * Legacy regex/line-based implementation preserved as fallback.
+ * Regex/line-based fallback implementation.
  */
 export function legacyAddSubscript(content, name, marker = DEFAULT_MARKER) {
     const lines = content.split('\n');

package/dist/src/core/wire-utils.d.ts

@@ -104,7 +104,7 @@ export declare function walkToTryBlockEnd(lines: string[], startLine: number, op
 }): number;
 /**
  * Scans the entire file and returns the net brace balance so callers can
- * assert that a legacy fallback mutation did not silently introduce or
+ * assert that a line-based fallback mutation did not silently introduce or
  * drop a `{` / `}`. The helper reuses {@link countBraceDepth} so strings,
  * comments, and regex literals are handled consistently with the walker.
  *
@@ -117,7 +117,7 @@ export declare function computeFileBraceBalance(content: string): {
     balanced: boolean;
 };
 /**
- * Round-trip guard used after a legacy fallback mutation: if the file's
+ * Round-trip guard used after a line-based fallback mutation: if the file's
  * net brace balance drifts between `before` and `after`, something went
  * wrong and the fallback is refusing to write a corrupted file. Expects
  * the delta to be exactly zero, since wire fallbacks only insert whole

package/dist/src/core/wire-utils.js

@@ -159,7 +159,7 @@ export function tokenizeXhtml(lines) {
     });
 }
 // ---------------------------------------------------------------------------
-// Legacy (line-based) helpers, shared by fallback implementations in
+// Line-based helpers, shared by fallback implementations in
 // the wire target modules.  Extracted to reduce duplication and make the brace-
 // walking logic independently testable.
 // ---------------------------------------------------------------------------
@@ -224,7 +224,7 @@ export function walkToTryBlockEnd(lines, startLine, options) {
 }
 /**
  * Scans the entire file and returns the net brace balance so callers can
- * assert that a legacy fallback mutation did not silently introduce or
+ * assert that a line-based fallback mutation did not silently introduce or
  * drop a `{` / `}`. The helper reuses {@link countBraceDepth} so strings,
  * comments, and regex literals are handled consistently with the walker.
  *
@@ -244,7 +244,7 @@ export function computeFileBraceBalance(content) {
     return { depth, balanced: depth === 0 };
 }
 /**
- * Round-trip guard used after a legacy fallback mutation: if the file's
+ * Round-trip guard used after a line-based fallback mutation: if the file's
  * net brace balance drifts between `before` and `after`, something went
  * wrong and the fallback is refusing to write a corrupted file. Expects
  * the delta to be exactly zero, since wire fallbacks only insert whole

package/dist/src/errors/base.d.ts

@@ -80,7 +80,7 @@ export declare class InternalInvariantError extends FireForgeError {
     get userMessage(): string;
 }
 /**
- * Raised when a legacy regex/brace-depth fallback parser decides it
+ * Raised when a regex/brace-depth fallback parser decides it
  * cannot safely perform its mutation, e.g. because a block it expected
  * to walk never closes, because the inserted result fails a round-trip
  * brace balance check, or because an expected pattern is missing.

package/dist/src/errors/base.js

@@ -106,7 +106,7 @@ export class InternalInvariantError extends FireForgeError {
     }
 }
 /**
- * Raised when a legacy regex/brace-depth fallback parser decides it
+ * Raised when a regex/brace-depth fallback parser decides it
  * cannot safely perform its mutation, e.g. because a block it expected
  * to walk never closes, because the inserted result fails a round-trip
  * brace balance check, or because an expected pattern is missing.

package/dist/src/errors/rebase.d.ts

@@ -33,7 +33,7 @@ export declare class CorruptRebaseSessionError extends RebaseError {
 }
 /**
  * Thrown by `rebase --dry-run` when the replay rejects at least one patch.
- * A dry run that exited 0 regardless used to read as "the rebase is ready".
+ * A dry run that exited 0 regardless would read as "the rebase is ready".
  */
 export declare class RebaseDryRunRejectError extends RebaseError {
     readonly rejected: readonly string[];

package/dist/src/errors/rebase.js

@@ -51,7 +51,7 @@ export class CorruptRebaseSessionError extends RebaseError {
 }
 /**
  * Thrown by `rebase --dry-run` when the replay rejects at least one patch.
- * A dry run that exited 0 regardless used to read as "the rebase is ready".
+ * A dry run that exited 0 regardless would read as "the rebase is ready".
  */
 export class RebaseDryRunRejectError extends RebaseError {
     rejected;

package/dist/src/types/commands/options.d.ts

@@ -516,6 +516,8 @@ export interface PatchSplitOptions extends Confirmable, PatchLockWaitable, Unsaf
     skipLint?: boolean;
     /** Where a refusal writes its one `--from`-ready declaration report. */
     declarationsOut?: string;
+    /** Write the committed old-to-new filename map of renumbered patches here as JSON. */
+    mapOut?: string;
 }
 /**
  * Options for the `fireforge patch move-files` subcommand. Without
@@ -541,6 +543,16 @@ export interface PatchMoveFilesOptions extends Confirmable, PatchLockWaitable, U
     skipLint?: boolean;
     /** Where a refusal writes its one `--from`-ready declaration report. */
     declarationsOut?: string;
+    /**
+     * New engine files no patch owns, adopted into the destination in the
+     * same transaction (engine-relative, repeatable).
+     */
+    scanFile?: string[];
+    /**
+     * Allow the move to empty the source: re-point the declarations it owns
+     * to the destination and retire its slot. Not valid with `create`.
+     */
+    retireEmpty?: boolean;
 }
 /**
  * Options for the rebase command.
@@ -673,8 +685,8 @@ export interface TestOptions extends EngineLockWaitable {
      * build would overwrite engine content recorded in neither a patch body
      * nor the pristine baseline. Same meaning as `fireforge build`'s flag of
      * the same name. A scripted `test --build` is exactly the shape the
-     * multi-session hazard shows up in, and until now it was the one shape
-     * that could not arm the refusal. Valid only with `--build`/`--build-only`.
+     * multi-session hazard shows up in, so it must be able to arm the
+     * refusal too. Valid only with `--build`/`--build-only`.
      */
     refuseUnexportedDrift?: boolean;
     /**
@@ -1073,7 +1085,7 @@ export interface PatchRenameOptions extends Confirmable, DryRunnable, PatchLockW
     /**
      * New category (validated against configured categories). Rewrites
      * the filename prefix and the manifest row in one transaction, so
-     * recategorising no longer requires `patch delete` + fresh export.
+     * recategorising does not require `patch delete` + fresh export.
      */
     category?: string;
     /**
@@ -1096,6 +1108,17 @@ export interface PatchReorderOptions extends PatchLockWaitable {
     to?: number;
     before?: string;
     after?: string;
+    /**
+     * Shift a run of patches up by this many orders (`--shift <n> --from
+     * <order> [--through <order>]`) instead of moving one patch.
+     */
+    shift?: number;
+    /** First order of the run `shift` moves. */
+    from?: number;
+    /** Last order of the run `shift` moves (default: the end of the run). */
+    through?: number;
+    /** Write the committed old-to-new filename map here as JSON. */
+    mapOut?: string;
     yes?: boolean;
     dryRun?: boolean;
     forceUnsafe?: boolean;

package/dist/src/types/config.d.ts

@@ -433,11 +433,10 @@ export interface PatchLintFileSizeTier {
 /**
  * Overrides for the `file-too-large` thresholds, per file class.
  *
- * These were module constants until 0.45.0, and nothing in `fireforge.json`
- * could move them. That is a problem specifically because the recommended
- * gate posture is `--max-warnings 0`: under it the `warning` band is not a
- * soft limit at all, so a project whose controllers legitimately sit a few
- * lines over 750 has a hard failure with no dial, at exactly the moment
+ * Configurable because the recommended gate posture is `--max-warnings 0`:
+ * under it the `warning` band is not a soft limit at all, so with fixed
+ * thresholds a project whose controllers legitimately sit a few lines over
+ * 750 would have a hard failure with no dial, at exactly the moment
  * someone is deciding whether to restructure a file.
  */
 export interface PatchLintFileSizeThresholds {
@@ -466,8 +465,7 @@ export interface PatchLintPatchSizeTier {
 /**
  * Overrides for the patch-size thresholds, per tier.
  *
- * Module constants until 0.50.0. The defaults are the old constants: lines
- * general 800/1500/3000, test 1500/3000/6000, branding 8000/18000/30000;
+ * Defaults: lines general 800/1500/3000, test 1500/3000/6000, branding 8000/18000/30000;
  * files warn above 5 (general, test) or 60 (branding). The files triple has
  * no notice or error band by default: an unset `files.notice` follows the
  * effective `files.warning`, and an unset `files.error` never fires.

package/dist/src/types/furnace.d.ts

@@ -115,6 +115,13 @@ export interface FurnaceValidationException {
      * check for every other element of the component.
      */
     tag?: string;
+    /**
+     * Narrows the exception to the findings in this module file of the
+     * component (a finding's `files`), by file name: a vendored bundle whose
+     * bytes are pinned can be accepted without muting the check for the
+     * authored modules beside it.
+     */
+    file?: string;
     /** Why the finding is accepted. Required: the entry is the review record. */
     reason: string;
 }
@@ -379,6 +386,8 @@ export interface ValidationIssue {
     message: string;
     /** Element tags the finding is about, when it is about particular elements. */
     tags?: string[];
+    /** Component module files the finding is in (`hardcoded-text`), by file name. */
+    files?: string[];
 }
 /** Resolved test-harness selection for a `furnace create` run. */
 export type ResolvedTestStyle = 'mochikit' | 'browser-chrome' | 'xpcshell' | 'none';

package/dist/src/utils/options.js

@@ -71,8 +71,8 @@ export const WAIT_LOCK_ENV_VAR = 'FIREFORGE_WAIT_LOCK';
 /**
  * Bounds shared by the flag and the environment variable. The ceiling is a
  * day: on a shared engine a re-export or `test --build` queued behind a
- * peer's long series can need more than the hour the cap used to be, and a
- * longer wait then had to be a requeue after exit 15.
+ * peer's long series can need more than an hour, and a cap below that turns
+ * a longer wait into a requeue after exit 15.
  */
 const MIN_WAIT_LOCK_SECONDS = 1;
 export const MAX_WAIT_LOCK_SECONDS = 86_400;

package/dist/src/utils/process.js

@@ -173,7 +173,7 @@ async function spawnTracked(spec) {
         let rejection;
         child.on('error', (error) => {
             // Abort/startup failure: make sure a partially-started tree does not
-            // outlive the dispatch (a mach dying at startup used to strand
+            // outlive the dispatch (a mach dying at startup would otherwise strand
             // multiprocessing workers).
             if (options.processGroup === true) {
                 killProcessTree(child, 'SIGKILL', usesProcessGroup);
@@ -229,7 +229,7 @@ export async function execStream(command, args, options = {}) {
         args,
         options,
         graceMs: 1500,
-        // A detached group leader no longer receives the terminal's Ctrl+C, so
+        // A detached group leader does not receive the terminal's Ctrl+C, so
         // the forwarder is mandatory (not just graceful-UX) when processGroup
         // is set. A plain streamed child does not get one.
         forwardWithoutProcessGroup: false,

package/dist/src/utils/regex.d.ts

@@ -18,7 +18,7 @@ export declare function hasRawCssColors(content: string): boolean;
  * the line is blanked, corrupting whatever lint pass consumes the stripped
  * text. The source is tokenized as a module, then as a script. Firefox
  * chrome sources can contain constructs acorn tokenizes under neither goal.
- * Those fall back to the legacy regex strip, which handles strings but not
+ * Those fall back to the regex-only strip, which handles strings but not
  * regex literals.
  */
 export declare function stripJsComments(source: string): string;
@@ -30,7 +30,7 @@ export declare function stripJsComments(source: string): string;
  * legacy octal escape is a tokenizer error only under the module goal.
  * Callers that must not under-count when tokenizing fails (the code-line
  * size metric) read the `null` and pick their own fallback rather than the
- * legacy regex strip, which can blank code.
+ * regex-only strip, which can blank code.
  */
 export declare function stripJsCommentsParsed(source: string): string | null;
 /**

package/dist/src/utils/regex.js

@@ -34,7 +34,7 @@ export function hasRawCssColors(content) {
  * the line is blanked, corrupting whatever lint pass consumes the stripped
  * text. The source is tokenized as a module, then as a script. Firefox
  * chrome sources can contain constructs acorn tokenizes under neither goal.
- * Those fall back to the legacy regex strip, which handles strings but not
+ * Those fall back to the regex-only strip, which handles strings but not
  * regex literals.
  */
 export function stripJsComments(source) {
@@ -48,7 +48,7 @@ export function stripJsComments(source) {
  * legacy octal escape is a tokenizer error only under the module goal.
  * Callers that must not under-count when tokenizing fails (the code-line
  * size metric) read the `null` and pick their own fallback rather than the
- * legacy regex strip, which can blank code.
+ * regex-only strip, which can blank code.
  */
 export function stripJsCommentsParsed(source) {
     const comments = collectJsComments(source, 'module') ?? collectJsComments(source, 'script');
@@ -91,7 +91,7 @@ function collectJsComments(source, sourceType) {
     return comments;
 }
 /**
- * Legacy pure-regex comment strip, used only when acorn cannot tokenize
+ * Pure-regex comment strip, used only when acorn cannot tokenize
  * the source (preprocessor directives, syntax errors). Strings survive.
  * Regex literals are not modeled, so `//` inside a regex blanks the rest
  * of the line.

package/dist/src/utils/sleep.d.ts

@@ -1,12 +1,11 @@
 /**
  * The single awaitable delay used across FireForge.
  *
- * Five modules had grown a private copy of this (`sleep`, `delay`,
- * `sweepDelay`) and four more sites inlined
- * `new Promise((resolve) => setTimeout(resolve, ms))`. The copies disagreed on
- * the one property that actually matters (whether the pending timer holds
- * the event loop open) and the disagreement was invisible at each call site.
- * Both behaviours now live here, and callers state which one they need.
+ * Callers use this rather than a private `sleep`/`delay` or an inline
+ * `new Promise((resolve) => setTimeout(resolve, ms))`, because such copies
+ * disagree on the one property that actually matters (whether the pending
+ * timer holds the event loop open) and the disagreement is invisible at each
+ * call site. Both behaviours live here, and callers state which one they need.
  *
  * The default is a ref'd timer, because the dangerous mistake is the other
  * one: an unref'd delay awaited between a SIGTERM and its escalation lets Node

package/dist/src/utils/sleep.js

@@ -2,12 +2,11 @@
 /**
  * The single awaitable delay used across FireForge.
  *
- * Five modules had grown a private copy of this (`sleep`, `delay`,
- * `sweepDelay`) and four more sites inlined
- * `new Promise((resolve) => setTimeout(resolve, ms))`. The copies disagreed on
- * the one property that actually matters (whether the pending timer holds
- * the event loop open) and the disagreement was invisible at each call site.
- * Both behaviours now live here, and callers state which one they need.
+ * Callers use this rather than a private `sleep`/`delay` or an inline
+ * `new Promise((resolve) => setTimeout(resolve, ms))`, because such copies
+ * disagree on the one property that actually matters (whether the pending
+ * timer holds the event loop open) and the disagreement is invisible at each
+ * call site. Both behaviours live here, and callers state which one they need.
  *
  * The default is a ref'd timer, because the dangerous mistake is the other
  * one: an unref'd delay awaited between a SIGTERM and its escalation lets Node

package/dist/src/utils/validation.js

@@ -20,8 +20,8 @@ export function isString(value) {
  */
 export function isNumber(value) {
     // Number.isFinite matches the documented contract: NaN and ±Infinity are
-    // excluded (a JSON config field of 1e999 parses to Infinity and used to
-    // validate as a legal number).
+    // excluded (a JSON config field of 1e999 parses to Infinity, which must
+    // not validate as a legal number).
     return typeof value === 'number' && Number.isFinite(value);
 }
 /**