docs: real output for the latency example, and a count check that bites

[0-jake-0]

What this changes

Follow-up to #946, merged as 6bdd82d. Three documentation fixes — two of them that PR's, one of them ours.

The example's output block was not real. Its header line was copied verbatim from showcase/latency/README.md, but format_latency_report sizes the label column to the widest label — 27 characters there, received -> decided (end to end) is 32 here — so every numeric column sat five characters off, and the elided ... cells moved them further again. Replaced with a captured run, plus the caveat naming which columns are a reading of one machine. That retires the paragraph hedging about a same-cycle reconciliation the reader will never see: stamp_precise re-reads the clock per stage, so all five observations get measured on any normal clock, and the pasted run shows count 5 on every row.

The snippet named two functions that do not exist. main.rs uses inline closures, and those closures are the interesting half of the example — Traced::with_latency is what carries the stamps across a map while the payload changes type from u64 to bool. Pasted the real ones and added a sentence saying what they demonstrate. Also cross-linked showcase/latency from the stamp vs stamp_precise paragraph, since that example is the cross-process case the paragraph describes.

And ours: the example count check did not check anything. #945 added a sentence to README.md claiming a count "asserted in CI by scripts/check-example-docs.sh, so it cannot drift" — but that script only ever printed the count. It compared it to nothing, which is #939, still open. #946 duly added a 48th target under a README still saying 47, in a different hunk, and merged green.

So the script now parses the numbers back out of the README sentence and fails when they disagree with the manifest — and the sentence goes back to saying only what a reader wants, which is how many examples there are. How the number is kept honest is the script's business and does not belong in the README's opening lines; the sed pattern is the contract between the two, and it is documented as such where it lives. The sentence remains the single source of truth, so there is no second constant to keep in sync, and deleting it to dodge the check is itself a failure with its own message.

Turning it on immediately found the other half of the drift: the parenthetical claimed 38 directories where the manifest declares 43. #945's figure had counted [[bench]] paths alongside the [[example]] ones.

Why

#946 is a good example and the code needed nothing, but CLAUDE.md is explicit that sample output must be real — "Several adapter READMEs were written from invented output and had to be corrected against the actual println!s; do not repeat that." Merging it and fixing the docs here was the cheaper path than a round trip with the contributor, especially for the half that was our churn landing under their branch.

Closes #939.

How it was verified

• scripts/check-example-docs.sh — passes: OK — 48 example targets in 43 directories, all documented and indexed
• The assertion actually fires, re-checked after the README wording was trimmed. Stale count → exit 1 naming both figures; sentence deleted → exit 1 telling you to restore it; correct → exit 0. Confirmed by exit code, not just output.
• bash -n scripts/check-example-docs.sh
• cargo run -p wingfoil --example latency — the block in the README is that run's stdout, pasted
• cargo fmt --all + cargo clippy --workspace --lib --bins via the pre-commit hook
• git diff --check

wc -l output is piped through tr -d before it is compared, because BSD wc pads with spaces and these are string comparisons now rather than just echo arguments.

Notes for the reviewer

cargo test -p wingfoil fails on this machine at tests/trybuild/must_use_combinators.rs with a snapshot mismatch under rustc 1.94.1. It fails identically on a clean origin/main worktree — I checked before pushing — so it is the local-toolchain gap CLAUDE.md describes rather than anything in this diff, and the snapshot is correct for the rustc CI pins. This PR touches no Rust. The contributor on #924 hit the same wall and reported it the same way, which suggests it is worth an issue of its own.

🤖 Generated with Claude Code

https://claude.ai/code/session_016E4AhS4mKjvR8HmS6cDx7k