Skip to main content

qualia_core_db/net/qdnf/resolve/
query.rs

1//! Bounded QSR query pipeline (NET-04 partial).
2//!
3//! Caps are remaining work, not a coverage proof. Authenticated exact lookup
4//! goes through snapshot `lookup` / `lookup_into` and returns [`QsrOutcome`].
5//! Compact hashes and `sameAs` are not authority. This is not Kademlia.
6
7use crate::net::qdnf::errors::QdnfError;
8use crate::net::qdnf::resolve::qsr::{lookup_into, CoverInterval, QsrOutcome, QsrSnapshot};
9use crate::net::qdnf::types::{Generation, QHashIndex, StrongDigest};
10
11pub const MAX_CANDIDATES: usize = 64;
12pub const MAX_VERIFICATIONS: usize = 16;
13pub const MAX_RETURNED_ROUTES: usize = 8;
14pub const MAX_CONNECTION_RACES: usize = 3;
15
16/// Remaining lookup budget. `initial` loads the MAX_* remaining slots.
17/// Continuations must not refill these fields (NET-04.22).
18#[repr(C)]
19#[derive(Clone, Copy, Debug, PartialEq, Eq)]
20pub struct QueryBudget {
21    pub candidates: u8,
22    pub verifications: u8,
23    pub returned: u8,
24    pub races: u8,
25    pub bytes: u32,
26    pub work: u64,
27}
28
29impl QueryBudget {
30    /// `QueryBudget::initial`.
31    pub const fn initial() -> Self {
32        Self {
33            candidates: MAX_CANDIDATES as u8,
34            verifications: MAX_VERIFICATIONS as u8,
35            returned: MAX_RETURNED_ROUTES as u8,
36            races: MAX_CONNECTION_RACES as u8,
37            bytes: 0,
38            work: 0,
39        }
40    }
41
42    /// Capacity when collected candidates would exceed 64. Does not wrap.
43    pub fn collect_candidate(&mut self) -> Result<(), QdnfError> {
44        take_remaining(&mut self.candidates)
45    }
46
47    /// Capacity when verifications would exceed 16. Does not wrap.
48    pub fn verify_one(&mut self) -> Result<(), QdnfError> {
49        take_remaining(&mut self.verifications)
50    }
51
52    /// `QueryBudget::return_route`.
53    pub fn return_route(&mut self) -> Result<(), QdnfError> {
54        take_remaining(&mut self.returned)
55    }
56
57    /// Capacity when connection races would exceed 3. Does not wrap.
58    pub fn start_race(&mut self) -> Result<(), QdnfError> {
59        take_remaining(&mut self.races)
60    }
61}
62
63fn take_remaining(slot: &mut u8) -> Result<(), QdnfError> {
64    let next = slot.checked_sub(1).ok_or(QdnfError::Capacity)?;
65    *slot = next;
66    Ok(())
67}
68
69/// Short `QHashIndex` values are lookup aids only (NET-04.02).
70pub fn compact_hash_is_routing_authority() -> bool {
71    let _ = core::mem::size_of::<QHashIndex>();
72    false
73}
74
75/// Alias / `sameAs` classifiers cannot merge people (NET-04.03).
76pub fn same_as_merges_people() -> bool {
77    false
78}
79
80/// Provider silence is unavailable/unknown, never an allow (NET-04.08).
81pub fn provider_silence_outcome() -> QdnfError {
82    QdnfError::Incomplete
83}
84
85/// Unsupported or incomplete policy cannot become allow (NET-04.12).
86pub fn unsupported_policy_is_allow() -> bool {
87    false
88}
89
90/// Exact lookup against a generation-pinned snapshot. Cover membership alone
91/// is not existence; the snapshot walk compares the full 48-byte key.
92pub fn lookup_with_budget(
93    snapshot: &QsrSnapshot,
94    key: &StrongDigest,
95    covers: &[CoverInterval],
96    required_generation: Generation,
97    budget: &mut QueryBudget,
98    out: &mut [StrongDigest],
99) -> Result<QsrOutcome, QdnfError> {
100    budget.collect_candidate()?;
101    budget.verify_one()?;
102    lookup_into(snapshot, key, covers, required_generation, out)
103}
104
105/// Epochs, retries, branches and continuations cannot reset work or byte caps.
106pub fn continuation_resets_budget() -> bool {
107    false
108}
109
110#[cfg(test)]
111mod tests {
112    use super::*;
113
114    #[test]
115    fn sixty_fifth_collect_candidate_is_capacity() {
116        let mut budget = QueryBudget::initial();
117        for _ in 0..MAX_CANDIDATES {
118            assert_eq!(budget.collect_candidate(), Ok(()));
119        }
120        assert_eq!(budget.collect_candidate(), Err(QdnfError::Capacity));
121        assert_eq!(budget.candidates, 0);
122    }
123
124    #[test]
125    fn seventeenth_verify_one_is_capacity() {
126        let mut budget = QueryBudget::initial();
127        for _ in 0..MAX_VERIFICATIONS {
128            assert_eq!(budget.verify_one(), Ok(()));
129        }
130        assert_eq!(budget.verify_one(), Err(QdnfError::Capacity));
131        assert_eq!(budget.verifications, 0);
132    }
133
134    #[test]
135    fn fourth_start_race_is_capacity() {
136        let mut budget = QueryBudget::initial();
137        for _ in 0..MAX_CONNECTION_RACES {
138            assert_eq!(budget.start_race(), Ok(()));
139        }
140        assert_eq!(budget.start_race(), Err(QdnfError::Capacity));
141        assert_eq!(budget.races, 0);
142    }
143
144    #[test]
145    fn ninth_return_route_is_capacity() {
146        let mut budget = QueryBudget::initial();
147        for _ in 0..MAX_RETURNED_ROUTES {
148            assert_eq!(budget.return_route(), Ok(()));
149        }
150        assert_eq!(budget.return_route(), Err(QdnfError::Capacity));
151        assert_eq!(budget.returned, 0);
152    }
153
154    #[test]
155    fn compact_hash_is_not_routing_authority() {
156        assert!(!compact_hash_is_routing_authority());
157    }
158
159    #[test]
160    fn same_as_does_not_merge_people() {
161        assert!(!same_as_merges_people());
162    }
163
164    #[test]
165    fn unsupported_policy_is_not_allow() {
166        assert!(!unsupported_policy_is_allow());
167    }
168
169    #[test]
170    fn lookup_with_budget_rejects_overlapping_covers() {
171        let mut budget = QueryBudget::initial();
172        let snap = QsrSnapshot::empty(Generation::ZERO);
173        let covers = [
174            CoverInterval { start: 0, end: 10 },
175            CoverInterval { start: 8, end: 12 },
176        ];
177        let mut out = [StrongDigest::ZERO; 1];
178        assert_eq!(
179            lookup_with_budget(
180                &snap,
181                &StrongDigest::ZERO,
182                &covers,
183                Generation::ZERO,
184                &mut budget,
185                &mut out
186            ),
187            Err(QdnfError::Overlap)
188        );
189        assert_eq!(budget.candidates, MAX_CANDIDATES as u8 - 1);
190        assert_eq!(budget.verifications, MAX_VERIFICATIONS as u8 - 1);
191    }
192
193    #[test]
194    fn lookup_with_budget_uses_authenticated_exact_hit() {
195        let mut budget = QueryBudget::initial();
196        let mut snap = QsrSnapshot::empty(Generation(1));
197        snap.insert(StrongDigest::ZERO, StrongDigest::ZERO).unwrap();
198        let covers = [CoverInterval { start: 0, end: 10 }];
199        let mut out = [StrongDigest::ZERO; 1];
200        assert_eq!(
201            lookup_with_budget(
202                &snap,
203                &StrongDigest::ZERO,
204                &covers,
205                Generation(1),
206                &mut budget,
207                &mut out
208            ),
209            Ok(QsrOutcome::Found { count: 1 })
210        );
211    }
212
213    #[test]
214    fn lookup_with_budget_empty_snapshot_is_empty_not_found() {
215        let mut budget = QueryBudget::initial();
216        let snap = QsrSnapshot::empty(Generation(1));
217        let covers = [CoverInterval { start: 0, end: 15 }];
218        let mut out = [StrongDigest::ZERO; 1];
219        assert_eq!(
220            lookup_with_budget(
221                &snap,
222                &StrongDigest::ZERO,
223                &covers,
224                Generation(1),
225                &mut budget,
226                &mut out
227            ),
228            Ok(QsrOutcome::EmptyInSnapshot)
229        );
230    }
231
232    #[test]
233    fn continuation_does_not_reset_budget() {
234        assert!(!continuation_resets_budget());
235        let mut budget = QueryBudget::initial();
236        budget.bytes = 12;
237        budget.work = 7;
238        assert!(!continuation_resets_budget());
239        assert_eq!(budget.bytes, 12);
240        assert_eq!(budget.work, 7);
241    }
242
243    #[test]
244    fn provider_silence_is_incomplete() {
245        assert_eq!(provider_silence_outcome(), QdnfError::Incomplete);
246    }
247}