Skip to main content

qualia_core_db/q42/field_envelope/
reader.rs

1use super::*;
2/// Directory fields remain uninterpreted until family semantic admission.
3#[derive(Clone, Copy, Debug)]
4pub struct Entry<'a> {
5    bytes: &'a [u8],
6}
7impl<'a> Entry<'a> {
8    pub fn mode(self) -> u16 {
9        u16le(self.bytes, 0)
10    }
11    pub fn revision(self) -> u16 {
12        u16le(self.bytes, 2)
13    }
14    pub fn flags(self) -> u32 {
15        u32le(self.bytes, 4)
16    }
17    pub fn stream_id(self) -> u32 {
18        u32le(self.bytes, 8)
19    }
20    pub fn frame_id(self) -> u32 {
21        u32le(self.bytes, 12)
22    }
23    pub fn start_tick(self) -> i64 {
24        u64le(self.bytes, 16) as i64
25    }
26    pub fn time_count(self) -> u64 {
27        u64le(self.bytes, 24)
28    }
29    pub fn spatial_key(self) -> u64 {
30        u64le(self.bytes, 32)
31    }
32    pub fn payload_offset(self) -> u64 {
33        u64le(self.bytes, 40)
34    }
35    pub fn stored_bytes(self) -> u64 {
36        u64le(self.bytes, 48)
37    }
38    pub fn decoded_bytes(self) -> u64 {
39        u64le(self.bytes, 56)
40    }
41    pub fn record_count(self) -> u64 {
42        u64le(self.bytes, 64)
43    }
44    pub fn stride(self) -> u32 {
45        u32le(self.bytes, 72)
46    }
47    pub fn descriptor_id(self) -> u32 {
48        u32le(self.bytes, 112)
49    }
50    pub fn digest(self) -> &'a [u8] {
51        &self.bytes[80..112]
52    }
53    pub fn raw_directory_bytes(self) -> &'a [u8] {
54        self.bytes
55    }
56    fn key(self) -> (u32, i64, u64, u16, u32) {
57        (
58            self.stream_id(),
59            self.start_tick(),
60            self.spatial_key(),
61            self.mode(),
62            self.descriptor_id(),
63        )
64    }
65}
66/// Borrowed structural/index validation only; no scientific admission or authentication.
67#[derive(Debug)]
68pub struct StructuralView<'a> {
69    bytes: &'a [u8],
70    family: Family,
71    directory: &'a [u8],
72    metadata: &'a [u8],
73}
74impl<'a> StructuralView<'a> {
75    pub fn open(bytes: &'a [u8], family: Family, limits: Limits) -> Result<Self, Error> {
76        let magic = bytes.get(..8).ok_or(Error::Extent)?;
77        if magic != family.magic() {
78            return Err(Error::Family);
79        }
80        let h = bytes.get(..128).ok_or(Error::Extent)?;
81        if u16le(h, 8) != family.version() {
82            return Err(Error::Version);
83        }
84        crc(h)?;
85        if bytes.len() as u64 > limits.file_bytes {
86            return Err(Error::Limit);
87        }
88        if u16le(h, 10) != 128
89            || u32le(h, 12) & !1 != 0
90            || u64le(h, 16) != bytes.len() as u64
91            || u64le(h, 24) != 128
92            || u16le(h, 36) != 128
93            || u16le(h, 38) != 1
94        {
95            return Err(Error::Header);
96        }
97        zero(&h[88..124])?;
98        let count = u32le(h, 32);
99        let meta_len = u64le(h, 48);
100        if count > limits.entries || meta_len > limits.metadata_bytes {
101            return Err(Error::Limit);
102        }
103        let dir_len = u64::from(count).checked_mul(128).ok_or(Error::Overflow)?;
104        let meta_start = 128u64.checked_add(dir_len).ok_or(Error::Overflow)?;
105        if u64le(h, 40) != meta_start {
106            return Err(Error::Header);
107        }
108        let directory = extent(bytes, 128, dir_len)?;
109        let metadata = extent(bytes, meta_start, meta_len)?;
110        let alignment = if u32le(h, 12) & 1 != 0 { 4096 } else { 64 };
111        let meta_end = meta_start.checked_add(meta_len).ok_or(Error::Overflow)?;
112        let mut next = align(meta_end, alignment)?;
113        zero(extent(bytes, meta_end, next - meta_end)?)?;
114        let mut prior = None;
115        let mut decoded = 0u64;
116        for row in directory.chunks_exact(128) {
117            crc(row)?;
118            zero(&row[78..80])?;
119            zero(&row[116..124])?;
120            let e = Entry { bytes: row };
121            if e.flags() & !7 != 0
122                || e.descriptor_id() == 0
123                || e.stride() == 0
124                || e.record_count() == 0
125            {
126                return Err(Error::Directory);
127            }
128            if u16le(row, 76) != 0 {
129                return Err(Error::Codec);
130            }
131            if (e.flags() & 2 == 0 && (e.start_tick() != 0 || e.time_count() != 0))
132                || (e.flags() & 2 != 0 && e.time_count() == 0)
133                || (e.flags() & 4 == 0 && e.spatial_key() != 0)
134            {
135                return Err(Error::Directory);
136            }
137            if prior.is_some_and(|p| p >= e.key()) {
138                return Err(Error::Order);
139            }
140            prior = Some(e.key());
141            let size = e
142                .record_count()
143                .checked_mul(u64::from(e.stride()))
144                .ok_or(Error::Overflow)?;
145            if size != e.stored_bytes() || size != e.decoded_bytes() || e.payload_offset() != next {
146                return Err(Error::Directory);
147            }
148            decoded = decoded.checked_add(size).ok_or(Error::Overflow)?;
149            if size > limits.chunk_bytes || decoded > limits.aggregate_decoded_bytes {
150                return Err(Error::Limit);
151            }
152            extent(bytes, next, size)?;
153            let end = next.checked_add(size).ok_or(Error::Overflow)?;
154            next = align(end, alignment)?;
155            zero(extent(bytes, end, next - end)?)?;
156        }
157        if next != bytes.len() as u64 {
158            return Err(Error::Extent);
159        }
160        let mut root_header = [0; 128];
161        root_header.copy_from_slice(h);
162        root_header[56..88].fill(0);
163        root_header[124..128].fill(0);
164        let mut hasher = blake3::Hasher::new();
165        hasher.update(INDEX_DOMAIN);
166        hasher.update(&root_header);
167        hasher.update(directory);
168        hasher.update(metadata);
169        if hasher.finalize().as_bytes()[..] != h[56..88] {
170            return Err(Error::IndexDigest);
171        }
172        metadata::validate(metadata, limits)?;
173        Ok(Self {
174            bytes,
175            family,
176            directory,
177            metadata,
178        })
179    }
180    pub fn family(&self) -> Family {
181        self.family
182    }
183    pub fn entry_count(&self) -> u32 {
184        (self.directory.len() / 128) as u32
185    }
186    /// One-based directory index; zero is absent and rejected here.
187    pub fn entry(&self, index: u32) -> Result<Entry<'a>, Error> {
188        let n = index.checked_sub(1).ok_or(Error::EntryIndex)?;
189        Ok(Entry {
190            bytes: extent(self.directory, u64::from(n) * 128, 128)
191                .map_err(|_| Error::EntryIndex)?,
192        })
193    }
194    pub fn blocks(&self) -> Blocks<'a> {
195        Blocks::new(self.metadata)
196    }
197    pub fn metadata_bytes(&self) -> &'a [u8] {
198        self.metadata
199    }
200    pub fn index_digest(&self) -> &'a [u8] {
201        &self.bytes[56..88]
202    }
203    /// Whole stored-chunk digest verification, still no scientific/numeric claim.
204    pub fn verify_chunk(&self, index: u32) -> Result<&'a [u8], Error> {
205        let e = self.entry(index)?;
206        let bytes = extent(self.bytes, e.payload_offset(), e.stored_bytes())?;
207        if blake3::hash(bytes).as_bytes()[..] != *e.digest() {
208            return Err(Error::PayloadDigest);
209        }
210        Ok(bytes)
211    }
212}