qualia_core_db/net/peer/cells/
admit.rs1use crate::governance::webizen::{
17 classify_budget, ArenaBudgetClass, ORDINARY_CELL_BYTES, SENTINEL_PASS_BYTES,
18};
19use crate::net::peer::runtime::ledger::ChargeRef;
20use crate::net::peer::runtime::{
21 BufferLease, LeaseTable, ReservationHandle, ReservationLedger, ResourceBudget,
22};
23use crate::net::qdnf::errors::QdnfError;
24
25pub const MAX_ORDINARY_CELL: u64 = ORDINARY_CELL_BYTES as u64;
27pub const MAX_CELLS: usize = 16;
29
30#[repr(u8)]
33#[derive(Clone, Copy, Debug, PartialEq, Eq)]
34pub enum CellProfile {
35 NetworkSmall = 0,
36 SentinelPass = 1,
37 Ordinary = 2,
38 LlmException = 3,
39}
40
41#[derive(Clone, Copy, Debug, PartialEq, Eq)]
43pub struct CellSlot {
44 pub id: u8,
45 pub profile: CellProfile,
46 pub bytes: u64,
47 pub lease: BufferLease,
48}
49
50pub struct CellTable {
52 occupied: [bool; MAX_CELLS],
53 charges: [ChargeRef; MAX_CELLS],
54 reserved_bytes: [u64; MAX_CELLS],
55}
56
57impl CellTable {
58 pub const fn new() -> Self {
60 Self {
61 occupied: [false; MAX_CELLS],
62 charges: [ChargeRef::EMPTY; MAX_CELLS],
63 reserved_bytes: [0; MAX_CELLS],
64 }
65 }
66
67 pub fn reserve(
73 &mut self,
74 leases: &mut LeaseTable,
75 ledger: &mut ReservationLedger,
76 profile: CellProfile,
77 bytes: u64,
78 ) -> Result<CellSlot, QdnfError> {
79 if bytes == 0 || bytes > MAX_ORDINARY_CELL {
80 return Err(QdnfError::Capacity);
81 }
82 match profile {
83 CellProfile::NetworkSmall => {
84 if bytes >= SENTINEL_PASS_BYTES as u64 {
86 return Err(QdnfError::Capacity);
87 }
88 }
89 CellProfile::SentinelPass => match classify_budget(bytes)? {
90 ArenaBudgetClass::SentinelPass => {}
91 ArenaBudgetClass::OrdinaryCell | ArenaBudgetClass::Rejected => {
92 return Err(QdnfError::Capacity);
93 }
94 },
95 CellProfile::Ordinary => match classify_budget(bytes)? {
96 ArenaBudgetClass::OrdinaryCell => {}
97 ArenaBudgetClass::SentinelPass | ArenaBudgetClass::Rejected => {
98 return Err(QdnfError::Capacity);
99 }
100 },
101 CellProfile::LlmException => {
102 match classify_budget(bytes)? {
104 ArenaBudgetClass::OrdinaryCell => {}
105 ArenaBudgetClass::SentinelPass | ArenaBudgetClass::Rejected => {
106 return Err(QdnfError::Capacity);
107 }
108 }
109 }
110 }
111
112 let id = match self.free_id() {
113 Some(id) => id,
114 None => return Err(QdnfError::Capacity),
115 };
116 let capacity = u32::try_from(bytes).map_err(|_| QdnfError::Capacity)?;
117 let budget = cell_bytes_budget(bytes);
118 let charge = ledger.reserve(budget, true)?;
119 let lease = match leases.acquire(capacity, true) {
120 Ok(lease) => lease,
121 Err(e) => {
122 let _ = ledger.release(charge);
123 return Err(e);
124 }
125 };
126 self.occupied[id as usize] = true;
127 self.charges[id as usize] = charge.as_ref();
128 self.reserved_bytes[id as usize] = bytes;
129 Ok(CellSlot {
130 id,
131 profile,
132 bytes,
133 lease,
134 })
135 }
136
137 pub fn release(
139 &mut self,
140 leases: &mut LeaseTable,
141 ledger: &mut ReservationLedger,
142 slot: CellSlot,
143 ) -> Result<(), QdnfError> {
144 let idx = slot.id as usize;
145 if idx >= MAX_CELLS {
146 return Err(QdnfError::Range);
147 }
148 if !self.occupied[idx] {
149 return Err(QdnfError::DoubleRelease);
150 }
151 leases.release(slot.lease.handle)?;
152 let charge = self.charges[idx];
153 if charge == ChargeRef::EMPTY {
154 return Err(QdnfError::DoubleRelease);
155 }
156 self.charges[idx] = ChargeRef::EMPTY;
157 self.reserved_bytes[idx] = 0;
158 let _ = slot.bytes;
159 ledger.release(ReservationHandle::from_ref(charge))?;
160 self.occupied[idx] = false;
161 Ok(())
162 }
163
164 pub fn release_strict(
168 &mut self,
169 leases: &mut LeaseTable,
170 ledger: &mut ReservationLedger,
171 slot: CellSlot,
172 ) -> Result<(), QdnfError> {
173 let idx = slot.id as usize;
174 if idx >= MAX_CELLS {
175 return Err(QdnfError::Range);
176 }
177 if !self.occupied[idx] {
178 return Err(QdnfError::DoubleRelease);
179 }
180 if slot.bytes != self.reserved_bytes[idx] {
181 return Err(QdnfError::Conflict);
182 }
183 let charge = self.charges[idx];
184 if charge == ChargeRef::EMPTY {
185 return Err(QdnfError::DoubleRelease);
186 }
187 leases.release(slot.lease.handle)?;
188 self.charges[idx] = ChargeRef::EMPTY;
189 let expected = self.reserved_bytes[idx];
190 self.reserved_bytes[idx] = 0;
191 ledger.release_checked_bytes(ReservationHandle::from_ref(charge), expected)?;
192 self.occupied[idx] = false;
193 Ok(())
194 }
195
196 pub fn occupied(&self) -> usize {
198 let mut n = 0;
199 let mut i = 0;
200 while i < MAX_CELLS {
201 if self.occupied[i] {
202 n += 1;
203 }
204 i += 1;
205 }
206 n
207 }
208
209 fn free_id(&self) -> Option<u8> {
210 let mut i = 0;
211 while i < MAX_CELLS {
212 if !self.occupied[i] {
213 return Some(i as u8);
214 }
215 i += 1;
216 }
217 None
218 }
219}
220
221impl Default for CellTable {
222 fn default() -> Self {
223 Self::new()
224 }
225}
226
227pub fn llm_shares_ordinary_network_reserve() -> bool {
229 false
230}
231
232fn cell_bytes_budget(bytes: u64) -> ResourceBudget {
233 ResourceBudget {
234 bytes,
235 work: 0,
236 io: 0,
237 }
238}
239
240#[cfg(test)]
241mod tests {
242 use super::*;
243
244 fn cell_ledger() -> ReservationLedger {
245 let cap = ResourceBudget {
246 bytes: MAX_ORDINARY_CELL * MAX_CELLS as u64,
247 work: 64,
248 io: 64,
249 };
250 ReservationLedger::new(cap, cap, cap, cap, cap)
251 }
252
253 const MIB: u64 = 1024 * 1024;
254 const ORDINARY_64: u64 = 64 * MIB;
255
256 #[test]
257 fn network_small_one_mib_ok_forty_two_mib_capacity() {
258 let mut table = CellTable::new();
259 let mut leases = LeaseTable::new();
260 let mut ledger = cell_ledger();
261 let slot = table
262 .reserve(&mut leases, &mut ledger, CellProfile::NetworkSmall, MIB)
263 .expect("1 MiB NetworkSmall");
264 assert_eq!(slot.profile, CellProfile::NetworkSmall);
265 assert_eq!(slot.bytes, MIB);
266 assert_eq!(table.occupied(), 1);
267 assert_eq!(
268 table.reserve(
269 &mut leases,
270 &mut ledger,
271 CellProfile::NetworkSmall,
272 SENTINEL_PASS_BYTES as u64
273 ),
274 Err(QdnfError::Capacity)
275 );
276 assert_eq!(table.occupied(), 1);
277 }
278
279 #[test]
280 fn ordinary_over_512_mib_is_capacity() {
281 let mut table = CellTable::new();
282 let mut leases = LeaseTable::new();
283 let mut ledger = cell_ledger();
284 assert_eq!(
285 table.reserve(
286 &mut leases,
287 &mut ledger,
288 CellProfile::Ordinary,
289 MAX_ORDINARY_CELL + 1
290 ),
291 Err(QdnfError::Capacity)
292 );
293 let slot = table
294 .reserve(
295 &mut leases,
296 &mut ledger,
297 CellProfile::Ordinary,
298 MAX_ORDINARY_CELL,
299 )
300 .expect("512 MiB Ordinary is the ceiling");
301 assert_eq!(slot.profile, CellProfile::Ordinary);
302 assert_eq!(table.occupied(), 1);
303 }
304
305 #[test]
306 fn sixteen_cells_ok_seventeenth_capacity() {
307 let mut table = CellTable::new();
308 let mut leases = LeaseTable::new();
309 let mut ledger = cell_ledger();
310 let mut i = 0usize;
311 while i < MAX_CELLS {
312 table
313 .reserve(&mut leases, &mut ledger, CellProfile::Ordinary, ORDINARY_64)
314 .expect("cell within 16");
315 i += 1;
316 }
317 assert_eq!(table.occupied(), MAX_CELLS);
318 assert_eq!(leases.occupied_count(), MAX_CELLS);
319 assert_eq!(
320 table.reserve(&mut leases, &mut ledger, CellProfile::Ordinary, ORDINARY_64,),
321 Err(QdnfError::Capacity)
322 );
323 assert_eq!(table.occupied(), MAX_CELLS);
324 assert_eq!(ledger.used().cell.bytes, ORDINARY_64 * MAX_CELLS as u64);
325 }
326
327 #[test]
328 fn llm_does_not_share_ordinary_network_reserve() {
329 assert!(!llm_shares_ordinary_network_reserve());
330 let mut table = CellTable::new();
331 let mut leases = LeaseTable::new();
332 let mut ledger = cell_ledger();
333 let slot = table
334 .reserve(
335 &mut leases,
336 &mut ledger,
337 CellProfile::LlmException,
338 ORDINARY_64,
339 )
340 .expect("LlmException may request OrdinaryCell class");
341 assert_eq!(slot.profile, CellProfile::LlmException);
342 assert_ne!(slot.profile, CellProfile::Ordinary);
343 assert_eq!(
344 table.reserve(
345 &mut leases,
346 &mut ledger,
347 CellProfile::LlmException,
348 MAX_ORDINARY_CELL + 1
349 ),
350 Err(QdnfError::Capacity)
351 );
352 }
353
354 #[test]
355 fn release_restores_occupancy_and_lease() {
356 let mut table = CellTable::new();
357 let mut leases = LeaseTable::new();
358 let mut ledger = cell_ledger();
359 let slot = table
360 .reserve(&mut leases, &mut ledger, CellProfile::Ordinary, ORDINARY_64)
361 .expect("reserve");
362 assert_eq!(table.occupied(), 1);
363 assert_eq!(leases.occupied_count(), 1);
364 table
365 .release(&mut leases, &mut ledger, slot)
366 .expect("release");
367 assert_eq!(table.occupied(), 0);
368 assert_eq!(leases.occupied_count(), 0);
369 assert_eq!(ledger.used().cell.bytes, 0);
370 let again = table
371 .reserve(&mut leases, &mut ledger, CellProfile::Ordinary, ORDINARY_64)
372 .expect("reserve after release");
373 assert_eq!(table.occupied(), 1);
374 assert_eq!(again.id, 0);
375 table
376 .release(&mut leases, &mut ledger, again)
377 .expect("second release");
378 assert_eq!(
379 table.release(&mut leases, &mut ledger, again),
380 Err(QdnfError::DoubleRelease)
381 );
382 }
383
384 #[test]
385 fn sentinel_pass_exact_42_mib_ok_41_mib_capacity() {
386 let mut table = CellTable::new();
387 let mut leases = LeaseTable::new();
388 let mut ledger = cell_ledger();
389 let slot = table
390 .reserve(
391 &mut leases,
392 &mut ledger,
393 CellProfile::SentinelPass,
394 SENTINEL_PASS_BYTES as u64,
395 )
396 .expect("exact 42 MiB SentinelPass");
397 assert_eq!(slot.profile, CellProfile::SentinelPass);
398 assert_eq!(slot.bytes, SENTINEL_PASS_BYTES as u64);
399 assert_eq!(
400 classify_budget(slot.bytes),
401 Ok(ArenaBudgetClass::SentinelPass)
402 );
403 assert_eq!(
404 table.reserve(
405 &mut leases,
406 &mut ledger,
407 CellProfile::SentinelPass,
408 SENTINEL_PASS_BYTES as u64 - MIB
409 ),
410 Err(QdnfError::Capacity)
411 );
412 assert_eq!(table.occupied(), 1);
413 }
414
415 #[test]
416 fn copied_token_byte_mutation_does_not_change_release() {
417 let mut table = CellTable::new();
418 let mut leases = LeaseTable::new();
419 let mut ledger = cell_ledger();
420 let slot = table
421 .reserve(&mut leases, &mut ledger, CellProfile::Ordinary, ORDINARY_64)
422 .expect("reserve");
423 assert_eq!(ledger.used().cell.bytes, ORDINARY_64);
424 let mut mutated = slot;
425 mutated.bytes = 1;
426 table
427 .release(&mut leases, &mut ledger, mutated)
428 .expect("owner-held charge");
429 assert_eq!(ledger.used().cell.bytes, 0);
430 assert_eq!(table.occupied(), 0);
431 }
432
433 #[test]
434 fn r10_r11_release_strict_rejects_mismatched_caller_bytes() {
435 let mut table = CellTable::new();
436 let mut leases = LeaseTable::new();
437 let mut ledger = cell_ledger();
438 let slot = table
439 .reserve(&mut leases, &mut ledger, CellProfile::Ordinary, ORDINARY_64)
440 .expect("reserve");
441 let mut mutated = slot;
442 mutated.bytes = ORDINARY_64 * 2;
443 assert_eq!(
444 table.release_strict(&mut leases, &mut ledger, mutated),
445 Err(QdnfError::Conflict)
446 );
447 assert_eq!(ledger.used().cell.bytes, ORDINARY_64);
448 assert_eq!(table.occupied(), 1);
449 table
450 .release_strict(&mut leases, &mut ledger, slot)
451 .expect("strict release with authoritative bytes");
452 assert_eq!(ledger.used().cell.bytes, 0);
453 assert_eq!(table.occupied(), 0);
454 }
455}