feat(benchmark): add benchmark-history capture and initial record

[skuenzli]

Summary

• Add make benchmark-history: a release-mode multi-state runner (tests/benchmark/capture_history.sh) and aggregator (tests/benchmark/aggregate.py) that produce per-commit summary JSONs and a rendered HISTORY.md. Run count is parameterized via BENCHMARK_RUNS (default 5).
• Capture the initial historical record across v4.8.0, v4.8.1, 6f601df (PR fix: surface invalid schema as NoDecision with diagnostic error (#27) #65 merge), 500a8d0 (PR feat: honor @id("...") annotation as the policy id #66 merge), and ca5d83c (current main HEAD). 25 native pytest-benchmark JSONs + 5 per-commit summaries + the rendered HISTORY.md.
• The record cleanly captures the @id-annotation perf regression introduced by PR feat: honor @id("...") annotation as the policy id #66: test_complex_policy median +14.9% at ca5d83c vs v4.8.0 — matches the original release-mode bisect for perf: rename_from_id_annotation regresses is_authorized by up to 31% on policy-heavy workloads #68 exactly. The perf: rename_from_id_annotation regresses is_authorized by up to 31% on policy-heavy workloads #68 fix that resolves this regression lives on fix/optional-resolve-policy-ids and is not yet on main.

Foundation for issue #69 goal 2 (historical record) and goal 3 (multi-run aggregation primitives the gating refactor will build on).

Out of scope (separate follow-ups)

• Switching make benchmark / benchmark-save / benchmark-compare to release mode (benchmark process improvements: release builds, refreshed baseline, multi-run signal #69 goal 1).
• Refreshing tests/benchmark/results/baseline.json to a release-mode capture (benchmark process improvements: release builds, refreshed baseline, multi-run signal #69 goal 2 proper). Gated on the perf: rename_from_id_annotation regresses is_authorized by up to 31% on policy-heavy workloads #68 fix landing on main.
• Rewiring make benchmark-compare to use median-of-N gating (benchmark process improvements: release builds, refreshed baseline, multi-run signal #69 goal 3).
• Adding a 6th historical state for "main post-perf: rename_from_id_annotation regresses is_authorized by up to 31% on policy-heavy workloads #68 fix" once that fix lands.

Notes for reviewers

• The 25 native pytest-benchmark JSONs are large (~25k lines diff); git diff --stat is the friendlier view. The substantive changes for review are in tests/benchmark/capture_history.sh, tests/benchmark/aggregate.py, tests/benchmark/README.md, the Makefile benchmark-history target, and tests/benchmark/results/HISTORY.md.
• Δ max column in HISTORY.md is intentionally noisy — pytest-benchmark tail times vary run-to-run on the same machine. Useful for spotting consistent tail regressions, but expect ±5–10% noise on individual rows. The Δ median column is the trustworthy signal.
• Branch is based on ca5d83c (current main HEAD). Once the perf: rename_from_id_annotation regresses is_authorized by up to 31% on policy-heavy workloads #68 fix lands on main, this branch can be rebased and a follow-up PR can append the post-fix state.

Test plan

• Read tests/benchmark/README.md and verify the documented workflow makes sense from a clean main checkout.
• Inspect tests/benchmark/results/HISTORY.md — verify the table shape (Commit | Date | Median | Δ median | Max | Δ max) and that the ~+15% regression on test_complex_policy at 500a8d0/ca5d83c is visible.
• Spot-check one per-commit summary JSON (e.g., tests/benchmark/results/history/v4.8.0.json) — schema, source_runs listing, n_runs count.
• Optional fast path: python3 tests/benchmark/aggregate.py --phase b regenerates HISTORY.md from the committed per-commit JSONs (no capture needed; ~1 second).
• Optional full reproduction (~30–40 min): make benchmark-history end-to-end. Runs release-mode 5×5 capture, regenerates HISTORY.md, restores starting branch on exit. Should produce identical statistical results modulo run-to-run variance.