Give the failure module's two absences the reasons that hold, which are the request and the division of labour

[iderex]

The issue this belongs to

Closes #447

What changed

The section in src/failure/mod.rs headed "What is not here, said once so a green
build is not read as covering it" carried three statements, and two of them rested
on reasons the tree refutes.

The first said no caller in this tree reaches any of it yet. It now says the thing
that holds - no request is made anywhere in this library, so nothing here has been
built out of an answer a server sent - and records what was wrong, when the four
callers arrived, and that the three issues named as the reason were not what they
came from. The set of modules reaching this point is derived rather than carried,
with the command handed to the reader and its bound stated.

The second said the retry-after hint is carried as given or absent because #38 is
not built. It keeps what it is about, which is that this type invents no number,
and gives the division of labour as the reason: the assumed value belongs to the
retry policy, which is in the tree with its numbers.

The third statement is untouched and is named in the issue as read and still
holding.

No behaviour changes and no signature changes. The whole diff is doc comments.

What failure it prevents

A reader taking that section at its word and concluding that the library's own use
of the one point every failure is meant to pass through is still ahead of the
tree, when four modules already build or match one of its values outside every
test module. The section names itself as the place a green build must not be read
past, so a wrong sentence in it is read as coverage of exactly what it does not
cover.

Evidence

Read at the commit pushed, 4f59fa3, and at its base 9fe6420.

What the section said:

git show 9fe6420:src/failure/mod.rs | sed -n '46,47p'
//! **No caller in this tree reaches any of it yet.** The transport is #27, the
//! query surface is #39 and the artwork fetch is #49, so what exists today is the

The four callers, and that every one of them is above its file's test module:

git grep -n 'Failure::cancelled()\|Failure::nothing_playable\|Failure::answer_not_understood' 4f59fa3 -- src/lifecycle/mod.rs src/playback/handover.rs src/server/destinations.rs
4f59fa3:src/lifecycle/mod.rs:486:            return WhatACallDoes::FailsWith(Failure::cancelled());
4f59fa3:src/playback/handover.rs:865:        Failure::nothing_playable(self.server_code())
4f59fa3:src/server/destinations.rs:260:        WhatARedirectDoes::Refused(Failure::answer_not_understood(

git grep -n 'if let Failure::ServerBusy' 4f59fa3 -- src/server/retry.rs
4f59fa3:src/server/retry.rs:471:    if let Failure::ServerBusy {

git grep -n '^#\[cfg(test)\]' 4f59fa3 -- src/lifecycle/mod.rs src/playback/handover.rs src/server/destinations.rs src/server/retry.rs
4f59fa3:src/lifecycle/mod.rs:533:#[cfg(test)]
4f59fa3:src/playback/handover.rs:881:#[cfg(test)]
4f59fa3:src/server/destinations.rs:272:#[cfg(test)]
4f59fa3:src/server/retry.rs:499:#[cfg(test)]

The sentence landed before the callers, and none of the four changes had a reason
to open this header:

git log -1 --format='%cI %s' b6db24d
2026-08-28T22:11:46+02:00 Build the one point a failure becomes a kind, and refuse a second one (#228)
git log 9fe6420 --diff-filter=A --format='%h %ad %s' --date=short --reverse -- src/server/retry.rs src/server/destinations.rs src/playback/handover.rs src/lifecycle/mod.rs
822b9f2 2026-08-31 Hold 0038's policy, its three kinds and the seam its wait is drawn through (#255)
965e1a3 2026-09-02 Hold 0069's destination set and its redirect rule as values (#69)
8d2d2da 2026-09-02 Hold 0115's creation, its capability answer and the core's lifetime (#115)
d9de3c7 2026-09-03 Hold 0111's ladder as values: which source, which streams, and what the handover carries (#111) (#294)

0038's policy, which the second statement said was not built:

git show 4f59fa3:src/server/retry.rs | sed -n '112p;124p;133p'
pub const ATTEMPTS_AT_MOST: u32 = 3;
pub const THE_FIRST_WAIT_IS_DRAWN_OVER: Duration = Duration::from_millis(250);
pub const AN_ATTEMPT_NEEDS_THIS_MUCH_DEADLINE_LEFT: Duration = Duration::from_millis(500);

The statement kept in place of it still holds:

git grep -n 'std::net\|TcpStream\|TcpListener' 4f59fa3 -- 'src/**/*.rs' ; echo "exit=$?"
exit=1

Checks run on this machine over the tree at 4f59fa3, with nothing uncommitted
in it but an untracked directory no rule here reads:

bash .github/invariants/invariants.sh check | tail -1
Every rule above was applied to its subject and refused nothing.

bash .github/format/format.sh check | tail -1
Every tracked source file above is written the way the formatter would write it.

cargo build --locked --all-targets > /dev/null 2>&1 ; echo "exit=$?"
exit=0

cargo test --locked 2>&1 | grep -E '^test result:'
test result: ok. 587 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.05s
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.18s
test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
test result: ok. 11 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.27s
test result: ok. 28 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.19s
test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s
test result: ok. 125 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s

What this does not cover

• The third statement in that section. answer-not-understood carrying an
  offset and a reading site rather than a field name, on the ground that nothing
  here parses a body, was re-read while this was found and still holds. It is
  named so the next reader knows it was read, and it is not edited.
• 0037's check over the tree. The honest proof the paragraph quotes - that
  every failure went through this point, proven over the tree rather than by a
  test - is still not built and nothing here builds it.
• Whether the intra-doc links added resolve. Four are added, each naming a
  pub mod of this crate, and the tool that would say so is not run on this board:
  Seven names in the crate's own documentation do not resolve, and the tool that says so is not run here #414 recorded that and is where it stands. cargo doc was not run here either,
  so this is a reading of src/lib.rs, src/playback/mod.rs and
  src/server/mod.rs rather than a measurement.
• lint, shellcheck, coverage, mutation and the cross-toolchain leg.
  None of those was run on this machine. No shell file and no dependency is
  touched, and the gate runs every one of them on this pull request.
• A check that would refuse the next one. Nothing in this tree reads a doc
  comment's claim against the code around it, and this adds no rule.

Who has read it

Nobody other than the author. There is one account here, which is what
security/statements.json says under scorecard/CodeReviewID, so the evidence
above stands in place of a review rather than beside one.