Module kv_dict 

W5b Phase 4b — the KV-dictionary type and its sparse codec, in CORE.

This is the “engine runs the certified artifact” half of the sparse-KV-dictionary work. A learned per-layer dictionary D of n_atoms unit atoms represents each KV vector as a k-sparse linear combination — k (atom_index, coefficient) pairs. The engine needs two operations at runtime, and neither may depend on the forge feature:

• KvDictionary::encode — Orthogonal Matching Pursuit: a vector → its k-sparse code (write path).
• KvDictionary::reconstruct — code → vector (read path, in attention).

The MOD learner that PRODUCES a dictionary is a forge/training step and lives in wgsl_forge::calibration::kv_dictionary (which re-exports this type). Colocation would blur “forge produces, engine runs”, so only the data + codec + the small numeric helpers they share live here. Pure CPU + f32; the GPU reconstruction shader (Phase 4b step 5) mirrors [reconstruct] in WGSL.

Structs

KvDictionary

A learned per-layer KV dictionary: n_atoms atoms, each of length dim, row-major in atoms.

SparseCode

A K-sparse code of one vector: indices[i] selects an atom, coeffs[i] its weight.

Functions

pack_code_word

Pack a (atom_index, coefficient) pair into one 32-bit KV code word — u16 atom-index (high) | f16 coeff (low) — stored as an f32 in the dict-mode KV arena. The GPU attention shader unpacks the coeff with unpack2x16float(word).x and the index with word >> 16.

unpack_code_word

Inverse of pack_code_word: (atom_index, coefficient) from a code word.