docs(terminal): quote a payload big enough to reach the threshold it tests

The comment cited 1 MiB of RIS as evidence the tail high-water is zero. At
1 MiB the *deleted-pump* arm never reaches TAIL_CAP either, so the number
proved nothing: both worlds report "never full" and the measurement agrees
with whatever it was pointed at. 4 MiB is also short -- a 16 KiB read of RIS
defers 16382 bytes, not 16384, so it stops 512 bytes under the cap. 8 MiB is
where the counterfactual fires.

Also disambiguates the read count. 257 is reads *completed*; the 256 in the
review thread was a zero-based loop index, and a comment that doesn't say
which invites the next probe to disagree with it by one.

Found by Sami, in wording he had written and I had shipped -- I hit the same
defect on my own probe an hour earlier, fixed my run, and copied his number
across without noticing it had the flaw I'd just corrected.

Co-authored-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
Signed-off-by: tlongwell-block <109685178+tlongwell-block@users.noreply.github.com>
This commit is contained in:
npub1cc3ha7z055mu0rwwu7806t2wt8mj3pvu0uv5mfp2c50dahaqhczshdalg6
2026-08-02 02:02:22 -04:00
parent 232f56b672
commit 9f57a718a4

View File

@@ -115,16 +115,17 @@ impl Feeder {
/// **No production consumer today, and not an oversight.** The runtime
/// reader pumps [`Feeder::drain`] to completion after every read
/// (`terminal_runtime.rs`), so the tail is empty between iterations and
/// this can never go true -- measured 0 bytes high-water against 1 MiB of
/// this can never go true -- measured 0 bytes high-water against 8 MiB of
/// pure RIS, the densest atom there is. It exists for a future reader
/// that defers pumping, and such a reader **must** consult it: without
/// the pump loop the same stream reaches [`TAIL_CAP`] in 257 reads of
/// 16 KiB.
/// the pump loop the same stream first reaches [`TAIL_CAP`] on the 257th
/// completed read of 16 KiB.
///
/// The numbers are here rather than "nothing calls this" because the
/// signal and the loop are one fact from two sides. Delete the loop and
/// this predicate stops being unreachable in the same instant it starts
/// being needed.
/// 8 MiB, not 1 or 4, because the counterfactual has to actually fire: a
/// 16 KiB read of RIS defers 16382 bytes rather than 16384, so 4 MiB
/// stops 512 bytes short of the cap and reports "never full" for both
/// arms -- a probe too small to reach its own threshold agrees with
/// whatever it was meant to test.
pub fn tail_full(&self) -> bool {
self.pending_bytes() >= TAIL_CAP
}