Skip to main content

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    /// Creates a default `Q42KvPageHeader`.
83    pub fn new() -> Self {
84        Self {
85            magic: QKVP_MAGIC,
86            version: QKVP_VERSION,
87            flags: 0,
88            model_hash: [0; 32],
89            token_start: 0,
90            token_count: 0,
91            manifold_idx_start: 0,
92            manifold_idx_count: 0,
93            kv_heads: 0,
94            head_dim: 0,
95            kv_dtype: 0,
96            quant_codec: 0,
97            compression_flags: 0,
98            payload_offset: 0,
99            payload_length: 0,
100            parent_page_id: 0,
101            next_page_id: 0,
102            semantic_index_off: 0,
103            manifold_index_off: 0,
104            sketch_offset: 0,
105            entropy_score: 0.0,
106            attention_score: 0.0,
107            recency_score: 0.0,
108            confidence_score: 0.0,
109            _reserved1: [0; 80],
110            checksum: [0; 32],
111        }
112    }
113}
114
115impl Default for Q42KvPageHeader {
116    fn default() -> Self {
117        Self::new()
118    }
119}
120
121#[cfg(test)]
122mod tests {
123    use super::*;
124
125    #[test]
126    fn test_qkvp_alignment() {
127        assert_eq!(std::mem::size_of::<Q42KvPageHeader>(), 256);
128        assert_eq!(std::mem::size_of::<Q42ChunkPolicy>(), 64);
129        assert_eq!(std::mem::size_of::<Q42QuerySketch>(), 128);
130    }
131}