Skip to main content

qualia_core_db/net/peer/cells/
admit.rs

1//! Cell-slot reserve/release. Ordinary cells cannot exceed 512 MiB.
2//!
3//! E10.1 / RT-02 slice (partial, packages remain open):
4//! - RT-02.01 partial — reuse RT-01 leases/ledger; no third scheduler.
5//! - RT-02.02 / E10.1 — reserve before construction; 512 MiB ordinary ceiling;
6//!   production [`MAX_CELLS`] is 16 (was a four-slot demonstration table).
7//! - RT-02.03 partial — `NetworkSmall` cannot silently take a 42 MiB Sentinel pass.
8//! - RT-02.05 partial — `LlmException` is tagged and isolated (`llm_shares_ordinary_network_reserve` is false);
9//!   this slice still refuses > 512 MiB (full LLM profiles are not admitted here).
10//!
11//! Caller-backed descriptor admission lives in [`super::descriptors`]. The
12//! four-slot demonstration table is gone: [`CellTable`] is the production table.
13//!
14//! Not in this slice: RT-02.04 measurement split, E10.5 scaling, E10.6 AF_XDP.
15
16use 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
25/// Ordinary cell ceiling. Same value as [`ORDINARY_CELL_BYTES`].
26pub const MAX_ORDINARY_CELL: u64 = ORDINARY_CELL_BYTES as u64;
27/// Occupied cell slots (E10.1 production table). A 17th is [`QdnfError::Capacity`].
28pub const MAX_CELLS: usize = 16;
29
30/// Local cell admission class. `LlmException` may request the OrdinaryCell size class
31/// but stays tagged so it is not mixed with ordinary networking.
32#[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/// One admitted cell. Caller holds the slot token until [`CellTable::release`].
42#[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
50/// Sixteen occupancy flags plus owner-held reservation handles (E10.1).
51pub struct CellTable {
52    occupied: [bool; MAX_CELLS],
53    charges: [ChargeRef; MAX_CELLS],
54    reserved_bytes: [u64; MAX_CELLS],
55}
56
57impl CellTable {
58    /// Creates a default `CellTable`.
59    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    /// Reserve **before** construction. Ordinary cells cannot exceed 512 MiB.
68    ///
69    /// Ledger charge uses [`ReservationLedger::reserve`] / [`ReservationLedger::release`]
70    /// with a [`ResourceBudget`] of `bytes` (work/io = 0) and `verified_peer = true`.
71    /// Lease acquire is all-or-nothing: a failed [`LeaseTable::acquire`] releases the ledger charge.
72    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                // Cannot silently allocate a full Sentinel arena.
85                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                // OrdinaryCell class only; remains tagged LlmException (RT-02.05 partial).
103                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    /// Releases the resource.
138    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    /// Strict release (`R10` / `R11`): rejects any release call whose caller-supplied
165    /// `slot.bytes` does not match the authoritative recorded reservation or whose
166    /// `(lease_id, generation)` handle is stale.
167    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    /// Occupied cells.
197    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
227/// LLM/exception profiles do not consume the ordinary networking reserve (RT-02.05 partial).
228pub 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}