[B4] bench: add absolute p1-FPS / spike / draw-call / vertex / GPU-memory ceilings per preset

[MichaelFisher1997]

Part of #834 (Production-Readiness Audit) — Batch B4 (make bench/visual actually fail, parallel-safe).
Replaces audit items #4 + #23 (merged because both touch the benchmark harness source). Parallel with: audit-b4 siblings — this issue owns the benchmark harness Zig source.

Problem

Two related gaps in the same source area, so they ship as one PR:

1. feat: worm cave system with connected underground networks #4 — no frame-time / SLO assertion. Benchmarks report FPS percentiles (p1, p5, p50, p95, p99), CPU ms, GPU ms, draw calls, vertices — but nothing fails. A 50% FPS regression ships green.
2. Resolve Issue #19: Remaining Audit Fixes #23 — no draw-call / GPU-memory / vertex budget test. Benchmarks log draw_calls_avg, vertices_avg, GPU ms — but never assert a ceiling. A 3× draw-call regression ships green.

Acceptance criteria

• Absolute SLO thresholds added to the benchmark harness per preset (low/medium/high/ultra/extreme):
  • p1 FPS floor (the worst 1% frame) per preset.
  • Spike guard: no single frame > N ms (e.g. 50 ms).
  • Draw-call ceiling per preset.
  • Vertex ceiling per preset.
  • GPU-memory ceiling per preset.
• Any breach causes the benchmark run to exit non-zero (so it can gate PRs once B4-1 enables the trigger).
• Thresholds are separate from the regression-vs-baseline comparison (these are absolute SLOs).
• Thresholds documented in docs/benchmarks/README.md with rationale.

Files in scope

• benchmark harness source (find the runner — likely under modules/engine-graphics or src/game benchmark code; identify and edit)
• docs/benchmarks/README.md (threshold table)

Dependencies

• After: B1-3 ([B1] ci(bench): populate docs/benchmarks/baseline.json and enable regression gating #861, real baseline) — thresholds should be derived from the real baseline numbers, not invented.
• Coordinate with B4-1 (workflow trigger) — once both land, benchmark PR runs actually fail on SLO breaches.

Out of scope

• Regression-vs-baseline gating itself (B1-3 / audit Roadmapv3 #1).
• Bencher trend (B4-1 / audit 🔍 Conduct Comprehensive Code Audit - Architecture, Performance, SOLID, and Quality Standards #19).

Branch / PR

• Branch: bench/slo-drawcall-ceilings · Targets: dev

[github-actions]

Classification

Feature Request — clearly scoped enhancement to the benchmark harness. Part of a trusted audit batch (#834 → B4).

Validation Findings

Issue is well-formed and appropriately scoped for a single PR:

• Acceptance criteria are concrete and testable
• Two related audit items (feat: worm cave system with connected underground networks #4 + Resolve Issue #19: Remaining Audit Fixes #23) genuinely share the same source area — merging them is correct
• Dependencies and out-of-scope items are explicit

File path correction: The benchmark runner source is modules/game-core/src/benchmark.zig (not modules/engine-graphics or src/game as the issue guessed). src/game/app.zig:442-453 is the call site that records frames and writes the JSON; it would need a follow-up to exit non-zero on SLO breach (currently it just sets should_quit = true).

Missing docs file: docs/benchmarks/README.md does not exist yet — only docs/benchmarks/baseline.json exists. The PR will need to create it.

Existing data points the SLO checks can use today (modules/game-core/src/benchmark.zig):

• Summary.p1 (line 39) — already computed, so p1-FPS floor needs zero new sampling logic
• FrameSample.cpu_ms (line 25) — already captured per-frame, so a "no frame > N ms" spike guard just needs a max(cpu_ms) reduction in makeResults / a post-run pass
• BenchmarkResults.draw_calls_avg / vertices_avg (lines 60-61) — already reported; ceiling check just needs a max(draw_calls) and max(vertices) reduction in makeResults (currently only averages exist)
• gpu_ms.total_avg exists for GPU-time ceilings, but per-frame GPU memory is not currently captured anywhere — FrameSample would need a new field populated from the RHI's memory query interface

Existing infrastructure that complements this work:

• scripts/compare_benchmarks.sh already gates on FPS/GPU/draw-call regression percentages vs baseline.json — this issue's SLO checks are intentionally separate (absolute ceilings), which the acceptance criteria correctly calls out
• .github/workflows/benchmark.yml already runs the suite via scripts/run_benchmark.sh and publishes a commit status — once SLO breaches exit non-zero, BENCHMARK_RUN_OUTCOME will naturally propagate to the status check (B4-1 trigger work is correctly flagged as out-of-scope here)

Suggested Implementation Shape

1. New SloThresholds config — either a new docs/benchmarks/slos.json parallel to baseline.json, or compile-time constants in benchmark.zig. A JSON file is preferable so thresholds can be tuned without recompiling and so B1-3 can seed it from real baselines.
2. Extend BenchmarkResults with p1_fps, max_cpu_ms, max_draw_calls, max_vertices, max_gpu_mem_mb (new reductions in makeResults).
3. Extend FrameSample with gpu_mem_mb and plumb through recordFrame from src/game/app.zig:446 — requires an RHI memory-query method (check engine-rhi for an existing one; if absent, this needs a small interface addition).
4. Add BenchmarkRunner.checkSlos(thresholds) that compares results against ceilings, logs breaches, and returns error.SloBreach. Caller in app.zig translates that to std.process.exit(1) so the workflow status surfaces correctly.
5. Create docs/benchmarks/README.md with the threshold table + rationale, as specified in acceptance criteria.

Scope Check

Single PR is correct — all five thresholds share one new checkSlos function and one new pass over self.samples.items. No reason to split further.

Dependencies Note

The "After: B1-3 (#861)" dependency is correct and important — implementing ceilings before real baselines exist will lock in arbitrary numbers. Recommend:

• Land the mechanism (config + checks + non-zero exit) with placeholder thresholds clearly marked TODO
• Update the placeholder values in a follow-up PR once B1-3 populates baseline.json with "generated": true

This way B4-1 (workflow trigger) can land in parallel without blocking.

opencode session  |  github run

[MichaelFisher1997]

Completed by merged PR #888; follow-up runtime CI stabilization landed in #891.