Skip to content

Commit 1a614a9

Browse files
committed
feat(fold): Tier D3 — OLMo-2 full-width qk-norm+rope onto shared FusedChain catalog
Executes Tier D3 of the cross-arch merged-GEMM/glue fold plan (.agents/specs/arch-fusion-fold-plan-2026-07-30.md). OLMo-2's FULL-WIDTH q/k RMSNorm (_apply_qk_norm, olmo2.py:113-117,160-172 — RMSNorm over the WHOLE q-dim/k-dim, all heads folded into ONE variance statistic, distinct from the per-head head_dim norm) + standard NeoX RoPE preamble now folds onto the shared vt::FusedChain glue catalog instead of a bespoke inline sequence. The shape-param generalization: FStep gains a `norm_full_width` structural flag (include/vt/fused_recipe.h, additive, default false = per-head Dh -> every existing recipe byte-identical), and a NEW sibling recipe kAttnQkNormRopeFullWidth (include/vt/recipes.h) sets it on its two RMSNorm steps — the full-width variant of Qwen3-dense's kAttnQkNormRope, SAME operand table / step wiring, only the bound norm SHAPE differs (operand 0/2 = [T,qdim]/[T,kdim] with a full-width [qdim]/[kdim] weight, vs the per-head [.,Dh]/[Dh]). olmo2.cpp Olmo2AttnBlock routes through vt::FusedChain(kAttnQkNormRopeFullWidth) when RoPE runs from a cache (YaRN full-attn / default-ON bf16 cos-sin cache); the in-place RopeNeox fallback (VT_QWEN3_ROPE_CACHE=0) keeps the standalone sequence (mirrors the qwen3.cpp guard — the recipe's kRope is RopeFromCache). Realization is composite-only (fast_op=kNoFastOp): the per-head kAttnQkNormRope bespoke fast kernel (Metal) assumes a Dh reduction, so the full-width variant does not claim it; a full-width fast kernel is a clean follow-up. Additive/inert: kAttnQkNormRope (per-head, fast_op intact) is UNTOUCHED -> qwen3/27B byte-identical. Bit-exact by construction: because the Tier-0 composite's RmsNorm reduces over the bound row's last dim (device-agnostic walker), the composite realizes the full-width norm BYTE-EXACTLY with NO new primitive — it dispatches the EXACT standalone RmsNorm(q,[qdim]) + RmsNorm(k,[kdim]) + RopeFromCache sequence OLMo-2 hand-called before the fold. GATED (CPU RED-first, this box; VLLM_CPP_CUDA=OFF): tests/vt/test_ops_fused_chain .cpp new case kAttnQkNormRopeFullWidth composite == full-width RmsNorm(q)+RmsNorm (k)+RopeFromCache byte-compares (raw f32 memcmp) across MHA+GQA+head_dim 64/128, RED-first (full-width proven DISTINCT from a per-head Dh norm). Full test_ops_fused_chain suite 10/10 * 379 assertions GREEN under the new FStep ABI (per-head kAttnQkNormRope regression + all 10 recipes intact -> shape-param is additive). olmo2.cpp + the 26 CPU vt TUs rebuild -Werror clean. OWED (DGX GB10 sm_121a, RelWithDebInfo + cutlass-4.5.0 + triton): the OLMo-2 SACRED token-exact gate test_olmo2_paged_engine (olmo2_greedy_1b 16/16) + shared- catalog canaries test_qwen3_paged_engine 0.6B/4B + test_qwen27_paged_engine 235/235. NOT run this pass — executed on a CPU-only dev box (no GPU/cutlass, DGX unreachable). Bit-exact by construction on CUDA (composite-only realization = the identical device-agnostic walker the CPU byte-check pins; OLMo-2's committed default rope path is cache-based -> the fold fires, composite == the pre-fold standalone sequence), but a pass != the code ran, so the empirical DGX SACRED run is owed before D3 is fully closed. Records (same commit): docs/STATUS.md OLMo-2 row + docs/BENCHMARKS.md Tier-D3 section + arch-fusion-fold-plan-2026-07-30.md D3 marked DONE (code + CPU bit-exact) with the DGX SACRED gate flagged OWED. All CPU record checkers rc=0 (fusion-consistency, agent-record, readme-structure, model-checklist, env-doc, doc-checkpoint). FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-4-8 [ClaudeCode]
1 parent d21c442 commit 1a614a9

7 files changed

Lines changed: 220 additions & 28 deletions

File tree

.agents/specs/arch-fusion-fold-plan-2026-07-30.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,10 @@ Extend the non-Marlin `MoeGroupedGemmNvfp4` path to the already-tuned fused-w13
107107
**D2. GDN in_proj merge (qkv+z along N)** *(shared-op: merged-QKV, GDN instance)*
108108
Near-tie, distributionally sensitive; GDN layers are the majority of the 35B hybrid so it compounds — but verify token-exact gate. `qwen3_5.cpp:2952-2958`.
109109

110-
**D3. OLMo-2 full-width qk-norm+rope** — needs a **shape-param generalization** of `kAttnQkNormRope` (norm over qdim/kdim, not Dh). Bit-exact once the full-width dim is wired. `olmo2.cpp:110-115,131-139`.
110+
**D3. OLMo-2 full-width qk-norm+rope** — ✅ **DONE (code + CPU RED-first bit-exact gate; DGX SACRED OWED) 2026-07-31** (branch `fold/d3-olmo2-fullwidth-qknorm` off `d21c442d`, NOT pushed).
111+
OLMo-2's FULL-WIDTH q/k RMSNorm (`_apply_qk_norm`, olmo2.py:113-117,160-172: RMSNorm over the WHOLE q-dim/k-dim, all heads folded into one variance statistic) + standard NeoX RoPE preamble now folds onto the SHARED FusedChain catalog. **The shape-param generalization:** `FStep` gains a `norm_full_width` structural flag (`fused_recipe.h`, additive, default false = per-head Dh → every existing recipe byte-identical), and a new sibling recipe `kAttnQkNormRopeFullWidth` (`recipes.h`) sets it on its two RMSNorm steps — the full-width variant of Qwen3-dense's `kAttnQkNormRope`, same operand table/step wiring, only the bound norm SHAPE differs (operand 0/2 = `[T,qdim]`/`[T,kdim]` with a full-width `[qdim]`/`[kdim]` weight, vs the per-head `[.,Dh]`/`[Dh]`). Because the Tier-0 composite's `RmsNorm` reduces over the bound row's last dim, the composite realizes the full-width norm BYTE-EXACTLY with NO new primitive — it dispatches the EXACT standalone `RmsNorm(q,[qdim]) + RmsNorm(k,[kdim]) + RopeFromCache` sequence OLMo-2 hand-called before this fold. `olmo2.cpp` `Olmo2AttnBlock` (was `:110-115,131-139`) routes through `vt::FusedChain(kAttnQkNormRopeFullWidth, ...)` when RoPE runs from a cache (YaRN full-attn / default-ON bf16 cos-sin cache); the in-place `RopeNeox` fallback (`VT_QWEN3_ROPE_CACHE=0`) keeps the standalone sequence (mirrors the qwen3.cpp guard — the recipe's kRope is RopeFromCache, so routing RopeNeox through it would swap RoPE impls). Realization: **composite-only** (`fast_op=kNoFastOp`) — the per-head `kAttnQkNormRope` bespoke fast kernel (Metal) assumes a Dh reduction, so the full-width variant does not claim it; a full-width fast kernel is a clean follow-up perf step (§S4). The generalization is ADDITIVE: `kAttnQkNormRope` (per-head, fast_op intact) is untouched → qwen3/27B byte-identical.
112+
- **GATED (CPU RED-first, this box):** `tests/vt/test_ops_fused_chain.cpp` new case `kAttnQkNormRopeFullWidth composite == full-width RmsNorm(q)+RmsNorm(k)+RopeFromCache` — byte-exact (raw f32 memcmp) across MHA + GQA + head_dim 64/128 shapes, RED-first discrimination (the full-width result is proven DISTINCT from a per-head Dh norm, so a wrong-domain realization fails). The FULL `test_ops_fused_chain` suite **10/10 · 379 assertions** GREEN under the new `FStep` ABI (the per-head `kAttnQkNormRope` regression + all 10 recipes intact → the shape-param is additive). `olmo2.cpp` + the vt runtime rebuild `-Werror` clean.
113+
- **OWED (DGX GB10 sm_121a, RelWithDebInfo + cutlass-4.5.0 + triton):** the OLMo-2 SACRED token-exact gate `test_olmo2_paged_engine` (`olmo2_greedy_1b`, 16/16) + shared-catalog canaries `test_qwen3_paged_engine` 0.6B/4B + `test_qwen27_paged_engine` 235/235. NOT run in this pass — executed on a CPU-only box (`VLLM_CPP_CUDA=OFF`, no GPU/cutlass, DGX unreachable). Bit-exact BY CONSTRUCTION on CUDA (fast_op=kNoFastOp → the identical device-agnostic composite that the CPU byte-check pins; OLMo-2's committed default rope path is cache-based → the fold fires, composite == the pre-fold standalone sequence), but the empirical DGX SACRED run is still owed before D3 is considered fully gated (a pass ≠ the code ran).
111114

112115
### TIER E — MM-tower epilogues needing NEW recipes (towers furthest from parity; lowest ROI/site)
113116

@@ -145,7 +148,7 @@ Every arch's MLP / QKV / MoE / attn-glue resolves through **one descriptor famil
145148
- nvfp4 fused-w13 (cutlass + Marlin unified) *(C3)* ← 35B routed + shared
146149
- Invariant across all arms: route-weight stays in `moe_combine`.
147150

148-
**S4. FusedChain glue catalog**`kAttnQkNormRope` / `kAttnQkNormRopeGate` / `kFusedAddRmsNorm(Std)` *(exist)*; **NEW:** `kFusedNormRope` (MLA, A5), full-width qk-norm variant (D3), `kFusedAddLayerNorm` (whisper), post-norm `kRmsNorm+Add` sandwich (gemma4_vision), bias+gelu epilogue + `kGluSigmoid` (towers).
151+
**S4. FusedChain glue catalog**`kAttnQkNormRope` / `kAttnQkNormRopeGate` / `kFusedAddRmsNorm(Std)` *(exist)* + `kFusedNormRope` (MLA, A5, ✅) + `kAttnQkNormRopeFullWidth` (full-width qk-norm variant, D3, ✅ composite-only); **NEW remaining:** `kFusedAddLayerNorm` (whisper), post-norm `kRmsNorm+Add` sandwich (gemma4_vision), bias+gelu epilogue + `kGluSigmoid` (towers).
149152

150153
At the end state, adding a new dense/MoE arch is *born fused*: pick the quant arm, bind the FusedChain recipes, no per-model GEMM+act copy. kimi_k3 is the proof — it inherits A2/A4/A5 with zero Kimi-specific work.
151154

docs/BENCHMARKS.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,18 @@ See `.agents/specs/laguna-s21-w4-2026-07-31.md`.
106106

107107
## Laguna-S-2.1 (`LagunaForCausalLM`) W3 real forward + 3 new ops (2026-07-31, `CLAIM-LAGUNA-W3`) - no throughput owed yet (gate PENDING W4)
108108

109+
## OLMo-2 full-width qk-norm+rope fold — Tier-D3 (2026-07-31, `CLAIM-D3-OLMO2-FULLWIDTH-QKNORM`) - CONSISTENCY/SHARED-CATALOG fold, bit-exact (CPU RED-first gated; DGX SACRED OWED)
110+
111+
Tier-D3 of the cross-arch merged-GEMM/glue fold plan (`.agents/specs/arch-fusion-fold-plan-2026-07-30.md`). OLMo-2's FULL-WIDTH q/k RMSNorm (`_apply_qk_norm`, olmo2.py:113-117,160-172 — RMSNorm over the WHOLE q-dim/k-dim, all heads folded into ONE variance statistic, distinct from the per-head head_dim norm) + standard NeoX RoPE preamble folds onto the SHARED FusedChain glue catalog. **The shape-param generalization:** `FStep` gains a `norm_full_width` structural flag (`include/vt/fused_recipe.h`, additive, default false = per-head Dh → EVERY existing recipe byte-identical), and a new sibling recipe `kAttnQkNormRopeFullWidth` (`include/vt/recipes.h`) sets it on its two RMSNorm steps — the full-width variant of Qwen3-dense's `kAttnQkNormRope`, SAME operand table / step wiring, only the bound norm SHAPE differs (operand 0/2 = `[T,qdim]`/`[T,kdim]` with a full-width `[qdim]`/`[kdim]` weight, vs the per-head `[.,Dh]`/`[Dh]`). `olmo2.cpp` `Olmo2AttnBlock` routes through `vt::FusedChain(kAttnQkNormRopeFullWidth, ...)` when RoPE runs from a cache (YaRN full-attn layers / the default-ON bf16 cos-sin cache); the in-place `RopeNeox` fallback (`VT_QWEN3_ROPE_CACHE=0`) keeps the standalone sequence (mirrors the qwen3.cpp guard — the recipe's third step is RopeFromCache, so routing RopeNeox through it would swap RoPE impls). Realization: **composite-only** (`fast_op=kNoFastOp`) — the per-head `kAttnQkNormRope` bespoke fast kernel (Metal-registered) assumes a Dh reduction, so the full-width variant does not claim it; a full-width fast kernel is a clean follow-up perf step. **Additive/inert:** `kAttnQkNormRope` (per-head, fast_op intact) is UNTOUCHED → qwen3/27B byte-identical; the `norm_full_width` field defaults false so every prior recipe is unchanged.
112+
113+
**Bit-exact by construction, PROVEN on CPU.** Because the Tier-0 composite's `RmsNorm` reduces over the bound row's last dim (device-agnostic — the SAME walker on CPU and CUDA), the composite realizes the full-width norm BYTE-EXACTLY with NO new primitive: it dispatches the EXACT standalone `RmsNorm(q,[qdim]) + RmsNorm(k,[kdim]) + RopeFromCache` sequence OLMo-2 hand-called before the fold. `tests/vt/test_ops_fused_chain.cpp` new case `kAttnQkNormRopeFullWidth composite == full-width RmsNorm(q)+RmsNorm(k)+RopeFromCache` byte-compares (raw f32 memcmp) the composite against the standalone full-width sequence across MHA + GQA + head_dim 64/128 shapes, RED-first (the full-width result is proven DISTINCT from a per-head Dh norm, so a wrong-domain realization fails the byte-check). The FULL `test_ops_fused_chain` suite is **10/10 · 379 assertions** GREEN under the new `FStep` ABI (the per-head `kAttnQkNormRope` regression + all 10 catalog recipes intact ⇒ the shape-param is additive). `olmo2.cpp` + the CPU vt runtime rebuild `-Werror` clean.
114+
115+
Gate status:
116+
- **CPU (this box, mudler-ubuntu-box, `VLLM_CPP_CUDA=OFF`):** `test_ops_fused_chain` **10/10 · 379** (D3 full-width case + per-head regression + all recipes), RED-first bit-exact. Build `-Werror` clean (olmo2.cpp fold + 26 vt CPU TUs rebuilt with the grown `FStep`).
117+
- **DGX (GB10 sm_121a, RelWithDebInfo + cutlass-4.5.0 + triton) — OWED, NOT RUN this pass:** `test_olmo2_paged_engine` SACRED (`olmo2_greedy_1b`, 16/16) + shared-catalog canaries `test_qwen3_paged_engine` 0.6B/4B + `test_qwen27_paged_engine` 235/235. This lane executed on a CPU-only dev box (no GPU, no cutlass, DGX unreachable), so the empirical GPU SACRED run could not be performed. The fold is bit-exact BY CONSTRUCTION on CUDA (composite-only realization = the identical device-agnostic walker the CPU byte-check pins; OLMo-2's committed default rope path is cache-based ⇒ the fold fires and the composite == the pre-fold standalone sequence), but per project discipline a pass ≠ the code ran — the DGX SACRED gate is owed before D3 is fully closed.
118+
119+
Disposition: a shared-catalog consistency fold (OLMo-2 now resolves its qk-norm-rope preamble through the one FusedChain recipe family instead of a bespoke inline sequence); no isolated tok/s A/B (identical numerics, composite realization). The binding proof is the CPU RED-first byte-exact unit + (owed) the OLMo-2 SACRED gate holding on the DGX.
120+
109121
## bf16 merged-QKV default-ON — Tier-D1 (dense/coder/dflash/Gemma×4, 2026-07-31, `CLAIM-D1-BF16-MERGED-QKV`) - CONSISTENCY/LAUNCH-COUNT fold, CHARACTERIZED near-tie (0.6B golden regenerated), correctness-gated (no new throughput ratio owed)
110122

111123
Tier-D1 of the cross-arch merged-GEMM fold plan (`.agents/specs/arch-fusion-fold-plan-2026-07-30.md`). The q/k/v projections that SHARE the layer input collapse to ONE bf16 `vt::MatmulBT` over the merged `[qdim+2kdim,H]` owner + a contiguous `vt::QkvSplit` (the OLMo-2/Granite/StableLM exemplar), replacing three per-shard GEMMs (folds the two tiny GQA k/v GEMMs into one wide tensor-core GEMM, −2 launches/layer). The shared gate `Qwen3QkvMergeEnabled()` (alias `MergedQkvEnabled()`, env `VT_QWEN3_QKV_MERGE`) FLIPPED default-ON across all six bf16 consumers: qwen3_dense (`dense_attn_block.h`), qwen3_coder (inherits the shared dense `AttnBlock` via `qwen3_moe.cpp`), qwen3_dflash (`qwen3_dflash.cpp`), and Gemma-1/2/3/4 (`gemma*.cpp`). `=0` restores the byte-identical 3-shard path in the same binary. **No loader concat needed** — every consumer already packs the merged `qkv_proj` owner. RoPE handling UNCHANGED (no RopeNeox→RopeFromCache swap — the second-1-ULP-flip hazard from the fold plan §gaps.2 avoided). 27B/35B are UNTOUCHED (resident nvfp4/fp8 QKV, not this bf16 path).

docs/STATUS.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ token-for-token correctness against the pinned oracle.
4848
| Gemma-3 dense (GeGLU, dual rope, sandwich norms) | Correctness-complete, speed-pending | STRICT token-exact 48/48 greedy (gemma-3-1b-it); first Gemma-family model; GeGLU (gelu_pytorch_tanh) + dual per-layer RoPE theta + Gemma-RMSNorm sandwich norms + sqrt(hidden) embed-scale + query_pre_attn_scalar scaling |
4949
| Gemma-2 dense (attn + final logit soft-cap) | Correctness-complete, speed-pending | Near-tie-band 48/48 (gemma-2-2b-it): 44/48 strict on vLLM's greedy + 4/48 at 0.0-nat ties in vLLM's own logits; proves the attention + final logit soft-cap primitives (attn_logit_softcapping 50 + final 30); the inverse of Gemma-3 (both soft-caps, no QK-norm) |
5050
| Gemma-1 dense (the original Gemma) | Correctness-complete, speed-pending | STRICT token-exact 48/48 greedy (gemma-2b); two fused norms/layer, head_dim scale, GeGLU + sqrt(hidden) embed-scale, tied lm_head; no soft-cap/QK-norm/sliding. **D1 (2026-07-31): the whole Gemma family (1/2/3/4) folded to the default-ON bf16 merged-QKV descriptor (`MergedQkvEnabled`); re-gated Gemma-2 SACRED 48/48 (global+sliding) + Gemma-4 STRICT 32/32 — its existing gate held** |
51-
| OLMo-2 dense (pure post-norm, full-width QK-norm) | Correctness-complete, speed-pending | Token-exact 16/16 (OLMo-2-0425-1B); first OLMo-family model; ZERO new compute kernel (pure post-norm `norm_after` + full-width QK-norm reuse existing ops); real ByteLevel-tokenizer gate (no BOS) |
51+
| OLMo-2 dense (pure post-norm, full-width QK-norm) | Correctness-complete, speed-pending | Token-exact 16/16 (OLMo-2-0425-1B); first OLMo-family model; ZERO new compute kernel (pure post-norm `norm_after` + full-width QK-norm reuse existing ops); real ByteLevel-tokenizer gate (no BOS). **D3 (2026-07-31, `CLAIM-D3-OLMO2-FULLWIDTH-QKNORM`): the full-width q/k RMSNorm + RoPE preamble folds onto the SHARED FusedChain catalog** — new sibling recipe `kAttnQkNormRopeFullWidth` (the `norm_full_width` shape-param variant of Qwen3-dense's `kAttnQkNormRope`; `FStep.norm_full_width` additive, default false ⇒ every existing recipe byte-identical). Composite-only realization (`fast_op=kNoFastOp`) is byte-exact to the pre-fold standalone `RmsNorm(qdim)+RmsNorm(kdim)+RopeFromCache` sequence — CPU RED-first `test_ops_fused_chain` 10/10·379 GREEN (byte-exact, full-width proven distinct from per-head). **DGX SACRED (`olmo2_greedy_1b` 16/16) + qwen3/27B canaries OWED** — this lane ran on a CPU-only box (no GPU/cutlass); bit-exact by construction on CUDA (composite = the identical device-agnostic walker), empirical GPU run still owed. See docs/BENCHMARKS.md |
5252
| Phi-3 / Phi-4 dense (Llama subclass, LongRoPE) | Correctness-complete, speed-pending | Token-exact (near-tie-robust) 16/16 (Phi-4-mini-instruct: 7 strict + 9 near-tie, 0 divergent) by the ratified root-divergence gate; bigger-dense STRICT anchor phi-4 (14B) 14/16 fully token-exact + 2 exact-tie (0.0 nats); pre-fused qkv/gate_up loader + LongRoPE cache bit-identical to vLLM's |
5353
| Granite-3 dense (Llama + 4 scalar multipliers) | Correctness-complete, speed-pending | Token-exact 16/16 (granite-3.3-2b-instruct); first IBM Granite model; ZERO new compute kernel; embedding/residual/attention/logits multipliers (attention scale 1/64, not 1/sqrt(head_dim)) threaded over the shared dense path |
5454
| StableLM dense (LayerNorm, partial rope, qkv bias) | Correctness-complete, speed-pending | Token-exact 16/16 (stablelm-2-1_6b): 14/16 strict on vLLM's greedy + 2/16 at bf16 near-ties (max gap 0.438 nats), 0 forward-divergent; first Stability AI model; ZERO new compute kernel (nn.LayerNorm with weight+bias + partial NeoX rope 16/64 + merged qkv bias, all reuse existing ops) |

include/vt/fused_recipe.h

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -115,8 +115,9 @@ struct FOperandSlot {
115115
// One recipe step: an opcode + the operand INDICES it reads/writes + the small
116116
// structural constants the opcode needs. `out` is the primary output operand
117117
// index; `out2` a secondary output (fp4 scale stream) or kNoOperand; `in[nin]`
118-
// the input operand indices. `gemma`/`reduce`/`sigmoid_gate` are structural;
119-
// runtime scalars (eps, quant scale, rope args) travel in the op call.
118+
// the input operand indices. `gemma`/`reduce`/`sigmoid_gate`/`norm_full_width`
119+
// are structural; runtime scalars (eps, quant scale, rope args) travel in the op
120+
// call.
120121
struct FStep {
121122
FOp op = FOp::kAdd;
122123
uint8_t out = 0; // primary output operand index
@@ -126,6 +127,18 @@ struct FStep {
126127
FReduce reduce = FReduce::kNone;
127128
bool gemma = false; // kRmsNorm/kAttn: weight as (1 + w), GemmaRMSNorm style
128129
bool sigmoid_gate = false; // kRmsNormGated: sigmoid gate activation (else silu)
130+
// kRmsNorm SHAPE param (the qk-norm domain, D3). false (default): the norm
131+
// reduces over the PER-HEAD head_dim Dh — the bound row operand is [.,Dh]
132+
// (Qwen3 dense / 27B). true: the norm reduces over the WHOLE q-dim / k-dim —
133+
// the bound row operand is [T,qdim]/[T,kdim] with a full-width weight
134+
// [qdim]/[kdim] (OLMo-2's `_apply_qk_norm`, all heads folded into one variance
135+
// statistic). The Tier-0 composite is already shape-driven (RmsNorm reduces
136+
// over the bound row's last dim), so this flag changes NO composite math; it
137+
// DECLARES the intended norm domain so a bespoke fast realization can branch,
138+
// and lets the two otherwise-identical qk-norm-rope recipes (per-head vs
139+
// full-width) be told apart. Additive: default false keeps every existing
140+
// recipe byte-identical.
141+
bool norm_full_width = false;
129142
};
130143

131144
// The declaration: a fixed-size step list + an indexed operand table + live

include/vt/recipes.h

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -354,4 +354,58 @@ constexpr FusedRecipe kAttnQkNormRope = {
354354
/*fast_op=*/static_cast<int>(OpId::kAttnQkNormRope),
355355
};
356356

357+
// kAttnQkNormRopeFullWidth — the FULL-WIDTH qk-norm variant of kAttnQkNormRope
358+
// (D3, arch-fusion-fold-plan-2026-07-30 Tier-D3). Structurally identical to
359+
// kAttnQkNormRope EXCEPT the two RMSNorm steps carry the `norm_full_width` shape
360+
// param: the q/k norm reduces over the WHOLE q-dim / k-dim (all heads folded into
361+
// one variance statistic), not the per-head head_dim. This transcribes OLMo-2's
362+
// `_apply_qk_norm` (vllm/model_executor/models/olmo2.py:113-117,160-172 @
363+
// e24d1b24): `q = q_norm(q.view(*, q_size)); k = k_norm(k.view(*, kv_size))`
364+
// applied to the FLAT [T,q_size]/[T,kv_size] views BEFORE the head reshape, then
365+
// standard NeoX RoPE on the per-head views.
366+
//
367+
// The operand table + step wiring are the SAME as kAttnQkNormRope — only the
368+
// bound SHAPES differ at the call: operand 0 (q) is [T,qdim] with q_norm[qdim],
369+
// operand 2 (k) is [T,kdim] with k_norm[kdim], and operands 4/5 (q3/k3) are the
370+
// per-head [T,Hq,Dh]/[T,Hkv,Dh] rope views aliasing the same buffers. Because the
371+
// Tier-0 composite's RmsNorm reduces over the bound row's last dim, the composite
372+
// realizes the full-width norm BYTE-EXACTLY with NO new primitive (it dispatches
373+
// the exact standalone RmsNorm(q,[qdim])+RmsNorm(k,[kdim])+RopeFromCache sequence
374+
// OLMo-2 hand-calls today).
375+
//
376+
// Realization: composite-only (fast_op = kNoFastOp). The existing bespoke fast
377+
// kernel (kAttnQkNormRope, Metal) assumes a per-head Dh reduction, so this
378+
// full-width variant does NOT claim it — it keeps the byte-exact composite on
379+
// every backend. A full-width fast kernel is a clean follow-up perf step (like
380+
// kSiluMulQuantFp8's deferred fast tier); it is NOT needed for the D3 fold, which
381+
// is a launch-consolidation / shared-catalog consistency fold whose bit-exactness
382+
// is proven by OLMo-2's SACRED token-exact gate on the composite path.
383+
constexpr FusedRecipe kAttnQkNormRopeFullWidth = {
384+
{
385+
{FOp::kRmsNorm, /*out=*/0, /*in=*/{0, 1}, /*nin=*/2, kNoOperand, FReduce::kMeanSquare,
386+
/*gemma=*/false, /*sigmoid_gate=*/false, /*norm_full_width=*/true},
387+
{FOp::kRmsNorm, /*out=*/2, /*in=*/{2, 3}, /*nin=*/2, kNoOperand, FReduce::kMeanSquare,
388+
/*gemma=*/false, /*sigmoid_gate=*/false, /*norm_full_width=*/true},
389+
{FOp::kRope, /*out=*/4, /*in=*/{4, 6, 7}, /*nin=*/3, /*out2=*/5, FReduce::kNone, false,
390+
false},
391+
},
392+
{
393+
{FKind::kRow, "q"},
394+
{FKind::kWeight, "q_norm"},
395+
{FKind::kRow, "k"},
396+
{FKind::kWeight, "k_norm"},
397+
{FKind::kAux, "q3"},
398+
{FKind::kAux, "k3"},
399+
{FKind::kAux, "cos_sin"},
400+
{FKind::kAux, "positions"},
401+
},
402+
/*n=*/3,
403+
/*n_operands=*/8,
404+
/*name=*/"attn_qk_norm_rope_full_width",
405+
// Composite-only: no full-width bespoke fast kernel yet (the per-head
406+
// kAttnQkNormRope fast kernel would norm over the wrong domain). The composite
407+
// is byte-exact by construction, so this is safe on every backend.
408+
/*fast_op=*/kNoFastOp,
409+
};
410+
357411
} // namespace vt

0 commit comments

Comments
 (0)