docs(benchmarks): online-maintenance section + refresh to 122fd5c

[ChronicallyJD]

Ran a full bench/run_bench.sh on current main (122fd5c, PG18.4 non-assert, 6M rows, median of 5) and benchmarked today's maintenance-path work. Docs only.

Refresh

The storage, query, and mutation tables re-ran materially unchanged from the 2026-08-12 numbers — today's work is on the maintenance path and does not touch the scan/storage/write code these measure. Updated the header stamp and "What changed" to record the re-run at 122fd5c.

New "Online maintenance" section

recluster self-gate (#614) — measured as a true before/after (built the pre-#614 commit bd983d9 and the current .so, same 10M-row / 67-group fixture on each):

build	groups rewritten	time
before #614 (bd983d9)	67 (all)	14,750 ms
after #614 (self-gate)	0	0.96 ms

A redundant recluster on an already-clustered table went from a full rewrite (~14.7 s, layout digest changes every call) to a ~1 ms no-op (returns 0, layout byte-identical). That is the cost a scheduled recluster / the daemon would otherwise pay every sweep.

autovacuum daemon (#624) — a foreground scan is 174.3 ms (daemon off) vs 173.9 ms (daemon on, actively compact_rewriteing a separate deleted-heavy table): no measurable foreground impact. Non-blocking under lock conflict is proven separately with a hard bound by test/autovacuum_yield.sh.

Scope

bench/run_bench.sh single-engine only. Cross-engine (Citus) and ClickBench were not re-run — those paths are unchanged by today's work and their sections keep their prior dated numbers. docs_style.sh passes 9/9.

🤖 Generated with Claude Code

[jdatcmd]

Approved. Honest methodology, honest scope, and the headline claim is backed by a merged removal-proven test.

Docs-only, so I verified what a docs review can: the claims' soundness and internal consistency, the scope honesty, and the gate.

Methodology is the right shape. The recluster number is a true before/after: you built the pre-#614 commit (bd983d9) and the current .so and ran the same 10M-row / 67-group fixture on each, median of 3. That is the only way to measure a self-gate honestly, and the doc states the caveat that matters, that establishing the order the first time costs ~21s either way, so the win is only on the repeat call. The daemon number carries its own anti-vacuity control ("the daemon completed its maintenance during the window, so the table was genuinely being rewritten"), without which "no impact" could mean the daemon did nothing.

The headline claim is not just plausible, it is pinned. The recluster no-op shape, 0 groups rewritten and a byte-identical physical layout, is exactly what the merged recluster_gate.sh asserts via the (group_number, file_offset, rowcount) multiset, and that arm reds when the self-gate is removed (I ran that removal proof reviewing #614). So the benchmark's direction rests on a falsifiable, removal-proven test, not on the timing alone. The daemon-no-foreground-impact result is structurally expected too: a scan on one table and compact_rewrite on another share no lock (AccessShare vs SUEL on different relations), so ~174 ms vs ~174 ms is the confirmation, not a surprise, and the yield itself is separately hard-bounded by autovacuum_yield.sh.

Scope is stated plainly and correctly. Single-engine only; Citus and ClickBench not re-run because today's work does not touch those paths; the storage/query/mutation tables re-run and "materially unchanged" with concrete spot checks (heap 707 MB vs columnar-zstd 6.1 MB, count(*) 0.04 ms). No overclaim.

Consistency and gate. 14,750 ms / 0.96 ms / 10,000,000 rows are cited identically in the table and the "What changed" bullet. No em/en-dash. docs_style.sh 9/9 on my lane.

Merge when ready.