[B4] ci: track and gate SPIR-V size regression per shader

[MichaelFisher1997]

Part of #834 (Production-Readiness Audit) — Batch B4 (regression prevention, parallel-safe).
Replaces audit item #24 (P3). Parallel with: audit-b4 siblings — this issue owns the SPIR-V size-check step (build/test wiring).

Problem

glslangValidator validates shader correctness in zig build test, but doesn't fail on a 2× SPIR-V size growth or compile-time spike. Shader bloat creeps in unobserved.

Acceptance criteria

• SPIR-V size per shader logged during zig build test (or a dedicated step).
• A baseline of SPIR-V sizes committed (e.g. docs/shaders/spirv-sizes.json).
• Check fails on >N% regression vs baseline (start strict: e.g. 10%).
• New shaders automatically added to the baseline on first appearance (with a clear "baseline updated" log line).
• Compile time per shader optionally logged (stretch goal).

Files in scope

• build.zig (test step wiring) — identify the shader-test invocation
• docs/shaders/spirv-sizes.json (new baseline)
• comparison helper script if needed (scripts/compare_spirv.sh)

Dependencies

• After: B1-1 ([B1] ci(fmt): enforce zig fmt --check on src/ and modules/ in build.yml #859, fmt-check) and the base test job being trustworthy — this plugs into the existing test job.

Out of scope

• Shader perf (covered by B4-3 ceilings + benchmark harness).
• Cross-toolchain SPIR-V comparison.

Branch / PR

• Branch: ci/spirv-size-regression · Targets: dev

[github-actions]

I'll analyze the issue and post a comment.

Classification: Feature Request (CI enhancement) — well-scoped, audit-tracked.

Validation:

• Issue is well-defined with explicit acceptance criteria, files in scope, and dependency note (#859 B1-1 fmt-check).
• No blocking PRs found (gh pr list --search "spirv-size" returns none).
• Sibling audit-b4 issues present: #873 (bench Bencher), #874 (visual golden), #875 (perf ceilings) — all open and parallel-safe.

Codebase pointers:

• build.zig:790-823 — defineShaderValidation runs glslangValidator -V <path> per shader, only checks correctness, no size. Shader list is hardcoded (24 entries) and drifts from the actual assets/shaders/vulkan/*.vert/*.frag/*.comp content (e.g. bloom_downsample, bloom_upsample, fxaa, post_process, terrain_debug exist on disk but are absent from the validation list).
• build.zig:413 — second shader compile step (the run target) globs the same *.vert/*.frag/*.comp files but doesn't validate. Both lists should be reconciled by the new step.
• .gitignore:25 — *.spv is ignored except for 14 manually-tracked .spv files. A size baseline should NOT depend on disk .spv artifacts; use glslangValidator -V stdout or compile-to-temp-then-stat flow.

Suggested next steps (no implementation):

1. Reconcile the shader list. Derive it from a single source of truth (e.g. walk assets/shaders/vulkan/ for .vert/.frag/.comp) instead of two hardcoded lists.
2. Generate docs/shaders/spirv-sizes.json on first run by compiling each shader to a temp .spv and recording {path, bytes, sha256} (hash guards against silent reformat changes that happen to keep size identical).
3. Implement the comparator in scripts/compare_spirv.py (or .sh) — Python keeps it portable across CI runners; use the same Nix shell if a Zig helper is preferred.
4. Wire it into build.zig as a new step that depends on shader validation but is gated by an option (e.g. -Dspirv-size-check) so the regression gate can be opt-in until the baseline stabilizes.
5. Add a clear baseline updated log line per new shader entry (per AC).
6. Stretch goal (compile time): wrap each glslangValidator call with time and append to the JSON; cheap to add now, valuable later.

Scope: Appropriately narrow — single subsystem (CI/shader validation). Not a candidate for sub-issues.

Missing info (non-blocking):

• Threshold confirmation: AC suggests 10% — please confirm whether absolute-byte ceilings are also desired (e.g. flag any single shader >256 KiB regardless of % delta).
• Desired failure mode: hard fail vs warn-then-fail-after-N-runs for first-time adoption.

opencode session  |  github run

[MichaelFisher1997]

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