Vulkan: the KHR coopmat kq tile rebuilt (word stage, f16 accumulators, 2x4 tiling), emission-time [unroll_full], the recurrent f16 feed decided per activation buffer

CLAUDE.md

@@ -91,7 +91,7 @@ Task-specific instructions are split into skill files under `skills/`. You MUST
 | `skills/das_formatting.md` | Creating or modifying any `.das` file |
 | `skills/comment_style_hygiene.md` | Writing or reviewing comments, names, or local code shape in ANY language |
 | `skills/writing_tests.md` | Writing or editing any dastest test |
-| `skills/internal/tests_in_repo.md` | Adding/moving tests **in this repo** - AOT registration, the `.das_test` gating filter, deep-engine model tests |
+| `skills/internal/tests_in_repo.md` | Adding/moving tests **in this repo** - AOT registration, the `.das_test` gating filter, deep-engine model tests, the `tests/spirv` emitter suite's local `spirv-val` run |
 | `skills/internal/writing_cpp_tests.md` | Writing or editing C++ tests under `tests-cpp/` |
 | `skills/internal/documentation_rst.md` | Editing RST in `doc/source/`, `//!` doc-comments in `daslib/*.das`, tutorial RST pages |
 | `skills/internal/tutorials.md` | Anything that looks like a tutorial - they live under `/tutorials/<area>/`, NEVER `modules/<X>/tutorial/` |

modules/REVIEW_SHADER_EMITTERS.md

@@ -1,14 +1,13 @@
 # Shader Emitters Code Review Checklist
 
 **Read `REVIEW_COMMON.md` (repo root) first - its contract binds this checklist.** Architecture
-docs: `dasMetal/ARCHITECTURE.md`, `dasSpirv/ARCHITECTURE.md`.
+docs: `dasMetal/ARCHITECTURE.md`, `dasSpirv/ARCHITECTURE.md`, `dasSpirv/ARCHITECTURE_COOPMAT.md`.
 
-**Routed here by another checklist: a diff under either emitter module, or to any kernel body
-or fixture either emitter compiles, applies this list together with its own folder's.**
+**Routed here by another checklist: a diff under `dasMetal/` or `dasSpirv/`, or to any kernel
+body or fixture either emitter compiles, applies this list together with its own folder's.**
 
 **Never put anything that cannot run on the CPU into a kernel body or into a function a kernel
-calls - keep both in ordinary das.** The CPU run of the same body is what the tests compare
-against.
+calls - keep both in ordinary das.** The tests compare the kernel against a CPU run.
 
 **A diff that adds or changes an emitter builtin - a declaration in
 `daslib/shader_lingua_franca.das` or an emitter's builtin table - ships a CPU body that returns
@@ -21,18 +20,17 @@ reports a compile error that names the construct.**
 constant.** A shape constant is any value that fixes the kernel's tiling: a tile row count, a
 tile column count, a cooperating-simdgroup count, a staged chunk depth.
 
-**Never pass a matmul reduction width known only at run time into a kernel that loads its
-operands with the emitter's tensor-load ops (`coopmatLoadTensor*`, `coopmatLoadTensorDecode`)
-any way but through the emitter's runtime-extent descriptor - `dynamic_extent` on Metal, and on
-SPIR-V a `tensorLayout2D` or `tensorLayout2DPad` whose dimension `tensorLayoutSetDimension`
-sets.** The reduction width is the K dimension - the length of the loop the kernel accumulates
-over; it does not fix tiling, so it is not a shape constant. A loop that stages its own tiles
-and loads fragments with `coopmatLoad` takes K as a plain uniform.
+**A kernel that loads its operands with the emitter's tensor-load ops (`coopmatLoadTensor*`,
+`coopmatLoadTensorDecode`) receives a run-time-only matmul reduction width through the
+emitter's runtime-extent descriptor and no other way - `dynamic_extent` on Metal, a
+`tensorLayout2D` or `tensorLayout2DPad` whose dimension `tensorLayoutSetDimension` sets on
+SPIR-V.** The reduction width is the K dimension - the length of the loop the kernel
+accumulates over; it does not fix tiling, so it is not a shape constant.
 
 **A diff that makes a kernel need a shape constant known only at run time ships a
-specialization path, or records in the emitter's architecture doc - `dasMetal/ARCHITECTURE.md`
-for a Metal kernel, `dasSpirv/ARCHITECTURE.md` for a SPIR-V kernel - that the kernel cannot
-have one.** A specialization path is one compiled variant per constant shape.
+specialization path, or records in an `ARCHITECTURE*.md` at the root of the module the kernel
+ships in that the kernel cannot have one.** A specialization path is one compiled variant per
+constant shape.
 
 **Never check a claim about emitted shape against the das source - check it in the emitted
 words or text.** Emitted shape is the structure of the emitted kernel - its signature, its
@@ -41,9 +39,9 @@ threadgroup sizes).
 
 **A diff that adds a kernel-model capability to one emitter adds it to the other, or records
 the asymmetry in the shared ledger (`dasMetal/ARCHITECTURE.md`).** A kernel-model capability
-is anything a kernel author can write differently because of it - an annotation, a call form,
-a declaration the emitter now accepts or refuses; a change to lowering alone is the folder's
-own checklist's.
+is present on an emitter when a kernel source that uses it compiles there; a diff that leaves
+every kernel source compiling exactly as it did before changed lowering alone, and answers to
+that emitter folder's own checklist.
 
 **A diff that puts a `daslib/shader_lingua_franca` declaration into a kernel body or fixture an
 emitter compiles, where that emitter does not handle it, ships, in the same change, either
@@ -52,7 +50,7 @@ declaration by name.** A declaration in that module is available to both emitter
 
 **A `?:`, `&&`, or `||` in a `[spirv_kernel]` or `[compute_shader]` body, or in any `def` that
 body calls, whose skippable operand subscripts a global-rooted array - a module global, a
-`@workgroup` array, or a `self.<member>` resource - is written as the language reads it: never
+`@workgroup` array, or a `self.<member>` resource - is left in its short-circuit form: never
 rewritten around the emitter with an if/else, a clamp or an unconditional read.** The emitter
 lowers such an operand as a branch (`dasSpirv/ARCHITECTURE.md`, "Operand laziness follows the
-language"); a branchless form where it matters waits for `select` (`plans/shader_emitter_followups.md`).
+language").

modules/dasLLAMA/ARCHITECTURE.md

@@ -48,12 +48,14 @@ re-transcoding `$LCPP/src/unicode-data.cpp`).
 - `ARCHITECTURE_GPU_PREFILL.md` - sec.2.2c-2.2i, 2.2u-2.2v, 2.2aa: the Metal prefill driver's
   GEMM form ladder, dev-W knee map, attention slab, MoE bucket rail, chunked submission, the
   f16 twin dual-store, the last-layer FFN tail, and the dense-KQ tensor mul_mm scaffold.
-- `ARCHITECTURE_GPU_VULKAN.md` - sec.2.2j, 2.2p, 2.2ab: the Vulkan resident driver's prefill
-  chain and byte stores - the prefill window chain, the Q8 requant byte store, and the decode
-  GEMV family's grid codebook buffer.
-- `ARCHITECTURE_GPU_VULKAN_GEMM.md` - sec.2.2k-2.2m, 2.2q: the cooperative-matrix tiles the
-  Vulkan tier's GEMMs run on - the cm2 decode lanes, the tile pick and the coopmat mode ladder,
-  the class-pipeline build seat, and the MoE expert chain on those tiles.
+- `ARCHITECTURE_GPU_VULKAN.md` - sec.2.2j, 2.2p, 2.2ab, 2.2ac, 2.2ad: the Vulkan resident
+  driver's prefill chain and byte stores - the prefill window chain, the Q8 requant byte store,
+  the decode GEMV family's grid codebook buffer, the tile probe's shared descriptor set layout,
+  and the recurrent block of the prefill window.
+- `ARCHITECTURE_GPU_VULKAN_GEMM.md` - sec.2.2k-2.2m, 2.2q, 2.2ae: the cooperative-matrix tiles
+  the Vulkan tier's GEMMs run on - the cm2 decode lanes, the tile pick and the coopmat mode
+  ladder, the class-pipeline build seat, the MoE expert chain on those tiles, and the KHR arm's
+  hand-staged kq tile.
 - `ARCHITECTURE_GPU_VULKAN_RESIDENCY.md` - sec.2.2n-2.2o: what a model has to fit on the card
   before the driver runs - the residency plan, and the GPU-slot marks swap that lets one slot
   serve many models.
@@ -65,16 +67,18 @@ re-transcoding `$LCPP/src/unicode-data.cpp`).
 - `ARCHITECTURE_GPU_MTP.md` - sec.2.28-2.39: the Metal speculative round over the batch driver's
   same-slab verify, the box knob that sets the depth a round drafts, and the kernel
   argument-alignment contract enforced at every dispatch.
-- `ARCHITECTURE_RUNTIME.md` - sec.2.2, 2.3, 2.3a, 2.4, 2.6-2.9, 2.11, 2.12, 2.18-2.19: kernel
-  shape, caches, lint policy, knobs, coverage, the GPU ramp, the hybrid worker pool, and the
-  MoE region split.
+- `ARCHITECTURE_RUNTIME.md` - sec.2.2, 2.3, 2.3a, 2.4, 2.6-2.9, 2.11, 2.12, 2.18-2.19, 2.44:
+  kernel shape, caches, lint policy, knobs, coverage, the GPU ramp, the hybrid worker pool, the
+  MoE region split, and the job queue the engine dispatches on.
 - `ARCHITECTURE_MEDIA.md` - sec.2.13-2.16: the padded tower GEMM widths, the family GPU hooks,
   the tower weight lane, and the plain-Model ASR decoders.
-- `ARCHITECTURE_MEASUREMENT.md` - sec.2.5, 2.10, 2.20, 2.21, 2.26-2.28, 2.40-2.41, 2.42a: the
-  benchmark rig, the tune gate, the sanctioned instrumentation rails, kernel-race fidelity, the
-  gemv's own tune seat, the CPU kernel bench's fixture conditions, the speculative round's ruler
-  record, the `[tuned]` perm precedence, the mint wall in the sidecar's provenance, and the fat
-  exe's first-start race.
+- `ARCHITECTURE_MEASUREMENT.md` - sec.2.5, 2.10, 2.20, 2.40-2.41, 2.42a, 2.45: the benchmark
+  rig, the tune gate, the sanctioned instrumentation rails, the ASR board's GPU row pairs, the
+  `[tuned]` perm precedence, the mint wall in the sidecar's provenance, the fat exe's
+  first-start race, and the speculative round's ruler record.
+- `ARCHITECTURE_MEASUREMENT_KERNEL_RACE.md` - sec.2.21, 2.26-2.27: the instruments that time a
+  kernel away from the served graph - kernel-race fidelity, the gemv's own tune seat, and the
+  CPU kernel bench's fixture conditions.
 - `ARCHITECTURE_CPU_KERNELS.md` - sec.2.22-2.24, 2.42: the sub-block-packed k3/k6 planes, the grid
   formats' panel and row-group decodes, the VBMI symbol lattice, and the tier that selects on the
   target rather than the host.

modules/dasLLAMA/ARCHITECTURE_CPU_KERNELS.md

@@ -42,7 +42,7 @@ codes for the rest. Per row group and weight octet a constant two-source shuffle
 code bytes in its qword, `VPMULTISHIFTQB` spreads the symbols into bytes, one `vpshufb` maps them to
 magnitudes, and the signs ride the activation copy as a mask `(x ^ m) - m`. The lattice row shares
 its tile body and planes with the 512/mr16 row, so only the gemv differs - what the gemv's own seat
-(`ARCHITECTURE_MEASUREMENT.md` sec.2.26) races.
+(`ARCHITECTURE_MEASUREMENT_KERNEL_RACE.md` sec.2.26) races.
 
 ### 2.42 A CPU tier selects on the TARGET, not the host {#cpu-tier-target-select}
 

modules/dasLLAMA/ARCHITECTURE_GPU.md

@@ -119,7 +119,7 @@ that a question answered for one backend has an obvious address in the other. Th
 
 **PSO lifecycle - the family shares ONE device and queue** (`metal_common_init`; the second-device
 question was surveyed and closed against; the tune-time race arms' transient queue is
-`ARCHITECTURE_MEASUREMENT.md` sec.2.21's). The decode PSO set lives as `g_pso_*` in
+`ARCHITECTURE_MEASUREMENT_KERNEL_RACE.md` sec.2.21's). The decode PSO set lives as `g_pso_*` in
 `dasllama_metal_common`, is compiled by `metal_decode_init` in `dasllama_metal_kernels` and
 released by `metal_kernels_release` there - the kernels module owns its set's lifecycle even
 though the vars live with the device state. Prefill's `g_pf_pso_*` set is prefill-private end to
@@ -260,10 +260,10 @@ consecutive staging runs, relaxed_precision always - are `REVIEW_GPU.md` rules a
 `modules/dasMetal/REVIEW.das` descriptor gate; this section keeps only the refuted shapes
 and why they lose.
 
-Sections 2.2j, 2.2p and 2.2ab, the Vulkan resident driver's prefill chain and byte stores, are
-`ARCHITECTURE_GPU_VULKAN.md`; its 2.2k-2.2m and 2.2q - the cooperative-matrix GEMM tiles - are
-`ARCHITECTURE_GPU_VULKAN_GEMM.md`; its 2.2n-2.2o - the residency plan and the marks swap - are
-`ARCHITECTURE_GPU_VULKAN_RESIDENCY.md`.
+Sections 2.2j, 2.2p, 2.2ab, 2.2ac and 2.2ad, the Vulkan resident driver's prefill chain and
+byte stores, are `ARCHITECTURE_GPU_VULKAN.md`; its 2.2k-2.2m, 2.2q and 2.2ae - the cooperative-matrix
+GEMM tiles - are `ARCHITECTURE_GPU_VULKAN_GEMM.md`; its 2.2n-2.2o - the residency plan and the
+marks swap - are `ARCHITECTURE_GPU_VULKAN_RESIDENCY.md`.
 
 ### 2.2w The tower attention routes {#tower-attn-routes}
 

modules/dasLLAMA/ARCHITECTURE_GPU_QUANT_PLANES.md

@@ -41,4 +41,4 @@ twin exactly when that PSO is non-null, so a box with no crown never compiles it
 
 The `kq_gemv_iq3s_f4` and `kq_gemv_iq3xxs_f4` crowns are raced (`race_gemv_f4_twin`).
 `kq_gemv_iq2xxs_f4` cannot be settled by an isolated race at all and is minted from a serving
-A/B instead - `ARCHITECTURE_MEASUREMENT.md` sec.2.21.
+A/B instead - `ARCHITECTURE_MEASUREMENT_KERNEL_RACE.md` sec.2.21.