Skip to main content

qualia_core_db/container_10d/section/
opaque_preservation.rs

1//! Explicit structural retention; never used implicitly by the strict reader.
2//!
3//! Unknown tags, header flags and descriptor metadata can be inspected/copied
4//! byte-exactly, not interpreted or admitted. Unknown outer header or alignment
5//! grammar refuses. Semantic edits with unresolved dependencies refuse. This
6//! does not negotiate required/optional extensions or validate typed payloads.
7use super::{
8    table_validation, AlignmentTier, SectionDescriptor, SectionTableError, SectionType,
9    SECTION_DESCRIPTOR_SIZE,
10};
11use crate::container_10d::crc32c::crc32c;
12use crate::container_10d::header::{
13    Container10dHeader, HeaderParseError, FLAG_DEFAULT_DISPOSITION_REFUSE, HEADER_VERSION,
14};
15use crate::container_10d::integrity::{
16    check_whole_file_crc32c, seal_whole_file_crc32c, IntegrityError,
17};
18
19/// Explicit limits apply before checksum traversal or output mutation. The
20/// canonical header's independent maximum section count still applies.
21#[derive(Debug, Clone, Copy, PartialEq, Eq)]
22pub struct OpaquePreservationBudget {
23    pub max_bytes: usize,
24    pub max_sections: usize,
25}
26
27#[derive(Debug, Clone, PartialEq, Eq)]
28pub enum OpaquePreservationError {
29    Header(HeaderParseError),
30    Integrity(IntegrityError),
31    Section(SectionTableError),
32    ByteBudget { needed: usize, maximum: usize },
33    SectionBudget { needed: usize, maximum: usize },
34    OutputTooSmall { needed: usize, have: usize },
35    UnsupportedTarget { section_type: u8 },
36    MissingTarget { section_type: u8 },
37    LengthChangeUnsupported { existing: usize, replacement: usize },
38    UnknownHeaderFlags { flags: u16 },
39    ReservedDescriptorMetadata { index: usize, reserved16: u16 },
40    UnresolvedDependencies { section_type: u8 },
41    OpaqueTailBytes { at: usize },
42}
43
44impl From<HeaderParseError> for OpaquePreservationError {
45    fn from(value: HeaderParseError) -> Self {
46        Self::Header(value)
47    }
48}
49impl From<IntegrityError> for OpaquePreservationError {
50    fn from(value: IntegrityError) -> Self {
51        Self::Integrity(value)
52    }
53}
54impl From<SectionTableError> for OpaquePreservationError {
55    fn from(value: SectionTableError) -> Self {
56        Self::Section(value)
57    }
58}
59impl std::fmt::Display for OpaquePreservationError {
60    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
61        write!(f, "10d opaque preservation: {self:?}")
62    }
63}
64impl std::error::Error for OpaquePreservationError {}
65
66/// Fully structurally checked immutable bytes. This is not a typed-admission
67/// token. Private fields prevent callers constructing a view from unchecked data.
68#[derive(Debug)]
69pub struct OpaqueContainerView<'a> {
70    bytes: &'a [u8],
71    header: Container10dHeader,
72    sections: &'a [SectionDescriptor],
73}
74impl<'a> OpaqueContainerView<'a> {
75    pub fn bytes(&self) -> &'a [u8] {
76        self.bytes
77    }
78    pub fn header(&self) -> &Container10dHeader {
79        &self.header
80    }
81    pub fn sections(&self) -> &'a [SectionDescriptor] {
82        self.sections
83    }
84    /// Raw bytes only; no section semantics are asserted.
85    pub fn payload(&self, index: usize) -> Option<&'a [u8]> {
86        let d = self.sections.get(index)?;
87        Some(&self.bytes[d.byte_offset as usize..d.byte_offset as usize + d.byte_length as usize])
88    }
89}
90
91/// Validate the complete supported envelope without decoding unknown payloads.
92/// Padding follows the canonical reader (interior zero; tail opaque). Nonzero
93/// descriptor reserved16 and unknown header flags are retained only here.
94/// Returns a typed error for an unaligned descriptor table, never a cast panic.
95pub fn inspect_opaque_container(
96    data: &[u8],
97    budget: OpaquePreservationBudget,
98) -> Result<OpaqueContainerView<'_>, OpaquePreservationError> {
99    if data.len() > budget.max_bytes {
100        return Err(OpaquePreservationError::ByteBudget {
101            needed: data.len(),
102            maximum: budget.max_bytes,
103        });
104    }
105    let header = Container10dHeader::parse(data)?;
106    let count = header.section_count as usize;
107    if count > budget.max_sections {
108        return Err(OpaquePreservationError::SectionBudget {
109            needed: count,
110            maximum: budget.max_sections,
111        });
112    }
113    check_whole_file_crc32c(data)?;
114    let sections = inspect_table(data, &header)?;
115    Ok(OpaqueContainerView {
116        bytes: data,
117        header,
118        sections,
119    })
120}
121
122fn inspect_table<'a>(
123    data: &'a [u8],
124    header: &Container10dHeader,
125) -> Result<&'a [SectionDescriptor], SectionTableError> {
126    if header.section_count == 0 {
127        return Ok(&[]);
128    }
129    // Header parser established pointer/count bounds; checked_add also covers
130    // a 32-bit target near usize::MAX before any slicing or metadata arithmetic.
131    let start = header.section_table_offset as usize;
132    let end = start
133        .checked_add(header.section_count as usize * SECTION_DESCRIPTOR_SIZE)
134        .ok_or(SectionTableError::BadSectionTablePointer {
135            offset: header.section_table_offset,
136            count: header.section_count,
137        })?;
138    let table = data
139        .get(start..end)
140        .ok_or(SectionTableError::InputTooShort {
141            got: data.len(),
142            need: end,
143        })?;
144    let descriptors = table_validation::borrow_table(table)?;
145    for (index, d) in descriptors.iter().enumerate() {
146        if d.section_type == 0 {
147            return Err(SectionTableError::UndefinedSectionType { index, got: 0 });
148        }
149        if descriptors[..index]
150            .iter()
151            .any(|old| old.section_type == d.section_type)
152        {
153            return Err(SectionTableError::DuplicateSectionType {
154                section_type: d.section_type,
155            });
156        }
157        if d.typ() == Some(SectionType::ManifoldIdentityV2) && header.version < HEADER_VERSION {
158            return Err(SectionTableError::SectionRequiresVersion {
159                section_type: d.section_type,
160                minimum_version: HEADER_VERSION,
161                actual_version: header.version,
162            });
163        }
164        let tier = AlignmentTier::from_u8(d.alignment_tier).ok_or(
165            SectionTableError::UndefinedAlignmentTier {
166                index,
167                got: d.alignment_tier,
168            },
169        )?;
170        let offset = d.byte_offset as usize;
171        let length = d.byte_length as usize;
172        if offset % tier.to_bytes() != 0 {
173            return Err(SectionTableError::MisalignedSection {
174                index,
175                offset: d.byte_offset,
176                tier,
177            });
178        }
179        let bounds_error = || SectionTableError::OutOfBounds {
180            index,
181            offset: d.byte_offset,
182            length: d.byte_length,
183            file_len: data.len(),
184        };
185        let payload_end = offset.checked_add(length).ok_or_else(bounds_error)?;
186        let payload = data.get(offset..payload_end).ok_or_else(bounds_error)?;
187        // Structural retention permits unknown tags/reserved metadata. Keep
188        // the same payload/header/table exclusion without the strict typed
189        // descriptor validator, which intentionally rejects those extensions.
190        if length != 0
191            && (offset < super::HEADER_BYTE_SIZE || (offset < end && payload_end > start))
192        {
193            return Err(SectionTableError::SectionOverlapsMetadata { index });
194        }
195        if d.stride != 0
196            && u64::from(d.stride) * u64::from(d.element_count) != u64::from(d.byte_length)
197        {
198            return Err(SectionTableError::StrideInconsistentDescriptor {
199                index,
200                stride: d.stride,
201                element_count: d.element_count,
202                byte_length: d.byte_length,
203            });
204        }
205        let actual = crc32c(payload);
206        if actual != d.crc32c {
207            return Err(SectionTableError::CrcMismatch {
208                index,
209                section_type: d.section_type,
210                expected: d.crc32c,
211                got: actual,
212            });
213        }
214        for (previous, old) in descriptors[..index].iter().enumerate() {
215            // Every earlier descriptor has already passed checked bounds.
216            if length != 0
217                && old.byte_length != 0
218                && offset < old.byte_offset as usize + old.byte_length as usize
219                && (old.byte_offset as usize) < payload_end
220            {
221                return Err(SectionTableError::OverlappingSections {
222                    index_a: previous,
223                    index_b: index,
224                });
225            }
226        }
227    }
228    table_validation::padding(data, descriptors, start, end)?;
229    Ok(descriptors)
230}
231
232fn capacity(out: &[u8], needed: usize) -> Result<(), OpaquePreservationError> {
233    if out.len() < needed {
234        Err(OpaquePreservationError::OutputTooSmall {
235            needed,
236            have: out.len(),
237        })
238    } else {
239        Ok(())
240    }
241}
242
243/// Copy the complete structurally checked envelope byte-exactly. All checks
244/// finish before output mutation; output suffix is untouched. Safe Rust borrows
245/// exclude overlapping source/output. This grants no authority over unknowns.
246pub fn copy_opaque_container_into(
247    data: &[u8],
248    budget: OpaquePreservationBudget,
249    out: &mut [u8],
250) -> Result<usize, OpaquePreservationError> {
251    let view = inspect_opaque_container(data, budget)?;
252    capacity(out, view.bytes.len())?;
253    out[..data.len()].copy_from_slice(data);
254    Ok(data.len())
255}
256
257/// Replace one implemented section's raw bytes at the same offset and length,
258/// retaining every unrelated byte. Typed payload correctness and known semantic
259/// dependency admission remain the caller's job; this is not a material/mesh
260/// validator. Refuses changed bytes if any unknown flags, reserved metadata or
261/// unimplemented section could hide a dependency. Byte-identical no-ops may copy
262/// structurally checked unknowns. Section addition/relocation is unsupported.
263/// Every error precedes mutation; only payload and its two CRC layers change.
264pub fn replace_known_section_bytes_preserving_layout(
265    data: &[u8],
266    section_type: SectionType,
267    replacement: &[u8],
268    budget: OpaquePreservationBudget,
269    out: &mut [u8],
270) -> Result<usize, OpaquePreservationError> {
271    let view = inspect_opaque_container(data, budget)?;
272    if !section_type.is_implemented() {
273        return Err(OpaquePreservationError::UnsupportedTarget {
274            section_type: section_type as u8,
275        });
276    }
277    let index = view
278        .sections
279        .iter()
280        .position(|d| d.typ() == Some(section_type))
281        .ok_or(OpaquePreservationError::MissingTarget {
282            section_type: section_type as u8,
283        })?;
284    let target = view.sections[index];
285    if replacement.len() != target.byte_length as usize {
286        return Err(OpaquePreservationError::LengthChangeUnsupported {
287            existing: target.byte_length as usize,
288            replacement: replacement.len(),
289        });
290    }
291    let unchanged = view.payload(index) == Some(replacement);
292    if !unchanged {
293        let flags = view.header.flags & !FLAG_DEFAULT_DISPOSITION_REFUSE;
294        if flags != 0 {
295            return Err(OpaquePreservationError::UnknownHeaderFlags { flags });
296        }
297        for (index, d) in view.sections.iter().enumerate() {
298            if d.reserved16 != 0 {
299                return Err(OpaquePreservationError::ReservedDescriptorMetadata {
300                    index,
301                    reserved16: d.reserved16,
302                });
303            }
304            if !d.typ().is_some_and(SectionType::is_implemented) {
305                return Err(OpaquePreservationError::UnresolvedDependencies {
306                    section_type: d.section_type,
307                });
308            }
309        }
310        // The strict table grammar deliberately does not interpret trailing
311        // bytes. Retain them for copies, but do not assume they are independent
312        // of an edited section. Zero tail padding carries no additional bytes.
313        let occupied_end = view
314            .sections
315            .iter()
316            .filter(|d| d.byte_length != 0)
317            .map(|d| d.byte_offset as usize + d.byte_length as usize)
318            .max()
319            .unwrap_or(0)
320            .max(
321                view.header.section_table_offset as usize
322                    + view.sections.len() * SECTION_DESCRIPTOR_SIZE,
323            )
324            .max(crate::container_10d::header::HEADER_BYTE_SIZE);
325        if let Some(relative) = data[occupied_end..].iter().position(|b| *b != 0) {
326            return Err(OpaquePreservationError::OpaqueTailBytes {
327                at: occupied_end + relative,
328            });
329        }
330    }
331    capacity(out, data.len())?;
332    // Commit point: all validation, policy and capacity failures are above.
333    out[..data.len()].copy_from_slice(data);
334    if !unchanged {
335        let offset = target.byte_offset as usize;
336        out[offset..offset + replacement.len()].copy_from_slice(replacement);
337        let crc_offset = view.header.section_table_offset as usize
338            + index * SECTION_DESCRIPTOR_SIZE
339            + std::mem::offset_of!(SectionDescriptor, crc32c);
340        out[crc_offset..crc_offset + 4].copy_from_slice(&crc32c(replacement).to_le_bytes());
341        seal_whole_file_crc32c(&mut out[..data.len()]);
342    }
343    Ok(data.len())
344}