diff --git a/docs/benchmarks.md b/docs/benchmarks.md index 1def2ff..161d693 100644 --- a/docs/benchmarks.md +++ b/docs/benchmarks.md @@ -23,8 +23,6 @@ shape is visible rather than accidental. | Bench | Subsystem | Upstream counterpart | |---|---|---| -| `block_encode` | storage | `BenchmarkEncodeColumns` / `BenchmarkEncodeBlock` | -| `block_decode` | storage | `BenchmarkDecodeColumns` / `BenchmarkDecodeBlock` | | `archive_append_live` | ingest→storage | `BenchmarkWriterLiveShape` | | `archive_append_backfill` | ingest→storage | `BenchmarkWriterBackfillShape` | | `archive_seal` | storage | `BenchmarkSeal` | @@ -35,9 +33,18 @@ shape is visible rather than accidental. | `wire_encode_v1` / `wire_encode_v2` | serve | `BenchmarkDecodeSegmentEvent*` (mirror side) | | `cold_replay_batch` | serve | `BenchmarkColdFanout` | -Two upstream benchmarks have no counterpart yet and that is deliberate rather +The table is exactly what `just bench` prints — ten rows, in that order. If you +count a different number, the doc has rotted; trust the binary. + +Four upstream benchmarks have no counterpart yet, and that is deliberate rather than forgotten: +- `BenchmarkEncodeColumns` / `BenchmarkEncodeBlock` and `BenchmarkDecodeColumns` + / `BenchmarkDecodeBlock` — bare block encode/decode in isolation. Ours are + covered transitively: `archive_append_*` drives encode and `sealed_read_block` + drives decode, both through the real call path rather than a synthetic block. + Worth splitting out only if a regression lands in encode/decode specifically + and the append/read numbers are too coarse to localize it. - `BenchmarkDeleteCompactionSyntheticArchive` — compaction is measured, but a synthetic-archive harness is a bigger fixture than this file should own. - `BenchmarkFlushToTmpfs` — isolates filesystem cost from encode cost; worth @@ -78,6 +85,12 @@ open costs ~51x an unchecked one. That is why the cold path opens with `parseUnchecked` and the admission-critical paths do not, and why upstream splits `ReaderOpen` from `ReaderOpenNoVerify`. +("Admission-critical" means a path whose result decides whether a build is +allowed to ship — see `docs/semantic-parity.md`. Those paths pay for the +checksum because a silently corrupt segment read there would let a broken +artifact through. The cold read path is serving traffic that a client can +retry, so it takes the 51x instead.) + The harness is deliberately naive — a fixed iteration count, no warmup discipline beyond a short prime, no statistical treatment. It is here to catch order-of-magnitude regressions, not to resolve a few percent. If a number