qualia_core_db/tensor/
kv_provenance.rs1use 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 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 pub fn generation(&self) -> u32 {
40 self.generation
41 }
42
43 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 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 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 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 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 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]
140pub fn global_kv_provenance() -> std::sync::RwLockReadGuard<'static, KvProvenanceMap> {
142 kv_lock().read().expect("kv provenance poisoned")
143}
144
145#[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
151pub 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]
167pub 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 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}