Rubric: checkpoints
Written by a person. Last read by a person on 2026-09-05, 3 days ago. Its facts were checked by the eval suite on 2026-09-07.
Enforced by check_checkpoints.
The claim
A worked example declares positions a reader can recognize themselves in, and says what each one proves is already working.
Observable evidence
- For each checkpoint:
id,signal,means. - Whether any id repeats within an example.
The pass bar
All three fields present on every checkpoint, ids unique.
Why checkpoints exist
Documentation models outcomes as binary and almost nobody is in either state. The common case is partial: the request went through and the stream cut off, or a 200 arrived with nothing in it. A reader in that state is not failing, they are somewhere, and being told only that it did not work discards everything they learned getting there.
Ambiguous cases
A signal the reader cannot observe. The rule is that signal describes what they will see,
not what the system did. "The API validated the request" is a system fact and useless as a
checkpoint; "the error names an HTTP status" is something they can look at. The check cannot tell
these apart, so this is the reviewer's job and it is the one that matters most.
A means that flatters. Every claim must be true of the protocol. A checkpoint saying an
error proves something it does not is worse than saying nothing, because a reader who checks will
stop trusting the rest of the page — and they are exactly the reader worth keeping.
Checkpoints that overlap. Allowed and often correct. "Anything came back" and "the error names a status" are both true at once, and a reader may recognize either. Forcing them to be disjoint would make the reader classify themselves before they can be helped.
Whether the set of checkpoints is the right set. Not checkable. This rubric confirms each one is well formed. Whether they carve up the real space of positions readers find themselves in is a question only use can answer, and the evidence for it is which ones nobody ever selects.