If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/EmbarkStudios/rust-gpu shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 6mo ago
• 10 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 6mo ago
• ⚠ Concentrated ownership — top contributor handles 74% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live EmbarkStudios/rust-gpu repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/EmbarkStudios/rust-gpu.

What it runs against: a local clone of EmbarkStudios/rust-gpu — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in EmbarkStudios/rust-gpu | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 218 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of EmbarkStudios/rust-gpu. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/EmbarkStudios/rust-gpu.git
#   cd rust-gpu
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of EmbarkStudios/rust-gpu and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "EmbarkStudios/rust-gpu(\\.git)?\\b" \\
  && ok "origin remote is EmbarkStudios/rust-gpu" \\
  || miss "origin remote is not EmbarkStudios/rust-gpu (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "crates/rustc_codegen_spirv/src/lib.rs" \\
  && ok "crates/rustc_codegen_spirv/src/lib.rs" \\
  || miss "missing critical file: crates/rustc_codegen_spirv/src/lib.rs"
test -f "crates/spirv-std/src/lib.rs" \\
  && ok "crates/spirv-std/src/lib.rs" \\
  || miss "missing critical file: crates/spirv-std/src/lib.rs"
test -f "crates/rustc_codegen_spirv/src/builder/mod.rs" \\
  && ok "crates/rustc_codegen_spirv/src/builder/mod.rs" \\
  || miss "missing critical file: crates/rustc_codegen_spirv/src/builder/mod.rs"
test -f "crates/spirv-builder/src/lib.rs" \\
  && ok "crates/spirv-builder/src/lib.rs" \\
  || miss "missing critical file: crates/spirv-builder/src/lib.rs"
test -f "crates/rustc_codegen_spirv/src/linker/mod.rs" \\
  && ok "crates/rustc_codegen_spirv/src/linker/mod.rs" \\
  || miss "missing critical file: crates/rustc_codegen_spirv/src/linker/mod.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 218 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~188d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/EmbarkStudios/rust-gpu"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

rust-gpu is a custom Rust compiler backend (via rustc_codegen_spirv) that compiles Rust code to SPIR-V bytecode for GPU execution, enabling Rust as a first-class shader language for graphics and compute workloads. It converts Rust's MIR (Mid-level Intermediate Representation) directly to SPIR-V instead of requiring developers to write HLSL or GLSL, bringing Rust's safety guarantees and module system to GPU programming. Monorepo structure: crates/rustc_codegen_spirv/ contains the core compiler backend with builder/ subdirectory handling SPIR-V instruction emission and intrinsics; crates/rustc_codegen_spirv-types/ defines type definitions for compilation results; .github/install-spirv-tools/ is a standalone utility for CI to download SPIR-V validation tools.

Game engine developers, graphics researchers, and compute shader authors who want to write GPU shaders in Rust instead of HLSL/GLSL while maintaining memory safety and leveraging Rust's ecosystem. Contributors are primarily graphics engineers familiar with compilation, SPIR-V, and Rust compiler internals.

Actively developed but experimental. The README explicitly states 'no guarantees about backwards compatibility' and recommends 'building from source with the latest main branch only.' The project recently migrated from Embark Studios to community ownership under Rust-GPU org, indicating ongoing investment. CI/CD pipelines exist (.github/workflows/ci.yaml) but the codebase is still in early-stage development with frequent breaking changes expected.

High risk for production use due to explicit stability warnings—this is a research/development project where APIs change frequently. Single-maintainer risk is mitigated by community ownership but development pace depends on volunteer contributors. Build system complexity (custom Nix configs, spirv-tools installation scripts) may cause reproducibility issues. No formal deprecation model exists, so upgrading could require significant code rewrites.

Active development on SPIR-V codegen with focus on builder infrastructure (intrinsics.rs, libm_intrinsics.rs, spirv_asm.rs for inline assembly support). Entry point handling (codegen_cx/entry.rs) and constant evaluation (codegen_cx/constant.rs) suggest ongoing work on shader entry point compatibility. Nix flake maintenance (android.nix) indicates cross-platform shader compilation support being added.

Clone from the Rust-GPU org (not EmbarkStudios), install Rust nightly with spirv-unknown-vulkan target: rustup toolchain install nightly && rustup target add spirv-unknown-vulkan --toolchain nightly, then build with cargo build. See .github/install-spirv-tools for SPIR-V validation tool setup if needed.

Daily commands: Not a runnable application—it's a compiler. Use it by creating a Rust shader crate with #![no_std] and #![cfg_attr(target_arch = "spirv", spirv(...))] attributes, then compile with cargo build --target spirv-unknown-vulkan. The rustc_codegen_spirv backend will generate .spv (SPIR-V) binaries.

• crates/rustc_codegen_spirv/src/lib.rs — Entry point for the Rust compiler codegen backend that transforms Rust code into SPIR-V shaders; all GPU compilation flows through this file.
• crates/spirv-std/src/lib.rs — Standard library for GPU shaders exposing GPU-specific intrinsics and abstractions; directly imported by all shader crates.
• crates/rustc_codegen_spirv/src/builder/mod.rs — Core builder abstraction that constructs SPIR-V instructions from Rust MIR; handles IR lowering for all code generation.
• crates/spirv-builder/src/lib.rs — Build system integration and shader compilation orchestration; provides the public API for building GPU shader crates.
• crates/rustc_codegen_spirv/src/linker/mod.rs — SPIR-V module linking and optimization pipeline; applies post-codegen passes that specialize and optimize shader modules.
• crates/rustc_codegen_spirv/src/spirv_type.rs — Type system mapping between Rust types and SPIR-V types; critical for correctness of memory layout and operations.
• Cargo.toml — Workspace root defining crate structure, dependencies, and build configuration for the entire rust-gpu ecosystem.

Add a new GPU intrinsic function

1. Define the intrinsic binding in spirv-std, exposing it as an unsafe extern function wrapping a SPIR-V opcode (crates/spirv-std/src/arch.rs)
2. Implement lowering code in the builder to recognize the intrinsic and emit SPIR-V instructions (crates/rustc_codegen_spirv/src/builder/intrinsics.rs)
3. Add type constraints if the intrinsic has specific requirements (e.g., only for float types) (crates/rustc_codegen_spirv/src/spirv_type_constraints.rs)
4. Test the intrinsic with a shader example in the integration test suite (crates/spirv-builder/src/lib.rs)

Add a new linker optimization pass

1. Create a new pass module in the linker directory following the existing pass structure (crates/rustc_codegen_spirv/src/linker/mod.rs)
2. Implement the pass transformation logic operating on SPIR-V modules (crates/rustc_codegen_spirv/src/linker/simple_passes.rs)
3. Register the pass in the linker's pass pipeline and conditionally enable it based on optimization level (crates/rustc_codegen_spirv/src/link.rs)
4. Add test cases validating the pass behavior in isolation and within the full pipeline (crates/rustc_codegen_spirv/src/linker/test.rs)

Support a new shader entry point or decoration type

1. Define the entry point enum variant and associated metadata in the codegen context (crates/rustc_codegen_spirv/src/codegen_cx/entry.rs)
2. Add procedural attribute parsing to recognize the new decorator in source code (crates/rustc_codegen_spirv/src/attr.rs)
3. Implement SPIR-V emission logic for the new entry point type and decorations (crates/rustc_codegen_spirv/src/custom_decorations.rs)
4. Update entry interface linkage logic to handle the new type correctly (crates/rustc_codegen_spirv/src/linker/entry_interface.rs)

Add support for a new shader library function (e.g., math operation)

1. Define the function signature in spirv-std with appropriate type parameters and attributes (crates/spirv-std/src/lib.rs)
2. Implement the lowering in the builder to map the function call to SPIR-V extended instructions or custom code (crates/rustc_codegen_spirv/src/builder/libm_intrinsics.rs)
3. Register the function in the builder's function dispatch mechanism (crates/rustc_codegen_spirv/src/builder/ext_inst.rs)
4. Write shader tests demonstrating the function behavior and performance characteristics (crates/spirv-builder/src/lib.rs)

Requires Rust nightly compiler (not stable) and spirv-unknown-vulkan target which may not exist in older nightly versions. SPIR-V validation requires external spirv-tools binary (installed via .github/install-spirv-tools), leading to fragile CI if tool URLs change. Nix flakes (android.nix, flake.nix if present) may be required for reproducible builds on some platforms. No #![no_std] support enforcement at compile time—incorrect std usage will silently fail or produce invalid SPIR-V.

• SPIR-V (Scalable Processor Intermediate Representation - Vulkan) — rust-gpu's entire output format—understanding SPIR-V module structure, opcodes, and decoration semantics is essential to debugging codegen issues
• Rustc Codegen Backend / Custom Compiler Plugin — rust-gpu replaces LLVM's code generation with SPIR-V emission by implementing rustc's backend trait—understanding this hook into the compiler pipeline is fundamental
• MIR (Mid-level Intermediate Representation) — rust-gpu lowers Rust's MIR directly to SPIR-V rather than going through LLVM, so MIR structure and semantics determine translation correctness
• GLSL Extended Instruction Set (GLSLStd450) — libm_intrinsics.rs uses GLSLStd450 for math functions; understanding this SPIR-V extension is needed to add transcendental functions or optimize math operations
• Shader Entry Points and Decorations — codegen_cx/entry.rs handles stage-specific metadata (vertex, fragment, compute); decorations control visibility, layout, and execution model which differ per GPU pipeline stage
• Byte-Addressable Storage (SSBO) — builder/byte_addressable_buffer.rs abstracts compute shader storage access; SPIR-V doesn't natively support byte-level addressing so this layer emulates it
• Nix Flakes for Reproducible Builds — android.nix and potential flake.nix files manage hermetic build environments and SPIR-V tool dependencies across platforms—critical for CI stability

• gfx-rs/naga — Alternative shader compilation approach: Naga is a portable shading language compiler that also targets SPIR-V but from a custom intermediate language rather than Rust source
• KhronosGroup/SPIRV-Tools — Upstream SPIR-V ecosystem: official validation and optimization tools that rust-gpu depends on via .github/install-spirv-tools/
• Rust-GPU/rust-gpu-examples — Official example shaders and integration tests showing real-world usage patterns for this compiler backend
• EmbarkStudios/kajiya — Real-world graphics engine proof-of-concept that uses rust-gpu shaders in production rendering pipelines
• rust-lang/rust — Upstream: rust-gpu is a custom rustc backend, so compiler changes and MIR format evolution directly impact this project

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for SPIR-V linker passes

The linker directory (crates/rustc_codegen_spirv/src/linker/) contains 13 specialized optimization passes (dce.rs, inline.rs, mem2reg.rs, etc.) but there's no indication of dedicated integration tests. Each pass transforms SPIR-V in complex ways (dead code elimination, inlining, memory-to-register promotion). Adding integration tests would catch regressions and make the linker more maintainable as the codebase evolves.

• [ ] Create crates/rustc_codegen_spirv/tests/linker_passes/ directory
• [ ] Add test fixtures with simple SPIR-V modules in crates/rustc_codegen_spirv/tests/fixtures/
• [ ] Write integration tests for each pass in src/linker/ (dce, inline, mem2reg, specializer, etc.) verifying input→output transformations
• [ ] Document expected behavior for edge cases (e.g., recursive inlining, dead code in loops)
• [ ] Add CI step to run linker tests in .github/workflows/ci.yaml

Create comprehensive documentation for rustc_codegen_spirv-types public API

The rustc_codegen_spirv-types crate (crates/rustc_codegen_spirv-types/) has a README.md but lacks detailed API documentation. It defines types like CompileResult that are critical for users consuming this library. The compile_result.rs module needs doc comments explaining error handling, serialization, and usage patterns. This will help external tools and IDE plugins properly integrate with rust-gpu.

• [ ] Add comprehensive rustdoc comments to crates/rustc_codegen_spirv-types/src/lib.rs explaining crate purpose and usage
• [ ] Add detailed doc comments to crates/rustc_codegen_spirv-types/src/compile_result.rs for CompileResult struct and all variants
• [ ] Create examples/ directory in rustc_codegen_spirv-types with example code showing how to deserialize and use CompileResult
• [ ] Update crates/rustc_codegen_spirv-types/README.md with API overview and link to generated rustdoc
• [ ] Run cargo doc and verify output renders correctly

Add CI workflow to validate SPIR-V output against spirv-val validator

The repo has install-spirv-tools infrastructure (.github/install-spirv-tools/) suggesting SPIR-V validation is a concern, but there's no automated CI step validating generated SPIR-V modules. This means invalid SPIR-V could merge undetected. Adding a CI job to run spirv-val on generated shaders would catch codegen bugs early and ensure compliance with SPIR-V spec.

• [ ] Create .github/workflows/spirv-validation.yml workflow file
• [ ] Add step to run install-spirv-tools binary and extract spirv-val
• [ ] Create integration test harness in crates/rustc_codegen_spirv/tests/ that generates SPIR-V and pipes through spirv-val
• [ ] Configure workflow to run on PR with matrix for different Vulkan/SPIR-V versions
• [ ] Document validation setup in CONTRIBUTING.md with local testing instructions

• Add unit tests for crates/rustc_codegen_spirv/src/builder/byte_addressable_buffer.rs intrinsics—the file exists but likely has incomplete test coverage for SSBOs and UBOs which are critical for compute shaders.
• Document the ABI contract in crates/rustc_codegen_spirv/src/abi.rs with examples showing how Rust types map to SPIR-V types—this file controls parameter passing but has no usage examples in README.
• Extend crates/rustc_codegen_spirv/src/builder/spirv_asm.rs to support inline SPIR-V assembly comments and validation—currently bare instructions without documentation of which SPIR-V opcodes are safe to emit directly.

The rust-gpu codebase shows moderate security posture. The primary concerns are outdated dependencies (tar 0.4 with known path traversal CVEs, zstd 0.13) in the install-spirv-tools helper utility. The project lacks visible hardcoded secrets or injection vulnerabilities in the analyzed files. However, there is supply chain risk from external binary downloads in CI workflows. Recommended actions: (1) Immediately update tar and zstd dependencies, (2) Run 'cargo audit' regularly in CI, (3) Implement checksum verification for external downloads, (4) Add SBOM generation to CI pipeline.

• Medium · Outdated tar Dependency — .github/install-spirv-tools/Cargo.toml. The install-spirv-tools crate depends on tar version 0.4, which is significantly outdated. The tar crate has had multiple security vulnerabilities in older versions, including path traversal issues (CVE-2021-32713) that could allow malicious tar archives to extract files outside the intended directory. Fix: Update tar dependency to the latest version (0.4.41 or newer for the 0.4.x series, or consider upgrading to 0.5+ if compatible). Run 'cargo audit' to identify specific known vulnerabilities.
• Medium · Outdated zstd Dependency — .github/install-spirv-tools/Cargo.toml. The zstd dependency is pinned to version 0.13, which is outdated. Compression libraries can have deserialization vulnerabilities or denial-of-service issues. No specific audit found, but old versions may have unpatched security issues. Fix: Update zstd to the latest stable version (0.14+ or latest available). Verify compatibility and run 'cargo audit' to check for known vulnerabilities.
• Low · External Binary Installation via CI — .github/install-spirv-tools/src/main.rs. The repository contains tooling (.github/install-spirv-tools) that downloads and extracts pre-built SPIRV tools binaries during CI. While this is common practice, it introduces supply chain risk if the source repository is compromised or if the download isn't verified with checksums/signatures. Fix: Implement checksum verification (SHA256) for downloaded binaries. Consider maintaining a signed release process or hosting pre-built binaries in a controlled registry. Document the source and maintenance status of SPIRV tools.
• Low · Cargo.lock in Repository — Cargo.lock. The presence of Cargo.lock in a library/framework repository can lock dependencies to potentially outdated versions. While necessary for binaries, it may prevent consumers from receiving security updates. Fix: For libraries, consider if Cargo.lock is necessary. If maintained, implement regular dependency updates. For the main workspace, ensure security patches are applied promptly and CI includes 'cargo audit' checks.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.