Skip to main content

qualia_core_db/q42/volume/
network_quanta.rs

1//! Bounded-work quanta for network graph reads (CORE-02.03, 02.04, 02.10 partial).
2//!
3//! Output page size is not a work limit. Continuations bind to an exact
4//! source digest, query generation, profile and scope. A recent-fact window
5//! never certifies global completeness. Logical Quin count — not a small
6//! physical root — decides whether a full load is admitted.
7
8use crate::net::qdnf::errors::QdnfError;
9
10/// Remaining scan-block, work and wall-time quanta.
11///
12/// Callers size output pages independently. Filling or emptying a page does
13/// not consume this budget; [`ScanBudget::consume`] is the only deduction.
14#[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    /// Deduct one quantum. Fails [`QdnfError::BudgetExhausted`] without wrapping
30    /// or mutating the budget when any counter would underflow.
31    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/// Resumable network-graph continuation.
52///
53/// Bound to one immutable source, query generation, profile and scope. Offset
54/// is progress within that bind; it is not an authorization field.
55#[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    /// Issue a continuation at offset 0 for this exact query/source/profile/scope.
67    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    /// Advance `delta` only when the live query/source/profile/scope match this
83    /// cursor. Stale generation is [`QdnfError::StaleGeneration`]; forged source,
84    /// profile or cross-scope reuse is [`QdnfError::Unauthorized`]. Offset does
85    /// not wrap.
86    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/// Honesty of a bounded scan relative to the logical universe.
112#[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    /// Classify a recent-fact window. Never [`Completeness::Complete`]: a window
122    /// is a frontier, not a census. `universe_unknown` yields IncompleteFrontier.
123    pub fn from_window(window_size: u64, universe_unknown: bool) -> Self {
124        // A finite (or empty) window is not a universe census, even when the
125        // caller believes the universe is known.
126        let _ = (window_size, universe_unknown);
127        Self::IncompleteFrontier
128    }
129}
130
131/// Admit a resident/full load from logical Quin count, not physical root size.
132///
133/// A tiny root (manifest pointer) must not authorize loading a logical graph
134/// that exceeds `cap_quins`.
135pub 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}