Skip to content

feat(cli,render): Milestone 2 Phase 0 + Phase 2 offline Slang shader cook and cooked-shader validator - #11

Merged
brasga-a merged 1 commit into
masterfrom
feat/m2-p2-shader-cook
Nov 18, 2026
Merged

brasga-a merged 1 commit into
masterfrom
feat/m2-p2-shader-cook

Conversation

@brasga-a

Copy link
Copy Markdown
Owner

Summary

Implements Milestone 2 — Phase 0 (slangc pin) and Phase 2 (spawn-cli offline shader cook & spawn-render headless cooked-shader validation) stacked on feat/m2-p1-math (#10), following ADR-0014, ADR-0004, and ADR-0009.

  • Phase 0 (slangc toolchain pin): Installed official Linux x86_64 Slang 2026.22 (v2026.22, Apache-2.0 WITH LLVM-exception) in user-space (~/.local/opt/slang-2026.22 + ~/.local/bin/slangc) on the reference host and pinned spawn_cli::SLANGC_VERSION = "2026.22".
  • Headless cooked-shader contract & validator (crates/spawn-render):
    • Added src/shader.rs (default-features = false, #![forbid(unsafe_code)], #![deny(clippy::indexing_slicing)], zero normal third-party dependencies, zero ash/unsafe): versioned SPNSHDR\0 (v1) binary codec (CookedShader), pre-allocation size/alignment/overflow bounds checking (SPN-INV-034), SPIR-V 1.0–1.6 framing + OpEntryPoint uniqueness verification, and Vulkan 1.3 compatible-superset pipeline-layout validation (CookedShader::validate_against, validate_graphics_pipeline_shaders).
    • Added RenderErrorKind::InvalidShaderArtifact (REND-0010) and RenderErrorKind::ShaderLayoutMismatch (REND-0011) preserving REND-0001..0009.
    • Added standalone Gate G2 cargo-fuzz package crates/spawn-render/fuzz (decode_cooked_shader, excluded from root [workspace]).
  • Offline shader build CLI (tools/spawn-cli):
    • Implemented [[bin]] name = "spawn" (#![forbid(unsafe_code)]) with spawn shaders build over injectable SlangCompiler / ProcessSlangCompiler (slangc -target spirv -profile spirv_1_6 -matrix-layout-column-major -fvk-use-entrypoint-name, never -fvk-invert-y).
    • Added brace-aware .slang entry-point scanner (slang_scan.rs), rspirv 0.13 SPIR-V reflection extraction (reflect.rs, including MemberMatrixLayout propagation through OpTypeArray, signed constant checks, and descriptor/push-constant/vertex-input extraction), RAII .spv intermediate cleanup, uncommitted .spnshdr emission (target/shaders/), and pointer-sized located CliError (CLI-0001..0006).
  • Authored Milestone 2 .slang shaders: shaders/triangle.slang (SV_VulkanVertexID, CCW positive Vulkan signed area, reversed-Z z = 0.5) and shaders/mesh_3d.slang (camera-relative f32 Mat4 + normal_col0..2 + base_color 128 B push constants, vertex locations 0..=2).
  • Repository & docs sync: Updated .gitignore (*.spv, *.spnshdr, fuzz artifacts), Cargo.toml, AGENTS.md (root, crates/spawn-render/AGENTS.md, tools/spawn-cli/AGENTS.md), docs/DEPENDENCIES.md (In use), and docs/first-3d/{PLAN,VERIFICATION}.md.

Requirements Covered

  • F3D-FR-04 (offline Slang → Vulkan 1.3 SPIR-V + reflection cooking via spawn-cli)
  • F3D-FR-05 (headless cooked-shader binary parser & pipeline-layout compatibility validator in spawn-render)
  • F3D-FR-12 (located CLI-0001..0006 and REND-0010..0011 diagnostics per ADR-0009)
  • F3D-NFR-01..05, 07 (genre-free infrastructure, downward acyclic headless crate graph, approved dependencies only, zero runtime or build.rs shader compilation, #![forbid(unsafe_code)] / #![deny(clippy::indexing_slicing)])

Tests Run

  • PATH="$HOME/.local/bin:$PATH" ./scripts/check.sh → exit 0 (cargo fmt --all --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace including FND-T01..T10, F3D-T01..T04, F3D-T06 mock + live slangc 2026.22, F3D-T07 corrupt/truncated/unaligned/overflow/layout-mismatch + proptest fuzzing + insta snapshots, Phases 1–2 of F3D-T13, cargo doc --workspace --no-deps with RUSTDOCFLAGS="-D warnings", Linux wayland + vulkan feature tests/docs, and cargo deny check).
  • PATH=/usr/bin:/usr/local/bin:/bin ./scripts/check.sh → exit 0 (verifies 100% headless CI execution when slangc is absent from PATH).
  • PATH="$HOME/.local/bin:$PATH" cargo test -p spawn-cli -- --ignored → exit 0 (f3d_t06_opt_in_pinned_slangc_required: live slangc 2026.22 cook of shaders/{triangle,mesh_3d}.slang, compiler diagnostic forwarding, and descriptors_and_mat_array.slang with float3x3[2] push constants + all 6 descriptor kinds).
  • cargo run -p spawn-cli -- shaders build → exit 0 (4 uncommitted .spnshdr bundles emitted in target/shaders/; missing-compiler probe PATH=/usr/bin target/debug/spawn shaders build prints error[CLI-0002] and exits 1).
  • cargo check --manifest-path crates/spawn-render/fuzz/Cargo.toml --bins → exit 0 (Gate G2 cargo-fuzz target compiles cleanly).

Platforms Tested

  • Linux x86_64 (reference host): Omarchy (Arch Linux), Rust 1.99.1, pinned official Slang 2026.22 (~/.local/opt/slang-2026.22), AMD Ryzen 5 1600 / AMD Radeon RX 460.

Invariants & Gate G2 Coverage

  • Layering & public API (SPN-INV-001, 003, 004, 009, 011): spawn-render (default = []) has 0 normal third-party deps; spawn-cli depends only on clap, rspirv, and headless spawn-render (default-features = false, zero Vulkan/Wayland backends); zero third-party types or genre terms in public APIs.
  • Dependencies & licenses (SPN-INV-020..023, Gate G2): Added only owner-approved crates (arbitrary, clap, insta, proptest, rspirv in [workspace.dependencies] with default-features = false) and external slangc 2026.22 (Apache-2.0 WITH LLVM-exception); cargo deny check clean; docs/DEPENDENCIES.md In use synchronized.
  • Safety, untrusted input & versioned format (SPN-INV-030, 032, 034, 053, 080, 081, 083, 084, 100, 101, Gate G2): #![forbid(unsafe_code)] on spawn-cli and spawn-render::shader; #![deny(clippy::indexing_slicing)] on shader.rs, slang_scan.rs, and reflect.rs; pre-allocation header/count/alignment validation + proptest + cargo-fuzz target; single-site Y-flip preserved (no -fvk-invert-y); zero build.rs slangc invocations and zero git-tracked .spv/.spnshdr artifacts.

Known Limitations

  • GPU vkCreateShaderModule / Vulkan 1.3 dynamicRendering execution of cooked .spnshdr artifacts is PLANNED for Milestone 2 Phases 3–4 (F3D-T11, F3D-T12).
  • Windows slangc.exe execution is not verified on this Linux host (CI headless tests use the injected SlangCompiler mock).
  • Nightly LLVM ASan cargo fuzz run was not executed on this stable-only toolchain host; the standalone spawn-render-fuzz target was verified via cargo check --bins and its arbitrary::Unstructured harness runs deterministically under proptest in F3D-T07.

@brasga-a
brasga-a force-pushed the feat/m2-p2-shader-cook branch from 359c9fc to c3bc712 Compare November 18, 2026 17:03
@brasga-a
brasga-a changed the base branch from feat/m2-p1-math to master November 18, 2026 19:39
@brasga-a
brasga-a merged commit 511148f into master Nov 18, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant