Skip to main content

qualia_core_db/bundle/stream/storage/
bitmap.rs

1//! Caller-owned candidate marks and untrusted restart hints; neither establishes presence.
2#[path = "bitmap/owned.rs"]
3mod owned;
4pub use owned::OwnedIntegrityPage;
5
6use super::{StorageError as E, StorageIdentity, VerifiedLeafView};
7pub const BITMAP_BYTES: usize = 4096;
8pub const LEAVES_PER_PAGE: u64 = (BITMAP_BYTES as u64) * 8;
9#[derive(Clone, Copy, Debug, PartialEq, Eq)]
10pub enum MarkStatus {
11    New,
12    AlreadyMarked,
13}
14pub(super) fn geometry(identity: &StorageIdentity, page: u64) -> Result<(u64, usize), E> {
15    let first = page.checked_mul(LEAVES_PER_PAGE).ok_or(E::Overflow)?;
16    let count = identity.leaf_count();
17    if first >= count {
18        return Err(E::Bounds);
19    }
20    Ok((first, (count - first).min(LEAVES_PER_PAGE) as usize))
21}
22fn bit(identity: &StorageIdentity, page: u64, index: u64) -> Result<(usize, u8), E> {
23    let (first, valid) = geometry(identity, page)?;
24    if index >= identity.leaf_count() {
25        return Err(E::Bounds);
26    }
27    if index < first {
28        return Err(E::PageMismatch);
29    }
30    let local = index - first;
31    if local >= valid as u64 {
32        return Err(E::PageMismatch);
33    }
34    let local = usize::try_from(local).map_err(|_| E::Overflow)?;
35    Ok((local / 8, 1u8 << (local % 8)))
36}
37pub(super) fn validate_tail(payload: &[u8; BITMAP_BYTES], valid: usize) -> Result<(), E> {
38    let mut first = valid / 8;
39    let bits = valid % 8;
40    if bits != 0 {
41        let mask = ((1u16 << bits) - 1) as u8;
42        if payload[first] & !mask != 0 {
43            return Err(E::Bounds);
44        }
45        first += 1;
46    }
47    if payload[first..].iter().any(|b| *b != 0) {
48        return Err(E::Bounds);
49    }
50    Ok(())
51}
52/// Fresh marks require actual VerifiedLeafView; never constructed from resume bits.
53pub struct CandidateBitmapPage<'a> {
54    identity: StorageIdentity,
55    page: u64,
56    payload: &'a mut [u8; BITMAP_BYTES],
57}
58impl<'a> CandidateBitmapPage<'a> {
59    pub fn new(
60        identity: StorageIdentity,
61        page: u64,
62        payload: &'a mut [u8; BITMAP_BYTES],
63    ) -> Result<Self, E> {
64        geometry(&identity, page)?;
65        payload.fill(0);
66        Ok(Self {
67            identity,
68            page,
69            payload,
70        })
71    }
72    pub const fn identity(&self) -> &StorageIdentity {
73        &self.identity
74    }
75    pub const fn page_number(&self) -> u64 {
76        self.page
77    }
78    pub fn payload(&self) -> &[u8; BITMAP_BYTES] {
79        self.payload
80    }
81    pub fn record_integrity(&mut self, leaf: &VerifiedLeafView<'_>) -> Result<MarkStatus, E> {
82        if *leaf.identity() != self.identity {
83            return Err(E::IdentityMismatch);
84        }
85        let (byte, mask) = bit(&self.identity, self.page, leaf.leaf_index())?;
86        let previous = self.payload[byte] & mask != 0;
87        self.payload[byte] |= mask;
88        Ok(if previous {
89            MarkStatus::AlreadyMarked
90        } else {
91            MarkStatus::New
92        })
93    }
94    pub fn has_integrity_mark(&self, index: u64) -> Result<bool, E> {
95        let (byte, mask) = bit(&self.identity, self.page, index)?;
96        Ok(self.payload[byte] & mask != 0)
97    }
98}
99/// Borrowed untrusted bitmap claims. No method promotes a claim to verified leaf bytes.
100pub struct ResumeHint<'a> {
101    pub(super) identity: StorageIdentity,
102    pub(super) page: u64,
103    pub(super) sequence: u64,
104    pub(super) payload: &'a [u8; BITMAP_BYTES],
105}
106impl ResumeHint<'_> {
107    pub const fn identity(&self) -> &StorageIdentity {
108        &self.identity
109    }
110    pub const fn page_number(&self) -> u64 {
111        self.page
112    }
113    pub const fn sequence(&self) -> u64 {
114        self.sequence
115    }
116    pub fn claims_leaf(&self, index: u64) -> Result<bool, E> {
117        let (byte, mask) = bit(&self.identity, self.page, index)?;
118        Ok(self.payload[byte] & mask != 0)
119    }
120}
121
122impl core::fmt::Debug for ResumeHint<'_> {
123    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
124        f.debug_struct("ResumeHint")
125            .field("page", &self.page)
126            .field("sequence", &self.sequence)
127            .finish_non_exhaustive()
128    }
129}
130impl core::fmt::Debug for CandidateBitmapPage<'_> {
131    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
132        f.debug_struct("CandidateBitmapPage")
133            .field("page", &self.page)
134            .finish_non_exhaustive()
135    }
136}