From 0704bea0652d55141acc7181a4bd40f1020f1b9f Mon Sep 17 00:00:00 2001 From: zzstoatzz Date: Thu, 30 Jul 2026 03:09:11 -0500 Subject: [PATCH] docs: drop two benchmarks the harness never had benchmarks.md's table listed block_encode and block_decode, which do not exist in src/bench.zig and never appear in the doc's own sample output. Moved them to the "no upstream counterpart yet" section with the reason they are covered transitively, and stated that the table is exactly what `just bench` prints so a count mismatch reads as doc rot. Also defined "admission-critical", which the verify/unchecked rationale leans on without ever saying what it means. Co-Authored-By: Claude Opus 5 (1M context) --- docs/benchmarks.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) 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 -- 2.51.2