nx_gqa_head_map.nx

nx_gqa_head_map.nx -- H6 grouped/multi-query attention bits-up. Per NISHI_ELDER_AI_OFF_DOCKER_2026_05_20.md §2.1 H6: grouped-query attention (Ainslie 2023) + multi-query attention (Shazeer 2019) collapse the K and V projection dimensions so multiple query heads share one KV head. Memory + bandwidth wins on the KV cache scale with (n_q_heads / n_kv_heads): a 32-Q-head model with 8 KV heads cuts KV cache 4x; with 1 KV head (MQA) cuts it 32x. Llama 3, Mistral, Qwen, every modern open-weight model ships some flavour of this. V1 mechanics: a static mapping table head_to_kv_group[q_head_idx] = kv_head_idx, computed once at model-load time from (n_q_heads, n_kv_heads). The mapping is contiguous-group: q heads [0..group_size) -> kv head 0, [group_size..2*group_size) -> kv head 1, etc. This matches the layout every published implementation uses (Llama / Mistral / Qwen). Three named attention kinds fall out as sealed-enum special cases: MHA: n_kv_heads == n_q_heads (group_size = 1) GQA: 1 < n_kv_heads < n_q_heads (group_size > 1, divides n_q_heads) MQA: n_kv_heads == 1 (group_size = n_q_heads) Composition path: a downstream attention kernel (FlashAttention or naive softmax) loops over q heads, calls nx_gqa_head_map_kv_head_for_q_head(map, q_h) to find which KV head to read from, and computes attention against that smaller shared K/V. H5 nx_flash_attention can compose with this -- the tile plan reads from the shared KV head. Pure substrate logic. No Linux features. Composes with shipped H1 nx_kv_arena (KV pages are now sized by n_kv_heads not n_q_heads -- the arena allocator's hidden_dim parameter should reflect the smaller GQA/MQA layout), H5 nx_flash_attention (tile plan reads from shared KV head). V1 honest scope: - Contiguous-group mapping only (V2 could add strided or learned mapping for research variants; not in any production open-weight model as of 2026-05-20) - Sealed attention kind derived from (n_q, n_kv) -- not stored