b817dc93

docs: the transient had two causes, and neither story alone ever fit

a73x 2026-08-08 18:22

Commit message

docs: the transient had two causes, and neither story alone ever fit

The record said the re-entrancy defect causing the 171/172 transient was
strong inference rather than proof. That was the honest state of knowledge
and it stays on the page, because what settled it is an answer no
single-cause explanation could have reached.

Two independent defects, each explaining half the evidence. The transient
was drainPending giving up on the first quiet wakeup — reproduced on HEAD at
25 failures in 40 runs under contention and driven to 0 in 40 by the fix,
observed rather than inferred. The leaks were the ngtcp2 abort, but reaching
the suite through other concurrent processes sharing /tmp rather than
through the run that showed the failure; the HEAD failures produced zero
leaks, because an assertion failure runs its defers and only a signal kills
a process before they can.

So the leaked temp directory was a true clue pointing at a real defect, and
the failure it was found beside had a different cause entirely. Both
findings were right. The mistake available was assuming one story.

The new drainPending section carries the contention matrix, including that
the two halves of that fix are not both required — the stall bound alone
closes it, the poll half alone halves the rate without closing it — and
states plainly that the end-to-end defect is not pinnable in-suite, only
the two decisions inside it are.

Worth noting what "strong inference, not proof" bought: this correction is
an addition underneath it, not a retraction of it. Nothing above had to be
taken back.

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

docs/decisions.md

+fatal. Every QUIC session before this fix was corrupting loss-detection
+state silently.
+**The causal link, finally settled — and it was two defects, not one.**
+The paragraph that stood here said the re-entrancy defect causing the
+/172 transient was strong inference rather than proof: the transient had
+never been reproduced and its test name had never been captured. That was
+the honest state of knowledge at the time and it is left on the record as
+such, because the answer turned out to be one no single-cause explanation
+could have reached.
+There were **two independent defects**, and the reason nothing ever quite
+fit is that each explained half the evidence:
+- **The transient was `drainPending`.** It gives up the first time a wakeup
+  retires nothing, which misreads a coalesced or flow-control-only
+  acknowledgement as a finished peer. Reproduced on HEAD under four-way
+  contention on one core at **25 failures in 40 runs**, always the same
+  test, and driven to **0 in 40** by the fix. Observed, not inferred.
+- **The leaks were the ngtcp2 abort** — but reaching the test suite through
+  *other concurrent processes sharing `/tmp`*, not through the run that
+  showed the failure. That is why the two never correlated: the 21 HEAD
+  failures produced zero leaks, because an assertion failure runs its
+  defers and only a signal kills a process before they can run.
+So the leaked temp directory was a true clue pointing at a real defect, and
+the failure it was found next to had a different cause entirely. Neither
+finding was wrong; the mistake available here was to assume one story.
+**What the earlier inference got right and wrong.** Right: the re-entrancy
+was real, constant, and capable of producing exactly the signature seen.
+Wrong: nothing — it never claimed more than that, which is why the
+correction is an addition rather than a retraction. The value of having
+written "strong inference, not proof" is precisely that this paragraph could
+be added underneath it without anything above needing to be taken back.
+Two things queue-only broke that had to be fixed with it, neither in the
+audit's list — latency (a reply would have waited for the next poll cycle,
+directly (`wrote=4, n=-1` must account the four and then stop) without
+needing to make ngtcp2 fail on demand.
+### The second defect: drainPending gave up too easily
+`drainPending` is the shutdown path's bounded wait — the one that gets the
+shell's exit status to a client before the daemon goes. It concluded a peer
+was finished the first time a wakeup retired no bytes. A quiet wakeup means
+none of those things: an acknowledgement can arrive coalesced with others,
+re-acknowledge packets already acknowledged, or carry only a flow-control
+update. So the loop abandoned data the peer was still going to take, and the
+exit status was lost rather than delayed.
+Fixed by bounding a **run** of unproductive wakeups (`max_drain_stalls`,
+reset by any progress) rather than acting on one, and by bounding the poll
+slice with ngtcp2's own next deadline, floored at 1ms.
+**Both halves were handed over as required; measurement says otherwise, and
+the measurement is what goes in the record.** Four-way contention on one
+core, 40 runs each:
+| | failures |
+|---|---|
+| unpatched | 25/40 |
+| poll half only | 13/40 |
+| stall bound only | 0/40 |
+| both halves | 0/40 |
+The stall bound alone closes it. The poll half alone roughly halves the rate
+without closing it — evidence that it touches the same mechanism rather than
+a different one. Both are kept, because the poll half stands on its own
+reasoning about PTO starvation (retransmission lives only in `tick()` since
+the re-entrancy fix, so a slice that sleeps past an expiry wedges a lossy
+path) and a loopback reproduction with no packet loss cannot exercise that.
+But "required" was not true of it and the record does not say so.
+**What is pinned, and what is not.** The stall bound is pinned by literal
+count and the floor by value, both mutation-checked in both directions. The
+end-to-end defect is **not** pinnable in-suite: it needs contention, and
+nothing in `make test` defends it. That is stated rather than left for
+someone to discover when it regresses.
+### Reconcile v2: judge evidence, not arrival order
+The first design read any cell that did not already hold the prediction as a