Phase 0 / Housekeeping / Post-M0.4 + Renderer Debt

[guysenpai]

Brief

briefs/M0.5-housekeeping.md — M0.5 (Post-M0.4 Housekeeping + Renderer Debt).

Status

Draft. The milestone runs E1→E6 with a mandatory stop for GO at each end-of-step gate (M0.1 model). This PR opens after E1 is green; it will be marked ready for review only after E6 + CI green.

• ✅ E1 — GAL capture + CI PSNR de-duplication (items 2, 1)
• ⏸ E2–E6 — pending Guy's GO, one step at a time
• ⚠️ Blocker B1 (item 2 ≤ 200-line gate) routed to Claude.ai (Cas 2): the brief's ~250 premise is wrong (main.zig was 501, and has been since M0.4). The ≤ 200 gate is unreachable via the prescribed capture-helper extraction alone. Per Guy's interim GO the gate is removed (FROZEN amendment pending) and NOT chased; the in-scope extraction + CI de-dup proceeded. See the brief's Blockers § B1.

E1 summary

• Item 2 — extracted the texture→PPM readback + encode into a public GAL helper gal/capture.zig (captureFrameToPPM + pure encodePpm/writePpm), exposed as a Device.captureFrameToPPM method on the Vulkan + Null backends and in the interface contract; wired the triangle example to consume it. §13 coverage in tests/render/capture_helper.zig (pure encode + Null Unsupported propagation; the full Vulkan path is exercised on lavapipe CI by the example + the PSNR gate). examples/triangle/src/main.zig: 501 → 449 lines (observation, not a gate).
• Item 1 — new std-only tests/render/ppm_psnr_compare.zig + zig build test-ppm-psnr that compares the already-produced out/smoke_test.ppm vs golden with no render-stack rebuild and no triangle re-spawn; CI runtime-smoke-test switched from test-render-capture (saves ~3-5 min/run). The spawn-based tests/render/capture.zig is retained per source-preservation (engine-development-workflow.md §2.5) until the new gate is proven on Linux CI.

Acceptance criteria (E1)

• Device.captureFrameToPPM on the public GAL surface, exercised by ≥ 1 test (§13)
• CI PSNR step no longer rebuilds the render stack / re-spawns the triangle
• Local: zig build test (debug + ReleaseSafe), zig fmt --check, zig build lint, run-example-triangle --smoke-test all green
• Linux + Windows CI green (this push)
• E2–E6 + final review

Changelog (so far)

• refactor(render): extract captureFrameToPPM into GAL surface (M0.5)
• test(render): cover captureFrameToPPM, add PSNR gate (M0.5)
• perf(ci): drop PSNR rebuild in runtime-smoke-test (M0.5 item 1)
• docs(brief): record E1 deliverables and 449-line baseline (M0.5)
• (+ brief setup, specs tick-off, and the B1 blocker log)

Manual GPU validation

Best-effort only for M0.5 (engine-development-workflow.md §4.5.1). Win11 + RTX 4080 marked unavailable (machine down — item 6).

🤖 Generated with Claude Code