Skip to main content

qualia_core_db/q42/field_envelope/
mod.rs

1//! Common current-format EMF/QAC storage envelope, with no scientific admission.
2//!
3//! Successful parsing checks bounded byte structure and index integrity only.
4//! Unknown modes, schemas, revisions, critical fields and references are exposed
5//! uninterpreted. Family adapters MUST admit these, resolve reference graphs,
6//! check shapes/units and verify requested whole chunks before scientific use.
7//! This module does not authenticate publishers or implement range proofs.
8
9mod metadata;
10mod metadata_writer;
11mod reader;
12mod writer;
13pub use metadata::{Block, Blocks, Field, Fields};
14pub use metadata_writer::{BlockInput, FieldInput, FieldValue, MetadataInput};
15pub use reader::{Entry, StructuralView};
16pub use writer::{EntryInput, EnvelopeInput};
17
18pub const HEADER_BYTES: usize = 128;
19pub const DIRECTORY_BYTES: usize = 128;
20pub const INDEX_DOMAIN: &[u8] = b"QUALIA-FIELD-INDEX-v1\0";
21
22/// Current structural family selectors. Variant names retain their development
23/// spellings until a coordinated API rename; they do not define dispatch defaults.
24#[derive(Clone, Copy, Debug, PartialEq, Eq)]
25pub enum Family {
26    QacV1Candidate,
27    EmfV4Candidate,
28}
29impl Family {
30    pub fn magic(self) -> &'static [u8; 8] {
31        match self {
32            Self::QacV1Candidate => b"qac\0\0\0\0\0",
33            Self::EmfV4Candidate => b"Q42EMF64",
34        }
35    }
36    pub fn version(self) -> u16 {
37        match self {
38            Self::QacV1Candidate => 1,
39            Self::EmfV4Candidate => 4,
40        }
41    }
42}
43
44#[derive(Clone, Copy, Debug, PartialEq, Eq)]
45pub struct Limits {
46    pub file_bytes: u64,
47    pub metadata_bytes: u64,
48    pub entries: u32,
49    pub blocks: u32,
50    pub fields_per_block: u32,
51    pub string_bytes: u32,
52    pub chunk_bytes: u64,
53    pub aggregate_decoded_bytes: u64,
54}
55impl Default for Limits {
56    fn default() -> Self {
57        Self {
58            file_bytes: 256 << 20,
59            metadata_bytes: 4 << 20,
60            entries: 4096,
61            blocks: 4096,
62            fields_per_block: 128,
63            string_bytes: 16 << 10,
64            chunk_bytes: 16 << 20,
65            aggregate_decoded_bytes: 256 << 20,
66        }
67    }
68}
69
70#[derive(Clone, Copy, Debug, PartialEq, Eq)]
71pub enum Error {
72    Extent,
73    Overflow,
74    Limit,
75    Family,
76    Version,
77    Header,
78    Crc,
79    IndexDigest,
80    Directory,
81    Order,
82    Padding,
83    Codec,
84    Metadata,
85    Numeric,
86    PayloadDigest,
87    EntryIndex,
88}
89pub(crate) fn u16le(b: &[u8], o: usize) -> u16 {
90    u16::from_le_bytes([b[o], b[o + 1]])
91}
92pub(crate) fn u32le(b: &[u8], o: usize) -> u32 {
93    u32::from_le_bytes([b[o], b[o + 1], b[o + 2], b[o + 3]])
94}
95pub(crate) fn u64le(b: &[u8], o: usize) -> u64 {
96    u64::from_le_bytes(b[o..o + 8].try_into().unwrap())
97}
98pub(crate) fn align(n: u64, a: u64) -> Result<u64, Error> {
99    Ok(n.checked_add(a - 1).ok_or(Error::Overflow)? & !(a - 1))
100}
101pub(crate) fn extent(b: &[u8], start: u64, len: u64) -> Result<&[u8], Error> {
102    let end = start.checked_add(len).ok_or(Error::Overflow)?;
103    let s = usize::try_from(start).map_err(|_| Error::Extent)?;
104    let e = usize::try_from(end).map_err(|_| Error::Extent)?;
105    b.get(s..e).ok_or(Error::Extent)
106}
107pub(crate) fn zero(b: &[u8]) -> Result<(), Error> {
108    if b.iter().all(|&v| v == 0) {
109        Ok(())
110    } else {
111        Err(Error::Padding)
112    }
113}
114pub(crate) fn crc(b: &[u8]) -> Result<(), Error> {
115    let mut bytes = [0; 128];
116    bytes.copy_from_slice(b);
117    bytes[124..].fill(0);
118    if crate::container_10d::crc32c::crc32c(&bytes) == u32le(b, 124) {
119        Ok(())
120    } else {
121        Err(Error::Crc)
122    }
123}
124
125#[cfg(test)]
126mod tests;
127
128#[cfg(test)]
129mod writer_tests;
130
131#[cfg(test)]
132mod metadata_writer_tests;
133
134#[cfg(test)]
135mod adversarial_tests;