Skip to main content

qualia_core_db/net/qdnf/resolve/qsr/
mod.rs

1//! Qualia Scoped Rendezvous exact lookup (QSR-A through QSR-H, E07.4–E07.8).
2//!
3//! Digit indexing, cover validation, closed-world snapshot traversal, tagged
4//! outcomes, membership-versus-completeness evidence, scoped private tokens,
5//! hot-key coalescing, writer handover, closed-world XOR comparison, and an
6//! in-process k-bucket table. In-process k-buckets are not equivalent
7//! transport, crypto, or replication Kademlia and are not a two-host overlay.
8//! Authenticated lookup never returns bool. Found/EmptyInSnapshot is not
9//! completeness.
10
11mod compare;
12mod completeness;
13mod cover;
14mod exact;
15mod handover;
16mod hot;
17mod kbucket;
18mod key;
19mod outcome;
20mod roots;
21mod tokens;
22mod traversal;
23
24pub use compare::{
25    in_process_kbucket_comparison_executed, kademlia_comparison_executed, local_xor_nearest,
26    networked_kademlia_comparison_executed, run_closed_world_comparison,
27    run_in_process_kbucket_comparison, unmeasured_better_than_kademlia_claimed, xor_distance,
28    ClosedWorldComparison, KBucketComparison, LOCAL_XOR_CAP,
29};
30pub use completeness::{
31    absence_is_authoritative, lookup_with_completeness, membership_implies_completeness,
32    CompletenessEvidence, CompletenessKind, QsrAnswer,
33};
34pub use cover::{covers_digit, lookup_exact, validate_cover, CoverInterval};
35pub use exact::{HandoverStage, Qsr, TokenStage};
36pub use handover::{
37    accept_mutation, activate_new, admit_write, drain_accepted, fence_old, lookup_via_handover,
38    persist_boundary, Handover, WriterEpoch, ACCEPTED_CAP,
39};
40pub use hot::{
41    coalesce_hot, insert_parent, partition_record, ParentTable, Partition, MAX_HOT_REPLICAS,
42    PARENT_CAP,
43};
44pub use kbucket::{
45    bucket_index, KBucketTable, ALPHA, BUCKET_COUNT, CONTACT_CAP, K, STALE_GENERATIONS,
46};
47pub use key::{digit, keys_equal, DIGIT_RADIX, KEY_DEPTH};
48pub use outcome::QsrOutcome;
49pub use roots::{bind_roots, snapshot_root, IndexRoots, SNAPSHOT_ROOT_DOMAIN};
50pub use tokens::{
51    admit_token, empty_in_snapshot_does_not_enumerate_neighbors, issue_token, lookup_private,
52    token_reveals_degree, PrivateToken, TOKEN_DOMAIN,
53};
54pub use traversal::{lookup as lookup_snapshot, lookup_into, QsrSnapshot, SNAPSHOT_CAP};
55
56use crate::net::qdnf::errors::QdnfError;
57use crate::net::qdnf::types::{Generation, StrongDigest};
58
59/// Public QSR lookup: exact cover/snapshot, then tokens, then handover.
60///
61/// Cover membership ([`lookup_exact`]) is not existence. [`QsrOutcome::Found`]
62/// is membership, not completeness. `NativePeer::lookup_qsr` remains cover-only;
63/// `NativePeer::lookup_qsr_full` calls this production path.
64pub fn lookup_qsr_full(
65    key: &StrongDigest,
66    covers: &[CoverInterval],
67    snapshot: &QsrSnapshot,
68    required_generation: Generation,
69    token: Option<TokenStage<'_>>,
70    handover: Option<HandoverStage<'_>>,
71    out: &mut [StrongDigest],
72) -> Result<QsrOutcome, QdnfError> {
73    Qsr::lookup(
74        key,
75        covers,
76        snapshot,
77        required_generation,
78        token,
79        handover,
80        out,
81    )
82}
83
84/// Same staged lookup as [`lookup_qsr_full`]. Snapshot-only closed-world
85/// membership remains [`lookup_snapshot`] / [`lookup_into`].
86pub fn lookup(
87    key: &StrongDigest,
88    covers: &[CoverInterval],
89    snapshot: &QsrSnapshot,
90    required_generation: Generation,
91    token: Option<TokenStage<'_>>,
92    handover: Option<HandoverStage<'_>>,
93    out: &mut [StrongDigest],
94) -> Result<QsrOutcome, QdnfError> {
95    lookup_qsr_full(
96        key,
97        covers,
98        snapshot,
99        required_generation,
100        token,
101        handover,
102        out,
103    )
104}