qualia_core_db/q42/volume/
network_quanta.rs1use crate::net::qdnf::errors::QdnfError;
9
10#[repr(C)]
15#[derive(Clone, Copy, Debug, Eq, PartialEq)]
16pub struct ScanBudget {
17 pub blocks: u32,
18 pub work: u64,
19 pub micros: u64,
20}
21
22impl ScanBudget {
23 pub const ZERO: Self = Self {
24 blocks: 0,
25 work: 0,
26 micros: 0,
27 };
28
29 pub fn consume(&mut self, blocks: u32, work: u64, micros: u64) -> Result<(), QdnfError> {
32 let blocks = self
33 .blocks
34 .checked_sub(blocks)
35 .ok_or(QdnfError::BudgetExhausted)?;
36 let work = self
37 .work
38 .checked_sub(work)
39 .ok_or(QdnfError::BudgetExhausted)?;
40 let micros = self
41 .micros
42 .checked_sub(micros)
43 .ok_or(QdnfError::BudgetExhausted)?;
44 self.blocks = blocks;
45 self.work = work;
46 self.micros = micros;
47 Ok(())
48 }
49}
50
51#[repr(C)]
56#[derive(Clone, Copy, Debug, Eq, PartialEq)]
57pub struct NetworkCursor {
58 pub source_digest: [u8; 32],
59 pub query_generation: u64,
60 pub profile: u16,
61 pub scope: u64,
62 pub offset: u64,
63}
64
65impl NetworkCursor {
66 pub const fn bind(
68 source_digest: [u8; 32],
69 query_generation: u64,
70 profile: u16,
71 scope: u64,
72 ) -> Self {
73 Self {
74 source_digest,
75 query_generation,
76 profile,
77 scope,
78 offset: 0,
79 }
80 }
81
82 pub fn advance(
87 &mut self,
88 source_digest: &[u8; 32],
89 query_generation: u64,
90 profile: u16,
91 scope: u64,
92 delta: u64,
93 ) -> Result<u64, QdnfError> {
94 if self.query_generation != query_generation {
95 return Err(QdnfError::StaleGeneration);
96 }
97 if self.source_digest != *source_digest {
98 return Err(QdnfError::Unauthorized);
99 }
100 if self.profile != profile {
101 return Err(QdnfError::Unauthorized);
102 }
103 if self.scope != scope {
104 return Err(QdnfError::Unauthorized);
105 }
106 self.offset = self.offset.checked_add(delta).ok_or(QdnfError::Range)?;
107 Ok(self.offset)
108 }
109}
110
111#[repr(u8)]
113#[derive(Clone, Copy, Debug, Eq, PartialEq)]
114pub enum Completeness {
115 Complete = 0,
116 IncompleteFrontier = 1,
117 Unsupported = 2,
118}
119
120impl Completeness {
121 pub fn from_window(window_size: u64, universe_unknown: bool) -> Self {
124 let _ = (window_size, universe_unknown);
127 Self::IncompleteFrontier
128 }
129}
130
131pub fn admit_logical_size(
136 root_bytes: u64,
137 logical_quin_count: u64,
138 cap_quins: u64,
139) -> Result<(), QdnfError> {
140 let _ = root_bytes;
141 if logical_quin_count > cap_quins {
142 Err(QdnfError::Capacity)
143 } else {
144 Ok(())
145 }
146}
147
148#[cfg(test)]
149mod tests {
150 use super::*;
151
152 #[test]
153 fn consume_deducts_quanta_not_page_size() {
154 let mut budget = ScanBudget {
155 blocks: 64,
156 work: 10_000,
157 micros: 5_000,
158 };
159 let page_slots: u32 = 8;
160 budget.consume(50, 400, 200).unwrap();
161 assert_eq!(budget.blocks, 14);
162 assert_eq!(budget.work, 9_600);
163 assert_eq!(budget.micros, 4_800);
164 assert!(budget.work > page_slots as u64);
165 assert!(budget.blocks > page_slots);
166 }
167
168 #[test]
169 fn consume_fails_exhausted_without_wrapping_or_partial_update() {
170 let mut budget = ScanBudget {
171 blocks: 1,
172 work: 2,
173 micros: 3,
174 };
175 assert_eq!(budget.consume(2, 0, 0), Err(QdnfError::BudgetExhausted));
176 assert_eq!(budget.blocks, 1);
177 assert_eq!(budget.work, 2);
178 assert_eq!(budget.micros, 3);
179
180 assert_eq!(budget.consume(0, 3, 0), Err(QdnfError::BudgetExhausted));
181 assert_eq!(budget.work, 2);
182
183 assert_eq!(budget.consume(0, 0, 4), Err(QdnfError::BudgetExhausted));
184 assert_eq!(budget.micros, 3);
185
186 let mut saturated = ScanBudget {
187 blocks: 0,
188 work: 0,
189 micros: 0,
190 };
191 assert_eq!(saturated.consume(1, 0, 0), Err(QdnfError::BudgetExhausted));
192 assert_eq!(saturated, ScanBudget::ZERO);
193 saturated.consume(0, 0, 0).unwrap();
194 }
195
196 #[test]
197 fn advance_binds_query_source_profile_generation() {
198 let digest = [0x11u8; 32];
199 let mut cursor = NetworkCursor::bind(digest, 7, 0x0101, 0xA11CE);
200 assert_eq!(cursor.advance(&digest, 7, 0x0101, 0xA11CE, 4).unwrap(), 4);
201 assert_eq!(cursor.offset, 4);
202 assert_eq!(cursor.advance(&digest, 7, 0x0101, 0xA11CE, 1).unwrap(), 5);
203 }
204
205 #[test]
206 fn advance_rejects_stale_forged_and_cross_scope() {
207 let digest = [0x22u8; 32];
208 let mut cursor = NetworkCursor::bind(digest, 3, 9, 100);
209
210 assert_eq!(
211 cursor.advance(&digest, 2, 9, 100, 1),
212 Err(QdnfError::StaleGeneration)
213 );
214 assert_eq!(
215 cursor.advance(&digest, 4, 9, 100, 1),
216 Err(QdnfError::StaleGeneration)
217 );
218 assert_eq!(cursor.offset, 0);
219
220 let other_source = [0x33u8; 32];
221 assert_eq!(
222 cursor.advance(&other_source, 3, 9, 100, 1),
223 Err(QdnfError::Unauthorized)
224 );
225
226 assert_eq!(
227 cursor.advance(&digest, 3, 8, 100, 1),
228 Err(QdnfError::Unauthorized)
229 );
230
231 assert_eq!(
232 cursor.advance(&digest, 3, 9, 101, 1),
233 Err(QdnfError::Unauthorized)
234 );
235 assert_eq!(cursor.offset, 0);
236 }
237
238 #[test]
239 fn advance_offset_does_not_wrap() {
240 let digest = [0u8; 32];
241 let mut cursor = NetworkCursor::bind(digest, 1, 1, 1);
242 cursor.offset = u64::MAX;
243 assert_eq!(cursor.advance(&digest, 1, 1, 1, 1), Err(QdnfError::Range));
244 assert_eq!(cursor.offset, u64::MAX);
245 }
246
247 #[test]
248 fn recent_fact_window_never_certifies_complete() {
249 assert_eq!(
250 Completeness::from_window(8, true),
251 Completeness::IncompleteFrontier
252 );
253 assert_eq!(
254 Completeness::from_window(0, true),
255 Completeness::IncompleteFrontier
256 );
257 assert_ne!(Completeness::from_window(8, false), Completeness::Complete);
258 assert_ne!(
259 Completeness::from_window(u64::MAX, false),
260 Completeness::Complete
261 );
262 assert_eq!(
263 Completeness::from_window(1, false),
264 Completeness::IncompleteFrontier
265 );
266 assert_ne!(Completeness::Unsupported, Completeness::Complete);
267 }
268
269 #[test]
270 fn small_root_does_not_admit_oversize_logical_graph() {
271 assert_eq!(
272 admit_logical_size(256, 1_000_001, 1_000_000),
273 Err(QdnfError::Capacity)
274 );
275 admit_logical_size(256, 1_000_000, 1_000_000).unwrap();
276 admit_logical_size(u64::MAX, 0, 0).unwrap();
277 assert_eq!(admit_logical_size(1, 1, 0), Err(QdnfError::Capacity));
278 }
279}