Module kv_dict_runtime 

W5b Phase 4b — runtime KV-dictionary install + reconstruction, in CORE (engine-side, no forge dep).

Holds the certified per-layer K/V dictionaries and, when enabled, reconstructs each K/V vector on the KV-cache write path (reconstruct_kv) so attention reads the dictionary-reconstructed vectors. This is the engine half of “forge produces, engine runs”: the forge learns + certifies + packages a dictionary artifact; the engine load_certifieds it (verifying the provenance gate) and installs it here. Reconstruct-on-write is quality-identical to a real compressed cache (store code, reconstruct on read) — the compressed GPU cache layout + shader reconstruction is the remaining Phase 4b work.

Gated + zero-cost when off (one relaxed atomic load on the attention path).

Structs

CertInfo

Metadata returned by load_certified on success — the gate numbers the artifact was certified at.

KvDictArtifact

The serialized dictionary artifact payload (what rides inside the framed .q42art after the provenance header). Shared by the forge packager and the engine loader — the one source of truth for the on-disk dictionary format.

Functions

activate

User switch — ON. Load a certified dictionary from path and turn the dict-coded KV cache on (QUALIA_LLM_KV_DICT). One call for “use the small KV cache”. Fail-closed via load_certified. Take effect at the NEXT model load (the cache layout is chosen then), like the int8 toggle.

atoms_flat

Flatten the installed atoms into the arena layout [layer][K atoms n_atoms×head_dim][V atoms …], with (flat, n_atoms, head_dim); layers/streams with no dictionary are zero (never selected). The engine uploads this into the tail of each layer’s KV-arena slice for the GPU shader to reconstruct.

clear

Free the installed dictionaries.

clone_layer_dict

Clone a layer’s K (k_not_v = true) or V dictionary, or None if that layer/stream is passthrough. The dict-cache write (encode) and read (reconstruct) paths clone once per attention call and work against the local copy, avoiding a mutex lock per KV vector on the hot loop.

deactivate

User switch — OFF. Turn the dict-coded KV cache off and drop the installed dictionaries; the next model load uses the default f32/int8 cache.

dict_active

Whether the dict-coded KV cache is currently the active choice: the toggle is on AND a dictionary is installed. (QUALIA_LLM_KV_DICT / crate::llm_bench::set_kv_dict / this read-back = the 3-way user switch, mirroring speculative-decode and int8-KV.)

disable

enable

Install the per-layer dictionaries and turn reconstruction ON.

install_from_cbor

Decode a dictionary artifact payload (CBOR KvDictArtifact) and install it. The payload is the bytes AFTER the provenance frame header — see load_certified for the full framed path.

installed_meta

The installed dictionary’s (sparsity, head_dim), or None if nothing is installed. The KV-cache layout consults this to size the dict-coded slots (Phase 4b step 3).

is_enabled

load_certified

Load a certified KV-dictionary artifact from a framed .q42art file, verify its provenance gate (kind == KvDictionary AND passed == true), and install it. Fail-closed: a bad frame, wrong artifact kind, or an artifact that did NOT pass its ΔPPL gate is refused — the engine only runs certified artifacts. Returns the certified gate numbers on success.

reconstruct_kv

Reconstruct each of the n_kv head vectors in proj (length ≥ n_kv * head_dim) through this layer’s dictionary, in place. No-op (one atomic load) when disabled, when the layer has no dictionary, or on a head_dim mismatch — so the caller stores the original vector unchanged.

sparsity

The installed sparsity k (0 if nothing installed).