test(eng2): expand renderer bench suite

[aram-devdocs]

Overview

Type: test

Summary:
Adds the ENG2-P0-03 renderer benchmark coverage for frustum-cull scaling, legacy primitive draw-call cost, and an opt-in real-wgpu shadow benchmark. Also records the expanded Criterion baseline and wires the new CPU-safe groups into scripts/bench-gate.py.

Related Issues: Fixes #743

---

Changes Made

Engine Core (goud_engine/src/)

No engine runtime changes.

FFI Layer (goud_engine/src/ffi/)

No changes.

C# SDK (sdks/csharp/)

No changes.

Python SDK (sdks/python/)

No changes.

TypeScript SDK (sdks/typescript/)

• Node napi binding changes
• Web WASM binding changes
• Type definition changes
• Tests updated
  No changes.

Codegen Pipeline (codegen/)

• Schema changes
• Generator changes
• Validator changes
• ffi_mapping changes
  No changes.

Proc Macros (goud_engine_macros/)

• #[goud_api] attribute changes
  No changes.

Tools (tools/)

• lint-layers changes
  No tools/ changes. scripts/bench-gate.py now tracks cull_scaling and primitive_draw_calls by default.

WASM (goud_engine/src/wasm/)

• wasm-bindgen exports
• Sprite renderer changes
• Texture loader changes
  No changes.

Examples (examples/)

No changes.

Documentation

No docs changes; benchmark usage is documented in the new bench file comments.

---

Architectural Compliance

• Rust-first: Benchmark behavior and tests live in Rust.
• FFI boundary: No FFI changes.
• Dependency flow: Bench/test code uses existing engine APIs; ./codegen.sh ran lint-layers cleanly.
• SDK parity: No FFI or SDK surface changes.
• Unsafe discipline: No new unsafe blocks.
• File size: No changed source file exceeds 500 lines.

---

Testing

• cargo test passes
• cargo clippy -- -D warnings is clean
• cargo fmt --all -- --check passes
• Python SDK tests pass (python3 sdks/python/test_bindings.py) — if SDK changed
• C# SDK tests pass (dotnet test sdks/csharp.tests/) — if SDK changed
• TypeScript SDK tests pass (cd sdks/typescript && npm test) — if TS SDK changed
• Codegen produces consistent output (./codegen.sh)
• Pre-commit hooks pass

Additional local checks:

• cargo check passed.
• cargo test --test spec -- --nocapture passed.
• cargo test --test renderer3d_frame_counts -- --nocapture passed.
• cargo bench --bench engine_tick_benchmarks -- --sample-size 10 --warm-up-time 1 --measurement-time 1 passed.
• cargo bench --bench renderer3d_frame_benchmarks -- --sample-size 10 --warm-up-time 1 --measurement-time 1 passed.
• GOUD_BENCH_REAL_WGPU_SHADOW=1 cargo bench --bench renderer3d_real_wgpu_shadow_benchmarks -- --sample-size 10 --warm-up-time 1 --measurement-time 1 passed locally on macOS.
• python3 scripts/bench-gate.py --quick passed with 16 tracked benches.

Known baseline failure:

• Full cargo test still fails at goud_engine/tests/native_main_thread.rs:109 (assertion failed: game.end_render()). This was reproduced on current main before this branch, so it is not introduced here.

---

Code Quality

• No todo!() or unimplemented!() in production code.
• No new #[allow(unused)] in production code.
• Error handling uses Result; benchmark panics are limited to explicit bench setup failures.
• New public benchmark helpers have doc comments where useful.

---

Documentation

• Updated relevant AGENTS.md files (if architecture changed): N/A.
• Updated README.md (if user-facing behavior changed): N/A.
• Added or updated doc comments on new public APIs.

---

Breaking Changes

None.

• API changes: None
• FFI signature changes: None
• SDK interface changes: None

---

Version Bump

Bump type: none
Justification: Internal benchmark/test infrastructure only.

---

Security

• No new unsafe blocks — or each one has a // SAFETY: comment and is necessary.
• No new FFI pointer parameters without null checks.
• No new dependencies with known advisories (cargo deny check)
• No secrets or credentials in committed files.

---

Performance

Recorded expanded CPU-safe baseline in goud_engine/benches/baselines/criterion_baseline.json with 16 tracked benches.

Selected local Criterion captures:

• cull_scaling/visible_5k_total_10k: [348.85 us 349.32 us 349.73 us]
• cull_scaling/visible_5k_total_30k: [477.06 us 482.61 us 488.59 us]
• cull_scaling/visible_5k_total_100k: [882.73 us 894.86 us 926.77 us]
• primitive_draw_calls/plane_10k: [623.77 us 624.90 us 626.37 us]
• primitive_draw_calls/cube_10k: [620.42 us 621.34 us 623.53 us]
• shadow_record_real_gpu/casters_1400: [18.852 ms 19.132 ms 19.586 ms]
• shadow_record_real_gpu/casters_5k: [71.606 ms 75.424 ms 79.437 ms]

---

Deployment

• NuGet package version updated (if SDK changed)
• Python package version updated (if SDK changed)
• npm package version updated (if TS SDK changed)
• Native library builds on all targets (macOS, Linux, Windows)

N/A for this internal benchmark/test change.

---

Reviewer Notes

The real-wgpu shadow bench is deliberately separate and opt-in through GOUD_BENCH_REAL_WGPU_SHADOW=1. It creates a small native window because hidden or occluded wgpu surfaces do not produce presentable frames; the default Criterion suite remains NullBackend-only and CI-safe.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[claude]

Claude finished @aram-devdocs's task in 5m 50s —— View job

---

Review: test(eng2): expand renderer bench suite (#816)

• Gather context (PR body, changed files list)
• Read AGENTS.md / rules for perf-work, testing-v2, render-v2
• Review diff against origin/main
• Phase 1-2: Context & architecture validation
• Phase 3: Anti-pattern scan
• Phase 4: Quality assessment
• Phase 5: Security review (FFI/unsafe)
• Phase 6: Scope verification
• Phase 7: Post structured review

Verdict: APPROVED

Rust-only test/bench infra change (no FFI/SDK/engine surface touched). No blockers found.

---

BLOCKERS

None.

WARNINGS (non-blocking)

#	File:Line	Issue
1	goud_engine/tests/renderer3d_frame_counts.rs:76-111 vs goud_engine/tests/spec/eng2_p0_03_bench_suite_expansion.rs:54-78	The cull-scaling and plane/cube draw-count invariants (total/visible/culled/draw_calls) are asserted twice, in near-identical tests in both files, just with different n values (10k/1k vs 10k/512). Not wrong, just redundant coverage — could consolidate into one location (spec test can be the sole source of truth per testing-v2.md, or the frame-counts file can own it and the spec test can just check wiring). Not asking for a change, flagging for awareness.
2	.github/workflows/*.yml	scripts/bench-gate.py (and the renderer3d_frame_benchmarks/engine_tick_benchmarks targets this PR wires new groups into) is not invoked from any CI workflow — confirmed via grep across all .github/workflows/*.yml. benchmarks.yml only runs ecs_benchmarks/asset_benchmarks/sprite_batch_benchmarks and never calls bench-gate.py. This predates this PR and isn't its responsibility to fix, but perf-work.md names this script as the CI-runnable gate mechanism — worth a follow-up issue so the gate is actually enforced automatically rather than manual-only.
3	deny.toml / Cargo.lock	The security-refresh commit (crossbeam-epoch 0.9.18→0.9.20, memmap2 0.9.10→0.9.11, dropping the RUSTSEC-2026-0186/-0189 ignore entries) is bundled into a PR titled/scoped as bench-suite test infra. It's small and verified consistent (memmap2 bump backs the 0186 removal; rmcp was already 1.5.0 on main, so the 0189 removal is stale-entry cleanup), so not blocking, but it's scope outside the stated PR description.

Verification performed

• Read all 11 changed files in full (scene3d.rs, both bench files, both test files, bench-gate.py, Cargo.toml, deny.toml, baseline JSON).
• Confirmed cull_scaling_scene/dynamic_primitive_scene object-id and position math is internally consistent (ids 1..=n sequential from create_primitive, visible/hidden positions non-overlapping).
• Confirmed the new [[bench]] renderer3d_real_wgpu_shadow_benchmarks target is correctly separated from the default CPU-safe Criterion suite and gated behind GOUD_BENCH_REAL_WGPU_SHADOW=1, keeping raw wgpu calls opt-in and CI-safe per render-v2.md/perf-work.md.
• Confirmed the ratio-normalized bench-gate.py design (comparing each bench against engine_tick/tick_10k on the same run) means the full baseline recapture in criterion_baseline.json (which shifted absolute mean_ns for pre-existing groups) is not a red flag — ratios, not raw times, are what's gated.
• Confirmed is_multiple_of (used in the new label() helper) has repo precedent (engine_tick_benchmarks.rs:81, renderer3d/core_model_animation/mod.rs:237), so it's not a toolchain risk.
• Confirmed the new spec test file name/location (goud_engine/tests/spec/eng2_p0_03_bench_suite_expansion.rs) matches the tracked issue ENG2-P0-03 in docs/src/runbook/phase-specs.md:78 and phases/phase-0.md:19, and follows the eng2_p<N>_<nn>_<slug>.rs convention from testing-v2.md.
• cargo fmt --all -- --check — clean.
• Could not verify: cargo build/cargo test/cargo bench/cargo clippy in this sandbox — the default desktop-native feature set pulls in winit/gilrs, which need the system libudev dev package; it isn't installed here and sudo apt-get install is blocked by this environment's sandbox policy. Reviewed by careful reading instead of full compilation; the PR body's reported local runs (cargo check, spec tests, renderer3d_frame_counts, both new Criterion benches, bench-gate.py --quick) look consistent with the code as written.

Positive callouts

• Real-GPU shadow bench is cleanly isolated in its own file/target with an explicit opt-in env var, keeping the default suite headless/CI-safe — good adherence to render-v2.md's backend-isolation rule.
• New scenes (cull_scaling_scene, dynamic_primitive_scene) are deterministic and backed by dedicated exact-count assertions in renderer3d_frame_counts.rs, matching testing-v2.md's "assert exact draw/culled/visible counts" requirement.
• No FFI, unsafe, or SDK surface touched; file sizes are well under the 500-line cap (largest changed file ~410 lines).
• bench-gate.py's ratio-vs-reference design is a solid piece of engineering — it insulates the gate from machine-to-machine noise, which is exactly why the wholesale baseline recapture here isn't a problem.

[aram-devdocs]

Claude warning triage:

• Duplicate renderer count assertions: keeping both. The spec test is the ENG2 issue-level contract; renderer3d_frame_counts keeps reusable exact-count coverage for the frame-count helpers with different sizes. The overlap is intentional and low-cost.
• bench-gate.py not wired into CI: confirmed as a pre-existing workflow gap outside P0-03. This PR makes the gate aware of the new groups and attaches local captures; CI wiring should be handled separately so it does not expand the bench-suite implementation.
• Security refresh in scope: included only because current CI security checks failed on the branch after the initial PR. The lockfile and deny.toml changes are the minimum needed to restore green CI and remove stale advisory ignores.

No code changes are needed for these warnings.