M2-PERF-01: the render-50k bench suite (PRD §8.1 50k-sprite workload)

[offdev]

M2-PERF-01: the render-50k bench suite (PRD §8.1 "50k visible sprites")

Implements roadmap step M2-PERF-01 (roadmap/M2-rendering-2.5d.md):
laige-bench --suite=render-50k — the PRD §8.1 "50k visible sprites"
budget in executable form, binding the two existing budgets.json
entries (sprites_50k_draw_calls, sprites_50k_cpu) to the full
reference scene rendered offscreen for 3000 frames.

What lands

• New suite render-50k in tools/bench/laige-bench.cpp (both
  SimMath backends via --math): renders the FULL M2-SCENE-01
  reference scene (50 000 sprites, 65 536 terrain tiles, 3 parallax
  layers, 8 particle emitters, a 2-widget UI) offscreen at the
  1280×720 M2-GOLD-01 reference resolution. One measured iteration is
  one frame:
  • sim-side pacing (one particle update per frame) outside the
    measured window (the sim tick is the sim_tick budget's
    territory, ARCH-002);
  • the measured window = the frame's batch stage (world beginFrame
    • declareIsoReferenceScene + build, UI beginFrame +
      declareUi + build) — its CPU time is the
      sprites_50k_cpu sample (mean);
  • the submit stage renders the built frame offscreen outside
    the window (world pass, then UI pass on top — the engine's frame
    order); the frame's draw-call count (both passes'
    frameStats.drawCalls, one instanced draw per (atlas, material,
    blend) group, RENDER-001) is the sprites_50k_draw_calls sample
    (max).
• Zero-allocation assertion (M1-ALLOC-01 extended to the batcher):
  the allocation watch arms around every measured window; a window
  with a nonzero count aborts the run with the first offending site
  (the sim-tick G-R1 shape). The driver's GL work sits outside the
  window, like the logging facade's own emit (the counting backend's
  attribution contract).
• Two-histogram support in the harness tool: the suite records
  two quantities per frame (CPU window + draw-call count) into its own
  capacity-runs rolling windows (recorded on every iteration, warmup
  included — the window holds exactly the measured region's last
  runs samples); a --budget=<name> check against a name the suite
  records evaluates that suite-owned histogram (the Suite table gains
  a histogramFor hook).
• CPU-only degradation: a host without an offscreen GL 3.3
  context runs the suite CPU-only (loud notice): the batch-stage
  window + zero-allocation still measure; the draw-call histogram
  stays empty and a named check against it fails NO_SAMPLES
  (CORE-008).
• CI gate (tools/bench/CMakeLists.txt): two entries
  laige_bench_render_50k_fpx16 / _fp32 — the canonical
  --runs=3000 --warmup=1000 shape, both budgets checked against the
  repo budgets.json, TIMEOUT 1800. Platform scope: the absolute
  targets are calibrated on the CI reference machine (methodology §5)
  — Linux-only (the suite needs the CI's Mesa surfaceless EGL +
  llvmpipe offscreen stack); excluded from the sanitizer trees
  (instrumentation inflates the absolute cost — the m1-profiler-cost
  precedent). No all-platform smoke: the macOS runners have no usable
  GL (the GL smokes' documented SKIP) and the 4000 × 116k-quad
  renders would not fit the other lanes' time budgets.
• Docs: docs/api/budget_harness.md (suite table, the
  per-quantity budget mapping, exit codes, determinism),
  docs/api/iso_reference_scene.md, docs/api/sprite_batcher.md,
  docs/api/sprite_renderer.md (the composite budget is now measured
  by this suite).

Budgets — first CI measurement + re-baseline (in this PR)

First CI reference-lane measurement (run 38257115294, commit
23a27ab, both P0 Linux jobs, ubuntu-24.04):

• sprites_50k_draw_calls (max ≤ 30): 14 on every backend and
  toolchain (13 world-pass groups + 1 UI group), 2.1× inside —
  PASS.
• sprites_50k_cpu (mean, batch stage): 60.4450 ms on the CI
  reference lane (Clang 18.1.3, worse backend fp32_pinned); the g++
  lane (GCC 13.3.0) measured 69.4684 ms; zero bad-alloc frames on all
  backends/toolchains (8000 frames per toolchain, in-suite assertion).
  The 2.0 ms bar predates the concrete M2-SCENE-01 workload, so
  the first CI run failed it by design; that failure was the
  measurement, not a regression.

The documented revision landed in this PR (PRD §8.1 + budgets.json +
new baseline file + change-log row, methodology §5 — the particle
2.0→3.0 precedent):

• PRD v0.5: §8.1 50k row + §4 acceptance line ≤ 2 ms CPU →
  ≤ 100 ms CPU (65% above the latest recorded reference-lane
  value, 44% above the worst observed mean on either P0 Linux job);
• budgets.json: sprites_50k_cpu target 2.0 → 100.0,
  measured 0 → 60.4450 (latest recorded value, worse backend,
  CI reference lane); sprites_50k_draw_calls measured 0 → 14
  (target 30 unchanged);
• New baseline docs/benchmarks/baselines/m2-render-50k.md
  (the twelfth baseline — AGENTS §12 metadata + verbatim CI reports)
  • the baselines index row.

budgets.json entry count stays 17 (no new entries — the
allocation budget is the in-suite assertion, not a budgets.json
row, per the M1-ALLOC-01 precedent; the pin test passes in all four
local gate trees on the updated file).

First-lane bugs fixed in this PR

Two setup bugs, caught by the PR lanes (locally uncatchable — no
local GL), both aborted loudly (exit 1, CORE-008 — exactly what the
contract requires):

1. UI renderer's registry (run 38245856118): the registry domain
   is [0, maxAtlases), and the scene's sparse UI atlas id is 100 —
   the suite created the UI renderer with maxAtlases = 1, so
   bindAtlas correctly failed. Fixed by sizing the registry to the
   scene's id plan (kIsoRefSceneUiFontAtlas + 1 = 102); the world
   renderer's dense 0..8 ids were already covered.
2. The fg parallax atlas (run 38249843671): the world submit
   requires every group's atlas bound, and the scene's fg parallax
   layer declares atlas 8 — the bind loop stopped at
   kIsoRefSceneParticleAtlas (7). The loop now covers the scene's
   atlas-id plan 0..8 (bg/mid/ground/sprites/particles/fg).

Verification status (honest split)

• Compiled + linked + locally run (CPU-only): the batch-stage
  window, both backends, 4000 frames each — zero-allocation asserted
  per frame (0 bad frames); draw-call count 14 via the batcher's
  group counts (1:1 with the instanced draws by the M2-SPRITE-02
  contract).
• CI-only (GPU policy — no local GL): the offscreen GL context +
  submit stage (the sprites_50k_cpu window measured on the
  reference machine with the submit stage outside it, and the
  sprites_50k_draw_calls from the renderer's own bookkeeping).
  The first full reference-lane run has completed (run
  38257115294, commit 23a27ab): both Linux jobs 124/126 — the only
  failures are the two budget entries, and only on
  sprites_50k_cpu (the 2.0 ms bar predating the concrete workload,
  re-baselined to 100 ms in this PR's second commit); all other 9
  jobs green. The reference-lane numbers (60.4450 / 69.4684 ms) are
  the recorded values; the local numbers above are CPU-only
  estimates of the same window.
• Local Linux gate: all 4 trees, full ctest minus the
  GL-creating entries (which include the two new entries — GPU
  policy): gate-gcc 115/115, gate-clang 115/115, gate-asan 112/112,
  gate-tsan 112/112; include-lint OK (80 files, 315 system headers).

Dependencies

• fix/ci-linux-timeout-render-50k (Linux job timeout 10→45 min,
  macOS arm64 15→20 min) — merged (PR Extend the CI build-job timeout caps for M2-PERF-01 (Linux 10→45, macOS arm64 15→20) #94). GitHub runs this PR's
  workflow from the BASE branch, so its Linux jobs would otherwise
  have hit the 10-min wall before the render-50k entries report.