feat(MODEL-MM-QWEN4-EXP): W4 — Qwen Sparse Attention with a GATHER consumer, counted at the key-row read

.agents/oracles/transformers.md

@@ -129,5 +129,16 @@ precedent says an oracle is gateable only once it demonstrably builds and runs t
 model. Resolving the runtime string is owed to the first wave that stands an oracle
 up. Do not promote this pin to `gateable = yes` by editing the line.
 
+**The version string is no longer unmeasured; `gateable` still is.** W4
+([#1991](https://github.com/mudler/vllm.cpp/issues/1991)) stood the lane oracle up
+and `transformers.__version__` reads **5.16.0** on a live import, with
+`transformers.models.qwen4_exp.modeling_qwen4_exp.Qwen4ExpTextQSAIndexer`
+importable and running on CPU against random weights.
+`tests/vllm/models/fixtures/gen_qwen4_exp_qsa_goldens.py` refuses to emit under any
+other version string, so that reading is now executable rather than recorded. This
+resolves only the half this note said was owed. `gateable` stays `no`: running one
+module on random weights is not running the model, no published artifact fits any
+fleet device, and the field means what `## Gateability` says it means.
+
 See [`../specs/qwen4-exp-flash-next.md`](../specs/qwen4-exp-flash-next.md)
 `## Oracles`.

.agents/specs/qwen4-exp-flash-next.md

@@ -779,10 +779,57 @@ change that makes any arm reachable, not later.
   substitution for a ragged-K Q4_K tensor, asserted here as Q5_0.
 - A K-divisibility assertion in whatever writes our GGUF files.
 - A speed denominator, once one exists.
+- **W4's QSA slice lands UNREACHED**, and this entry is what AGENTS.md "Nothing
+  lands dead" requires in exchange.
+  `src/vllm/model_executor/models/qwen4_exp_qsa.{h,cpp}`
+  ([#1991](https://github.com/mudler/vllm.cpp/issues/1991)) ship the indexer, the
+  side-cache sizing and the GATHER consumer as host reference math with no
+  production call site: `Qwen4ExpTextModel` does not exist yet, its PLE
+  ([#1987](https://github.com/mudler/vllm.cpp/issues/1987)), hyper-connection
+  stream ([#1988](https://github.com/mudler/vllm.cpp/issues/1988)) and GGUF
+  reader ([#1989](https://github.com/mudler/vllm.cpp/issues/1989)) are sibling
+  waves, and the registry entry plus runner wiring belong to W5. Row
+  `MODEL-MM-QWEN4-EXP` owns that wiring and
+  [#1978](https://github.com/mudler/vllm.cpp/issues/1978) tracks it.
+- **The QSA device arm.** `qwen4_exp_qsa.cpp` is the portable oracle a CUDA
+  kernel is written against, the way `deepseek_v4_dsa.h` is for
+  `src/vt/cuda/cuda_deepseek_v4.cu`. Nothing in W4 runs on a GPU, so the gather's
+  cost advantage over the mask is stated by a `keys_visited` count and NOT by a
+  measurement. The speed axis opens at G4.
+- **`QsaCompressNormRope` assumes a contiguous visible range.** Upstream forms
+  blocks over `local_visible_indices` of a padded batch; a serving engine's
+  ragged batch has no interior masking, so the two coincide and the function
+  asserts `num_keys % compress_ratio == 0` instead of accepting an arbitrary
+  visibility set. A padded-batch caller would need the general form.
+- **The row's lifecycle record is owed the W4 transition, and W5 lands it.** W4
+  ([#1991](https://github.com/mudler/vllm.cpp/issues/1991)) is this row's first
+  product code: `src/vllm/model_executor/models/qwen4_exp_qsa.cpp` joins
+  `add_library(vllm ...)` at its merge commit. `.agents/model-matrix.md` still
+  carries the row at `READY` with the note "SPEC ONLY, NO PRODUCT CODE, NO TOKEN,
+  NO SPEED", which was true at the merge base and is false from W4 onwards. That
+  cell is NOT edited here: W1 through W3 are live on the same file and the
+  operator is sequencing those writes, and a per-wave edit to one shared row is
+  exactly the lock AGENTS.md "Records" forbids. W5, which lands the registry entry
+  and the runner wiring, moves the row to `ACTIVE`, rewrites that note and updates
+  `## Now` in the one change. Until then this entry is where the discrepancy is
+  visible.
+- **Nothing gates the interleaved-mRoPE section layout, in W4 or anywhere yet.**
+  `gen_qwen4_exp_qsa_goldens.py` passes a 2-D `position_ids`, which
+  `Qwen4ExpTextRotaryEmbedding.forward` expands into three IDENTICAL streams, so
+  `apply_interleaved_mrope` runs value-blind and the captured `cos`/`sin` are
+  indistinguishable from plain RoPE. `qwen4_exp_qsa.h` scopes the tables out of W4
+  ("this function does not build them") and W4 is honest about that, but no wave
+  currently owns building them, and a multimodal caller with genuinely different
+  t/h/w streams would be running an untested section layout. The wave that builds
+  the cos/sin tables owes a case with three DISTINCT position streams.
 
 ## Now
 
-`READY`. Spec committed, no implementation.
+`READY` in the matrix, and the state cell is deliberately not moved here — see
+`## Owed`, "the row's lifecycle record is owed the W4 transition". The spec is
+committed; W4 has landed the QSA host reference math
+([#1991](https://github.com/mudler/vllm.cpp/issues/1991)) UNREACHED, and no other
+implementation exists.
 
 Both decisions this spec was blocked on are **settled** (developer, 2026-08-26) and
 recorded in place rather than left as proposals: the transformers lane pin is

CMakeLists.txt

@@ -774,6 +774,9 @@ add_library(vllm STATIC
   src/vllm/model_executor/models/qwen3_5_common.cpp
   src/vllm/model_executor/models/qwen3_5_dense.cpp
   src/vllm/model_executor/models/qwen3_5_moe.cpp
+  # Qwen4-Exp (Qwen3.8-Flash-Next) W4: Qwen Sparse Attention. Host reference
+  # math for the indexer, its side cache and the GATHER consumer (#1991).
+  src/vllm/model_executor/models/qwen4_exp_qsa.cpp
   src/vllm/model_executor/models/qwen3_dense.cpp
   src/vllm/model_executor/models/qwen3_weights.cpp
   src/vllm/model_executor/models/qwen3.cpp