@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -32,21 +32,21 @@ export interface PatchResult {
     /** Whether the patch was auto-resolved (new file vs existing file conflict) */
     autoResolved?: boolean;
     /**
-     * Pre-existing BYTES of files the auto-resolve overwrote (or, for a binary
-     * new file, removed), keyed by engine-relative path. Kept for the RUN's
-     * duration (not just the retry): if a later patch fails and
+     * Pre-existing bytes of files the auto-resolve overwrote (or, for a
+     * binary new file, removed), keyed by engine-relative path. Kept for the
+     * whole run's duration, not just the retry: if a later patch fails and
      * `rollbackPatches` reverse-applies this one, reversing a new-file patch
-     * DELETES the file — these snapshots are the only way to restore what was
-     * there before the auto-resolve.
+     * deletes the file, and these snapshots are the only way to restore what
+     * was there before the auto-resolve.
      *
      * Raw bytes rather than decoded text, because the same snapshot has to
      * restore a binary target byte-for-byte.
      *
-     * Typed `Uint8Array`, not `Buffer`: this interface is published, and the
-     * emitted `.d.ts` naming a Node global made a consumer without
+     * Typed `Uint8Array` rather than `Buffer`: this interface is published,
+     * and the emitted `.d.ts` naming a Node global made a consumer without
      * `@types/node` fail to compile against the package (`TS2591` in the
-     * pack smoke test). Every `Buffer` assigns to it — `Buffer` extends
-     * `Uint8Array` — and `fs.writeFile` accepts it, so nothing at the call
+     * pack smoke test). Every `Buffer` assigns to it, since `Buffer` extends
+     * `Uint8Array`, and `fs.writeFile` accepts it, so nothing at the call
      * sites changes.
      */
     autoResolvedOriginals?: Map<string, Uint8Array>;
@@ -81,15 +81,15 @@ export interface PatchMetadata {
     /**
      * Optional per-patch list of lint check IDs to suppress when this patch is
      * the target of `export`, `export-all`, or `re-export`. Exists for the
-     * class of patch that is advisory-noisy by nature — a cohesive branding
-     * bundle, a localised-resource pack, an auto-generated manifest — where
+     * class of patch that is advisory-noisy by nature (a cohesive branding
+     * bundle, a localised-resource pack, an auto-generated manifest) where
      * the generic `large-patch-lines` / `large-patch-files` thresholds do not
      * apply but `--skip-lint`, which silences every error rather than the one
      * that does not apply, is too coarse.
      *
      * Values are free-form check IDs (e.g. `"large-patch-lines"`). Checks not
      * listed here still run normally. An entry for an unknown check ID is a
-     * no-op — the metadata documents the intent to suppress even if the check
+     * no-op: the metadata documents the intent to suppress even if the check
      * is later renamed or removed.
      */
     lintIgnore?: string[];
@@ -99,14 +99,14 @@ export interface PatchMetadata {
      * cross-cutting registration files alongside `browser/branding/<name>/`
      * (notably `browser/moz.configure`, which registers the new branding
      * flavor with the top-level configure). The narrow auto-detect allowlist
-     * in `isBrandingOnlyPatch` covers the canonical shape; a fork whose
+     * in `isBrandingOnlyPatch` covers the canonical shape. A fork whose
      * branding patch also touches an unlisted sibling falls through to the
      * general tier and trips the hard limit on what is legitimately one
      * branding diff.
      *
      * Declaring `tier: "branding"` forces the branding thresholds (notice
      * 8000 / warning 18000 / error 30000 lines, ≤60 files) regardless of
-     * `filesAffected`. It is the weaker claim than test: an all-tests patch
+     * `filesAffected`. It is a weaker claim than test: an all-tests patch
      * stays in the test tier even with this set, because those thresholds are
      * already more permissive.
      *
@@ -130,11 +130,11 @@ export interface PatchStagedDependencies {
     forwardImports?: PatchStagedForwardImport[];
     /**
      * Registration-shaped forward dependencies: packaging or registration
-     * LINES (a jar.mn entry, a customElements registration, an actor
+     * lines (a jar.mn entry, a customElements registration, an actor
      * registration) this patch adds that reference a file a later patch
      * creates. Unlike `forwardImports`, these are validated by matching the
-     * declared line against the patch's added content, not by finding an
-     * import specifier — packaging lines have no import to match.
+     * declared line against the patch's added content rather than by finding
+     * an import specifier, since packaging lines have no import to match.
      */
     registrations?: PatchStagedRegistration[];
 }
@@ -227,8 +227,8 @@ export interface PatchLintIssue {
      * Diff-scoping tag populated by `lint --since <rev>`. Absent when the
      * caller did not request diff-scoping.
      *
-     * - `introduced` — the issue's file was touched in the diff since `<rev>`.
-     * - `cumulative` — the issue is pre-existing patch-state drift not
+     * - `introduced`: the issue's file was touched in the diff since `<rev>`.
+     * - `cumulative`: the issue is pre-existing patch-state drift not
      *   introduced by the current task.
      */
     tag?: 'introduced' | 'cumulative';

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

@@ -4,7 +4,7 @@
 /**
  * Result of a doctor check.
  *
- * `severity` is the single source of truth; consumers that want a boolean
+ * `severity` is the single source of truth. Consumers that want a boolean
  * derive it as `severity !== 'error'`.
  */
 export interface DoctorCheck {
@@ -23,7 +23,7 @@ export interface DoctorCheck {
 export interface TokenCoverageFileEntry {
     /** File path (relative to engine root) */
     file: string;
-    /** var(--{prefix}*) usages — fully tokenized */
+    /** var(--{prefix}*) usages, fully tokenized */
     tokenUsages: number;
     /** var(--*) usages referencing allowlisted tokens */
     allowlisted: number;
@@ -38,7 +38,7 @@ export interface TokenCoverageFileEntry {
 export interface TokenCoverageReport {
     /** Total CSS files scanned */
     filesScanned: number;
-    /** var(--{prefix}*) usages — fully tokenized */
+    /** var(--{prefix}*) usages, fully tokenized */
     tokenUsages: number;
     /** var(--*) usages referencing allowlisted tokens */
     allowlistedUsages: number;

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

@@ -12,6 +12,13 @@ export interface FirefoxConfig {
     product: FirefoxProduct;
     /** Optional pinned SHA-256 for the resolved source archive */
     sha256?: string;
+    /**
+     * Accept a freshly downloaded archive when Mozilla's published SHA256SUMS
+     * cannot be fetched or does not list it, instead of failing closed. The
+     * download is then trusted on TLS alone (with a warning). Ignored when
+     * `sha256` is pinned. Default false.
+     */
+    allowUnverifiedDownload?: boolean;
     /**
      * Optional release-candidate build directory (e.g. "build2"). When set,
      * the source archive resolves under
@@ -49,7 +56,7 @@ export interface ExternalToolRequirement {
     path?: string;
     /** Resolve the tool with `xcrun -find <name>` instead of PATH. */
     xcrun?: boolean;
-    /** Missing tool is an error by default; set false for advisory probes. */
+    /** Missing tool is an error by default. Set false for advisory probes. */
     required?: boolean;
 }
 /** Named group of project-specific external asset/build tools. */
@@ -124,6 +131,8 @@ export interface FireForgeConfig {
     firefox: FirefoxConfig;
     /** Build settings */
     build?: BuildConfig;
+    /** Post-build packaging audit configuration */
+    buildAudit?: BuildAuditConfig;
     /** Test command defaults */
     test?: TestConfig;
     /** Optional project-specific external toolchains checked by doctor. */
@@ -149,14 +158,14 @@ export interface FireForgeConfig {
 /**
  * Configuration for the `fireforge typecheck` command. Distinct from
  * `patchLint.checkJs`: patch-lint runs every time `fireforge lint` runs
- * and is scoped to patch-owned `.sys.mjs`; typecheck runs whole projects
+ * and is scoped to patch-owned `.sys.mjs`. Typecheck runs whole projects
  * the operator points at via `projects` and is intended as a CI gate.
  */
 export interface TypecheckConfig {
     /**
      * Project-relative paths to jsconfig.json (or tsconfig.json) files
      * the typecheck command should run. Must be non-empty when the
-     * `typecheck` block is present — an empty array would silently turn
+     * `typecheck` block is present. An empty array would silently turn
      * the command into a no-op.
      */
     projects: string[];
@@ -165,14 +174,15 @@ export interface TypecheckConfig {
      * contents are concatenated to the built-in `FIREFOX_GLOBALS_SHIM`.
      * Lets projects declare component patterns like `MozLitElement` /
      * `MozXULElement` once instead of per-file. Concat order is
-     * built-in shim first, extraShim second — augment, don't redeclare.
+     * built-in shim first, extraShim second: augment, don't redeclare.
      */
     extraShim?: string;
     /**
      * Per-project override of {@link extraShim}, keyed by the project's path
      * exactly as it appears in {@link projects}. A string value points the
-     * project at a different `.d.ts`; `null` opts the project out of the shared
-     * extra shim entirely (it absorbs only the built-in Firefox globals shim).
+     * project at a different `.d.ts`. `null` opts the project out of the
+     * shared extra shim entirely (it absorbs only the built-in Firefox globals
+     * shim).
      *
      * Needed because the shared shim is injected into every project: a shim hub
      * that references Gecko declaration libs (`lib.gecko.dom.d.ts`, …) is wanted
@@ -185,19 +195,44 @@ export interface TypecheckConfig {
      * How to report undefined free identifiers (TS2304/TS2552). Default
      * `'warning'`: visible without failing the gate, since shim gaps produce
      * the same diagnostic as a genuine missing import. `'error'` makes them
-     * blocking; `'off'` suppresses them.
+     * blocking. `'off'` suppresses them.
      */
     undefinedIdentifiers?: PatchLintSeverityGate;
 }
 /**
  * Wire command configuration.
  */
+/**
+ * One intentionally unpackaged source, declared so the post-build audit
+ * stops reporting it as a missing registration.
+ *
+ * `reason` is required and must be non-empty. A carve-out whose rationale
+ * nobody wrote down is indistinguishable from a mistake by the time someone
+ * reads it, and this is the one audit class FireForge cannot derive from the
+ * tree: the file's own header may say "never loaded", but nothing in
+ * `moz.build` or `jar.mn` records that.
+ */
+export interface BuildAuditUnpackagedDeclaration {
+    /** Engine-relative path, exact or with a `*` inside one path segment. */
+    path: string;
+    /** Why this file is never packaged. Required, non-empty. */
+    reason: string;
+}
+/** Post-build packaging audit configuration. */
+export interface BuildAuditConfig {
+    /**
+     * Sources the audit must treat as intentionally unpackaged. Admitted
+     * paths are listed in the audit output rather than silenced, and one that
+     * does resolve to a packaged artifact is reported as a stale carve-out.
+     */
+    unpackaged?: BuildAuditUnpackagedDeclaration[];
+}
 export interface WireConfig {
     /** Subscript directory relative to engine/. Default: "browser/base/content" */
     subscriptDir?: string;
 }
 /**
- * Severity gate for opt-in patch-lint rules. `'off'` disables the rule;
+ * Severity gate for opt-in patch-lint rules. `'off'` disables the rule.
  * `'warning'` and `'error'` emit issues at the matching severity.
  */
 export type PatchLintSeverityGate = 'off' | 'warning' | 'error';
@@ -208,7 +243,7 @@ export type PatchLintSeverityGate = 'off' | 'warning' | 'error';
  *
  * Boolean flags tighten the strict preset. The optional `paths` mapping
  * (each pattern may carry a single `*`) lets patch-owned modules be typed
- * from their real sources — e.g. `"resource:///modules/foo/*": ["./*"]` —
+ * from their real sources (e.g. `"resource:///modules/foo/*": ["./*"]`),
  * resolved host-side against the engine directory, so no `baseUrl` is set
  * (TS5090-safe) and no hand-generated ambient stub shim is needed. Other
  * options (`rootDir`, etc.) stay disallowed: they would fight the
@@ -229,10 +264,10 @@ export interface PatchLintCheckJsCompilerOptions {
 /**
  * Line-count thresholds for one `file-too-large` tier.
  *
- * Every field is optional; an omitted field keeps the built-in default.
+ * Every field is optional. An omitted field keeps the built-in default.
  * The three must stay ordered `notice <= warning <= error`, which the
- * config validator enforces — an out-of-order triple silently disables a
- * band rather than failing anything.
+ * config validator enforces, because an out-of-order triple silently
+ * disables a band rather than failing anything.
  */
 export interface PatchLintFileSizeTier {
     notice?: number;
@@ -269,7 +304,7 @@ export interface PatchLintConfig {
      */
     checkJsStrict?: boolean;
     /**
-     * Boolean overrides merged after the strict preset; only valid when
+     * Boolean overrides merged after the strict preset. Only valid when
      * `checkJsStrict` is true. Requires `checkJs: true`.
      */
     checkJsCompilerOptions?: PatchLintCheckJsCompilerOptions;
@@ -323,16 +358,16 @@ export interface PatchLintConfig {
      * `Services.scriptloader.loadSubScript`, e.g.
      * `browser/base/content/<binaryName>*.js`). Distinct from
      * `jsdocClassMethods` because chrome subscripts are parsed as scripts,
-     * not ES modules — using one flag for both would silently disable the
+     * not ES modules. Using one flag for both would silently disable the
      * rule when a chrome subscript was fed to the module parser. Default:
      * 'off'.
      */
     chromeScriptJsDoc?: PatchLintSeverityGate;
     /**
      * How the checkJs pass reports undefined free identifiers
-     * (TS2304/TS2552). Same semantics as `typecheck.undefinedIdentifiers`;
-     * the two flows share the suppression policy so a patch
-     * cannot pass one and fail the other. Default: 'warning'.
+     * (TS2304/TS2552). Same semantics as `typecheck.undefinedIdentifiers`.
+     * The two flows share the suppression policy so a patch cannot pass one
+     * and fail the other. Default: 'warning'.
      */
     undefinedIdentifiers?: PatchLintSeverityGate;
 }
@@ -352,8 +387,6 @@ export interface FireForgeState {
     brand?: string;
     /** Build mode: dev, debug, release */
     buildMode?: BuildMode;
-    /** Last successful build timestamp (ISO string) */
-    lastBuild?: string;
     /** Firefox version that was downloaded */
     downloadedVersion?: string;
     /** Initial commit hash of the engine (baseline) */

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

@@ -47,7 +47,7 @@ export interface CustomComponentConfig {
     /** Whether to register in customElements.js */
     register: boolean;
     /**
-     * What the component IS. `'element'` (the default when unset) is a custom
+     * What the component is. `'element'` (the default when unset) is a custom
      * element with its own tag. `'library'` is a base class + helpers module
      * that defines no element of its own (e.g. a shared MozLitElement
      * subclass other components extend): `furnace validate` skips the
@@ -55,7 +55,7 @@ export interface CustomComponentConfig {
      * and the `missing-css` structural advisory for it, while headers, module
      * shape, `relative-import`, and (when a `.css` exists) the CSS
      * compatibility rules still apply. A library exports no element, so
-     * `kind: "library"` requires `register: false` — the combination with
+     * `kind: "library"` requires `register: false`. The combination with
      * `register: true` is rejected at config parse time.
      */
     kind?: 'element' | 'library';
@@ -85,18 +85,18 @@ export interface CustomComponentConfig {
      * participates in, in the same form used by `insertFTLIfNeeded` (for
      * example `browser/mybrowser-dock.ftl`). When set:
      *
-     *   - `furnace create --localized` does NOT scaffold a per-component
-     *     `.ftl` stub — the component shares the feature bundle.
+     *   - `furnace create --localized` does not scaffold a per-component
+     *     `.ftl` stub. The component shares the feature bundle.
      *   - The generated `.mjs` calls `insertFTLIfNeeded("<sharedFtl>")` at
      *     the shared path instead of the per-component one.
      *   - `furnace validate`'s `missing-ftl` structural rule is skipped for
      *     the component (there is no `<tag>.ftl` to require).
-     *   - `furnace apply` does NOT copy a per-component `.ftl` into the FTL
-     *     tree nor register a new entry in the locale `jar.mn` — the shared
+     *   - `furnace apply` does not copy a per-component `.ftl` into the FTL
+     *     tree nor register a new entry in the locale `jar.mn`. The shared
      *     file is owned by whoever authored the feature bundle.
      *
      * Requires `localized: true`. Mutually exclusive with the per-component
-     * `.ftl` scaffold. Does NOT auto-migrate previous per-component FTL
+     * `.ftl` scaffold. Does not auto-migrate previous per-component FTL
      * state: flipping an existing component onto `sharedFtl` leaves the
      * prior per-component entry in the engine tree and the locale `jar.mn`
      * until explicitly cleaned up.
@@ -120,12 +120,12 @@ export interface FurnaceConfig {
      * variables the fork does not own. `token coverage` counts matches as
      * `allowlisted` rather than `unknown` so a copied upstream baseline does
      * not drag fork-owned coverage percentages down. Defaults to `['--moz-']`
-     * when unset; pass an explicit empty array to count every prefix.
+     * when unset. Pass an explicit empty array to count every prefix.
      */
     platformPrefixes?: string[];
     /**
-     * Custom properties used as runtime state channels — written and read by the
-     * component itself (e.g. per-frame camera/tile positions) rather than
+     * Custom properties used as runtime state channels, written and read by
+     * the component itself (e.g. per-frame camera/tile positions) rather than
      * consumed as design tokens. Listed names are exempt from the
      * `token-prefix-violation` check even when they do not match `tokenPrefix`
      * and are not in `tokenAllowlist`. Use this for cross-component runtime
@@ -139,7 +139,7 @@ export interface FurnaceConfig {
      * the tokens CSS file is `<link>`ed. Forks with multiple chrome host
      * documents (e.g. `mybrowser.xhtml` beside the stock `browser.xhtml`) should
      * list every document that may own the link. When omitted, defaults to
-     * `['browser/base/content/browser.xhtml']` — the upstream Firefox path.
+     * `['browser/base/content/browser.xhtml']`, the upstream Firefox path.
      */
     tokenHostDocuments?: string[];
     /**
@@ -157,7 +157,7 @@ export interface FurnaceConfig {
      * `compilerOptions.paths` entries for deployed component modules
      * (`chrome://global/content/elements/<file>.mjs`) Furnace keeps in sync
      * on deploy. Only entries under that chrome prefix that map into
-     * `components/custom/` are managed; everything else is preserved.
+     * `components/custom/` are managed. Everything else is preserved.
      * Unset disables jsconfig maintenance.
      */
     typecheckJsconfig?: string;
@@ -189,11 +189,11 @@ export type FurnacePendingRepairOperation = (typeof FURNACE_PENDING_REPAIR_OPERA
  * out-of-band from what the state file records.
  */
 export interface FurnacePendingRepair {
-    /** The operation that failed to clean up; used by doctor to route the fix. */
+    /** The operation that failed to clean up. Doctor uses it to route the fix. */
     operation: FurnacePendingRepairOperation;
     /** ISO timestamp of when the repair marker was written. */
     timestamp: string;
-    /** Human-readable summary of the failure; shown by doctor. */
+    /** Human-readable summary of the failure. Doctor shows it. */
     reason: string;
 }
 /**
@@ -259,13 +259,13 @@ export interface ApplyResult {
     /**
      * Set to true when the rollback journal was restored after a partial failure.
      * When true, entries in `applied` reflect what was attempted, not what
-     * persisted — the engine has been restored to its pre-apply state.
+     * persisted. The engine has been restored to its pre-apply state.
      */
     rolledBack?: boolean;
     /**
      * Operator-facing warnings, printed by `logApplyResult`. Populated when
      * apply overwrote a deployed, patch-owned file whose engine bytes
-     * differed from the component source — the case where a
+     * differed from the component source, which is the case where a
      * shipped engine-only fix is silently reverted by the copy.
      */
     warnings?: string[];
@@ -331,7 +331,7 @@ export type ResolvedTestStyle = 'mochikit' | 'browser-chrome' | 'xpcshell' | 'no
  * caller is never asked to invent a value it does not have.
  */
 export interface ComponentApplyContext {
-    /** Project root — what registration consistency resolves against. */
+    /** Project root, what registration consistency resolves against. */
     root: string;
     /** Firefox source directory the component deploys into. */
     engineDir: string;

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

@@ -1,6 +1,5 @@
 /**
  * Re-exports all type definitions.
  */
-export type {} from './commands/index.js';
 export type { BuildConfig, FireForgeConfig, FirefoxConfig, FirefoxProduct, ProjectLicense, ProjectPaths, WireConfig, } from './config.js';
 export type { ApplyResult, ComponentType, CustomComponentConfig, DryRunAction, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, StepError, ValidationIssue, } from './furnace.js';

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

@@ -1,8 +1,8 @@
 /**
  * Domain types for raw JSON documents (fireforge.json, furnace.json).
  *
- * FireForge deliberately reads and writes some documents in their raw,
- * unvalidated form — e.g. `fireforge config --force` round-trips keys that
+ * FireForge reads and writes some documents in their raw, unvalidated
+ * form. For example, `fireforge config --force` round-trips keys that
  * the validated `FireForgeConfig` schema would strip. These types give that
  * pipeline a concrete value contract: every value is JSON data, never a
  * function, class instance, symbol, or other non-serializable runtime value.
@@ -14,7 +14,7 @@ export type JsonValue = string | number | boolean | null | JsonValue[] | JsonObj
 /**
  * A JSON object node. `undefined` is admitted as a property value (not a
  * `JsonValue`) so in-memory documents can be built field-by-field from
- * optional inputs; `JSON.stringify` drops such properties on write, exactly
+ * optional inputs. `JSON.stringify` drops such properties on write, exactly
  * like an absent key.
  */
 export interface JsonObject {

package/dist/src/types/json.js

@@ -2,8 +2,8 @@
 /**
  * Domain types for raw JSON documents (fireforge.json, furnace.json).
  *
- * FireForge deliberately reads and writes some documents in their raw,
- * unvalidated form — e.g. `fireforge config --force` round-trips keys that
+ * FireForge reads and writes some documents in their raw, unvalidated
+ * form. For example, `fireforge config --force` round-trips keys that
  * the validated `FireForgeConfig` schema would strip. These types give that
  * pipeline a concrete value contract: every value is JSON data, never a
  * function, class instance, symbol, or other non-serializable runtime value.

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

@@ -23,9 +23,9 @@ export interface TypecheckIssue {
     /** Raw TypeScript diagnostic code (e.g. 2322 for a type mismatch). */
     code: number;
     /**
-     * Severity bucket — TS reports `Suggestion` and `Message` categories
-     * too, but `runTypecheck` collapses both into `'warning'` so the CLI
-     * has only two visible levels.
+     * Severity bucket. TS also reports `Suggestion` and `Message`
+     * categories, but `runTypecheck` collapses both into `'warning'` so
+     * the CLI has only two visible levels.
      */
     category: 'error' | 'warning';
     /** Human-readable message text (already flattened from chains). */

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

@@ -2,11 +2,11 @@
  * A failure description, or a thunk producing one.
  *
  * The thunk form exists so a hot call site pays nothing on the passing
- * path — `assert(ok, () => \`bad state: ${JSON.stringify(x)}\`)` builds
+ * path: `assert(ok, () => \`bad state: ${JSON.stringify(x)}\`)` builds
  * the string only when the assertion actually fails, where a plain
  * template literal would build it on every call.
  */
-export type AssertionMessage = string | (() => string);
+type AssertionMessage = string | (() => string);
 /**
  * Asserts that an internal invariant holds.
  *
@@ -18,23 +18,10 @@ export type AssertionMessage = string | (() => string);
  * @throws {@link InternalInvariantError} when `condition` is falsy.
  */
 export declare function assert(condition: unknown, message: AssertionMessage): asserts condition;
-/**
- * Asserts that a value is neither `null` nor `undefined`, narrowing it in
- * place for the statements that follow.
- *
- * Use this in statement position, where the value is already bound to a
- * name. Use {@link expectDefined} in expression position, where it is not.
- *
- * @param value - The value that should be present
- * @param message - What was supposed to be present, and why
- * @throws {@link InternalInvariantError} when `value` is `null` or `undefined`.
- */
-export declare function assertDefined<T>(value: T, message: AssertionMessage): asserts value is NonNullable<T>;
 /**
  * Returns a value that must be present, throwing if it is not.
  *
- * The expression-position counterpart to {@link assertDefined}: it checks
- * and returns in one step, so an indexed read can be asserted inline
+ * Checks and returns in one step, so an indexed read can be asserted inline
  * (`push({ content: expectDefined(lines[k], …) })`) without first binding
  * it to a local.
  *
@@ -44,3 +31,4 @@ export declare function assertDefined<T>(value: T, message: AssertionMessage): a
  * @throws {@link InternalInvariantError} when `value` is `null` or `undefined`.
  */
 export declare function expectDefined<T>(value: T, message: AssertionMessage): NonNullable<T>;
+export {};

package/dist/src/utils/assert.js

@@ -2,17 +2,17 @@
 /**
  * Runtime assertions for FireForge's own internal invariants.
  *
- * These check state that FireForge itself established — a journal was
+ * These check state that FireForge itself established: a journal was
  * registered before the first mutation, a lock is held before a write,
- * manifest ordering is contiguous after a renumber. They are NOT input
- * validation: anything derived from user input, the filesystem, or a
+ * manifest ordering is contiguous after a renumber. They are not input
+ * validation. Anything derived from user input, the filesystem, or a
  * subprocess belongs in a typed error from `src/errors/` with a
  * `userMessage` that tells the operator what to do. An assertion failure
- * says the opposite — that nothing the operator could have done would
- * have prevented it.
+ * says the opposite: nothing the operator could have done would have
+ * prevented it.
  *
  * Every check routes through a helper here rather than being open-coded
- * as `if (!condition) throw`. That is deliberate: an inline throw adds a
+ * as `if (!condition) throw`. An inline throw adds a
  * permanently-uncovered branch to every function it appears in, and the
  * per-module coverage floors in `scripts/check-coverage-thresholds.mjs`
  * would pay for it in ~40 places. Routed through a call, the branch lives
@@ -46,27 +46,10 @@ export function assert(condition, message) {
         throw new InternalInvariantError(resolveMessage(message));
     }
 }
-/**
- * Asserts that a value is neither `null` nor `undefined`, narrowing it in
- * place for the statements that follow.
- *
- * Use this in statement position, where the value is already bound to a
- * name. Use {@link expectDefined} in expression position, where it is not.
- *
- * @param value - The value that should be present
- * @param message - What was supposed to be present, and why
- * @throws {@link InternalInvariantError} when `value` is `null` or `undefined`.
- */
-export function assertDefined(value, message) {
-    if (value === null || value === undefined) {
-        throw new InternalInvariantError(resolveMessage(message));
-    }
-}
 /**
  * Returns a value that must be present, throwing if it is not.
  *
- * The expression-position counterpart to {@link assertDefined}: it checks
- * and returns in one step, so an indexed read can be asserted inline
+ * Checks and returns in one step, so an indexed read can be asserted inline
  * (`push({ content: expectDefined(lines[k], …) })`) without first binding
  * it to a local.
  *

package/dist/src/utils/build-info.d.ts

@@ -1,9 +1,9 @@
 /** Source identity of the running build. */
-export interface BuildIdentity {
+interface BuildIdentity {
     shortCommit: string;
     dirty: boolean;
     /**
-     * Content hash of the uncommitted diff, present only for a DIRTY installed
+     * Content hash of the uncommitted diff, present only for a dirty installed
      * build. Two packs from the same HEAD with different uncommitted content
      * share `shortCommit` and the `.dirty` marker, so without this they report
      * byte-identical `--version` strings and a report against
@@ -13,15 +13,15 @@ export interface BuildIdentity {
      */
     dirtyHash?: string;
 }
-/** @internal Reads the stamped dist/build-info.json; null when absent/invalid. */
+/** @internal Reads the stamped dist/build-info.json. Null when absent/invalid. */
 export declare function readBuildInfoFile(packageRoot: string): BuildIdentity | null;
 type GitRunner = (args: string[]) => string;
-/** @internal Live git identity of the checkout; null when git is unusable. */
+/** @internal Live git identity of the checkout. Null when git is unusable. */
 export declare function readGitBuildIdentity(runGit?: GitRunner): BuildIdentity | null;
 /**
- * @internal Formats `<version>+g<sha>[.dirty[.<hash>]]`; plain version on
+ * @internal Formats `<version>+g<sha>[.dirty[.<hash>]]`. Plain version on
  * null identity. The trailing content hash appears only for a dirty
- * INSTALLED build, where `dist/build-info.json` already carries it — every
+ * installed build, where `dist/build-info.json` already carries it. Every
  * segment stays valid semver build metadata (dot-separated alphanumerics).
  */
 export declare function formatVersionWithIdentity(version: string, identity: BuildIdentity | null): string;

package/dist/src/utils/build-info.js

@@ -6,14 +6,14 @@
  * fingerprinting tarballs by sha256 to know which build a claim was verified
  * against. `--version` reports `<semver>+g<short-sha>[.dirty[.<content-hash>]]`:
  *
- * - In a git checkout (dev runs via tsx), identity comes from live git — a
+ * - In a git checkout (dev runs via tsx), identity comes from live git, so a
  *   stale `dist/build-info.json` from an old build must never win.
  * - In an installed package, it comes from `dist/build-info.json`, stamped
  *   by scripts/generate-build-info.mjs at build/pack time.
  * - When neither yields an identity, `--version` degrades to the plain
  *   semver. Reading identity must never throw.
  *
- * Deliberately NOT wired into the per-patch lint cache key: identity would
+ * Not wired into the per-patch lint cache key: identity would
  * churn the cache on every commit at the same semver for no correctness gain
  * (`getPackageVersion` stays the cache input).
  */
@@ -22,7 +22,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getPackageRoot, getPackageVersion } from './package-root.js';
 import { isObject } from './validation.js';
-/** @internal Reads the stamped dist/build-info.json; null when absent/invalid. */
+/** @internal Reads the stamped dist/build-info.json. Null when absent/invalid. */
 export function readBuildInfoFile(packageRoot) {
     try {
         const raw = readFileSync(join(packageRoot, 'dist', 'build-info.json'), 'utf-8');
@@ -49,7 +49,7 @@ const defaultGitRunner = (args) => execFileSync('git', args, {
     encoding: 'utf-8',
     stdio: ['ignore', 'pipe', 'ignore'],
 });
-/** @internal Live git identity of the checkout; null when git is unusable. */
+/** @internal Live git identity of the checkout. Null when git is unusable. */
 export function readGitBuildIdentity(runGit = defaultGitRunner) {
     try {
         const commit = runGit(['rev-parse', 'HEAD']).trim();
@@ -80,9 +80,9 @@ function getBuildIdentity() {
     }
 }
 /**
- * @internal Formats `<version>+g<sha>[.dirty[.<hash>]]`; plain version on
+ * @internal Formats `<version>+g<sha>[.dirty[.<hash>]]`. Plain version on
  * null identity. The trailing content hash appears only for a dirty
- * INSTALLED build, where `dist/build-info.json` already carries it — every
+ * installed build, where `dist/build-info.json` already carries it. Every
  * segment stays valid semver build metadata (dot-separated alphanumerics).
  */
 export function formatVersionWithIdentity(version, identity) {