@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/index.d.ts

@@ -22,10 +22,21 @@ export type { ApplyAllComponentsResult } from './core/furnace-apply.js';
 export { applyAllComponents } from './core/furnace-apply.js';
 export { ensureFurnaceConfig, loadFurnaceConfig, loadFurnaceState, saveFurnaceState, validateFurnaceConfig, } from './core/furnace-config.js';
 export { validateAllComponents, validateComponent } from './core/furnace-validate.js';
-export type { PatchSizeTierDecision } from './core/patch-lint.js';
-export { countNonBinaryDiffLines, filesMeasuredByFileTooLarge, getPatchSizeThresholds, resolvePatchSizeTier, } from './core/patch-lint.js';
+export type { PatchSizeThresholds, PatchSizeTierDecision } from './core/patch-lint.js';
+export { countNonBinaryDiffLines, filesMeasuredByFileTooLarge, getPatchSizeThresholds, isTestFile, resolvePatchSizeTier, } from './core/patch-lint.js';
+export type { CodeLineCount, CodeLineMask } from './core/patch-lint-code-lines.js';
+export { codeLineMask, countCodeLines } from './core/patch-lint-code-lines.js';
+export type { ResolvedFileSizeTier } from './core/patch-lint-file-size.js';
+export { resolveFileSizeThresholds } from './core/patch-lint-file-size.js';
+export type { PatchSizeMeasurement } from './core/patch-lint-size.js';
+export { measurePatchSize } from './core/patch-lint-size.js';
+export type { ResolvedPatchFilesTier } from './core/patch-lint-size-thresholds.js';
+export { isPatchSizeRegistrationFile } from './core/patch-lint-size-thresholds.js';
+export type { PatchPolicyIssue, PatchPolicyIssueCode } from './core/patch-policy.js';
+export { evaluatePatchPolicyContentForQueue } from './core/patch-policy-content.js';
 export type { AddTokenOptions, AddTokenResult, TokenMode } from './core/token-manager.js';
 export { addToken, getTokensCssPath, validateTokenAdd } from './core/token-manager.js';
 export { CancellationError, CommandError, FireForgeError, GeneralError, InvalidArgumentError, ResolutionError, } from './errors/base.js';
 export { ExitCode } from './errors/codes.js';
-export type { ApplyResult, BuildConfig, ComponentType, CustomComponentConfig, DryRunAction, FireForgeConfig, FirefoxConfig, FirefoxProduct, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, ProjectLicense, StepError, ValidationIssue, WireConfig, } from './types/index.js';
+export type { PatchesManifest, PatchMetadata } from './types/commands/index.js';
+export type { ApplyResult, BuildConfig, ComponentType, CustomComponentConfig, DryRunAction, FireForgeConfig, FirefoxConfig, FirefoxProduct, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, PatchLintFileSizeThresholds, PatchLintFileSizeTier, PatchLintPatchSizeMetric, ProjectLicense, StepError, ValidationIssue, WireConfig, } from './types/index.js';

package/dist/src/index.js

@@ -21,7 +21,12 @@ export { findForwardRegistrations } from './core/forward-registrations.js';
 export { applyAllComponents } from './core/furnace-apply.js';
 export { ensureFurnaceConfig, loadFurnaceConfig, loadFurnaceState, saveFurnaceState, validateFurnaceConfig, } from './core/furnace-config.js';
 export { validateAllComponents, validateComponent } from './core/furnace-validate.js';
-export { countNonBinaryDiffLines, filesMeasuredByFileTooLarge, getPatchSizeThresholds, resolvePatchSizeTier, } from './core/patch-lint.js';
+export { countNonBinaryDiffLines, filesMeasuredByFileTooLarge, getPatchSizeThresholds, isTestFile, resolvePatchSizeTier, } from './core/patch-lint.js';
+export { codeLineMask, countCodeLines } from './core/patch-lint-code-lines.js';
+export { resolveFileSizeThresholds } from './core/patch-lint-file-size.js';
+export { measurePatchSize } from './core/patch-lint-size.js';
+export { isPatchSizeRegistrationFile } from './core/patch-lint-size-thresholds.js';
+export { evaluatePatchPolicyContentForQueue } from './core/patch-policy-content.js';
 export { addToken, getTokensCssPath, validateTokenAdd } from './core/token-manager.js';
 export { CancellationError, CommandError, FireForgeError, GeneralError, InvalidArgumentError, ResolutionError, } from './errors/base.js';
 export { ExitCode } from './errors/codes.js';

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

@@ -1,6 +1,6 @@
 /**
  * Re-exports all command-related types from focused sub-modules.
  */
-export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, ImportOptions, LintCommandOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchMoveFilesOptions, PatchRenameOptions, PatchReorderOptions, PatchSplitOptions, PatchStagedDependencyOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, SourceSetOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
-export type { ImportSummary, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration, } from './patches.js';
+export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceLockWaitable, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceRenameOptions, FurnaceSyncOptions, FurnaceValidateOptions, ImportOptions, LintCommandOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchMoveFilesOptions, PatchRenameOptions, PatchReorderOptions, PatchReserveOptions, PatchRetireOptions, PatchSplitOptions, PatchStagedDependencyOptions, PatchStageOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, SourceSetOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
+export type { ImportSummary, LintIgnoreCeiling, LintIgnoreEntry, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchLintStagedDeclaration, PatchMetadata, PatchReservedSlot, PatchResult, PatchRetiredSlot, PatchSizeShare, PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration, } from './patches.js';
 export type { DoctorCheck, TokenCoverageFileEntry, TokenCoverageReport } from './project.js';

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

@@ -2,7 +2,7 @@
  * Command option types for CLI commands.
  */
 import type { FirefoxProduct, ProjectLicense } from '../config.js';
-import type { PatchCategory } from './patches.js';
+import type { PatchCategory, PatchSizeShare } from './patches.js';
 /**
  * `--dry-run`: print the planned change and exit without writing anything.
  *
@@ -111,6 +111,8 @@ export interface SourceSetOptions {
 export interface BuildOptions extends EngineLockWaitable {
     /** Wait for the objdir browser before deploying/building. */
     waitBrowser?: number | boolean;
+    /** Also write the run log here, outside `.fireforge/logs/` retention. */
+    keepLog?: string;
     /** Fast UI-only rebuild */
     ui?: boolean;
     /** Number of parallel jobs */
@@ -263,7 +265,9 @@ export interface ReExportOptions extends EngineLockWaitable {
     /**
      * Explicit engine-relative files to add while scanning. Unlike broad
      * `--scan`, this does not collect adjacent files from the same directory.
-     * Requires `--scan` and exactly one target patch.
+     * Requires `--scan`. A `<patch>:<path>` entry names its owning patch, which
+     * a call with several target patches requires; selected patches without
+     * an entry then refresh scan-less.
      */
     scanFiles?: string[];
     /**
@@ -330,8 +334,8 @@ export interface ReExportOptions extends EngineLockWaitable {
      * unmanaged files exist adjacent to the patch's ownership, instead of
      * warning. Gate-driven workflows use this so a freshly created file
      * beside a patch's owned files cannot be silently left out of the
-     * refreshed body. Only meaningful on the plain path, and mutually
-     * exclusive with `--scan` and `--files`, which set filesAffected
+     * refreshed body. Beside `--scan` it judges the neighbours the scan did
+     * not adopt. Mutually exclusive with `--files`, which sets filesAffected
      * explicitly.
      */
     refuseAdjacentUnmanaged?: boolean;
@@ -343,11 +347,13 @@ export interface ReExportOptions extends EngineLockWaitable {
     noCache?: boolean;
     /**
      * Refuse (non-zero exit, patch not written) a re-export whose refreshed
-     * body would absorb engine lines not present in the old patch body.
+     * body would add or drop lines, in a file the patch already owns, that
+     * the old patch body did not carry.
      * This is the multi-session guard against silently capturing another
      * session's uncommitted edits in files the patch already owns. The drift preview
-     * always prints. This flag turns it into a hard stop. Mutually
-     * exclusive with `--scan` and `--files`.
+     * always prints. This flag turns it into a hard stop. Beside `--scan` it
+     * guards the files each patch already owns (adopted files count as
+     * expected). Mutually exclusive with `--files`.
      */
     refuseForeignDrift?: boolean;
     /**
@@ -370,8 +376,44 @@ export interface ReExportOptions extends EngineLockWaitable {
      * rather than hidden.
      */
     expectUnmanaged?: string[];
-    /** Explicitly retire named absent patch-created files in a scan-less export. */
+    /**
+     * Engine-relative files this session created and will adopt with its next
+     * export (`--expect-new`, repeatable). Requires
+     * `--refuse-adjacent-unmanaged`. Lets the owners of a new file's
+     * registration re-export first while a peer's unmanaged neighbour still
+     * refuses. The path must be changed in engine/ and owned by no patch.
+     */
+    expectNew?: string[];
+    /**
+     * Reviewed ignore list for `--refuse-adjacent-unmanaged`
+     * (`--adjacent-ignore`, repeatable): an engine-relative path, or a glob
+     * whose `*` stays within one segment (`**` is refused). Matches are
+     * reported, never refused.
+     */
+    adjacentIgnore?: string[];
+    /**
+     * Explicitly retire named files in a scan-less export: an absent file the
+     * patch created, or a patch-modified upstream file whose engine copy is
+     * back at HEAD.
+     */
     expectRemoved?: string[];
+    /**
+     * Where a refused `--scan` adoption writes its one `--from`-ready
+     * declaration report (`--declarations-out`). Defaults to
+     * `.fireforge/declarations/`.
+     */
+    declarationsOut?: string;
+    /**
+     * `--hunks-from <diff>`: export each named file as the patch's current
+     * body plus only the hunks in this diff, leaving every other session's
+     * edits in the file out.
+     */
+    hunksFrom?: string;
+    /**
+     * `--exclude-hunks <diff>`: export each named file as the working tree
+     * minus the hunks in this diff.
+     */
+    excludeHunks?: string;
 }
 /**
  * Options for the `fireforge patch tier` subcommand. Sets or clears the
@@ -396,6 +438,20 @@ export interface PatchLintIgnoreOptions extends Confirmable, DryRunnable, PatchL
     remove?: string[];
     /** Drop the `lintIgnore` field entirely. */
     clear?: boolean;
+    /**
+     * With `add`: write `{ rule, max, reason }` ceiling entries instead of
+     * bare IDs. Only the measured size rules accept one. Requires `reason`.
+     */
+    max?: number;
+    /** Why the ceiling exists. Required with `max` or a `<rule>=<max>` add. */
+    reason?: string;
+    /** With a ceiling on `large-patch-lines`: the share it bounds. */
+    share?: PatchSizeShare;
+    /**
+     * Add every entry in a JSON file under one lock hold: an array of
+     * entries, or a lint report whose ceilings for the patch are rebaselined.
+     */
+    from?: string;
 }
 /**
  * Options for the `fireforge patch staged-dependency` subcommand. Modes are
@@ -430,6 +486,11 @@ export interface PatchStagedDependencyOptions extends Confirmable, DryRunnable,
     owner?: string;
     /** Optional human-readable rationale stored with the declaration. */
     reason?: string;
+    /**
+     * JSON file of declarations to add in one call (`--add` only): a
+     * `lint --per-patch --report` document or a plain array of declarations.
+     */
+    from?: string;
 }
 /**
  * Options for the `patch split` command.
@@ -453,6 +514,8 @@ export interface PatchSplitOptions extends Confirmable, PatchLockWaitable, Unsaf
     dryRun?: boolean;
     /** Skip per-patch lint of the projected bodies. */
     skipLint?: boolean;
+    /** Where a refusal writes its one `--from`-ready declaration report. */
+    declarationsOut?: string;
 }
 /**
  * Options for the `fireforge patch move-files` subcommand. Without
@@ -476,6 +539,8 @@ export interface PatchMoveFilesOptions extends Confirmable, PatchLockWaitable, U
     dryRun?: boolean;
     /** Skip per-patch lint of the projected bodies. */
     skipLint?: boolean;
+    /** Where a refusal writes its one `--from`-ready declaration report. */
+    declarationsOut?: string;
 }
 /**
  * Options for the rebase command.
@@ -510,6 +575,16 @@ export interface RunOptions {
      * Implied by `smokeExit` unless `profile` is given.
      */
     tempProfile?: boolean;
+    /**
+     * Pass `-purgecaches` with a named `profile`, so Firefox discards the
+     * profile's startup cache (compiled chrome scripts) before it runs. A UI
+     * build keeps the build id the cache is keyed on, so a kept profile would
+     * otherwise run the chrome scripts an earlier build cached. Default
+     * `true`; `--no-purge-caches` sets `false`. Fresh temporary profiles and
+     * mach's own profile-default (cleaned before every run) have no cache to
+     * purge.
+     */
+    purgeCaches?: boolean;
     /**
      * Enable smoke-run mode. Launches the browser, streams the console,
      * sends SIGTERM to the whole process group after `smokeExit` seconds,
@@ -520,7 +595,9 @@ export interface RunOptions {
      *  - `ExitCode.SMOKE_LAUNCH_FAILURE` (13): the browser exited with a
      *    non-clean status before the smoke window elapsed (a launch-side
      *    failure we cannot observe as a console line, such as a crash
-     *    before console wiring, or a missing profile).
+     *    before console wiring, or a missing profile), or exited before the
+     *    window with no browser console output at all (a launch that never
+     *    reached a window, such as a profile in a startup-crash streak).
      *
      * POSIX only (process-group semantics do not map cleanly onto Windows).
      * `runSmokeExit` rejects the flag up front on `win32`.
@@ -559,6 +636,10 @@ export interface TestOptions extends EngineLockWaitable {
     waitBrowser?: number | boolean;
     /** Queue behind the mochitest/Marionette port holder. */
     waitPort?: number | boolean;
+    /** Also write the run log here, outside `.fireforge/logs/` retention. */
+    keepLog?: string;
+    /** Forward mochitest's `--restart-between-tests` (mochitest dispatch only). */
+    restartBetweenTests?: boolean;
     /** Copy a file into the profile at a relative destination (repeatable source=destination). */
     profileFile?: string[];
     /** Run tests in headless mode */
@@ -580,13 +661,11 @@ export interface TestOptions extends EngineLockWaitable {
      */
     buildOnly?: boolean;
     /**
-     * Union the paths this build packages onto the recorded coverage claim
-     * instead of REPLACING it, so successive scoped builds accumulate and an
-     * earlier slice's build-less runs stay covered. Valid only with
-     * `--build`/`--build-only` and explicit paths. Refused fail-closed unless
-     * the build anchor is unchanged: same engine HEAD, same `engine/mozconfig`,
-     * and every previously fingerprinted packageable file byte-identical. See
-     * `src/core/coverage-extend.ts`.
+     * Refuse, before the build, instead of dropping any earlier packaging
+     * claim. Scoped builds keep earlier paths by default while each path's own
+     * staging inputs and `engine/mozconfig` are unchanged; this flag makes a
+     * drop fail-closed. Valid only with `--build`/`--build-only` and explicit
+     * paths. See `src/core/coverage-extend.ts`.
      */
     extendCoverage?: boolean;
     /**
@@ -598,6 +677,13 @@ export interface TestOptions extends EngineLockWaitable {
      * that could not arm the refusal. Valid only with `--build`/`--build-only`.
      */
     refuseUnexportedDrift?: boolean;
+    /**
+     * Which components the pre-test build deploys: `all` (default), `reached`
+     * (only those a requested test reaches) or `none`. `false` is
+     * `--no-furnace-apply`, the same as `none`. Valid only with
+     * `--build`/`--build-only`.
+     */
+    furnaceApply?: boolean | 'all' | 'reached' | 'none';
     /** Forward mach's pathless auto-selection mode. Valid only with no explicit paths. */
     auto?: boolean;
     /**
@@ -691,6 +777,37 @@ export interface TestOptions extends EngineLockWaitable {
      * `FIREFORGE_SHUFFLE_SEED` for custom task code and recorded on the verdict.
      */
     shuffle?: number | boolean;
+    /**
+     * Run the same selection this many times under one engine-lock hold (the
+     * pre-test build, when requested, runs once). Each run prints a
+     * `FIREFORGE-RUN:` line; the verdict aggregates them with `runs=<p>/<n>`.
+     */
+    repeat?: number;
+    /**
+     * Project-relative path of a reviewed `git diff` against `engine/` or
+     * `components/` sources, applied after the pre-test build and before each
+     * dispatch, and restored byte-exact before the lock is released. The
+     * verdict carries `control=caught|missed|inconclusive`. See
+     * `src/core/negative-control.ts`.
+     */
+    negativeControl?: string;
+    /**
+     * Let a browser run proceed when the mochitest server or Marionette port
+     * is held by something that is not this checkout's own, relying on the
+     * engine harness's busy-port fallback. Same as `test.mochitestPorts: "auto"`.
+     */
+    autoPorts?: boolean;
+    /**
+     * Hold the engine session lock shared for a build-less run with auto
+     * ports, so peers' build-less runs overlap. Same as `test.lockMode: "shared"`.
+     */
+    sharedLock?: boolean;
+    /** Run shards on this many harness instances at once (requires auto ports). */
+    jobs?: number;
+    /** Dispatch n files per mach invocation, judged per file from the raw log. */
+    shardSize?: number;
+    /** Write per-file results (mozlog raw log) as JSON to this path. */
+    results?: string;
 }
 /**
  * Options for the furnace apply command.
@@ -707,10 +824,24 @@ export interface FurnaceApplyOptions extends DryRunnable {
      */
     waitLockSeconds?: number;
 }
+/**
+ * `--wait-lock` budget for a furnace command that takes only Furnace's own
+ * lock (`.fireforge/furnace.lock`, via `runFurnaceMutation`): `create`,
+ * `remove`, `rename`, `refresh`, `scan`, `override`, `preview` and the
+ * `chrome-doc` pair. Without it the flag was accepted and ignored on those
+ * commands, so their lock budget came only from `FIREFORGE_WAIT_LOCK`.
+ */
+export interface FurnaceLockWaitable {
+    /**
+     * Resolved `--wait-lock` budget in seconds, or undefined for the default
+     * (`FIREFORGE_WAIT_LOCK`, else the furnace lock's own 30 s).
+     */
+    waitLockSeconds?: number;
+}
 /**
  * Options for the furnace preview command.
  */
-export interface FurnacePreviewOptions {
+export interface FurnacePreviewOptions extends FurnaceLockWaitable {
     /** Force reinstall Storybook dependencies */
     install?: boolean;
 }
@@ -732,7 +863,7 @@ export interface FurnaceDeployOptions extends DryRunnable {
 /**
  * Options for the furnace refresh command.
  */
-export interface FurnaceRefreshOptions extends DryRunnable {
+export interface FurnaceRefreshOptions extends DryRunnable, FurnaceLockWaitable {
     /** Refresh all overrides in a single batch */
     all?: boolean;
     /** Conflict resolution strategy for automated use (ours = keep local, theirs = accept upstream) */
@@ -740,6 +871,11 @@ export interface FurnaceRefreshOptions extends DryRunnable {
     /** Reset the override's baseline to the current engine HEAD, skipping three-way merge */
     resetBase?: boolean;
 }
+/**
+ * Options for the furnace rename command.
+ */
+export interface FurnaceRenameOptions extends DryRunnable, FurnaceLockWaitable {
+}
 /**
  * Options for the furnace sync command.
  */
@@ -759,25 +895,30 @@ export interface FurnaceSyncOptions extends DryRunnable {
 export interface FurnaceValidateOptions {
     /** Auto-fix registration issues (missing jar.mn entries, customElements.js registration) */
     fix?: boolean;
+    /** Write one schemaVersion-1 JSON document to stdout instead of the human report. */
+    json?: boolean;
+    /** Fail when more than this many warnings remain after `validationExceptions`. */
+    maxWarnings?: number;
 }
 /**
  * Options for the furnace override command.
  */
-export interface FurnaceOverrideOptions {
+export interface FurnaceOverrideOptions extends FurnaceLockWaitable {
     /** Override type: css-only or full */
     type?: 'css-only' | 'full';
     /** Description of the override */
     description?: string;
 }
 /**
- * Options for the furnace remove command. `--yes` is the only flag it takes,
- * so the type is the confirmation mixin under a command-specific name.
+ * Options for the furnace remove command: the confirmation mixin plus the
+ * furnace lock budget.
  */
-export type FurnaceRemoveOptions = Confirmable;
+export interface FurnaceRemoveOptions extends Confirmable, FurnaceLockWaitable {
+}
 /**
  * Options for the furnace create command.
  */
-export interface FurnaceCreateOptions {
+export interface FurnaceCreateOptions extends FurnaceLockWaitable {
     /** Component description */
     description?: string;
     /**
@@ -883,6 +1024,35 @@ export interface RegisterOptions {
 export interface PatchDeleteOptions extends Confirmable, DryRunnable, PatchLockWaitable {
     /** Bypass the hard refusal when later patches depend on the target. */
     forceUnsafe?: boolean;
+    /** Also delete the engine files the patch creates that are still on disk. */
+    deleteCreated?: boolean;
+}
+/**
+ * Options for the `fireforge patch retire` subcommand: `patch delete` that
+ * keeps the removed patch's order as a retired slot in `patches.json`.
+ */
+export interface PatchRetireOptions extends PatchDeleteOptions {
+    /** Optional human-readable rationale stored on the retired slot. */
+    reason?: string;
+}
+/**
+ * Options for the `fireforge patch stage` subcommand: stage the named
+ * patches' files and only their `patches.json` rows in the project index.
+ */
+export type PatchStageOptions = DryRunnable & PatchLockWaitable;
+/**
+ * Options for the `fireforge patch reserve` subcommand: hold an order
+ * number for a patch not exported yet, or release the hold.
+ */
+export interface PatchReserveOptions extends DryRunnable, PatchLockWaitable {
+    /** Category the reserved patch will carry (required to reserve). */
+    category?: string;
+    /** Who holds the reservation (required to reserve). */
+    owner?: string;
+    /** Optional human-readable rationale stored on the reserved slot. */
+    reason?: string;
+    /** Release the reservation at the order instead of creating one. */
+    release?: boolean;
 }
 /**
  * Options for the `fireforge patch rename` subcommand. Updates the patch's
@@ -991,9 +1161,27 @@ export interface StatusOptions {
     /**
      * Comma-separated classification list replacing the default `--check`
      * policy. Implies `--check`. Unknown values refuse, naming the valid
-     * classification set.
+     * classification set. `ownership-conflict` (a path claimed by more than
+     * one patch) is accepted beside the file classifications.
      */
     failOn?: string;
+    /**
+     * Comma-separated classification list that never fails `--check`,
+     * removed from the fail set. Implies `--check`. Naming a class in both
+     * `failOn` and `allow` refuses.
+     */
+    allow?: string;
+    /**
+     * With `allow`: fail on every present classification that neither
+     * `failOn` nor `allow` names, so a classification added by a later
+     * FireForge fails closed. Implies `--check`.
+     */
+    failOnUnknown?: boolean;
+    /**
+     * Judge only these patches (`--patches`, each value may be a comma
+     * list): files they own or claim and ownership rows naming them.
+     */
+    patches?: string[];
 }
 /**
  * Options for the token add command.

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

@@ -51,6 +51,38 @@ export interface PatchResult {
      */
     autoResolvedOriginals?: Map<string, Uint8Array>;
 }
+/**
+ * A size waiver with a ceiling, one form of a `PatchMetadata.lintIgnore`
+ * entry. The named size rule stays suppressed while its measurement is at
+ * or below `max` and fires again past it, so a waived file cannot grow
+ * without bound. Only the measured size rules (`file-too-large`,
+ * `large-patch-lines`, `large-patch-files`) accept a ceiling.
+ */
+export interface LintIgnoreCeiling {
+    /** Size rule check ID the waiver applies to. */
+    rule: string;
+    /** Largest measurement (lines or files) the waiver still suppresses. */
+    max: number;
+    /** Why the waiver exists. Required so the ceiling is reviewable. */
+    reason: string;
+    /**
+     * Which share of a split `large-patch-lines` measurement the ceiling
+     * bounds: `product` (non-test files) or `test` (test files, held to the
+     * test tier). Absent: every finding of the rule. Only valid on
+     * `large-patch-lines`, and a rule carries either one share-less ceiling
+     * or at most one ceiling per share.
+     */
+    share?: PatchSizeShare;
+    /**
+     * Free-form JSON object FireForge preserves and never reads: a place for
+     * a project's own waiver bookkeeping (kind, owner, exit condition).
+     */
+    meta?: Record<string, unknown>;
+}
+/** The two classes a split `addedCode` line measurement reports. */
+export type PatchSizeShare = 'test' | 'product';
+/** One `PatchMetadata.lintIgnore` entry: a bare check ID or a ceiling waiver. */
+export type LintIgnoreEntry = string | LintIgnoreCeiling;
 /**
  * Extended patch information with metadata.
  */
@@ -91,8 +123,11 @@ export interface PatchMetadata {
      * 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
      * is later renamed or removed.
+     *
+     * An entry may instead be a {@link LintIgnoreCeiling}, which waives a size
+     * rule only up to a measured maximum.
      */
-    lintIgnore?: string[];
+    lintIgnore?: LintIgnoreEntry[];
     /**
      * Optional per-patch threshold-tier override for the `large-patch-lines`
      * rule. Exists for branding patches that must touch a small number of
@@ -171,6 +206,26 @@ export interface PatchStagedRegistration {
     /** Optional human-readable rationale for the staged dependency. */
     reason?: string;
 }
+/**
+ * A staged-dependency declaration a lint finding proposes: the arguments of
+ * one `patch staged-dependency <patch> --add` call.
+ */
+export interface PatchLintStagedDeclaration {
+    /** Patch that must carry the declaration. */
+    patch: string;
+    /** Declaration kind (`--kind`). */
+    kind: 'import' | 'registration';
+    /** Declaring file path relative to engine/. */
+    file: string;
+    /** Import specifier (`kind: import`). */
+    specifier?: string;
+    /** Registration line as the patch adds it (`kind: registration`). */
+    line?: string;
+    /** Later-created file path relative to engine/. */
+    creates: string;
+    /** Later patch that creates it. */
+    owner: string;
+}
 /**
  * Schema for patches/patches.json file.
  */
@@ -179,6 +234,49 @@ export interface PatchesManifest {
     version: 1;
     /** Array of patch metadata entries */
     patches: PatchMetadata[];
+    /**
+     * Order numbers a `patch retire` emptied on purpose. A retired slot has no
+     * `.patch` file and no row in `patches`, so apply, export, lint and rebase
+     * never see it; only the `patchPolicy.allowGaps: false` gap check reads it,
+     * as an occupied order. A patch that later takes the same order fills the
+     * slot, and the slot is dropped on that write.
+     */
+    retired?: PatchRetiredSlot[];
+    /**
+     * Order numbers `patch reserve` holds for a patch a session has agreed to
+     * export but has not exported yet. Like a retired slot, a reservation is
+     * read only by the `patchPolicy.allowGaps: false` gap check (as an
+     * occupied order) and by the earliest-legal-order search (as taken); the
+     * export that lands on the order fills it, and the slot is dropped on that
+     * write.
+     */
+    reserved?: PatchReservedSlot[];
+}
+/** One order held by `patch reserve` until its owner exports it. */
+export interface PatchReservedSlot {
+    /** The reserved order number. */
+    order: number;
+    /** Category the reserved patch will carry, so the slot stays in its range. */
+    category: PatchCategory;
+    /** Who holds the reservation: a session label or the planned filename. */
+    owner: string;
+    /** ISO timestamp of the reservation. */
+    reservedAt: string;
+    /** Optional human-readable rationale. */
+    reason?: string;
+}
+/** One placeholder left by `patch retire`. */
+export interface PatchRetiredSlot {
+    /** The order number the retired patch held. */
+    order: number;
+    /** Category of the retired patch, kept so the slot stays in its range. */
+    category: PatchCategory;
+    /** Filename of the retired patch, for the audit trail only. */
+    filename: string;
+    /** ISO timestamp of the retirement. */
+    retiredAt: string;
+    /** Optional human-readable rationale. */
+    reason?: string;
 }
 /**
  * Summary of import operation with continue mode.
@@ -221,6 +319,13 @@ export interface PatchLintIssue {
      * rename-sensitive fingerprint.
      */
     patches?: string[];
+    /**
+     * For a `forward-import` or `forward-registration` finding: the staged
+     * declarations that would discharge it, one per later creator. The same
+     * records the printed `patch staged-dependency --add` commands carry, in
+     * the shape `patch staged-dependency --from` reads back.
+     */
+    stagedDeclarations?: PatchLintStagedDeclaration[];
     /** Severity: errors block export, warnings are advisory, notices are informational (not counted) */
     severity: 'error' | 'warning' | 'notice';
     /**
@@ -232,4 +337,16 @@ export interface PatchLintIssue {
      *   introduced by the current task.
      */
     tag?: 'introduced' | 'cumulative';
+    /**
+     * The value a size rule measured (lines for `file-too-large` and
+     * `large-patch-lines`, files for `large-patch-files`). A lintIgnore
+     * ceiling compares against it, and `lint --report` carries it.
+     */
+    measurement?: number;
+    /**
+     * For a `large-patch-lines` finding under `patchSizeMetric: "addedCode"`
+     * on a general-tier patch: which share of the patch it measured. A
+     * share-scoped lintIgnore ceiling matches only findings of its share.
+     */
+    share?: PatchSizeShare;
 }