qualia_core_db/q42/
q42_kvp.rs

1//! QKVP: Q42 Runtime Page Profile for Semantic KV and Cache Reuse
2//!
3//! This module defines the page-aware structures for the KV cache,
4//! allowing the engine to intelligently reuse, quantize, or evict
5//! KV memory based on cognitive and thermodynamic context rather
6//! than simple chronological LRU.
7
8pub const QKVP_MAGIC: [u8; 4] = *b"QKVP";
9pub const QKVP_VERSION: u16 = 1;
10
11/// The root header for a KV cache page.
12///
13/// Precisely padded to 256 bytes for optimal CPU cache line (DOD) performance.
14#[repr(C, align(64))]
15#[derive(Clone, Copy, Debug)]
16pub struct Q42KvPageHeader {
17    pub magic: [u8; 4], // 0..4 (b"QKVP")
18    pub version: u16,   // 4..6
19    pub flags: u16,     // 6..8
20
21    pub model_hash: [u8; 32], // 8..40
22
23    pub token_start: u64,        // 40..48
24    pub token_count: u32,        // 48..52
25    pub manifold_idx_start: u32, // 52..56 (replaces layer_start)
26    pub manifold_idx_count: u32, // 56..60 (replaces layer_count)
27    pub kv_heads: u16,           // 60..62
28    pub head_dim: u16,           // 62..64
29
30    // -- 64 byte boundary --
31    pub kv_dtype: u16,          // 64..66
32    pub quant_codec: u16,       // 66..68
33    pub compression_flags: u32, // 68..72
34    pub payload_offset: u64,    // 72..80
35    pub payload_length: u64,    // 80..88
36
37    pub parent_page_id: u64,     // 88..96
38    pub next_page_id: u64,       // 96..104
39    pub semantic_index_off: u64, // 104..112
40    pub manifold_index_off: u64, // 112..120
41    pub sketch_offset: u64,      // 120..128
42
43    // -- 128 byte boundary --
44    pub entropy_score: f32,    // 128..132
45    pub attention_score: f32,  // 132..136
46    pub recency_score: f32,    // 136..140
47    pub confidence_score: f32, // 140..144
48
49    pub _reserved1: [u8; 80], // 144..224
50    pub checksum: [u8; 32],   // 224..256
51}
52
53/// Controls semantic chunking, boundary weights, and thermal biases.
54/// Padded to exactly 64 bytes.
55#[repr(C, align(64))]
56#[derive(Clone, Copy, Debug)]
57pub struct Q42ChunkPolicy {
58    pub max_tokens: u32,                // 0..4
59    pub semantic_shift_threshold: f32,  // 4..8
60    pub discourse_boundary_weight: f32, // 8..12
61    pub attention_phase_weight: f32,    // 12..16
62    pub max_entropy_drop: f32,          // 16..20
63    pub thermal_pressure_bias: f32,     // 20..24
64    pub reserved: [u8; 40],             // 24..64
65}
66
67/// Drives query-aware min/max selection for the KV cache pages.
68/// Padded to exactly 128 bytes.
69#[repr(C, align(64))]
70#[derive(Clone, Copy, Debug)]
71pub struct Q42QuerySketch {
72    pub k_min_offset: u64,            // 0..8
73    pub k_max_offset: u64,            // 8..16
74    pub centroid_offset: u64,         // 16..24
75    pub semantic_hash_hi: u64,        // 24..32
76    pub semantic_hash_lo: u64,        // 32..40
77    pub manifold_centroid: [f32; 10], // 40..80
78    pub reserved: [u8; 48],           // 80..128
79}
80
81impl Q42KvPageHeader {
82    pub fn new() -> Self {
83        Self {
84            magic: QKVP_MAGIC,
85            version: QKVP_VERSION,
86            flags: 0,
87            model_hash: [0; 32],
88            token_start: 0,
89            token_count: 0,
90            manifold_idx_start: 0,
91            manifold_idx_count: 0,
92            kv_heads: 0,
93            head_dim: 0,
94            kv_dtype: 0,
95            quant_codec: 0,
96            compression_flags: 0,
97            payload_offset: 0,
98            payload_length: 0,
99            parent_page_id: 0,
100            next_page_id: 0,
101            semantic_index_off: 0,
102            manifold_index_off: 0,
103            sketch_offset: 0,
104            entropy_score: 0.0,
105            attention_score: 0.0,
106            recency_score: 0.0,
107            confidence_score: 0.0,
108            _reserved1: [0; 80],
109            checksum: [0; 32],
110        }
111    }
112}
113
114impl Default for Q42KvPageHeader {
115    fn default() -> Self {
116        Self::new()
117    }
118}
119
120#[cfg(test)]
121mod tests {
122    use super::*;
123
124    #[test]
125    fn test_qkvp_alignment() {
126        assert_eq!(std::mem::size_of::<Q42KvPageHeader>(), 256);
127        assert_eq!(std::mem::size_of::<Q42ChunkPolicy>(), 64);
128        assert_eq!(std::mem::size_of::<Q42QuerySketch>(), 128);
129    }
130}
qualia_core_db/q42/q42_kvp.rs

qualia_core_db/q42/
q42_kvp.rs
