docs: reconcile the coverage account against a fresh report

The residual-coverage list was written from analysis rather than from
the report, and it was wrong three ways: it claimed closed/2 was
uncovered while the report showed the clause hit, and it grouped
publish/2 generic error and call/2 unrecognised answer with paths
needing modes or mounts when neither needs either. All three are now
covered, and the list is rebuilt line by line against a regenerated
cover/ - stale HTML from before the test/support exclusion is how the
inconsistency survived, so the note says to delete it first.

The mechanism claim is corrected: cover is not unable to run in a
non-distributed VM, it is that Mix instruments this node and nothing
instruments the peer.

The remaining 21 observable lines are split into the five compiler
generated clauses and the sixteen that need a mode, a device node or a
provider sabotaging the working directory, with the arithmetic for why
90% is out of reach honestly rather than absolutely.

Also records why fill/3 needs three different handles to pin its three
steps, and why stub_castle/2 compiles with :compile.forms/2.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ausimian

AGENTS.md

@@ -1143,7 +1143,9 @@ one Castle set silently would be one a consumer could not see in their own
 
 - Run `mix precommit` before committing. It is the single validation gate —
   `compile --warnings-as-errors`, `deps.unlock --unused`, `format`,
-  `credo --strict`, `test`. Do not run the individual checks piecemeal.
+  `credo --strict`, `test --cover`. Do not run the individual checks piecemeal.
+  The `--cover` is what enforces the coverage threshold; see *What
+  `mix test --cover` measures* for the figure and why it is what it is.
 - `@version` in `mix.exs` is the single source of truth for the version.
 - Add user-visible changes to `RELEASE.md` on the feature branch, using
   [Keep a Changelog](https://keepachangelog.com/) sections. Do not defer release
@@ -1259,6 +1261,18 @@ shapes differ in the version directory's release files: Mix assembles one,
 shape is how `Castle.Peer` came to refuse every unpacked release as ambiguous,
 having been reviewed seven times against a directory the peer path never meets.
 
+`build/2`'s `:override` points `lib/<app>-<vsn>` at a directory other than this
+node's own copy, leaving the release file alone — which is what a target
+carrying a *different build* of one of preboot's applications looks like, and the
+only way to be on the far side of `{Castle.Peer, :resolve, 1}`.
+`stub_castle/2` builds that castle: one exported `resolve/1` answering a fixed
+atom. **It compiles with `:compile.forms/2` rather than from Elixir source**,
+and that is load bearing rather than tidy — the module is named `Castle.Peer`,
+so `Code.compile_string/1` would load the stub over the running one and every
+peer test after it would be asserting against the fixture. Abstract forms are
+the one route to a beam the code server never sees. Do not "simplify" it onto
+`provider_app/5`.
+
 `Castle.Peer.materialise/2` takes `:boot_timeout` and `:resolve_timeout` for the
 same reason `Castle.Commands` takes the module to talk to — a deadline nothing
 can shorten is a deadline no test can show is enforced. Two tests give it a
@@ -1292,6 +1306,23 @@ asserting the acknowledged cost, that the by-path `chmod` does land on the
 swapped name. With the name left alone the two behaviours are identical, so
 there is no other way to tell them apart.
 
+**`fill/3`'s three steps need three different handles to be told apart, and a
+handle that is merely closed only reaches the first.** An already-closed handle
+fails the write *and* the close, `with :ok <- written, :ok <- closed` reports the
+write, and both helpers produce the same `"Cannot write #{path}"` prefix — so
+that case pins `written/3` (its discriminator is that `IO.binwrite/2` in place of
+`:file.write/2` raises instead of returning) and says nothing whatever about
+`closed/2`. It executed `closed/2`'s error clause without being able to detect it
+breaking, and this file claimed the clause was uncovered while the report showed
+it hit; both halves were wrong in the same place. Telling them apart needs a
+handle whose **write succeeds and whose close does not**, which is a process:
+`File.io_device/0` is `pid | file_descriptor`, so a pid is within what `fill/3`
+accepts, and `:file.write/2` sends a pid an io request while `File.close/1` sends
+it a `:file_request` — two protocols, so one can answer and the other refuse.
+That test asserts the close's own reason and that the file was **not** narrowed,
+which is the "mode only once both have succeeded" half of the contract. A
+`chmod` that cannot land is the third step, reached by removing the name.
+
 `secure_dir/1` is public so that the `mkdir`-to-`chmod` window can be stood in:
 a test creates a directory at 0777, plants a `sys.config` symlink inside it, and
 asserts that securing it is refused, the directory removed and what the symlink
@@ -1502,69 +1533,106 @@ seven `test/support` modules out of it. A fixture is covered by being run at
 all, so counting them moved the total without their ever being the thing
 measured — and two of them moved it *down* for a reason that is not about the
 suite. `Castle.PeerProviderStub` sat at 4.17% and `Castle.IoSink` at 76% while
-being exercised by every peer test, because they execute in the peer's VM and
-`cover` runs on this node. The list is module names rather than a pattern: a
-regex over `Stub` would swallow a production module spelled that way, which is
-the one thing an exclusion must not do.
-
-Lib-only that is **87.95%** — `Castle.Commands` 94.85%, `Castle` 90.48%,
-`Castle.Peer` 79.81%, `Castle.Deployment` and `Castle.Error` 100%.
-
-**The threshold is 85 because 90 is unreachable by construction rather than for
-want of tests.** Everything below the `## In the peer` comment in
-`lib/castle/peer.ex` — `resolve/1`, the standard-error relay, the pipeline and
-the compile-environment check — runs in the peer's VM, which has no node name
-and `is_alive() == false`, so `cover` cannot be started on it. That is 33 lines,
-about 7% of the shipped total, executed by `Castle.PeerTest` on every run and
-counted as missed, which puts the ceiling near 93%. Do not raise it by calling
-those functions on the test node: that runs Elixir's pipeline in the very VM the
-whole mechanism exists to keep it out of, and it would assert less than the peer
+being exercised by every peer test, because they execute in the peer's VM. The
+list is module names rather than a pattern: a regex over `Stub` would swallow a
+production module spelled that way, which is the one thing an exclusion must not
+do.
+
+**It is part of `mix precommit`**, which is what makes the threshold a gate
+rather than a number in a comment. Nothing else runs it, and CI's `test` matrix
+stays on a plain `mix test` deliberately, because cover's line attribution can
+differ between Elixir versions and the figure is measured on one toolchain — the
+pinned `precommit` job is where it is enforced.
+
+Lib-only that is **88.58%** — 419 of 473 relevant lines. Per module:
+`Castle.Commands` 94.85%, `Castle` 90.48%, `Castle.Peer` 81.22%,
+`Castle.Deployment` and `Castle.Error` 100%.
+
+**The threshold is the measured figure, 88.58, and not a rounder number near
+it.** One uncovered line added to `lib` gives 88.40% and fails; that was
+measured rather than assumed. It replaced an 85 that sat *below* the figure it
+was meant to floor, so it ratcheted nothing and licensed a thirteen-line
+regression. The cost of a threshold with no slack is that a refactor which
+legitimately removes covered lines fails it too, and the answer then is to
+re-measure and edit the number deliberately — the same rule every other claim
+here is held to.
+
+**What cannot be measured is the peer's VM, and the reason is where
+instrumentation is applied — not anything cover is unable to do.** An earlier
+version of this file said the peer "has no node name and `is_alive() == false`,
+so `cover` cannot be started on it", and that is false: `:cover.start/0` works
+in a VM with no distribution. What actually happens is that Mix starts cover on
+*this* node and instruments the modules loaded here, while the peer is a
+separate VM loading `Castle.Peer` from the target release's own beam files,
+which nothing has instrumented. Cover's only mechanism for reaching another VM
+is `:cover.start/1` over a *distributed* node, and this peer deliberately has
+none. So `resolve/1` and everything below the `## In the peer` comment — 33
+lines, about 7% of the shipped total — runs on every `Castle.PeerTest` and is
+counted as missed, which puts the observable ceiling near 93%.
+
+Do not raise it by calling those functions on the test node: that runs Elixir's
+pipeline in the very VM the whole mechanism exists to keep it out of, mutates
+this node's `:elixir` application environment, and asserts less than the peer
 tests already do. Splitting them into a module of their own to exclude it is
-worse still — `{Castle.Peer, :resolve, 1}` is a contract with the *next* version
-of Castle, so the MFA is not free to move for a metric.
-
-`--cover` is deliberately not part of `mix precommit`. Every test here is
-justified by what it fails against, and a merge-blocking percentage cannot tell
-a test that discriminates from one written to move the number.
-
-**What is left uncovered, and why each is a decision.** Every one of them is a
-failing branch, and the fixture is the problem in each case:
-
-* **A filesystem that stops behaving between one statement and the next.**
-  `arm/4`'s three ways of failing to publish — a working directory that cannot
-  be made, an `lstat` that fails for anything but `:enoent`, and a staged marker
-  that cannot be written or linked — together with `unarmed/3` and `detail/1`,
-  the message all three share. Reaching any of them needs a mode, a read-only
-  mount or a cross-device link, and a mode is refused here for the reason
-  `stub_stat/1` exists: root and some filesystems ignore one, so the fixture
-  would only sometimes describe the state it names. The one of the three the
-  filesystem *can* be made to produce is covered — `armed(:taken, …)`, the name
-  claimed between `unclaimed/3` and the publish, which is the second VM
-  `serialised/2` cannot reach and the case `publish/2` refusing rather than
-  replacing exists for. The seam is the materialisation, being the one step
-  between those two.
-* Same class, and the same answer: `armed_version/1`'s unreadable marker;
-  `describe_type/1`'s remaining catch-all, which only `:device` reaches now and
-  a device node needs root to make; `Castle.Peer`'s `empty/1` and
-  `release_file/1` listing failures; `closed/2`; `publish/2`'s non-`:eexist`
-  error; and the two writes at the end of `expand/2`.
-* **The compiler's own default-argument clauses**, five lines, for the arities
-  nothing calls: `install/2` and `install/3` in both `Castle` and
-  `Castle.Commands`, and `commit/2` and `commit/3`. There is no behaviour there
-  — a case that called an intermediate arity would be moving the number and
-  nothing else.
-* **A target release carrying a different `Castle.Peer`**, which is `call/2`'s
-  "may carry a version of Castle that predates this mechanism". A cross-version
-  condition: `Castle.SyntheticRelease` symlinks the running castle's own ebin
-  into the fixture, so reaching it needs a second `castle` application built to
-  answer differently, which is machinery out of proportion to one refusal.
-* **`stop/1`'s rescue**, which needs a control process that has already gone,
-  and about which the code deliberately makes nothing.
-* **A booted release**, which is Forecastle's `:e2e` suite, described just
-  above. That suite is where the in-peer section is exercised against a real
-  release rather than a synthetic one, where the marker is consumed by a real
-  launcher, where `running/1` is polled across a real reboot, and where the exit
-  statuses `bin/castle` returns are asserted. None of it is measured here.
+worse — `{Castle.Peer, :resolve, 1}` is a contract with the *next* version of
+Castle, so the MFA is not free to move for a metric.
+
+**Why 90% is not the threshold, stated as arithmetic rather than as a claim of
+impossibility.** 90% needs 426 covered, seven more than there are. Twenty-one
+missed lines are observable in principle, and they divide cleanly:
+
+* **Five are the compiler's own generated clauses**, one line per defaulted
+  arity nothing calls: `Castle.install/2` and `/3`, `Castle.Commands.install/2`
+  and `/3`, and `Castle.Commands.commit/3`. These *are* hittable — calling the
+  intermediate arities was measured to cover all five and to take the total to
+  89.64% — and that is exactly the problem. Each is a delegation whose defaults
+  are a subset of an arity that is already called, so `Castle.install/1` in
+  `castle_test.exs` already establishes that the defaults are the real modules.
+  A case calling `install/3` would assert nothing that arity 1 and arity 4 do
+  not, and would move this number. That is the move this project does not make,
+  and it is the reason 90% is out of reach: five of the seven can only come from
+  here.
+* **Sixteen need a file mode, a device node, or a provider sabotaging Castle's
+  own working directory.** In `Castle.Commands`: `arm/4`'s three publish
+  failures (`work_dir/1` refusing, an `lstat` failing for anything but
+  `:enoent`, a staged marker that cannot be written or linked) together with
+  `unarmed/3` and `detail/1`, the message all three share — seven lines that
+  stand or fall together, and every route to them needs the releases directory
+  to stop behaving between one statement and the next. Plus
+  `armed_version/1`'s unreadable marker, and `describe_type/1`'s catch-all,
+  which only `:device` reaches now and a device node needs root to make. In
+  `Castle.Peer`: `release_file/1`'s and `empty/1`'s listing failures (the
+  second unreachable through `work_dir/1` at all, which has just created the
+  directory — reaching it means calling `secure_dir/1` on something it never
+  hands over, whose one observable effect is that Castle deletes what you
+  pointed it at); `keep/2`'s generic publish error, where `write_like/3` has
+  created the staging file immediately before, so the only `File.ln/2` failures
+  left are cross-device; `stop/1`'s rescue, which needs the control process
+  already gone and is a race no fixture settles; and the two writes at the end
+  of `expand/2`, whose only route is a config provider removing the working
+  directory while the peer runs.
+
+  A mode fixture is refused here for the reason `stub_stat/1` exists: root and
+  some filesystems ignore one, so it would only sometimes describe the state it
+  names.
+
+**Two things that were in this list and should not have been.** `publish/2`'s
+generic error needs none of the above — `File.ln/2` with a staging file that is
+not there answers `:enoent` and creates no destination — and it is now covered.
+So is `call/2`'s "answered … may carry a version of Castle that predates this
+mechanism": `SyntheticRelease.stub_castle/2` builds a castle application for the
+target alone, which is what `build/2`'s `:override` is for. Both were dismissed
+as needing fixtures they did not need. And `closed/2` was listed as uncovered
+while the report showed its error clause *hit* — executed incidentally by the
+closed-handle test, which cannot discriminate it, and now pinned properly by a
+test of its own. Read this list against a freshly regenerated `cover/`; stale
+HTML from a previous run is how the inconsistency survived.
+
+**A booted release** is the last of it, and that is Forecastle's `:e2e` suite,
+described just above. That suite is where the in-peer section is exercised
+against a real release rather than a synthetic one, where the marker is consumed
+by a real launcher, where `running/1` is polled across a real reboot, and where
+the exit statuses `bin/castle` returns are asserted. None of it is measured here.
 
 ## Known limitations