@hominis/fireforge 0.50.0 → 0.51.0

package/docs/lifecycle-invariants.md

@@ -21,10 +21,11 @@ command, read the decision table at the bottom first.
    take the `.fireforge/engine-session.lock`, then subsystem locks such as
    build, furnace, or patch-directory locks. Furnace mutations serialize on a
    per-root lock, and patch directory mutations (filename allocation plus
-   manifest writes) on a per-directory lock. Dry runs hold the engine-session
-   lock too, because a `re-export --dry-run` over an untracked binary legally
-   touches the git index, and holding the lock serializes even "read-only"
-   previews against real writers.
+   manifest writes) on a per-directory lock. `re-export --dry-run` is the
+   exception: it writes nothing, runs its git plumbing on a private index
+   (so even the `--intent-to-add` staging an untracked binary needs never
+   reaches the shared `.git/index`), and serializes only against other dry
+   runs, so a preview no longer queues behind a peer's build or test run.
 
 3. **A furnace mutation that does not finish restores the engine or says
    so.** Both a signal (SIGINT or SIGTERM) and a thrown error trigger a
@@ -348,13 +349,14 @@ real-procfs `withFileLock` reap of a live-PID stale record.
 The project-wide engine-session lock under `.fireforge/`, stamped with PID,
 command, and start time metadata. CLI `build`, `test`, `export`, `re-export`,
 `furnace apply`, `furnace deploy` and `furnace sync` take it before subsystem
-locks, unconditionally, including dry runs: a `re-export --dry-run` over an
-untracked binary legally touches the git index (temporary `--intent-to-add`
-staging), so holding the lock serializes even "read-only" previews against
-real writers. Dry-run purity is separately enforced at runtime by
-`withDryRunPurityGuard` (`re-export-bulk-scan.ts`), which fingerprints the
-engine tree and every patch artifact around the dry run and fails hard on
-divergence.
+locks. `re-export --dry-run` does not: it runs inside `withPrivateGitIndex`,
+so its temporary `--intent-to-add` staging lands on a throwaway index, and it
+serializes only against other dry runs. Dry-run purity is enforced at runtime
+by `withDryRunPurityGuard` (`re-export-bulk-scan.ts`). For `re-export` it
+fingerprints what the dry run could touch (the engine HEAD and index, the
+selected patches' bodies, their `patches.json` rows and the engine files they
+own) and fails hard on divergence, naming a foreign writer when the history
+log or the engine-session lock shows one in the window (`re-export-purity-scope.ts`).
 
 Contention fails fast after about a second by default, with the fixed message
 "Another FireForge engine-mutating command is already running. Wait for it to

package/docs/machine-output.md

@@ -53,21 +53,21 @@ if (options.json === true) {
 
 ## Current surfaces
 
-| Surface                            | Shape                                                                                                                                                                                                              | Notes                                                                                                                                                                                                                              |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `status --json`                    | `{ schemaVersion: 1, … }`                                                                                                                                                                                          | Error envelope on three engine preconditions                                                                                                                                                                                       |
-| `status --json` under `--check`    | adds `check: { enabled, failOn, allow?, failOnUnknown?, failed, offenders }`                                                                                                                                       | Since 0.50.0 on the full payload too, not only `--summary`. `allow` and `failOnUnknown` appear only when set. An offender failing only through `--fail-on-unknown` carries `unnamed: true`. `--patches` adds `scope: { patches }`  |
-| `furnace validate --json`          | `{ schemaVersion: 1, passed, summary, maxWarnings?, components, issues, excepted, staleExceptions }`                                                                                                               | `issues` counts after `validationExceptions`, stale-exception warnings included. `excepted` carries each suppressed finding with its `reason`                                                                                      |
-| `check --json`                     | `{ schemaVersion: 1, verdict, reason?, summary, steps }`                                                                                                                                                           | One entry per step: `name`, `kind`, `command`, `status` (`pass`/`fail`/`skipped`), `exitCode`, `durationMs`, `detail`, and on failure `outputTail` (`timedOut` when killed at its budget). No verdict line under `--json`          |
-| `check` verdict line               | `FIREFORGE-VERDICT: PASS\|FAIL [reason=step-failures\|lock-timeout failed=<steps>] steps=<n> skipped=<n>`                                                                                                          | Not JSON. The last stdout line, after the step table, sealed like `test`'s. Its `reason=` set is its own, not `test`'s                                                                                                             |
-| `tree list --json`                 | `{ schemaVersion: 1, trees }`                                                                                                                                                                                      | Error envelope added in 0.44.0                                                                                                                                                                                                     |
-| `token list --json`                | `{ schemaVersion: 1, tokensCssPath, categories }`                                                                                                                                                                  | Categories in file order, each with its tokens (`name`, `line`, `value`)                                                                                                                                                           |
-| `token show --json`                | `{ schemaVersion: 1, name, category, declarations }`                                                                                                                                                               | One entry per declaring block, with its selector trail and line                                                                                                                                                                    |
-| `token lint --json`                | `{ schemaVersion: 1, tokensCssPath, tokenPrefix, filesScanned, findings }`                                                                                                                                         | Each finding has `check`, `file`, `line`, `token`, `message`. The document is written even when findings exist; the exit is then non-zero, as with `status --check --json`                                                         |
-| `test` verdict line                | `FIREFORGE-VERDICT: PASS\|FAIL reason=… [note=<class>] [started=<n>/<m> first-unstarted=<path>] [runs=<p>/<n>] [control=<outcome>] [shuffle=<seed>] [furnace-applied=<names>\|furnace-apply=skipped] [log=<path>]` | Not JSON. A single final stdout line, sealed by `setStdoutSealed` so nothing can displace it. `log=` names the run's own complete output under `.fireforge/logs/`, so a piped or truncated run still leaves a re-readable artifact |
-| `lint --per-patch --report <path>` | `{ schemaVersion: 1, patches, queueIssues, totals, … }`                                                                                                                                                            | Written to a file. `queueIssues` holds the cross-patch findings; `patch staged-dependency --add --from` reads back their `stagedDeclarations`                                                                                      |
-| `status --raw`                     | `git status --porcelain` lines                                                                                                                                                                                     | Not JSON, but still a machine surface: it engages the same stdout discipline, so rules 3 and 4 apply and rules 1 and 2 do not. A clean tree prints nothing                                                                         |
-| `build` log announcement           | `Full build output: <path>`                                                                                                                                                                                        | Not JSON. `build` prints no verdict line, so it names its run log directly on the way out                                                                                                                                          |
+| Surface                            | Shape                                                                                                                                                                                                                                                                             | Notes                                                                                                                                                                                                                              |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `status --json`                    | `{ schemaVersion: 1, … }`                                                                                                                                                                                                                                                         | Error envelope on three engine preconditions                                                                                                                                                                                       |
+| `status --json` under `--check`    | adds `check: { enabled, failOn, allow?, failOnUnknown?, failed, offenders }`                                                                                                                                                                                                      | Since 0.50.0 on the full payload too, not only `--summary`. `allow` and `failOnUnknown` appear only when set. An offender failing only through `--fail-on-unknown` carries `unnamed: true`. `--patches` adds `scope: { patches }`  |
+| `furnace validate --json`          | `{ schemaVersion: 1, passed, summary, maxWarnings?, components, issues, excepted, staleExceptions }`                                                                                                                                                                              | `issues` counts after `validationExceptions`, stale-exception warnings included. `excepted` carries each suppressed finding with its `reason`                                                                                      |
+| `check --json`                     | `{ schemaVersion: 1, verdict, reason?, summary, steps }`                                                                                                                                                                                                                          | One entry per step: `name`, `kind`, `command`, `status` (`pass`/`fail`/`skipped`), `exitCode`, `durationMs`, `detail`, and on failure `outputTail` (`timedOut` when killed at its budget). No verdict line under `--json`          |
+| `check` verdict line               | `FIREFORGE-VERDICT: PASS\|FAIL [reason=step-failures\|lock-timeout\|skipped-steps failed=<steps>] steps=<n> skipped=<n> [skipped-steps=<steps>]`                                                                                                                                  | Not JSON. The last stdout line, after the step table, sealed like `test`'s. Its `reason=` set is its own, not `test`'s                                                                                                             |
+| `tree list --json`                 | `{ schemaVersion: 1, trees }`                                                                                                                                                                                                                                                     | Error envelope added in 0.44.0                                                                                                                                                                                                     |
+| `token list --json`                | `{ schemaVersion: 1, tokensCssPath, categories }`                                                                                                                                                                                                                                 | Categories in file order, each with its tokens (`name`, `line`, `value`)                                                                                                                                                           |
+| `token show --json`                | `{ schemaVersion: 1, name, category, declarations }`                                                                                                                                                                                                                              | One entry per declaring block, with its selector trail and line                                                                                                                                                                    |
+| `token lint --json`                | `{ schemaVersion: 1, tokensCssPath, tokenPrefix, filesScanned, findings }`                                                                                                                                                                                                        | Each finding has `check`, `file`, `line`, `token`, `message`. The document is written even when findings exist; the exit is then non-zero, as with `status --check --json`                                                         |
+| `test` verdict line                | `FIREFORGE-VERDICT: PASS\|FAIL reason=… [note=<class>] [started=<n>/<m> first-unstarted=<path> started-source=<src>] [shards=<p>/<t> [failed-shards=<labels>]] [runs=<p>/<n>] [control=<outcome>] [shuffle=<seed>] [furnace-applied=<names>\|furnace-apply=skipped] [log=<path>]` | Not JSON. A single final stdout line, sealed by `setStdoutSealed` so nothing can displace it. `log=` names the run's own complete output under `.fireforge/logs/`, so a piped or truncated run still leaves a re-readable artifact |
+| `lint --per-patch --report <path>` | `{ schemaVersion: 1, patches, queueIssues, totals, … }`                                                                                                                                                                                                                           | Written to a file. `queueIssues` holds the cross-patch findings; `patch staged-dependency --add --from` reads back their `stagedDeclarations`                                                                                      |
+| `status --raw`                     | `git status --porcelain` lines                                                                                                                                                                                                                                                    | Not JSON, but still a machine surface: it engages the same stdout discipline, so rules 3 and 4 apply and rules 1 and 2 do not. A clean tree prints nothing                                                                         |
+| `build` log announcement           | `Full build output: <path>`                                                                                                                                                                                                                                                       | Not JSON. `build` prints no verdict line, so it names its run log directly on the way out                                                                                                                                          |
 
 `--raw` is why `cli.ts` reads `process.argv` for `--json` or `--raw` before
 dispatching. Rule 3 is about who owns stdout, and that question is settled
@@ -80,6 +80,19 @@ it. Follow the rules above rather than inventing a shape.
 
 The run logs behind `log=` are specified in [`run-logs.md`](run-logs.md).
 
+Additive keys since 0.51.0 outside `test`:
+
+- `check --json`: a skipped step carries `skipKind`, `config` when
+  `check.skip` names it and `unavailable` when the project has nothing for
+  it to run. The verdict line adds `skipped-steps=<steps>` whenever a step
+  is skipped, and `reason=skipped-steps` when `check.failOnSkipped` fails a
+  run on an `unavailable` skip alone.
+- `furnace validate --json`: a finding about particular elements carries
+  `tags` (`no-keyboard-handler` names each synthetic element with an
+  `@click`). An exception that matched an error adds a
+  `validation-exception-on-error` error, and a full run under
+  `furnace.json#minComponents` a `component-floor` error on `furnace.json`.
+
 ## Versioning
 
 `schemaVersion` is `MACHINE_OUTPUT_SCHEMA_VERSION` in
@@ -159,6 +172,35 @@ that has none. A run refused only for a non-zero `unexpected=` count or a
 mid-test shutdown carries neither. Absent on every other line. See
 [`testing.md`](testing.md#the-verdict-line).
 
+`started-source=raw|stream|capture` follows them and names the evidence the
+count came from: the mozlog structured log (a run with `--results` or
+`--shard-size`), the complete streamed output (every other run), or, only
+when nothing was streamed, the last 2 MB of the capture.
+
+### Shards: `FIREFORGE-SHARD:` and `failed-shards=`
+
+A sharded run prints one `FIREFORGE-SHARD:` line per finished shard, before
+the verdict line:
+
+```
+FIREFORGE-SHARD: PASS|FAIL [reason=…] [checks=<n>] [unexpected=<n>] shard=<i>/<n> path=<label> [failed-files=<path>,…]
+```
+
+`path=` is the shard's path argument (whitespace replaced by `_`), or a
+`--shard-size`/`--jobs` chunk's first file plus `+<k>`. `failed-files=`
+appears under `--shard-size` and names the chunk's files that failed. The
+aggregate verdict appends `failed-shards=<label>,…` after `shards=` when any
+shard did not pass; under `--shard-size` `shards=` counts files and
+`failed-shards=` names files. Both are absent on a green run.
+
+### Additive keys of parallel and per-file runs
+
+`jobs=<n>` marks a `--jobs` run, `lock=shared` a run that held the engine
+session lock shared, and `results=<path>` names the `--results` document. A
+run whose engine changed mid-run only in files the running browser cannot
+see keeps its verdict and appends `drift-tolerated=<n>`. A negative control
+on compiled source appends `control-build=compiled`.
+
 ### The additive `shuffle=` key
 
 A `fireforge test --shuffle [seed]` run records the seed used to permute
@@ -210,8 +252,10 @@ the verdict `reason=inconclusive` only when HEAD moved or a changed path is
 packaged by the running build: a source an objdir install manifest names, a
 directory one installs from, or a test file. Edits that no manifest installs
 (compiled sources, build files, docs) leave the sample standing with a
-warning naming them. Other runs keep the strict rule: any change is
-inconclusive.
+warning naming them. Other runs are inconclusive only when a changed path is
+one the running browser can see: a file the objdir links to its source, one
+staged at dispatch, or a test file or staging input of the run; anything
+else leaves the verdict standing with `drift-tolerated=<n>`.
 
 ### Additive Furnace keys
 
@@ -219,4 +263,6 @@ A `fireforge test --build` or `--build-only` run whose pre-test Furnace apply
 deployed components appends `furnace-applied=<name>,<name>…`: the components
 whose `components/` source changed since their last deploy, which the
 runtime under test therefore includes. `--no-furnace-apply` skips that apply
-and appends `furnace-apply=skipped`. Both are absent otherwise.
+and appends `furnace-apply=skipped`. `--furnace-apply reached` appends
+`furnace-skipped=<names>` for components with undeployed edits that no
+requested test reaches. All are absent otherwise.

package/docs/patch-workflow.md

@@ -37,6 +37,14 @@ directories. The manifest is JSON:
 The command can be dry-run, refuses ambiguous ownership, and reports each
 file-to-patch assignment before refreshing the patch.
 
+`re-export --dry-run` takes no engine-session lock: it writes nothing, so it
+does not queue behind a peer's build or test run, and its git plumbing runs on
+a private index. Its purity guard covers what the dry run could touch (the
+selected patches, their `patches.json` rows, the engine files they own, and
+the engine HEAD and index). A peer writing any of those during the preview is
+named from the history log or the engine-session lock, and the preview is
+simply rerun.
+
 To adopt files into several patches in one call, name each file's owner
 with `--scan-file <patch>:<path>`. A call with more than one target patch
 requires the prefix on every `--scan-file`. Selected patches that get no
@@ -68,6 +76,29 @@ module a later patch creates. They also refuse a forward registration
 module), in the same refusal and with the `patch staged-dependency` command
 that declares it, so one declaration pass covers both.
 
+### Exporting by hunk
+
+Re-export captures whole files, so on a shared engine a peer's unexported
+line in a shared manifest or chrome document lands in the exporting patch.
+Two flags export a file by hunk instead. Each takes one explicit patch and
+cannot combine with `--scan`, `--files` or `--all`:
+
+- `--hunks-from <diff>` exports each file the diff names as the patch's
+  current body for it plus only the diff's hunks. Files the diff does not
+  name keep their old section.
+- `--exclude-hunks <diff>` exports each named file as the working tree minus
+  the diff's hunks. The other files export as usual.
+
+Hunks are placed by their context, so a diff taken before a peer's edit
+above it still applies, and a hunk whose context is gone refuses. The
+section is diffed by git against HEAD on a throwaway index, and the engine
+is not touched. A spine patch can then export one change's lines at a time:
+
+```sh
+git -C engine diff -- browser/base/content/hominis.js > my-change.diff   # trim to your hunks
+fireforge re-export 200 --hunks-from my-change.diff
+```
+
 ### Re-export belts and arguments
 
 `--refuse-adjacent-unmanaged` refuses a patch when an unmanaged file is
@@ -82,6 +113,10 @@ session's unexported test in `test/hominis-tiles/` no longer refuses a
 patch that owns `test/hominis/browser.toml`. The refusal names every file
 with its anchor (`beside engine/<dir>` or `registered by engine/<carrier>`).
 
+Beside `--scan` and `--scan-file` the belt judges the adjacent files the
+scan did not adopt, so one call can adopt a new widget and its test and
+still refuse a peer's neighbour. It cannot combine with `--files`.
+
 Three carve-outs keep the belt armed for everything they do not name. Each
 requires `--refuse-adjacent-unmanaged`, and each admitted file is still
 listed:
@@ -142,7 +177,10 @@ deleted whose engine copy is back at HEAD:
 fireforge re-export 202 --refuse-adjacent-unmanaged --refuse-foreign-drift --expect browser/themes/shared/hominis/widgets.css --expect-removed browser/themes/shared/hominis/stop.svg
 ```
 
-The removal must have exactly one selected owner. A patch-created file must
+Each removal must have exactly one selected owner, and one call may retire
+paths from several selected patches (`re-export 102 202 --expect-removed a
+--expect-removed b`). A path whose owner was left out of the selection is
+refused with that owner named. A patch-created file must
 be absent from disk and engine HEAD, and have a `new file mode` section in
 that owner's patch. An upstream file must be tracked in HEAD, match it on
 disk, and have a section in that owner's patch. Without the retirement, a
@@ -161,7 +199,18 @@ later patch creates names the earliest legal order for exporting those
 files as their own patch (free, inside the category range, and not opening
 a gap under `allowGaps: false`), and prints the exact `patch
 staged-dependency --add` command for each edge, with a `--reason`
-placeholder.
+placeholder. A refused `--scan` adoption, `patch move-files` or `patch split`
+also writes every declaration it proposes into one lint-report-shaped JSON
+(`--declarations-out <path>`, by default under `.fireforge/declarations/`)
+and names the single `patch staged-dependency <holder> --add --from <file>`
+call per holding patch that discharges them all. Moving tests out of a patch
+that owns a shared manifest no longer needs one declaration typed per
+manifest line.
+
+A re-export also drops a staged registration whose `creates` path no patch
+in the queue owns any more, for example after a merge deleted the file it
+registered. The dry run names the drop, and the write records it in the
+history log (`re-export-staged-prune`).
 
 An `export --order` (or `--before`/`--after`) refused on a new system
 module that no patch registers in moz.build says "register first". When the
@@ -214,6 +263,40 @@ Under `fireforge patch`:
   occupied. A patch that later takes the order (`export --order <n>`, a
   rename or a renumber) fills the slot, which then disappears. `patch
 compact` renumbers through retired slots like any other gap.
+- `patch delete` and `patch retire` name each file the patch creates that is
+  still on disk, in the dry run and at the prompt: once the patch is gone
+  nothing owns it, so `status` would report it unmanaged. Delete those files
+  first, or pass `--delete-created` to remove them as part of the confirmed
+  operation (under the engine lock as well). Files the patch only modifies
+  keep their edits and become unmanaged, as before.
+- `patch reserve <order> --category <c> --owner <label> [--reason <text>]`
+  holds an order for a patch a session has agreed to export but has not
+  exported yet. The reservation lives in `patches.json#reserved`. Like a
+  retired slot, the gap check counts it as occupied, so `export --order 571`
+  is legal while a peer holds 569 and 570. Unlike a retired slot, the
+  earliest-legal-order search and a default `export` skip it, because it is
+  held for its owner. The export that lands on the order fills it, with a
+  notice naming the owner. `patch reserve <order> --release` drops a
+  reservation whose patch will not come. An order a patch, a retired slot or
+  another reservation holds, or one outside the category's range, is
+  refused.
+- `patch stage <name>...` stages the named patches' `.patch` files and only
+  their rows of `patches/patches.json` in the project repository's git index.
+  Every other row stays as at HEAD. The staged manifest is built from HEAD's
+  rows plus the named working rows (with their retired slots; a reservation
+  a staged row fills is dropped), validated, and written with `git
+hash-object` and `git update-index`. A collision (two rows at one order) or
+  an invalid result is refused before the index is touched. The working copy
+  is never changed and nothing is committed. Name a patch the working copy
+  no longer has by its HEAD filename to stage its removal, and name both
+  filenames of a renamed patch.
+- `patch staged-dependency <name> --remove` names the entries to remove by
+  any of `--file`, `--specifier`/`--line`, `--creates` and `--owner`. It needs
+  `--creates`, or `--file` with the matcher. `--creates` alone removes every
+  declaration for that created path, which is the cleanup after a merge
+  deletes it. Registration lines compare whitespace-insensitively, as the
+  lint does. A selection that matches nothing is refused with exit 8 (it used
+  to print "no staged registration matched" and exit 0), on a dry run too.
 - `patch staged-dependency <name> --add --from <json-file>` adds many
   declarations in one call under one lock hold. The file is a `lint
 --per-patch --report` document (its findings' `stagedDeclarations` for
@@ -223,6 +306,24 @@ reason?, patch? }` entries; entries naming another patch are skipped, and
   only its delta (`added` / `removed`) in the history; records written
   before 0.50.0 carry the whole `before` / `after` lists instead.
 
+### Parking a session's edits
+
+Several sessions edit the same files, and a peer's `re-export
+--refuse-foreign-drift` refuses while another session's hunks sit in its
+patch's files. `fireforge park <patch>` sets them aside: every drifted file of
+the patch goes back to its queue-applied baseline (or, with `--hunks <diff>`,
+only the named hunks come out of the working tree), and both sides of each
+file are kept under `.fireforge/park/<label>/`. After the owner commits,
+`fireforge park --restore <label>` three-way merges the parked edits back on
+top of the commit. A conflict leaves markers, keeps the park and exits
+non-zero. `park --list` and `park --drop <label>` manage parks, `--dry-run`
+previews, and park takes the engine lock.
+
+Before parking it warns when a hunk it takes out removes a Fluent message id,
+or a whole file, that files outside the patch still reference. A parked
+string still used by markup another patch owns makes `document.l10n.ready`
+reject in every new window, so move it somewhere you own first.
+
 Every queue-mutating patch command accepts `--wait-lock [seconds]`. See
 [`configuration.md`](configuration.md#lock-waits) for how the budget
 resolves.
@@ -260,7 +361,15 @@ programmatic API, with the file-size helpers `isTestFile`,
 `file-too-large` measures in a patch: the JS files it creates, and never a
 modified file or a new file of another kind. The rule selects its files
 through that same function, so an audit that uses it cannot drift from the
-rule.
+rule. Since 0.51.0 the API also exports the measurement the size rules
+themselves take, `measurePatchSize(engineDir, diff, filesAffected, config)`
+(lines, test-file lines, files and registration files under the configured
+metric), `isPatchSizeRegistrationFile(file, globs)`, the per-line
+`codeLineMask(file, content)` behind `countCodeLines`, and
+`evaluatePatchPolicyContentForQueue(config, projectRoot, patchesDir,
+manifest)`, the body-dependent `patchPolicy` rules `verify` runs. A waiver
+audit or a policy probe can then measure a patch exactly as the lint does,
+without importing `dist/` files by path.
 
 `lint --per-patch` measures sizes on the working tree, the way export and
 re-export do: each patch's diff is taken against the engine baseline from
@@ -272,10 +381,13 @@ thresholds.
 
 Per-patch lint type-checks plain Firefox JS against a built-in
 Firefox-globals shim that tracks upstream WebIDL additions per release. A
-`resource://` or `chrome://` import the per-patch program cannot resolve (a
-module another patch creates, outside the file's program) is typed `any`;
-an implicit-`any` finding in a file with such an import names it, since the
-whole-tree `fireforge typecheck` sees the real type. See
+`resource://` or `chrome://` import resolves to the module the queue
+creates under that name; a test script's own program sees the modules
+created up to the test's patch. An import the program cannot resolve (a
+module a later patch creates, an upstream module, or a basename two
+patches create) is typed `any`; an implicit-`any` finding in a file with
+such an import names it, since the whole-tree `fireforge typecheck` sees
+the real type. See
 [`configuration.md`](configuration.md#patchlint) for the project hooks
 (`checkJsExtraShim`, `checkJsTestFiles`, `checkJsTestShim`).
 
@@ -328,11 +440,49 @@ longer reaches its own warning band, `lint --per-patch` prints a
 `lint-ignore-removable` notice naming the `patch lint-ignore --remove`
 command, and the `--report` JSON carries each ceiling under
 `lintIgnoreCeilings` with its current `measurement` and a `state` of
-`within`, `exceeded` or `removable`. An `--add` for a rule that already has
-an entry replaces it, so the same command moves a ceiling or widens it back
-to a bare waiver. `export` and `re-export --lint-ignore <id>` only append
-bare IDs, and never widen an existing ceiling. The manifest refuses a
-ceiling on any other rule, and a second entry for the same rule.
+`within`, `exceeded` or `removable`. A notice never exceeds a ceiling: it
+gates nothing, so a notice-band measurement past `max` surfaces as the plain
+notice it is. The report's `lintIgnoreWaivers` lists every entry, bare IDs
+included (`kind: "bare"`, `max: null`), with the same `measurement` and
+`state`, so an audit does not have to re-measure bare waivers from
+`suppressedIssues`. For a bare waiver the state is informational:
+`removable` also covers a rule this lint does not run. An `--add` for a rule
+that already has an entry replaces it, so the same command moves a ceiling
+or widens it back to a bare waiver. `export` and `re-export --lint-ignore
+<id>` only append bare IDs, and never widen an existing ceiling. The manifest
+refuses a ceiling on any other rule, and a second entry for the same rule.
+
+Under `patchSizeMetric: "addedCode"` a general-tier patch's
+`large-patch-lines` findings carry `share: "product"` (non-test files) or
+`share: "test"` (test files, held to the test tier). A ceiling can name the
+share it bounds, and `large-patch-lines` may then carry one ceiling per
+share instead of a single one:
+
+```json
+"lintIgnore": [
+  { "rule": "large-patch-lines", "share": "product", "max": 900, "reason": "…" },
+  { "rule": "large-patch-lines", "share": "test", "max": 4000, "reason": "…",
+    "meta": { "kind": "structural", "owner": "tiles" } }
+]
+```
+
+A ceiling's optional `meta` is a free-form JSON object FireForge keeps
+verbatim and never reads, for a project's own waiver bookkeeping (kind,
+owner, exit condition). The report echoes it.
+
+Several ceilings go in one call, under one lock hold and one manifest write:
+`--add <rule>=<max>` gives each entry its own ceiling (`--reason` applies to
+all of them, `--share` scopes a `large-patch-lines` one), and `--from
+<json-file>` adds every entry of a JSON array (check IDs, or `{ rule, max,
+reason?, share?, meta?, patch? }` objects; entries naming another patch are
+skipped, and `--reason` fills objects without one). Given a `lint --per-patch
+--report` document instead, `--from` rebaselines each of the patch's
+ceilings to its current `measurement`.
+
+```sh
+fireforge patch lint-ignore 310-ui-sidebar --add file-too-large=1200 --add large-patch-files=40 --reason "Rebaseline 2026-10"
+fireforge patch lint-ignore 310-ui-sidebar --from lint-report.json
+```
 
 ## CI enforcement
 
@@ -369,9 +519,20 @@ them (filename, stem, order number, manifest name or slug). A peer's drifted
 patch then no longer turns this session's gate red. The limit is the
 point: an unmanaged file belongs to no patch, so a scoped run never judges
 unexported files, this session's included. Run the unscoped gate before a
-commit that should cover them. `verify --patches` keeps findings about the
+commit that should cover them. `lint --per-patch --patches` keeps every
+queue finding that names a scoped patch, even on a file the patch no longer
+touches (a stale `staged-dependency-unused` declaration, since 0.51.0). `verify --patches` keeps findings about the
 queue as a whole (a `patches.json` that does not parse) whatever the scope.
 
+`verify` resolves every `resource:///modules/…` and `resource://gre/modules/…`
+`.sys.mjs` specifier the queue's files import, and fails on a fork module that
+is missing or that no `moz.build` at or above its directory registers. Such
+an import otherwise crashes every browser start of the objdir, or kills
+xpcshell with no output. An unscoped run also scans the engine worktree:
+changed files are read for imports, and untracked files count as fork
+modules. That covers a chrome script's lazy getter for a module that neither
+file has exported yet.
+
 `fireforge check` composes the static gates into one command: `status`
 (as `--json --summary --check`), `verify`, `lint --per-patch`,
 `typecheck`, `furnace validate` and `token coverage`, plus the project's

package/docs/testing.md

@@ -107,6 +107,21 @@ read from the objdir, not from `engine/`, so a control on it stays green
 and reports `missed`: that result is the signal to target the file the
 browser actually loads.
 
+A control on compiled source (C/C++, Rust, IDL, WebIDL, IPDL or YAML that no
+install manifest ships) can only reach the binary through a build. Without
+`--build` it is refused before the lock. With `--build` it is applied before
+the pre-test build, so the binary under test carries it, stays applied for
+every `--repeat` run, and is restored with a fresh mtime so the next build
+recompiles the original. The verdict adds `control-build=compiled`. A
+build-less control whose packaging is not current is refused before the
+lock with the advice to add `--build`, instead of ending `inconclusive`
+after a full queue.
+
+Besides `git diff` output, a control may be a plain unified diff
+(`diff -u`, no `diff --git` lines; the path comes from `---`/`+++`) or a
+`git diff --no-index <engine file> <edited copy>`: when the new side names a
+copy outside `engine/` and `components/`, the control targets the old side.
+
 ### The restore safety model
 
 - **Only under the lock.** Apply, run and restore all happen inside the
@@ -194,7 +209,11 @@ earlier path whose own inputs and `engine/mozconfig` are unchanged, whatever
 moved elsewhere in the engine, including a peer's edits and an engine HEAD
 move that touches none of them. A path whose inputs changed is dropped and
 named, with the inputs that changed. Changed inputs this build restages are
-allowed.
+allowed, and a scoped build of one file restages that file's test manifest
+too: a manifest that gained an entry for the new file no longer drops the
+claims of its sibling files. A build-less run's packaging gates also run
+before the lock is requested, so a `coverage-replaced` or `stale-build`
+refusal arrives before the run queues.
 
 A scoped build after a full build keeps the claim full while nothing outside
 its scope moved. Otherwise it carries the full build's anchor forward, and a
@@ -221,6 +240,15 @@ packages `engine/` as it stands, for example for a before-capture, names the
 components with undeployed edits it left out, and stamps
 `furnace-apply=skipped`.
 
+On a shared engine a peer's default `test --build` deploys every session's
+undeployed component edits. `--furnace-apply reached` (or
+`test.furnaceApply: "reached"`) deploys only the components a requested test
+reaches: the test path, the test file, a `head*.js` beside it, or any test
+file under a requested directory names the component. The rest are named in
+a notice and stamped `furnace-skipped=<names>`. A path-less build reaches
+every component. `--furnace-apply none` is `--no-furnace-apply`; `all` is the
+default.
+
 When `patchLint.checkJs` and `patchLint.checkJsTestFiles` are enabled, named
 pre-test builds check the selected test scripts before deployment or mach.
 This includes new scripts not yet owned by an exported patch. The check runs
@@ -247,7 +275,7 @@ launchd-parented app remains unattributed and is not automatically killed.
 `test --wait-browser [seconds]` waits for this objdir's browser to exit;
 `test --wait-port [seconds]` waits for mochitest and Marionette listeners.
 `build --wait-browser [seconds]` queues a full or UI build behind the browser.
-Bare flags wait 60 seconds; explicit values accept 1–3600 seconds. They are
+Bare flags wait 60 seconds; explicit values accept 1–86400 seconds. They are
 independent of the FireForge lock budget, and they are spent BEFORE the
 engine session lock is requested, so a run waiting out a browser or a port
 does not hold every peer's build, test and re-export behind it. The run then
@@ -433,9 +461,16 @@ group sweep.
 Every test run ends with one machine-readable line:
 
 ```
-FIREFORGE-VERDICT: PASS|FAIL reason=… [note=<class>] [started=<n>/<m> first-unstarted=<path>] [runs=<p>/<n>] [control=<outcome>] [shuffle=<seed>] [orphans-reaped=<n>] [furnace-applied=<names>|furnace-apply=skipped] [log=<path>]
+FIREFORGE-VERDICT: PASS|FAIL reason=… [note=<class>] [started=<n>/<m> first-unstarted=<path> started-source=<src>] [shards=<p>/<t> [failed-shards=<labels>]] [runs=<p>/<n>] [control=<outcome>] [shuffle=<seed>] [orphans-reaped=<n>] [furnace-applied=<names>|furnace-apply=skipped] [furnace-skipped=<names>] [jobs=<n>] [lock=shared] [results=<path>] [log=<path>]
 ```
 
+The start count reads every line the harness printed, not the last 2 MB of
+captured output: a suite printing more than that (a large browser directory,
+or any run under `--full-output`) used to report files that ran and passed
+as never started. `started-source=` names the evidence. A sharded run also
+prints a `FIREFORGE-SHARD:` line per shard and names the shards that did not
+pass as `failed-shards=`; see [`machine-output.md`](machine-output.md).
+
 A run is never `PASS` when its summary reports unexpected results, when the
 harness printed "Application shut down (without crashing) in the middle of a
 test", or when a requested test file never produced a start (or skip)
@@ -528,7 +563,41 @@ The two phases handle it differently, on purpose:
 
 A test run holds the engine-session lock and snapshots the engine git
 generation before and after the harness run, failing the verdict as invalid
-if the tree changed mid-run. The checks that need no lock run before it is
+if the tree changed mid-run in a way the running browser can see: a file the
+objdir links to its source, a file staged at dispatch, or a test file or
+staging input of the run. A peer's edit to anything else (a compiled source,
+a copied file, an unrelated test) leaves the verdict standing with a warning
+and `drift-tolerated=<n>`; the next run's stale-build gate judges whether it
+needs a rebuild.
+
+`--shared-lock` (or `test.lockMode: "shared"`) holds the lock shared for a
+build-less run that applies no negative control and uses auto ports, so
+several such runs on one objdir overlap. Anything that writes (a build, a
+re-export, a `test --build`) still holds the lock alone: it waits for shared
+holders to finish, and new shared holders queue behind it.
+`status --lock` counts shared holders. Orphan reaping only touches helpers
+whose parent died, so overlapping runs do not reap each other's live
+helpers.
+
+`--jobs <n>` runs a request's shards on n harness instances inside one lock
+hold. Each instance has its own profile and its own Marionette port, and
+auto ports (required) move each instance's mochitest server ports; output
+lines carry a `[job <i>]` prefix in the terminal and the run log. With
+`--no-shard`, or a single directory argument, the files are split in order
+into n contiguous chunks. Parallel browsers raise host load, so measure
+before relying on it.
+
+`--shard-size <n>` dispatches n files per mach invocation (mochitest restarts
+the browser between files), paying the harness start once per chunk instead
+of once per file, and judges each file from mozlog's structured log:
+`shards=` then counts files and `failed-shards=` names failed files.
+
+`--results <path>` writes one JSON record per test file and `--repeat` run
+(status, expected status, duration, unexpected subtests, the shard, and the
+run-log line where the dispatch began) from mozlog's structured log, which
+each dispatch then writes with `--log-raw`, and names it on the verdict as
+`results=<path>`. A `--log-raw <file>` already forwarded with `--mach-arg` is
+read instead. The checks that need no lock run before it is
 requested: the launchable binary, the named-file checkJs pass, and the
 `--wait-browser`/`--wait-port` budgets. The run log is open from the start,
 so a `reason=lock-timeout` line carries `log=` too.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -76,9 +76,9 @@
     "eslint-plugin-simple-import-sort": "^14.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",
-    "knip": "6.39.0",
+    "knip": "6.41.0",
     "lint-staged": "^17.0.4",
-    "prettier": "3.9.9",
+    "prettier": "3.9.10",
     "tsx": "^4.7.0",
     "typescript": "~6.0.0",
     "typescript-eslint": "^8.0.0",