perf: a diagnostic costs nothing on the read or write path, measured (#546)

[gafferongames]

Closes #546.

The owner's rule, 2026-09-05:

"i'm all for greater diagnostics, but if it costs speed on read or write, it's not worth it."

and, on widening and the refusal reasons:

"if this costs any time, then we should not do this"

at runtime, when the packet or the table is being read.

1. The law, on the page

docs/SPEC-TABLES.md §13.2 (Cost and allocation, ruled) gains the quotation as a bullet beside the ladder's other rulings, and a paragraph naming what it binds: the read report and its counters, the refusal reasons, retain-unknown's counters (§6.6), the descriptor columns (§8.1), and anything added later that reports. docs/PERFORMANCE.md gains a section of its own, because that is the page a reader goes to with a question about speed.

Both say the same thing and neither says it alone: measured is the operative word, so the law arrives with an instrument.

2. The gate

make perf-gate runs the C++ reference over the bench corpus on both wires and compares four rows against bench/PERF-PINS:

row	what it guards
bench_mixed write	the packet wire's write path
bench_mixed round_trip	the packet wire's read path, carried
bench_table write	the table wire's write path
bench_table round_trip	the table wire's read path, carried

The read row is round_trip, and that is a decision the page had to make. Neither runner times a read on its own, deliberately: the decode's output IS the re-encode's input, which is how the read side gets its sink discipline with no per-language fold to audit (BENCH-STANDARD §2.7). Both runners do print a read rate, round-trip minus write, and both mark it DERIVED and keep it out of the CSV. A gate pinning that number would be pinning a subtraction of two medians, carrying the noise of both. So the gate pins what was measured and reads the pair: a cost on the read path raises round_trip and leaves write flat. A red verdict says WHICH path got slower, not merely that something did.

Neither leg's flags are spelled in the gate. It drives bench/run.sh's own cpp leg and bench/tables/cpp/leg, so it compiles the same translation units, with the same flags, as the published passes do.

Two refusals keep it from going quietly green:

• Off the pinned box it renders no verdict at all. A rate in messages per second is a fact about one machine.
• A sitting noisier than spread.max.pct renders no verdict either. A gate that passes on a noisy box is a gate that passes on noise.

3. The negative control

make perf-gate-control plants the exact shape the law refuses, a counter behind a runtime flag with one added branch per field, on the READ path only, into a scratch copy of the emitter's output under build/. It measures a clean sitting and a planted one back to back and requires the plant to separate round_trip from write by more than the band on both wires.

The separation, rather than a bare round_trip drop, is the verdict on purpose: a box that ran faster during the planted half can hide a real cost inside its own drift, and the difference between the rows cancels whatever the box did to both. It is also the claim the law makes. Nothing is planted on the write path, so write is the control's own control.

Nothing under generated/ or internal/codegen/ is touched. The plant lands in build/.

4. Wired into certification

certify.yml gains a perf-gate leg. It runs check -advisory (the pin file parses, states its sitting, pins every guarded row, and the job says out loud that it is off the pinned box) and then the negative control, whose verdict is a ratio inside one sitting and therefore holds on hardware nobody here owns. The enforcing comparison stays on the box the pins name.

ci.yml gains perf-pin-lock, which costs no measurement. It takes the model bench/LOCK's standing gate uses since the freeze lifted in #545: a pull request moving the packet emitters re-pins the reproduction rows in the same PR and states the sitting. So a combined diff is allowed. What is refused is a re-pin with no sitting behind it (pins moved while sitting.date, sitting.uptime and sitting.commit did not), and a sitting.commit the branch does not contain. When the pins move it prints each row's move as a percentage, so the size of a re-pin is visible in the log.

5. The pins

Cut on this machine at a stated quiet moment. bench/PERF-PINS records the box, the date, the commit, the compiler and the uptime line the machine was carrying, and the band's derivation travels with the numbers.

One shared hook

bench/run.sh and bench/tables/cpp/leg gain BENCH_CXXFLAGS_PREFIX, prepended to the C++ bench compiles and empty in every published pass. One caller exists: the negative control, which needs to win the include search over -Igenerated/bench/cpp. perfgate pin refuses to cut a pin while it is set, because a number measured under flags the shipped build does not carry is a number for a build nobody runs.