Skip to main content

qualia_core_db/q42/field_envelope/
writer.rs

1//! Caller-buffered candidate storage writer. This does not admit scientific schemas.
2use super::*;
3
4/// Raw stored payload and its uninterpreted directory fields. Codec 0 only.
5#[derive(Clone, Copy, Debug)]
6pub struct EntryInput<'a> {
7    pub mode: u16,
8    pub revision: u16,
9    pub flags: u32,
10    pub stream_id: u32,
11    pub frame_id: u32,
12    pub start_tick: i64,
13    pub time_count: u64,
14    pub spatial_key: u64,
15    pub record_count: u64,
16    pub stride: u32,
17    pub codec: u16,
18    pub descriptor_id: u32,
19    pub payload: &'a [u8],
20}
21impl EntryInput<'_> {
22    fn key(&self) -> (u32, i64, u64, u16, u32) {
23        (
24            self.stream_id,
25            self.start_tick,
26            self.spatial_key,
27            self.mode,
28            self.descriptor_id,
29        )
30    }
31    fn validate(&self) -> Result<u64, Error> {
32        if self.codec != 0 {
33            return Err(Error::Codec);
34        }
35        if self.flags & !7 != 0
36            || self.descriptor_id == 0
37            || self.stride == 0
38            || self.record_count == 0
39        {
40            return Err(Error::Directory);
41        }
42        if (self.flags & 2 == 0 && (self.start_tick != 0 || self.time_count != 0))
43            || (self.flags & 2 != 0 && (self.time_count == 0 || self.stream_id == 0))
44            || (self.flags & 4 == 0 && self.spatial_key != 0)
45            || (self.flags & 4 != 0 && self.frame_id == 0)
46        {
47            return Err(Error::Directory);
48        }
49        let size = self
50            .record_count
51            .checked_mul(u64::from(self.stride))
52            .ok_or(Error::Overflow)?;
53        if size != self.payload.len() as u64 {
54            return Err(Error::Directory);
55        }
56        Ok(size)
57    }
58}
59
60/// Exact metadata bytes are preserved, including unknown critical information.
61/// The caller must separately admit family schemas, references, modes and values.
62#[derive(Clone, Copy, Debug)]
63pub struct EnvelopeInput<'a> {
64    pub family: Family,
65    /// Bit 0 selects 4096-byte payload alignment, otherwise 64. Other bits reject.
66    pub flags: u32,
67    pub metadata: &'a [u8],
68    pub entries: &'a [EntryInput<'a>],
69}
70impl EnvelopeInput<'_> {
71    /// Validate every structural input and budget before returning the exact size.
72    /// No allocation, hashing, output mutation or scientific admission occurs.
73    pub fn encoded_len(&self, limits: Limits) -> Result<usize, Error> {
74        if self.flags & !1 != 0 {
75            return Err(Error::Header);
76        }
77        if self.entries.len() as u64 > u64::from(limits.entries)
78            || self.metadata.len() as u64 > limits.metadata_bytes
79        {
80            return Err(Error::Limit);
81        }
82        metadata::validate(self.metadata, limits)?;
83        let directory = (self.entries.len() as u64)
84            .checked_mul(128)
85            .ok_or(Error::Overflow)?;
86        let meta_start = 128u64.checked_add(directory).ok_or(Error::Overflow)?;
87        let end = meta_start
88            .checked_add(self.metadata.len() as u64)
89            .ok_or(Error::Overflow)?;
90        let alignment = if self.flags & 1 == 0 { 64 } else { 4096 };
91        let mut next = align(end, alignment)?;
92        let mut decoded = 0u64;
93        let mut prior = None;
94        for entry in self.entries {
95            let size = entry.validate()?;
96            if prior.is_some_and(|p| p >= entry.key()) {
97                return Err(Error::Order);
98            }
99            prior = Some(entry.key());
100            decoded = decoded.checked_add(size).ok_or(Error::Overflow)?;
101            if size > limits.chunk_bytes || decoded > limits.aggregate_decoded_bytes {
102                return Err(Error::Limit);
103            }
104            next = align(next.checked_add(size).ok_or(Error::Overflow)?, alignment)?;
105        }
106        if next > limits.file_bytes {
107            return Err(Error::Limit);
108        }
109        usize::try_from(next).map_err(|_| Error::Extent)
110    }
111
112    /// Validate the whole input and output capacity BEFORE touching output.
113    /// On success only the returned prefix is changed; a longer buffer tail is kept.
114    /// Borrow rules prevent payload/metadata aliasing the mutable output slice.
115    pub fn encode_into<'out>(
116        &self,
117        output: &'out mut [u8],
118        limits: Limits,
119    ) -> Result<&'out mut [u8], Error> {
120        let len = self.encoded_len(limits)?;
121        if output.len() < len {
122            return Err(Error::Extent);
123        }
124        let out = &mut output[..len];
125        out.fill(0);
126        let meta_start = 128 + self.entries.len() * 128;
127        let meta_end = meta_start + self.metadata.len();
128        out[meta_start..meta_end].copy_from_slice(self.metadata);
129        let alignment = if self.flags & 1 == 0 { 64 } else { 4096 };
130        let mut cursor = (meta_end + alignment - 1) & !(alignment - 1);
131        for (index, entry) in self.entries.iter().enumerate() {
132            let end = cursor + entry.payload.len();
133            out[cursor..end].copy_from_slice(entry.payload);
134            let row = &mut out[128 + index * 128..256 + index * 128];
135            put16(row, 0, entry.mode);
136            put16(row, 2, entry.revision);
137            put32(row, 4, entry.flags);
138            put32(row, 8, entry.stream_id);
139            put32(row, 12, entry.frame_id);
140            put64(row, 16, entry.start_tick as u64);
141            put64(row, 24, entry.time_count);
142            put64(row, 32, entry.spatial_key);
143            put64(row, 40, cursor as u64);
144            put64(row, 48, entry.payload.len() as u64);
145            put64(row, 56, entry.payload.len() as u64);
146            put64(row, 64, entry.record_count);
147            put32(row, 72, entry.stride);
148            // Codec and all reserved bytes were zeroed before writing.
149            row[80..112].copy_from_slice(blake3::hash(entry.payload).as_bytes());
150            put32(row, 112, entry.descriptor_id);
151            seal_crc(row);
152            cursor = (end + alignment - 1) & !(alignment - 1);
153        }
154        let header = &mut out[..128];
155        header[..8].copy_from_slice(self.family.magic());
156        put16(header, 8, self.family.version());
157        put16(header, 10, 128);
158        put32(header, 12, self.flags);
159        put64(header, 16, len as u64);
160        put64(header, 24, 128);
161        put32(header, 32, self.entries.len() as u32);
162        put16(header, 36, 128);
163        put16(header, 38, 1);
164        put64(header, 40, meta_start as u64);
165        put64(header, 48, self.metadata.len() as u64);
166        // Root and CRC fields are still zero; hash the exact encoded bytes.
167        let mut hasher = blake3::Hasher::new();
168        hasher.update(INDEX_DOMAIN);
169        hasher.update(&out[..128]);
170        hasher.update(&out[128..meta_start]);
171        hasher.update(&out[meta_start..meta_end]);
172        out[56..88].copy_from_slice(hasher.finalize().as_bytes());
173        seal_crc(&mut out[..128]);
174        Ok(out)
175    }
176}
177fn put16(bytes: &mut [u8], at: usize, value: u16) {
178    bytes[at..at + 2].copy_from_slice(&value.to_le_bytes());
179}
180fn put32(bytes: &mut [u8], at: usize, value: u32) {
181    bytes[at..at + 4].copy_from_slice(&value.to_le_bytes());
182}
183fn put64(bytes: &mut [u8], at: usize, value: u64) {
184    bytes[at..at + 8].copy_from_slice(&value.to_le_bytes());
185}
186fn seal_crc(bytes: &mut [u8]) {
187    let value = crate::container_10d::crc32c::crc32c(bytes);
188    put32(bytes, 124, value);
189}