@hominis/fireforge 0.44.1 → 0.44.3

package/docs/lifecycle-invariants.md

@@ -0,0 +1,309 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Mutation lifecycle invariants (internal)
+
+Internal architecture notes for contributors. FireForge's safety behavior
+around destructive operations is deliberately spread across small modules;
+this document is the one place that states the invariants those modules
+uphold **together**, and which module owns which piece. If you add a new
+mutating command, read the decision table at the bottom first.
+
+## The invariants
+
+1. **Only `bin/fireforge.ts` terminates the process.** Library code
+   propagates `CommandError` / `FireForgeError`; it never calls
+   `process.exit`. Enforced by the process-boundary test.
+2. **At most one real engine/patch mutation runs at a time** per resource:
+   CLI build/test/export/re-export/furnace mutations 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, patch directory mutations (filename allocation + manifest
+   writes) on a per-directory lock. Dry-runs hold the engine-session lock
+   too — 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.
+3. **A furnace mutation that does not finish restores the engine or says so.**
+   Both a signal (SIGINT/SIGTERM) and a thrown error trigger a journal-based
+   rollback; if rollback is incomplete or uncertain, a `pendingRepair` marker
+   blocks all further furnace mutations until
+   `fireforge doctor --repair-furnace` reconciles.
+
+   The thrown-error half landed in 0.43.0. Before it, `runFurnaceMutation`'s
+   `finally` only deregistered the operation — and because it also set
+   `completed`, a body that threw removed itself from the signal handler's
+   view as well, so a throw outside a body's own catch left the checkout
+   torn with no marker. `applyAllComponents` was the live instance: it rolls
+   back on collected `result.errors`/`stepErrors`, but a throw from its
+   pre/post-loop work escaped both. The wrapper now runs cleanups, restores
+   the journal, and rethrows the **original** error (a rollback failure
+   becomes a marker plus a warning, never a replacement error).
+
+   Both paths race for the same journal, so each operation carries a
+   `rollbackState` claimed synchronously before either path's first await;
+   whichever gets there first restores and the other skips. Bodies that
+   already restore on their own — the eight `furnace/*` command bodies,
+   `furnace-apply`, `preview` — call `ctx.markRolledBack()` so the wrapper
+   keeps its hands off. One deliberate asymmetry: on the throw path a body
+   that never registered a journal writes **no** marker, because a
+   pre-flight refusal would otherwise block every later mutation behind a
+   repair with nothing to reconcile; the signal path still writes one there,
+   since an interrupt genuinely may have landed mid-write.
+
+4. **A signal during a compound "apply + persist state" pair never tears the
+   pair.** Rebase-style operations intentionally leave the engine mutated,
+   so rollback is the wrong tool; instead the exit is _held_ (bounded) until
+   the bookkeeping write lands, so `--continue` never sees stale progress.
+5. **No lock outlives the process it belongs to** (best effort, two layers):
+   the signal pipeline force-releases furnace locks before exiting, and
+   stale-lock recovery (PID-first, then age) unblocks the next command for
+   anything that escaped.
+6. **Destructive patch operations are gated and audited**: explicit change
+   summary, confirmation (or `--yes`), `--dry-run`, hard refusal on
+   structural conflicts (`--force-unsafe` to override), and a JSONL history
+   entry appended only after the mutation succeeded. This covers metadata
+   mutations too: `patch tier` and `patch lint-ignore` route through
+   `confirmDestructive` (they used to accept `--yes` without ever
+   prompting, so the flag only appeared in the history record). Enforced
+   by `patch-tier-and-lint-ignore.integration.test.ts`.
+7. **A verification tree never mutates shared state**. Trees
+   are full project-root CoW snapshots under `.fireforge/trees/<name>`
+   with NO merge-back model. Enforcement is layered: the `.fireforge/
+tree.json` marker plus a default-deny command-verdict table
+   (`src/core/tree-guard.ts`) refuse every mutating command through one
+   commander `preAction` hook in `cli.ts` — a newly added command is
+   refused in trees until classified (drift test). Because a tree is a
+   full project root, its build and engine-session locks key on the TREE
+   root, so in-tree reads never contend with the primary. `tree create`
+   snapshots under the PRIMARY engine-session lock (never captures a
+   mid-mutation state) — and with `--with-objdir` additionally under the
+   primary BUILD lock, under which the objdir is resolved and its build
+   artifacts validated immediately before cloning (any pre-lock probe is
+   a fast-fail courtesy whose result is discarded, never the
+   authoritative answer), so a concurrent `fireforge build` can neither
+   tear the obj-\* snapshot nor swap it between preflight and clone.
+   A symlinked (or engine-escaping) primary obj-\* is refused BEFORE any
+   copying: every `cp` mode the clone uses preserves symlinks, so the
+   clone would carry a link back to the original build and the mozinfo
+   rewrite plus `_virtualenvs` removal would mutate that original
+   through it — `assertCloneSafeObjdir` (tree-store.ts) checks lstat and
+   realpath containment (lexical `resolve()` cannot see either) on the
+   primary objdir and again on the tree's copy before any write goes
+   through it, pinned by `tree-store.integration.test.ts` and
+   `tree.integration.test.ts`;
+   tree create/remove serialise on a primary-side
+   `.fireforge/trees.lock`; `tree remove` refuses while a live PID holds
+   a tree lock and path-contains its `rm -rf` target.
+
+   In-tree `test` (0.41.0) is the one conditional carve-out, and it is
+   marker-gated: mach objdirs embed absolute `topsrcdir`/`topobjdir`
+   paths, so `tree create --with-objdir` rewrites the cloned objdir's
+   `mozinfo.json` to the tree via the same safe-relocation rewriter
+   `build --rewrite-mozinfo` uses, scrubs the cloned `_virtualenvs`
+   (primary shebangs; mach rebuilds them in-tree), runs `mach configure`
+   inside the tree so the configure-generated root files are regenerated
+   against the tree's paths rather than retaining the primary's — and
+   verifies exactly that set afterwards (config.status, backend.mk,
+   Makefile, config/autoconf.mk, via `findObjdirRelocationViolation`,
+   pinned by `mach-objdir-relocation.test.ts`; nested Makefiles are
+   products of the verified config.status, and `.deps` build products
+   are out of scope as read-only staleness corrected by the first
+   in-tree rebuild) — and copies
+   `last-build.json` so the in-tree stale-build gates anchor correctly.
+   Both relocation steps are fail-closed — a rewrite refusal or a failed
+   in-tree configure aborts the create and removes the partial tree —
+   and only after both succeed is the marker's `clonedObjdir` field
+   written, which is what the guard's `test` predicate consults. At run
+   time, `test` additionally refuses when the objdir its preflight found
+   is not the one the marker vouches for
+   (`assertObjdirMatchesTreeMarker`), so an objdir that appeared through
+   any path other than `tree create --with-objdir` is never run against.
+   `test --build` stays refused (a tree is a snapshot with no merge-back
+   model), and a corrupt marker refuses `test` like every conditional
+   verdict.
+
+   **Both halves of that enforcement fail CLOSED on an unreadable state,
+   because "we cannot tell" is not "there is nothing there."** A marker
+   that exists but does not parse reports `corrupt`, not `absent`, and
+   refuses the command — reading it as absent granted a snapshot the
+   full mutating command set on the strength of a file that failed to
+   parse. A lock directory whose owner cannot be identified reports
+   `unknown`, not free, and refuses removal — `withFileLock` creates the
+   lock directory before writing its owner record and treats that write
+   as non-fatal, so a live holder legitimately produces a lock with no
+   readable PID (a lock directory that vanished between the probe and the
+   owner read is the one exception: that is a clean release, and reads as
+   free). Each has one named escape (`--ignore-corrupt-tree-marker`,
+   `tree remove --force`); neither has a silent one. The corrupt-marker
+   refusal spares the unconditionally-**allowed** read-only commands
+   (`status`, `lint`, `typecheck`, `verify`): their verdict never consults
+   marker fields, so an unreadable marker cannot change their answer, and
+   blocking them left the operator unable to diagnose the very tree that
+   needs inspecting. `conditional` verdicts can write and stay refused.
+   Enforced by
+   `tree-guard.test.ts` (verdict drift gate + corrupt-marker refusal),
+   `tree-store.integration.test.ts` (marker tri-state, unknown-owner
+   refusal, rewrite-then-reconfigure-then-marker ordering),
+   `tree.test.ts` (under-lock objdir re-validation ordering) and
+   `tree.integration.test.ts` (real-program refusal).
+
+8. **A verdict is only reported when it was actually verified.** `fireforge
+test` brackets the harness run with `snapshotEngineGeneration` and
+   fails the run if `engine/` changed underneath it. The probe can
+   legitimately fail — `engine/` need not be a git checkout — so a probe
+   that fails on **both** sides warns and proceeds; a one-sided
+   transition throws, because either the second probe measured nothing
+   about a checkout that had something to measure, or there was no
+   baseline to compare against. Enforced by
+   `engine-session-lock.test.ts`.
+
+   A probe that fails on a **transient** `.git/index.lock` — another
+   writer held the index for the instant we looked — is retried on a
+   bounded budget rather than latched as "unmeasurable";
+   a durable failure (a non-git `engine/`, an unreadable `.git`) still
+   reports immediately. Enforced by
+   `engine-generation-probe-retry.test.ts`.
+
+   The same invariant reaches across the `tree exec` boundary.
+   `tree exec` hands stdout to the child (`stdio: 'inherit'`), so the
+   child's `FIREFORGE-VERDICT:` line reaches the caller byte-for-byte; the
+   parent therefore seals stdout the moment the spawn settles, so its own
+   "exited with code N" refusal cannot print after the verdict and displace
+   it. A refusal raised BEFORE the child spawns emits no verdict at all —
+   consumers must read a missing verdict as a failed step, never a pass.
+
+9. **FireForge's own read-only commands are not writers of the primary
+   engine checkout**. `verify`, `lint --per-patch`, and
+   `typecheck` are read-only to the operator but not to git: `git status`
+   and `git diff HEAD` refresh and rewrite `.git/index`, and the
+   untracked-binary diff path stages and unstages for real. Each of those
+   commands therefore runs its whole body inside `withPrivateGitIndex`,
+   which seeds a temp `GIT_INDEX_FILE` from the repository's own index so
+   every refresh lands there and is discarded; `typecheck` additionally
+   forces `incremental: false` and drops `tsBuildInfoFile`, so no sidecar
+   is written under `engine/`. The scope is fail-open — an unresolvable
+   git dir simply does not install it — and non-reentrant. This exists so
+   invariant 8 stays evidential: a concurrent `fireforge test` must not be
+   invalidated by FireForge's own read-only lane. Enforced by
+   `git-readonly-index.test.ts` (real repository, real index mtime).
+
+10. **Lock queues are observable, and leaving one is as reliable as
+    joining it**. A waiter that contends registers a file in
+    `<lock>.waiters/` named `<startedAtMs>-<pid>-<uuid>` and deregisters
+    in a `finally` that covers both outcomes — acquired the lock, or timed
+    out. Depth counts only entries whose PID is still alive, so a killed
+    waiter cannot inflate it forever, and the registry is advisory:
+    failures to register are logged verbosely and never fail an
+    acquisition. `fireforge status --lock` and the `--wait-lock` progress
+    line read it. Enforced by `lock-visibility.test.ts` (real concurrent
+    waiter) and `engine-session-lock.test.ts` (queue position in the wait
+    line).
+
+11. **A manifest repair preserves what it cannot recompute, or refuses.**
+    `doctor --repair-patches-manifest` is a MERGE: only `filesAffected` and
+    `order` are derived from the patch files, and every other field on an
+    existing entry is carried forward by spreading it, so a field a `.patch`
+    body cannot express — `stagedDependencies`, `lintIgnore`, `tier`, and
+    whatever is added to `PatchMetadata` next — survives by construction
+    rather than by being listed. The one case where nothing can be carried
+    forward is a `patches.json` that exists but does not parse; the rebuild
+    refuses it, naming what would be reinvented, unless
+    `--allow-metadata-loss` is passed. `doctor --repair-files-affected` is
+    the narrow repair for drift that is only in the derived list: it goes
+    through `mutatePatchRowsInManifest`, so untouched rows keep their exact
+    JSON. Both repairs take the patch-directory lock (invariant 2), both
+    support `--dry-run`, and a repair that wrote is reported before the
+    doctor summary in every branch — the run can still exit non-zero on an
+    unrelated check, and a non-zero exit otherwise reads as "nothing
+    happened". Enforced by `patch-manifest-repair.test.ts` (real temp
+    queues) and the repair cases in `doctor.test.ts`.
+
+## Lock release (0.44.0)
+
+`releaseLockIfOwned(lockPath)` in `src/core/file-lock.ts` is the ownership-
+checked removal for callers that hold no acquisition token — currently the
+signal-time furnace sweeper (`forceReleaseFurnaceLocksForActiveOperations`).
+It verifies the PID before removing, which is the half of `releaseLock`'s
+guard a sweeper can still perform: the sweeper knows which lock paths its own
+operations opened but not the per-acquisition UUID they minted. The bare `rm`
+it replaced could delete a lock a DIFFERENT process had acquired in the window
+between our operation dying and the sweep running.
+
+`completeJournalRollback` in `src/core/furnace-operation.ts` owns the
+mutation-body rollback sequence that eight furnace commands previously
+duplicated verbatim. The ordering is the invariant: `markRolledBack()` runs
+BEFORE the restore, so a restore that itself fails does not leave the
+lifecycle wrapper replaying the same journal on the way out; and the ORIGINAL
+error is rethrown unless the rollback is what failed.
+
+## Who owns what
+
+| Module                            | Owns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bin/fireforge.ts`                | The only `process.exit` call sites; SIGINT/SIGTERM pipeline; re-entrancy guard (a second Ctrl+C exits immediately); exit codes 130/143.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `src/core/file-lock.ts`           | Generic directory-as-lock (`mkdir` atomicity), owner PID **+ per-acquisition token** file, stale recovery via **rename-aside reaping** (dead PID unblocks immediately; ageless fallback after 5 min; the probe re-runs every ~5 s while waiting, so a holder dying mid-wait cannot strand waiters until `timeoutMs`), poll + timeout. Release verifies the lock still carries this acquisition's token before removing — a reaper-replaced lock is never deleted by its previous owner. Enforced by `file-lock.test.ts` (two-waiter reap race, mid-wait holder death, foreign-owner release). Releases in `finally` — which never runs across `process.exit`, hence invariant 5's other layer. Opt-in wait ergonomics: `pollMaxMs` (poll interval doubles from `pollMs` up to the cap) and `waitProgressMs`/`onWaitProgress` (periodic progress callback carrying the holder's PID, liveness, and owner-metadata lines from the pid file). All three are inert when unset — existing callers keep byte-identical behavior.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `src/core/engine-session-lock.ts` | 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, dry-runs included: 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. Contention fails fast after ~1 s by default with the fixed message "Another FireForge engine-mutating command is already running. Wait for it to finish, then retry `<command>`." — that message contract is unchanged and also closes the bounded wait. Each of those commands accepts `--wait-lock [seconds]` (bare flag = 60, valid 1..3600) for a bounded operator wait instead: polling backs off exponentially 100 ms → 2 s, and roughly every 5 s a progress line identifies the holder from the lock's owner-metadata lines (`Waiting for the FireForge engine lock held by PID 12345 (command=build, started=…) — 10s of up to 60s.`). The budget is not the engine lock's alone: it covers EVERY lock the command takes, which for the three furnace commands means the per-root furnace lock as well (see the `furnace-operation.ts` row). `FIREFORGE_WAIT_LOCK=<seconds>` sets the same budget for a whole session, parsed by the same bounds as the flag so the two cannot drift; an explicit budget at a call site always wins. Commands that take no lock accept `--wait-lock` and ignore it, so a scripted sequence can blanket-append the flag without a usage error killing the run. `fireforge test` also snapshots the engine git generation before and after the harness run and fails the verdict as invalid if the tree changes mid-run. |
+| `src/core/furnace-operation.ts`   | `runFurnaceMutation` lifecycle wrapper: per-root furnace lock, `pendingRepair` pre-flight refusal, in-flight operation registry (journal + cleanups + `completed` flag), signal rollback with bounded timeouts, `pendingRepair` persistence, furnace-lock force-release sweep. The lock's wait budget is `options.lockTimeoutMs` (threaded from `--wait-lock` by `waitLockMutationOptions`, which does the seconds→ms conversion once) falling back to `sessionWaitLockMs()` (`FIREFORGE_WAIT_LOCK`) and then to `DEFAULT_LOCK_TIMEOUT_MS`. The fallback is what covers the twelve furnace mutators that declare no flag (`create`, `remove`, `rename`, `refresh`, `scan`, `override`, `chrome-doc`, …). A contended refusal here names the FURNACE lock, says it is the second of two, and points at `--wait-lock`/`FIREFORGE_WAIT_LOCK` — a budget that is paid in full and then refuses anyway is the worst shape a budget can have, so the refusal must not read as the engine lock's.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `src/core/furnace-rollback.ts`    | The rollback journal itself: file snapshots and their restoration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `src/utils/assert.ts`             | The runtime-assertion primitive (`assert`, `assertDefined`, `expectDefined`) and, through `InternalInvariantError`, exit code 11. Checks state FireForge itself established — journal-before-mutation, lock-held-before-write, manifest order well-formedness — and is deliberately NOT input validation: anything derived from user input, the filesystem, or a subprocess stays a typed error from `src/errors/`. Every check routes through the helper rather than an inline `if (!c) throw` so the failure branch is covered once here instead of uncovered at every call site.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `src/core/signal-critical.ts`     | Registry of signal-deferred critical sections (`runInSignalCriticalSection`). Pure registry — installs no handlers; the bin pipeline drains it with a bounded wait.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `src/core/patch-lock.ts`          | `withPatchDirectoryLock` — serializes patch filename allocation and manifest read-modify-writes. **Not reentrant**: callers must not already hold it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `src/core/destructive.ts`         | The destructive-operation contract: `confirmDestructive` (summary, prompt, `--yes`, `--dry-run`, conflict refusal, `--force-unsafe`) and the `.fireforge-history.jsonl` audit log.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `src/core/tree-store.ts`          | Verification-tree lifecycle: CoW snapshot contents/exclusions, the objdir clone relocation (mozinfo rewrite + caller-supplied in-tree `mach configure`, both before the marker records `clonedObjdir`; `assertObjdirMatchesTreeMarker` re-checks at `test` time), the `.fireforge/tree.json` marker and its absent/valid/**corrupt** tri-state, staleness fingerprints, the primary-side `trees.lock`, and removal that refuses both a live holder and a lock of **unknown** ownership, with rm-target containment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `src/core/tree-guard.ts`          | Read-only enforcement inside trees: the default-deny per-command verdict table and the `preAction` hook body `runTreeGuardHook` installed by `createProgram()` (invariant 7).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+
+## The signal pipeline, end to end
+
+On SIGINT/SIGTERM, `bin/fireforge.ts`:
+
+1. If a rollback is already in flight (second Ctrl+C), exits immediately.
+2. Otherwise runs **in parallel** and waits for both:
+   - `rollbackActiveOperationsForSignal(signal)` — per active furnace
+     operation: cleanup callbacks (15 s bound each), journal restore (15 s
+     bound), `pendingRepair` marker if anything failed or no journal was
+     registered yet. Operations whose body already completed are skipped, so
+     a signal in the finally-window can't roll back a committed mutation.
+   - `waitForActiveCriticalSections(5 s)` — holds exit for in-flight
+     "apply + persist" pairs (invariant 4), bounded so a stuck write cannot
+     postpone the exit the user asked for.
+3. Force-releases the furnace lock directories of active operations
+   (`withFileLock`'s `finally` will never run past `process.exit`).
+4. `process.exit(130 | 143)`.
+
+## Choosing a primitive for a new mutation
+
+| Your operation…                                                                                                      | Use                                                                                          |
+| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Mutates the engine and should be _undone_ on Ctrl+C (apply, deploy, preview, remove)                                 | `runFurnaceMutation` + `ctx.registerJournal` (plus `ctx.registerCleanup` for extra teardown) |
+| Intentionally leaves the engine mutated but must finish a paired bookkeeping write (rebase-style `--continue` state) | `runInSignalCriticalSection` around the apply + persist pair — keep the body short           |
+| Touches the patch directory / manifest                                                                               | `withPatchDirectoryLock` (never nested)                                                      |
+| Deletes or rewrites user-owned patch state                                                                           | The `confirmDestructive` contract, history appended only on success                          |
+| Only reads                                                                                                           | Nothing — dry-runs must not block or be blocked                                              |
+| Runs read verification concurrently beside a busy primary                                                            | A `fireforge tree` (CoW snapshot; mutation refused inside — invariant 7)                     |
+
+## Where this is tested
+
+- `src/core/__tests__/file-lock.test.ts` — lock acquisition, staleness, PID
+  recovery.
+- `src/core/__tests__/furnace-operation.test.ts` — wrapper lifecycle, signal
+  rollback outcomes, `pendingRepair` semantics, lock force-release.
+- `src/core/__tests__/signal-critical.test.ts` — the critical-section
+  registry contract in isolation.
+- `src/core/__tests__/signal-compound-mutation-scenario.test.ts` — the
+  composed bin-handler pipeline: exit held for a compound mutation, bounded
+  hold for a stuck section, rollback + drain + lock release together.
+- `src/core/__tests__/destructive.test.ts` — the destructive-op contract.
+- `src/core/__tests__/tree-guard.test.ts` — invariant 7's verdict table
+  (default-deny drift gate, conditional predicates, corrupt-marker refusal).
+- `src/core/__tests__/tree-store.integration.test.ts` — clone contents,
+  objdir rewrite/reconfigure/marker ordering, marker tri-state,
+  unknown-owner removal refusal.
+- `src/commands/__tests__/tree.test.ts` — create/remove command flow,
+  including objdir re-validation under the primary build lock, and the
+  `tree exec` stdout seal (invariant 8).
+- `src/__tests__/tree-exec-verdict.test.ts` — invariant 8 across a real
+  process boundary: exactly one verdict line, last on stdout, refusal on
+  stderr.
+- `src/commands/__tests__/tree.integration.test.ts` — real-program in-tree
+  refusals and `--with-objdir` end-to-end against a synthetic objdir.
+- `src/__tests__/process-boundary.test.ts` — invariant 1 (`process.exit`
+  only in bin).

package/docs/machine-output.md

@@ -0,0 +1,94 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Machine-readable output contract (internal)
+
+The `--json` surface is a contract with scripted consumers. Before 0.44.0 it
+was four unrelated shapes: `status --json` and `tree list --json` shared a
+`schemaVersion: 1` envelope but disagreed on failure, `test` emitted a
+`FIREFORGE-VERDICT:` line, and `lint --per-patch --report` wrote a versioned
+file nothing ever reads back. This file is the single statement of what a
+`--json` command must do, so the next one added does not invent a fifth.
+
+## The rules
+
+1. **Success writes exactly one JSON document to stdout**, with
+   `schemaVersion` as its first key.
+2. **Failure writes exactly one error document to stdout**, of the shape
+   `{ "schemaVersion": 1, "error": "<human message>", "code": "<tag>" }`,
+   and then exits non-zero. The `error` text is the same sentence the
+   non-JSON mode would print; `code` is a stable machine-readable tag
+   (`engine-missing`, `engine-not-git`, `tree-list-failed`, …) that consumers
+   may branch on.
+3. **Machine mode is engaged before any output.** `setMachineOutputMode(true)`
+   must run before the first write, so every diagnostic — including one
+   rendered later by `withErrorHandling` — routes to stderr and cannot
+   interleave with the payload.
+4. **stdout carries nothing else.** No banners, no progress, no warnings.
+   `logger.ts` enforces this through a single `routeToStderr()` gate that all
+   its helpers consult, including `spinner()`, `note()` and `intro`/`outro`.
+
+## Implementation
+
+Use `emitMachineError` from `src/utils/machine-output.ts` for rule 2. It
+writes the envelope and throws `CommandError`, which the CLI boundary treats
+as already-rendered — so the boundary adds no second rendering on stderr.
+
+```ts
+if (options.json === true) {
+  setMachineOutputMode(true);
+  try {
+    const payload = await collect();
+    process.stdout.write(
+      `${JSON.stringify({ schemaVersion: MACHINE_OUTPUT_SCHEMA_VERSION, ...payload }, null, 2)}\n`
+    );
+  } catch (error: unknown) {
+    emitMachineError('collect-failed', toError(error).message);
+  } finally {
+    setMachineOutputMode(false);
+  }
+  return;
+}
+```
+
+## Current surfaces
+
+| Surface                            | Shape                                                 | Notes                                                                                                                                                                                                                              |
+| ---------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `status --json`                    | `{ schemaVersion: 1, … }`                             | Error envelope on three engine preconditions                                                                                                                                                                                       |
+| `tree list --json`                 | `{ schemaVersion: 1, trees }`                         | Error envelope added in 0.44.0                                                                                                                                                                                                     |
+| `test` verdict line                | `FIREFORGE-VERDICT: PASS\|FAIL reason=… [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, … }`                             | Written to a file, never read back by FireForge                                                                                                                                                                                    |
+| `status --raw`                     | `git status --porcelain` lines                        | Not JSON, but 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 the same way for a porcelain stream as for a JSON document.
+
+`doctor` and `verify` have no `--json` mode. `doctor` already computes a
+serializable `DoctorCheck[]`, so adding one is cheap if a consumer asks —
+follow the rules above rather than inventing a shape.
+
+The run logs behind `log=` are specified in [`run-logs.md`](run-logs.md).
+
+## Versioning
+
+`schemaVersion` is `MACHINE_OUTPUT_SCHEMA_VERSION` in
+`src/utils/machine-output.ts`. Additive changes (a new key) do not bump it.
+Removing or retyping a key does, and needs a note in the changelog naming
+what moved.
+
+## `test` verdict reasons
+
+`FIREFORGE-VERDICT: FAIL reason=<reason>` uses a closed set
+(`FireforgeVerdictReason`, `src/commands/test-verdict.ts`):
+
+| Reason          | Meaning                                                                                                                                                                                                              |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `crash`         | The harness or the browser died; no trustworthy suite result.                                                                                                                                                        |
+| `no-tests`      | The run dispatched but nothing ran.                                                                                                                                                                                  |
+| `test-failures` | The suite ran and reported unexpected results.                                                                                                                                                                       |
+| `preflight`     | The run was refused before the harness was reached.                                                                                                                                                                  |
+| `inconclusive`  | A result exists but `engine/` moved under it, so it was discarded.                                                                                                                                                   |
+| `lock-timeout`  | The run never started: the engine session lock stayed contended.                                                                                                                                                     |
+| `killed`        | A signal terminated the run. Written from the signal handler so a log tail is always self-describing — a killed run must never be silent, or "killed", "still running" and "never started" become indistinguishable. |

package/docs/patch-workflow.md

@@ -0,0 +1,119 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Patch workflow
+
+The day-to-day loop: change code inside `engine/`, export it, keep the queue
+applying cleanly. `fireforge --help` remains the authority on flags; this file
+covers the behaviour that a flag list cannot state.
+
+## The loop
+
+```bash
+npx fireforge status
+npx fireforge export browser/base/content/browser.js --name custom-toolbar --category ui
+npx fireforge re-export custom-toolbar
+npx fireforge lint --per-patch
+npx fireforge verify
+```
+
+## Exporting
+
+Patch names are normalized on export and rename: `window-chrome-tests`,
+`ui-window-chrome-tests`, and `235-ui-window-chrome-tests` all resolve to the
+same `<order>-ui-window-chrome-tests.patch` shape.
+
+For large generated asset batches, `re-export --scan --scan-files <manifest>`
+assigns files to their owner patches without broad directory scanning. The
+manifest is JSON:
+
+```json
+{
+  "assignments": [
+    { "patch": "002-branding-runtime-icons.patch", "files": ["browser/branding/hominis/icon.svg"] }
+  ]
+}
+```
+
+The command is dry-runnable, refuses ambiguous ownership, and reports each
+file-to-patch assignment before refreshing the patch.
+
+Scan-less `re-export` previews drift; `--refuse-foreign-drift --expect <path>`
+restricts it to intended files.
+
+### Deletions
+
+A deleted upstream file is captured like any other change: a path that is
+tracked in HEAD but absent from disk stays in the diff scope, and the emitted
+patch carries a `deleted file mode` section. A captured deletion keeps its
+`filesAffected` entry — the patch is what performs the deletion, so pruning
+the entry would leave the body deleting a file the manifest says the patch has
+nothing to do with — and it still requires the confirmation, because the patch
+will remove those files wherever it is applied.
+
+An **untracked** absent path is refused rather than warned about: a patch
+cannot express it either way. The `--files` path also refuses when any
+requested path produces no hunk, checked against the full requested list
+rather than the post-filter subset, so nothing dropped upstream can pass as a
+silent success.
+
+## Queue maintenance
+
+Under `fireforge patch`:
+
+- `patch compact` closes ordinal gaps (range-aware when `patchPolicy.ranges`
+  is configured).
+- `patch reorder` moves a patch.
+- `patch split <source> --files <paths...> --name <name>` carves files out of
+  a patch into a new one as a single transaction — including staged-dependency
+  owner rewrites — with `--dry-run` support.
+- `patch rename` also supports `--category` and `--order`.
+
+Every queue-mutating patch command accepts `--wait-lock [seconds]`; see
+[`configuration.md`](configuration.md#lock-waits) for how the budget resolves.
+
+## Linting the queue
+
+`lint --per-patch --patches` accepts repeated flags, comma lists, full
+filenames/stems, manifest names, category-prefixed slugs, and bare slugs.
+
+`lint --per-patch --max-warnings 0` is the warning-clean form for a release
+gate.
+
+`lint --per-patch --report <path>` writes a machine-readable JSON report with
+each patch's line count, tier, active size thresholds, issues, and
+`lintIgnore`-suppressed issues. The size metrics
+(`countNonBinaryDiffLines`, `resolvePatchSizeTier`, `getPatchSizeThresholds`)
+are also exported on the programmatic API.
+
+Per-patch lint type-checks plain Firefox JS against a built-in Firefox-globals
+shim that tracks upstream WebIDL additions per release. See
+[`configuration.md`](configuration.md#patchlint) for the project hooks
+(`checkJsExtraShim`, `checkJsTestFiles`, `checkJsTestShim`).
+
+For release whitespace checks, use `npm run whitespace:check`; it still checks
+source diffs while excluding generated `patches/*.patch` diff syntax.
+
+## CI enforcement
+
+`fireforge status --check` exits non-zero when any unmanaged, drifted, or
+conflicted file exists. `--fail-on <class,...>` tunes the policy set, and
+`--json` composes — the JSON stays parseable and its `files[]` entries name
+the owning `patch`. `--include-ownership` adds ownership rows to JSON status
+output.
+
+The JSON shapes are specified in [`machine-output.md`](machine-output.md), and
+the codes a script should branch on in [`exit-codes.md`](exit-codes.md).
+
+## Rebasing onto a new Firefox source release
+
+```bash
+npx fireforge source set --version 145.0.0esr --product firefox-esr --sha256 <archive-sha256>
+npx fireforge download --force
+npx fireforge rebase
+```
+
+If a patch fails, fix the reject inside `engine/`, then run
+`npx fireforge rebase --continue`. A rebase deliberately leaves the engine
+mutated, so its apply-and-persist pairs are held across a signal rather than
+rolled back — see invariant 4 in
+[`lifecycle-invariants.md`](lifecycle-invariants.md).

package/docs/run-logs.md

@@ -0,0 +1,60 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Run logs (internal)
+
+`fireforge test` and `fireforge build` write their own complete output to
+`.fireforge/logs/<command>-<timestamp>.log` as they stream. The module is
+`src/core/run-log.ts`.
+
+## Why the tool holds the log, not the operator
+
+A run's diagnosis used to exist in exactly one place: the terminal. The
+ergonomic default when output is long — `fireforge test … 2>&1 | tail -40` —
+keeps the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say WHAT
+broke, and it launders the exit code besides. Nothing else held the output:
+`runMachCapture` keeps a 2 MB in-memory tail that dies with the process, and
+the shard retry loop discards earlier attempts outright.
+
+The operator rule ("never pipe a run") was written down three times downstream
+and broken after each writing. That is the tell that it is not an operator
+problem — the tool is the only party that can make the log survive the
+mistake.
+
+## The contract
+
+- **Raw bytes, never the echo filter's collapsed form.** The artifact exists
+  to be re-read by whoever is diagnosing the run; shortening it would
+  reintroduce the loss it prevents.
+- **Opened before any preflight**, so a refusal is logged too. Those are
+  exactly the runs whose only output a `tail` throws away.
+- **Retained 20 deep per command kind.** Per-kind, so a busy `test` loop
+  cannot evict the `build` log an operator needs to read beside it. Pruning
+  runs before the new file is opened, and orders by the filename's
+  timestamp rather than by stat-ing every entry.
+- **Timestamps are filesystem-safe**: the ISO form with `:` and `.` replaced
+  by `-`, which Windows accepts and which still sorts chronologically.
+- **Best-effort throughout.** A log that cannot be opened, written or pruned
+  degrades to no log. A run must never fail over a diagnostic, so `openRunLog`
+  returns `undefined` on failure, a post-open stream error latches `broken`
+  and drops every later write, and pruning failures are logged verbosely
+  only.
+
+## Where the path is announced
+
+`test` publishes it as an additive `log=<path>` key on the
+`FIREFORGE-VERDICT:` line. That is forced, not chosen: the verdict must stay
+the run's LAST stdout write ([`machine-output.md`](machine-output.md)), so a
+separate announcement after it would break the contract, and one before it is
+the first thing a `tail` cuts.
+
+`build` prints no verdict line, so it announces the path directly
+(`Full build output: <path>`).
+
+## Where the tee sits
+
+At the two mach capture funnels in `src/core/mach.ts`, not at the commands.
+That covers every dispatch: the three test dispatchers, `package`, and the
+stdio-inheriting path `mach build` uses — which rides the collectors' existing
+`mirror` hook rather than growing a second one. A new dispatcher added at the
+funnels is logged by construction; one added beside them is not, which is the
+reason to keep going through them.