Skip to main content

qualia_core_db/net/qdnf/cells/
pass_budget.rs

1//! 42 MiB Sentinel pass accounting (E03.4 / E10.5).
2//!
3//! This is **accounting only**. It does not allocate
4//! [`crate::governance::webizen::SlgArena`], does not map 42 MiB of RAM, and
5//! is not a measured process RSS.
6
7use crate::governance::webizen::SENTINEL_PASS_BYTES;
8use crate::net::qdnf::errors::QdnfError;
9
10/// Exact 42 MiB pass ceiling. Same value as [`SENTINEL_PASS_BYTES`].
11pub const SENTINEL_PASS_TOTAL: u64 = 42 * 1024 * 1024;
12
13/// Explicit pass charge components (E03.4).
14#[derive(Clone, Copy, Debug, PartialEq, Eq)]
15pub struct PassCharge {
16    pub arena: u64,
17    pub scratch: u64,
18    pub crypto: u64,
19    pub kernel: u64,
20    pub pinned: u64,
21}
22
23impl PassCharge {
24    pub const ZERO: Self = Self {
25        arena: 0,
26        scratch: 0,
27        crypto: 0,
28        kernel: 0,
29        pinned: 0,
30    };
31}
32
33/// Checked sum of every charged class. Greater than 42 MiB → [`QdnfError::Capacity`].
34pub fn charge_pass(c: &PassCharge) -> Result<u64, QdnfError> {
35    let mut total = 0u64;
36    total = total.checked_add(c.arena).ok_or(QdnfError::Capacity)?;
37    total = total.checked_add(c.scratch).ok_or(QdnfError::Capacity)?;
38    total = total.checked_add(c.crypto).ok_or(QdnfError::Capacity)?;
39    total = total.checked_add(c.kernel).ok_or(QdnfError::Capacity)?;
40    total = total.checked_add(c.pinned).ok_or(QdnfError::Capacity)?;
41    if total > SENTINEL_PASS_TOTAL {
42        return Err(QdnfError::Capacity);
43    }
44    let _ = SENTINEL_PASS_BYTES;
45    Ok(total)
46}
47
48/// Terminal pass outcomes that must still reclaim (E03.5).
49#[repr(u8)]
50#[derive(Clone, Copy, Debug, PartialEq, Eq)]
51pub enum PassOutcome {
52    Success = 0,
53    Error = 1,
54    Cancel = 2,
55    Unwind = 3,
56}
57
58/// Reclaim charged pass bytes. Every outcome returns 0 remaining.
59pub fn reclaim_pass(_outcome: PassOutcome, charged: u64) -> u64 {
60    let _ = charged;
61    0
62}
63
64/// RAII Sentinel pass. Reclaims on success, error, and unwind. Does not map 42 MiB.
65pub struct PassGuard {
66    charged: u64,
67    outcome: PassOutcome,
68}
69
70impl PassGuard {
71    /// Enters the pass budget.
72    pub fn enter(charge: &PassCharge) -> Result<Self, QdnfError> {
73        Ok(Self {
74            charged: charge_pass(charge)?,
75            outcome: PassOutcome::Error,
76        })
77    }
78
79    #[inline]
80    /// `PassGuard::charged`.
81    pub const fn charged(&self) -> u64 {
82        self.charged
83    }
84
85    #[inline]
86    /// `PassGuard::success`.
87    pub fn success(&mut self) {
88        self.outcome = PassOutcome::Success;
89    }
90}
91
92impl Drop for PassGuard {
93    fn drop(&mut self) {
94        let _ = reclaim_pass(self.outcome, self.charged);
95    }
96}
97
98/// 42 MiB is a pass ceiling, not a process RSS or test allocation.
99#[inline]
100pub const fn pass_maps_process_rss() -> bool {
101    false
102}
103
104#[cfg(test)]
105mod tests {
106    use super::*;
107
108    #[test]
109    fn forty_two_mib_is_accounting_not_rss() {
110        assert_eq!(SENTINEL_PASS_TOTAL, SENTINEL_PASS_BYTES as u64);
111        assert!(!pass_maps_process_rss());
112        let exact = PassCharge {
113            arena: SENTINEL_PASS_TOTAL,
114            ..PassCharge::ZERO
115        };
116        assert_eq!(charge_pass(&exact), Ok(SENTINEL_PASS_TOTAL));
117        let over = PassCharge {
118            arena: SENTINEL_PASS_TOTAL,
119            scratch: 1,
120            ..PassCharge::ZERO
121        };
122        assert_eq!(charge_pass(&over), Err(QdnfError::Capacity));
123    }
124
125    #[test]
126    fn reclaim_every_outcome_and_guard() {
127        let charged = charge_pass(&PassCharge {
128            scratch: 8,
129            crypto: 8,
130            kernel: 8,
131            ..PassCharge::ZERO
132        })
133        .unwrap();
134        assert_eq!(reclaim_pass(PassOutcome::Success, charged), 0);
135        assert_eq!(reclaim_pass(PassOutcome::Error, charged), 0);
136        assert_eq!(reclaim_pass(PassOutcome::Cancel, charged), 0);
137        assert_eq!(reclaim_pass(PassOutcome::Unwind, charged), 0);
138        let mut g = PassGuard::enter(&PassCharge {
139            scratch: 8,
140            crypto: 8,
141            kernel: 8,
142            ..PassCharge::ZERO
143        })
144        .unwrap();
145        assert_eq!(g.charged(), 24);
146        g.success();
147    }
148}