@hominis/fireforge 0.50.0 → 0.52.0

package/docs/furnace.md

@@ -47,7 +47,10 @@ in `toolkit/content/jar.mn`, including extra modules beside the main one. Add
 the file to the directory and deploy instead of writing the jar line by hand.
 A line that already registers the file anywhere in the jar (same target, or
 same `(widgets/<tag>/<file>)` source) is kept and never duplicated, so mach
-does not fail with "Item already in manifest".
+does not fail with "Item already in manifest". Removing a file from the
+directory drops only its line, and `furnace rename` rewrites the widget's
+lines where they stand, so the rest of the block keeps its order and the
+owning patch carries no reorder hunks.
 
 The apply and deploy summaries name why each component was skipped, for
 example `Applied 0, skipped 1 (1 already current)`. "Already current" means
@@ -112,6 +115,63 @@ warning asking for the entry to be deleted. A run over one component judges
 only that component's entries. `deploy` honours the same entries when it
 validates, but leaves the staleness report to `validate`.
 
+An entry never suppresses an error (since 0.51.0): an error blocks apply,
+and a review record cannot make a broken component deployable. The error
+stays counted, and the entry is reported as a
+`validation-exception-on-error` error until the finding is fixed and the
+entry deleted.
+
+An optional `tag` narrows an entry to findings about one element tag, so a
+reviewed `<panel-list>` menu does not mute `no-keyboard-handler` for the
+rest of the component. A finding that names several tags (`no-keyboard-handler`
+names every synthetic element with an `@click`) is suppressed only when
+entries cover all of them:
+
+```json
+{
+  "component": "moz-vault",
+  "check": "no-keyboard-handler",
+  "tag": "li",
+  "reason": "Rows are reached through the list's roving focus."
+}
+```
+
+An optional `file` (since 0.52.0) narrows an entry the same way to findings
+in one module of the component, by file name. `hardcoded-text` names the
+modules it found text in, so a vendored bundle whose bytes are pinned (and
+so cannot carry a `furnace-ignore` comment) can be accepted while the
+authored modules beside it keep the check. An entry names a `tag` or a
+`file`, not both:
+
+```json
+{
+  "component": "moz-editor",
+  "check": "hardcoded-text",
+  "file": "moz-editor-codemirror.mjs",
+  "reason": "The vendored bundle's width probe is never rendered."
+}
+```
+
+Accessibility checks judge the composed component: the host
+`<tag>.mjs` and its companion modules (`<tag>-*.mjs`, tests and stories
+left out) read as one source. Moving a template between the component's
+modules therefore no longer changes its findings: a keyboard handler in a
+companion covers an `@click` in the host, and an `@click` in a companion
+is judged too. `hardcoded-text` judges each module on its own, so a
+`// furnace-ignore: hardcoded-text` comment covers the file it is in, not
+its siblings. Toolkit's `panel-item` counts as natively
+keyboard-activated, beside `button`, form controls and the `moz-*` buttons.
+
+`minComponents` sets the fewest components a full `furnace validate` must
+judge. A run under it, an empty tree included, fails with a
+`component-floor` error on `furnace.json`, so a moved or emptied
+components tree cannot pass by validating nothing. A run naming one
+component is not held to it.
+
+```json
+{ "minComponents": 40 }
+```
+
 `optInChecks` turns on checks that are off by default:
 
 ```json

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,21 @@ 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`.
+- `furnace validate --json` (since 0.52.0): a `hardcoded-text` finding
+  carries `files`, the component's module file names it was found in.
+
 ## Versioning
 
 `schemaVersion` is `MACHINE_OUTPUT_SCHEMA_VERSION` in
@@ -159,6 +174,37 @@ 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`. Since 0.52.0 a raw log
+that starts none of a dispatch's requested files counts as
+`started=0/<m> ... started-source=raw` instead of leaving the run uncounted.
+
 ### The additive `shuffle=` key
 
 A `fireforge test --shuffle [seed]` run records the seed used to permute
@@ -210,8 +256,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 +267,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