feat: Vulkan compute-engine + shared-runtime foundation (upstream PR1)

[kdunn926]

First PR of the vllm-vulkan upstreaming stack. Introduces the model-free foundation that every subsequent model PR builds on:

• compute.rs: buffer pool (size-classes, idle-byte budget, staging), capacity/size split
• pipeline.rs: pipeline cache + ShaderClass, build.rs shader-registry codegen
• device.rs / vulkan_ctx.rs: device/context plumbing
• push_constants.rs, flags.rs: push-constant + env/flag registries
• gpu_error.rs, host_state.rs
• shared runtime: model.rs (layer/attn/rmsnorm/rope/sampling substrate), moe.rs, direct_engine.rs, direct_kernels.rs, tp.rs, spec_pipe.rs, vccl_ffi.rs, kvstore.rs, kv_prefix.rs
• the shader library and the #[pymodule] skeleton

default builds with NO model (same slice as
--no-default-features --features multiple-pymethods). Per-model feature flags are declared as stack scaffolding; each model's module(s) land in a follow-up PR that enables the corresponding feature.

[ericcurtin]

Code Review — PR #87 (foundation-compute-runtime)

Reviewed by checking out kdunn926/upstream/foundation-compute-runtime at bb8d243, building with cargo check/cargo build/cargo test/cargo clippy under the documented foundation slice (--no-default-features --features multiple-pymethods), and cross-referencing build.rs/scripts/compile_shaders.sh against shaders/.

What's good

• cargo check/cargo build succeed cleanly for the documented foundation slice; the built extension loads and VulkanContext construction (device init + all 77 shader pipelines) verified working on real Vulkan hardware.
• The buffer-pool/size-class design in compute.rs, the pipeline-cache + shader-registry codegen in pipeline.rs/build.rs, and the device-feature-detection fix (device.rs: shader_int64/shader_int16 now queried via PhysicalDeviceFeatures2 instead of unconditionally requested) are solid, well-commented improvements.
• No todo!()/unimplemented!(), and only one stray TODO comment — scaffolding is otherwise complete for what it claims to cover.
• clippy is clean of correctness lints (only expected dead_code for not-yet-landed model scaffolding + minor style nits).

Blocking issues

1. cargo test --lib does not compile under this PR's own documented default/foundation feature slice — 35 errors. Several #[cfg(test)] modules unconditionally reference qwen35/gemma-gated items that don't exist on this branch:

   • src/push_constants.rs:1884-1885 (use crate::qwen35;, crate::tp::{q35_tp_shard,...}) — blocks all 37 tests in dispatch_tests.
   • src/kvstore.rs:390-391,558,564,585 (crate::qwen35::kv_prefix_tests::{...}, crate::qwen35::LayerType).
   • src/tp.rs:5,8,1466,1595,1613,1630,1650,1669 (gemma_shard_tests calling gemma_fp8_tp_shard/gemma_nvfp4_tp_shard, gated behind feature = "gemma" in lib.rs:83).
   • src/lib.rs (multiple modules): 9264, 9723-9724 (use qwen35::{...}), plus calls into never-built model code (forward_batched_impl, forward_qwen35_prefill_impl, forward_qwen35_verify_impl, spec_snapshot_impl, dn_gpu_sync_to_host/_from_host, kv_export_prefix/kv_import_prefix), and 3 type mismatches from inner: placeholder (9093,9423,9780) expecting the foundation () stub but constructing Gemma4Model in test code.
   • This is invisible to CI: .github/workflows/ci.yml's test job only runs scripts/test.sh (pytest), and cargo test is never invoked anywhere in CI. Please gate these test modules on the relevant model features (or move them out of the foundation branch entirely) and confirm cargo test --no-default-features --features multiple-pymethods passes green before merge — ideally also add a cargo test step to CI so this class of bug can't recur.

2. Stale test assertion: src/lib.rs:8961 cutover_guard_registry_len() asserts include_all_shaders().len() == 131, copied from a much larger upstream tree. This branch's actual registry has ~79 entries. Once issue #1 is fixed and this test module actually compiles/runs, it will fail immediately. Please update the assertion (ideally derive expected count from the shader source list rather than hardcoding) and replace the stale narrative comment history above it (lib.rs:8866-8961, "MERGE (gemma-31b-spec into working main)... 108 registered shaders" etc.) with something accurate to this branch.

3. Self-contradictory Cargo.toml documentation (Cargo.toml:15-47): The first comment block (lines 15-40) states `default` re-enables EVERY model + debug-api, so a plain `cargo build`... [is] byte-for-behavior identical to before this refactor — this is false for this commit (default = ["multiple-pymethods"] at line 49 enables no model). The very next block (lines 41-47, "FOUNDATION BRANCH") correctly states the opposite. Please delete/rewrite lines 15-40 — this will actively mislead the author of the next stacked PR.

4. ~51 orphaned shader source files: scripts/compile_shaders.sh only compiles 77 targets; comparing against the new/changed .comp files in this diff, ~51 are never referenced by the compile script, never land in shader_registry.rs, and are never dispatched from Rust (their corresponding push_constants.rs helpers like q35_gdn_scan_pc, dsv4_swiglu_clamp_pc, laguna_moe_accum_pc, ling_kda_decay_pc, nemotron_gated_rmsnorm_pc are flagged "never used" by the compiler). Examples: all dsv4_*.comp (7), laguna_*/ling_* (9), nemotron_* (4), q35_* (6), kda_* (2), most new mul_mat_vec_mlx4*/nvfp4*/fp8* variants (~20), plus relu2.comp, mul_mat_vec_q8_0_cols.comp, paged_attn_decode_f16_sg.comp/_f32_sg.comp. For a PR whose premise is "no models, foundation only," pre-staging that much inert shader source is scope creep that's hard to review meaningfully and easy to silently leave dead. Either drop these from this PR (let each follow-up model PR add its own shaders) or add an explicit note (e.g. shaders/PENDING.md) marking them as intentionally-inert placeholders so nobody deletes or forgets to wire them up.

Non-blocking / follow-up worth tracking

• Heavy reliance on .unwrap() on Option fields inside #[pymethods] (e.g. self.qwen35.as_mut().unwrap() throughout lib.rs/tp.rs) will hard-panic the whole process on a wrong-dispatch call from Python rather than raising a catchable RuntimeError, which is at odds with the stated goal of gpu_error.rs ("replace unwrap() with a Python-catchable RuntimeError"). Pre-existing pattern, not introduced by this PR, but worth a follow-up pass given gpu_error.rs now exists to fix exactly this.
• direct_engine.rs:21 blanket #![allow(clippy::missing_safety_doc)] over 35 unsafe blocks/functions — consider narrowing this and adding // SAFETY comments per-callsite (only 8/230 unsafe blocks across the crate currently have one).

Verdict

Solid Vulkan-engineering foundation and the documented feature slice builds/runs correctly, but the test suite for that same slice doesn't compile (uncaught by CI), the Cargo.toml docs contradict themselves, and ~51 shader files are dead weight in a PR scoped to "no models." Requesting changes on items 1-4 before merge; happy to re-review quickly once addressed.

SCORE: 5/10 | VERDICT: Needs work — solid architecture but broken test suite under its own documented feature slice, contradictory Cargo.toml docs, and scope creep from 51 orphaned shader files | ISSUES: cargo test fails to compile (35 errors) under default features, CI never runs cargo test so this is invisible, stale shader-registry-length test assertion (131 vs ~79), self-contradictory Cargo.toml default-feature documentation, 51 orphaned/unreferenced shader files, unwrap()-heavy Option access in pymethods risks process panics across FFI boundary

[ericcurtin]

@kdunn926 I got opencode + claude sonnet to do an initial review, this PR is huge, it's helpful. Could you pick up the issues flagged?

[ericcurtin]

There's some big ones, this being one:

cargo test is never invoked anywhere in CI

[kdunn926]

@kdunn926 I got opencode + claude sonnet to do an initial review, this PR is huge, it's helpful. Could you pick up the issues flagged?

@ericcurtin - my mistake to not see the unwired CI issue before putting this up. The latest commit should address everything and I confirmed a green CI run in my fork as well. There are 10 more PRs (model/feature specific) to follow this "foundation".