Skip to main content

qualia_core_db/tensor/
kv_provenance.rs

1//! Bake-time map: tensor SOA index โ†” KV cache prompt slot (B3.2b / ยง7.3.3).
2
3use std::sync::{OnceLock, RwLock};
4
5pub const MAX_KV_PROVENANCE: usize = 1024;
6pub const KV_SLOT_UNMAPPED: u32 = u32::MAX;
7
8#[derive(Clone, Copy, Debug)]
9pub struct KvSlotInfo {
10    pub kv_slot: u32,
11    pub parent_page_id: u64,
12}
13
14impl KvSlotInfo {
15    pub const UNMAPPED: Self = Self {
16        kv_slot: KV_SLOT_UNMAPPED,
17        parent_page_id: 0,
18    };
19}
20
21pub struct KvProvenanceMap {
22    tensor_to_kv: [KvSlotInfo; MAX_KV_PROVENANCE],
23    kv_to_tensor: [u32; MAX_KV_PROVENANCE],
24    generation: u32,
25}
26
27impl KvProvenanceMap {
28    /// Creates a default `KvProvenanceMap`.
29    pub fn new() -> Self {
30        Self {
31            tensor_to_kv: [KvSlotInfo::UNMAPPED; MAX_KV_PROVENANCE],
32            kv_to_tensor: [KV_SLOT_UNMAPPED; MAX_KV_PROVENANCE],
33            generation: 0,
34        }
35    }
36
37    #[inline]
38    /// Generation.
39    pub fn generation(&self) -> u32 {
40        self.generation
41    }
42
43    /// Record a single tensor index โ†” KV slot bidirectional binding in O(1) (cold path).
44    pub fn record(&mut self, tensor_index: u32, kv_slot: u32, parent_page_id: u64) {
45        let ti = tensor_index as usize;
46        let ks = kv_slot as usize;
47        if ti < MAX_KV_PROVENANCE && ks < MAX_KV_PROVENANCE {
48            // Unmap old reverse slot if this tensor was previously bound elsewhere
49            let old_kv = self.tensor_to_kv[ti].kv_slot as usize;
50            if old_kv < MAX_KV_PROVENANCE && self.kv_to_tensor[old_kv] == tensor_index {
51                self.kv_to_tensor[old_kv] = KV_SLOT_UNMAPPED;
52            }
53            self.tensor_to_kv[ti] = KvSlotInfo {
54                kv_slot,
55                parent_page_id,
56            };
57            self.kv_to_tensor[ks] = tensor_index;
58            self.generation = self.generation.wrapping_add(1);
59        }
60    }
61
62    /// 1:1 prompt alignment: tensor node `i` โ†” KV slot `i` for `min(prompt, nodes)`.
63    pub fn build_prompt_alignment(
64        &mut self,
65        prompt_token_count: u32,
66        tensor_node_count: u32,
67        root_page_id: u64,
68    ) {
69        let n = prompt_token_count
70            .min(tensor_node_count)
71            .min(MAX_KV_PROVENANCE as u32);
72        for i in 0..n {
73            let idx = i as usize;
74            self.tensor_to_kv[idx] = KvSlotInfo {
75                kv_slot: i,
76                parent_page_id: root_page_id,
77            };
78            self.kv_to_tensor[idx] = i;
79        }
80        for i in n as usize..MAX_KV_PROVENANCE {
81            self.tensor_to_kv[i] = KvSlotInfo::UNMAPPED;
82            self.kv_to_tensor[i] = KV_SLOT_UNMAPPED;
83        }
84        self.generation = self.generation.wrapping_add(1);
85    }
86
87    #[inline]
88    /// `KvProvenanceMap::kv_slot_for_tensor`.
89    pub fn kv_slot_for_tensor(&self, tensor_index: u32) -> Option<u32> {
90        let ti = tensor_index as usize;
91        if ti >= MAX_KV_PROVENANCE {
92            return None;
93        }
94        let info = self.tensor_to_kv[ti];
95        if info.kv_slot == KV_SLOT_UNMAPPED {
96            None
97        } else {
98            Some(info.kv_slot)
99        }
100    }
101
102    #[inline]
103    /// Reverse lookup: find the 3D tensor index corresponding to a generated KV slot in O(1).
104    pub fn tensor_for_kv_slot(&self, kv_slot: u32) -> Option<u32> {
105        let ks = kv_slot as usize;
106        if ks >= MAX_KV_PROVENANCE {
107            return None;
108        }
109        let t = self.kv_to_tensor[ks];
110        if t == KV_SLOT_UNMAPPED {
111            None
112        } else {
113            Some(t)
114        }
115    }
116
117    #[inline]
118    /// `KvProvenanceMap::page_id_for_tensor`.
119    pub fn page_id_for_tensor(&self, tensor_index: u32) -> Option<u64> {
120        let ti = tensor_index as usize;
121        if ti >= MAX_KV_PROVENANCE {
122            return None;
123        }
124        let info = self.tensor_to_kv[ti];
125        if info.kv_slot == KV_SLOT_UNMAPPED {
126            None
127        } else {
128            Some(info.parent_page_id)
129        }
130    }
131}
132
133static KV_PROVENANCE: OnceLock<RwLock<KvProvenanceMap>> = OnceLock::new();
134
135fn kv_lock() -> &'static RwLock<KvProvenanceMap> {
136    KV_PROVENANCE.get_or_init(|| RwLock::new(KvProvenanceMap::new()))
137}
138
139#[inline]
140/// `KvProvenanceMap::global_kv_provenance`.
141pub fn global_kv_provenance() -> std::sync::RwLockReadGuard<'static, KvProvenanceMap> {
142    kv_lock().read().expect("kv provenance poisoned")
143}
144
145/// Reverse lookup helper for HUD/renderer: resolves KV slot to 3D tensor index in O(1) zero-heap.
146#[inline]
147pub fn global_tensor_for_kv_slot(kv_slot: u32) -> Option<u32> {
148    global_kv_provenance().tensor_for_kv_slot(kv_slot)
149}
150
151/// Rebuild provenance table (prompt prefill / spatial encode).
152pub fn rebuild_prompt_provenance(
153    prompt_token_count: u32,
154    tensor_node_count: u32,
155    root_page_id: u64,
156) {
157    if crate::compute_universe::rebuild_context_provenance(prompt_token_count, root_page_id) {
158        return;
159    }
160    kv_lock()
161        .write()
162        .expect("kv provenance poisoned")
163        .build_prompt_alignment(prompt_token_count, tensor_node_count, root_page_id);
164}
165
166#[inline]
167/// `KvProvenanceMap::record_kv_provenance`.
168pub fn record_kv_provenance(tensor_index: u32, kv_slot: u32, parent_page_id: u64) {
169    if crate::compute_universe::record_context_provenance(tensor_index, kv_slot, parent_page_id) {
170        return;
171    }
172    kv_lock().write().expect("kv provenance poisoned").record(
173        tensor_index,
174        kv_slot,
175        parent_page_id,
176    );
177}
178
179#[cfg(test)]
180mod tests {
181    use super::*;
182
183    #[test]
184    fn prompt_alignment_maps_tensor_to_kv_bidirectional() {
185        let mut map = KvProvenanceMap::new();
186        map.build_prompt_alignment(8, 10, 42);
187        assert_eq!(map.kv_slot_for_tensor(3), Some(3));
188        assert_eq!(map.tensor_for_kv_slot(3), Some(3));
189        assert_eq!(map.page_id_for_tensor(3), Some(42));
190
191        assert_eq!(map.kv_slot_for_tensor(9), None);
192        assert_eq!(map.tensor_for_kv_slot(9), None);
193    }
194
195    #[test]
196    fn record_maintains_bidirectional_mapping() {
197        let mut map = KvProvenanceMap::new();
198        map.record(42, 10, 777);
199        assert_eq!(map.kv_slot_for_tensor(42), Some(10));
200        assert_eq!(map.tensor_for_kv_slot(10), Some(42));
201        assert_eq!(map.page_id_for_tensor(42), Some(777));
202
203        // Re-record tensor 42 to slot 20
204        map.record(42, 20, 778);
205        assert_eq!(map.kv_slot_for_tensor(42), Some(20));
206        assert_eq!(map.tensor_for_kv_slot(20), Some(42));
207        assert_eq!(map.tensor_for_kv_slot(10), None);
208    }
209}