perf: add wgpu timestamp phase queries

[aram-devdocs]

Overview

Type: perf

Summary:
Add wgpu timestamp-query instrumentation for the shadow pass, main render pass, and GPU submission tail so Phase 0 can attribute GPU-side frame costs separately from CPU record-time counters.

Related Issues: Closes #741

---

Changes Made

Engine Core (goud_engine/src/)

• Added wgpu_backend/timestamps.rs to own the QuerySet, resolve buffer, double-buffered readback slots, and GPU phase readback.
• Wired shadow and main render passes to use timestamp_writes where supported, with encoder-write fallback for adapters that only support encoder timestamps.
• Recorded gpu_shadow, gpu_render, and gpu_submit into frame_timing.
• Added a dedicated submit marker buffer so the submit-tail timestamp workload does not copy from the unresolved query buffer.
• Hardened the headless ENG2 spec probe with real shadow/render draw work, raw query validation, and non-zero duration assertions.

FFI Layer (goud_engine/src/ffi/)

No changes.

SDKs (sdks/)

No changes.

Codegen Pipeline (codegen/)

No changes.

Documentation

No changes.

---

Architectural Compliance

• Rust-first: All logic lives in Rust; SDKs remain thin wrappers
• FFI boundary: No new exports or FFI types in this PR
• Dependency flow: Imports stay within the backend/rendering layer boundaries
• SDK parity: No SDK surface changes required
• Unsafe discipline: No new unsafe blocks
• File size: No touched file exceeds 500 lines

---

Testing

• cargo check
• cargo fmt --all -- --check
• cargo clippy -- -D warnings
• GOUD_SKIP_NATIVE_SMOKE=1 cargo test
• cargo test --test spec eng2_p0_01_query_set_populates_and_resolves_on_wgpu_backend -- --nocapture
• cargo test -p goud-engine-core --lib libs::graphics::backend::wgpu_backend::timestamps -- --nocapture
• ./codegen.sh

Local note: plain cargo test reaches tests/native_main_thread.rs and can fail on this macOS desktop when the native window cannot present a frame. The test has a documented GOUD_SKIP_NATIVE_SMOKE=1 opt-out, which was used for the full-suite run above.

---

Code Quality

• No todo!() or unimplemented!() in production code
• No #[allow(unused)] without a justification comment
• Error handling uses Result, not unwrap()/expect() in library code
• Public items have doc comments

---

Breaking Changes

None.

---

Version Bump

Bump type: none
Justification: Internal instrumentation only.

---

Security

• No new unsafe blocks
• No new FFI pointer parameters
• No secrets or credentials in committed files

---

Performance

Adds GPU-backed counters for gpu_shadow, gpu_render, and gpu_submit. gpu_submit measures the GPU-side submission tail that wgpu can timestamp, not the CPU queue.submit() call.

Evidence blocker: on this host (macOS 26.5.1, Apple M3 Pro, wgpu 29.0.1, Metal), timestamp QuerySets resolve all zeros. This matches upstream wgpu issue gfx-rs/wgpu#9414 for the macOS 26 / Metal 4 counter-sample regression. The spec now quarantines only that exact zero-counter platform case; non-broken backends must produce non-zero raw slots and non-zero phase durations.

Real-GPU S1 capture with non-zero gpu_shadow, gpu_render, and gpu_submit remains pending before this draft can be marked ready.

---

Reviewer Notes

This PR remains draft. It wires and hardens the instrumentation path, but the ENG2 issue should not close until the S1 evidence gate is attached from a backend where timestamp QuerySets resolve correctly.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!