Skip to main content

qualia_core_db/bundle/
writer.rs

1//! Build a `.hmc` bundle from a set of intact files.
2
3use sha2::{Digest, Sha256};
4
5use crate::container_10d::crc32c::crc32c;
6
7use super::format::{
8    align_up, BundleEntry, BundleError, BUNDLE_ENTRY_ALIGN, BUNDLE_FLAG_PAGE_ALIGN_4096,
9    BUNDLE_HEADER_SIZE, BUNDLE_MAGIC, BUNDLE_PAGE_ALIGN_4096, BUNDLE_VERSION, OFF_CRC32C,
10    OFF_ENTRY_COUNT, OFF_FLAGS, OFF_INDEX_LENGTH, OFF_INDEX_OFFSET, OFF_MAGIC, OFF_TOTAL_LENGTH,
11    OFF_VERSION,
12};
13
14/// Accumulates intact files and serialises them into a `.hmc` bundle.
15///
16/// Files are stored **verbatim** — no compression, no transformation — each
17/// page-aligned so the interior alignment (and thus zero-copy segment access)
18/// of embedded `.q42` / `.p64` / `.10d` files is preserved. Entry order in the
19/// index follows insertion order (deterministic bundles for a given input).
20#[derive(Default)]
21pub struct BundleWriter {
22    // (key, kind, bytes, meta)
23    entries: Vec<(String, String, Vec<u8>, Option<Vec<u8>>)>,
24    align_4096: bool,
25}
26
27impl BundleWriter {
28    /// Create an empty bundle writer.
29    pub fn new() -> Self {
30        Self::default()
31    }
32
33    /// Configure whether entries and index footer are aligned to 4096-byte page boundaries.
34    pub fn with_page_align_4096(mut self, enabled: bool) -> Self {
35        self.align_4096 = enabled;
36        self
37    }
38
39    /// Set whether entries and index footer are aligned to 4096-byte page boundaries.
40    pub fn set_page_align_4096(&mut self, enabled: bool) {
41        self.align_4096 = enabled;
42    }
43
44    /// Whether 4096-byte page alignment is enabled.
45    pub fn is_page_align_4096(&self) -> bool {
46        self.align_4096
47    }
48
49    /// Number of files added so far.
50    pub fn len(&self) -> usize {
51        self.entries.len()
52    }
53
54    /// True when no files have been added.
55    pub fn is_empty(&self) -> bool {
56        self.entries.is_empty()
57    }
58
59    /// Add one intact file. `key` must be unique and non-empty. `kind` names the
60    /// embedded format (`"10d"`, `"q42"`, `"p64"`, `"manifest"`, …). `meta` is an
61    /// optional opaque per-entry CBOR blob (domain-specific).
62    pub fn add_file(
63        &mut self,
64        key: impl Into<String>,
65        kind: impl Into<String>,
66        bytes: Vec<u8>,
67        meta: Option<Vec<u8>>,
68    ) -> Result<&mut Self, BundleError> {
69        let key = key.into();
70        if key.is_empty() {
71            return Err(BundleError::EmptyKey);
72        }
73        if self.entries.iter().any(|(k, _, _, _)| *k == key) {
74            return Err(BundleError::DuplicateKey(key));
75        }
76        self.entries.push((key, kind.into(), bytes, meta));
77        Ok(self)
78    }
79
80    /// Add a digital twin model family manifest describing variants, sexual dimorphism,
81    /// life stages, and LOD hierarchy to the bundle.
82    pub fn add_family_manifest(
83        &mut self,
84        manifest: &super::variant_matrix::TwinFamilyManifest,
85    ) -> Result<&mut Self, BundleError> {
86        let bytes = manifest.encode_to_cbor()?;
87        self.add_file(
88            super::variant_matrix::FAMILY_MANIFEST_ENTRY_KEY,
89            super::variant_matrix::FAMILY_MANIFEST_KIND,
90            bytes,
91            None,
92        )
93    }
94
95    /// Add a W3C Verifiable Credential manifest encoded as CBOR-LD.
96    pub fn add_cbor_ld_manifest(
97        &mut self,
98        manifest: &super::cbor_ld_manifest::CborLdManifest,
99    ) -> Result<&mut Self, BundleError> {
100        let bytes = manifest.encode_to_cbor()?;
101        self.add_file(
102            super::cbor_ld_manifest::CBOR_LD_MANIFEST_ENTRY_KEY,
103            super::cbor_ld_manifest::CBOR_LD_MANIFEST_KIND,
104            bytes,
105            None,
106        )
107    }
108
109    /// Add holistic species metadata (flora, fauna, or mechanical assembly) to the bundle.
110    pub fn add_species_meta(
111        &mut self,
112        meta: &super::species_meta::HolisticSpeciesMeta,
113    ) -> Result<&mut Self, BundleError> {
114        let bytes = meta.encode_to_cbor()?;
115        self.add_file(
116            super::species_meta::SPECIES_META_ENTRY_KEY,
117            super::species_meta::SPECIES_META_KIND,
118            bytes,
119            None,
120        )
121    }
122
123    /// Serialise the bundle to a `Vec<u8>`.
124    pub fn build(&self) -> Result<Vec<u8>, BundleError> {
125        let mut out = vec![0u8; BUNDLE_HEADER_SIZE];
126        let mut index: Vec<BundleEntry> = Vec::with_capacity(self.entries.len());
127        let align = if self.align_4096 {
128            BUNDLE_PAGE_ALIGN_4096
129        } else {
130            BUNDLE_ENTRY_ALIGN
131        };
132
133        for (key, kind, bytes, meta) in &self.entries {
134            // Page-align the entry so its interior stays aligned.
135            let padded = align_up(out.len(), align);
136            out.resize(padded, 0);
137            let offset = out.len() as u64;
138            out.extend_from_slice(bytes);
139
140            let mut hasher = Sha256::new();
141            hasher.update(bytes);
142            let sha256 = hasher.finalize().to_vec();
143
144            index.push(BundleEntry {
145                key: key.clone(),
146                kind: kind.clone(),
147                offset,
148                length: bytes.len() as u64,
149                sha256,
150                meta: meta.clone(),
151            });
152        }
153
154        // Page-align the index footer too (tidy range fetches of the directory).
155        let padded = align_up(out.len(), align);
156        out.resize(padded, 0);
157        let index_offset = out.len() as u64;
158
159        let mut index_bytes = Vec::new();
160        ciborium::into_writer(&index, &mut index_bytes)
161            .map_err(|e| BundleError::Cbor(e.to_string()))?;
162        out.extend_from_slice(&index_bytes);
163        let index_length = index_bytes.len() as u64;
164        let total_length = out.len() as u64;
165        let flags: u16 = if self.align_4096 {
166            BUNDLE_FLAG_PAGE_ALIGN_4096
167        } else {
168            0
169        };
170
171        // Fill the header (CRC field stays zero for the CRC computation).
172        out[OFF_MAGIC..OFF_MAGIC + 4].copy_from_slice(&BUNDLE_MAGIC);
173        out[OFF_VERSION..OFF_VERSION + 2].copy_from_slice(&BUNDLE_VERSION.to_le_bytes());
174        out[OFF_FLAGS..OFF_FLAGS + 2].copy_from_slice(&flags.to_le_bytes());
175        out[OFF_ENTRY_COUNT..OFF_ENTRY_COUNT + 4]
176            .copy_from_slice(&(self.entries.len() as u32).to_le_bytes());
177        out[OFF_INDEX_OFFSET..OFF_INDEX_OFFSET + 8].copy_from_slice(&index_offset.to_le_bytes());
178        out[OFF_INDEX_LENGTH..OFF_INDEX_LENGTH + 8].copy_from_slice(&index_length.to_le_bytes());
179        out[OFF_TOTAL_LENGTH..OFF_TOTAL_LENGTH + 8].copy_from_slice(&total_length.to_le_bytes());
180
181        // Whole-file CRC-32C over the buffer with the CRC field == 0.
182        let crc = crc32c(&out);
183        out[OFF_CRC32C..OFF_CRC32C + 4].copy_from_slice(&crc.to_le_bytes());
184
185        Ok(out)
186    }
187}
188
189#[cfg(test)]
190mod tests {
191    use super::*;
192
193    #[test]
194    fn rejects_empty_and_duplicate_keys() {
195        let mut w = BundleWriter::new();
196        assert!(matches!(
197            w.add_file("", "10d", vec![1], None),
198            Err(BundleError::EmptyKey)
199        ));
200        w.add_file("a", "10d", vec![1, 2], None).unwrap();
201        assert!(matches!(
202            w.add_file("a", "q42", vec![3], None),
203            Err(BundleError::DuplicateKey(_))
204        ));
205    }
206
207    #[test]
208    fn entries_are_page_aligned() {
209        let mut w = BundleWriter::new();
210        w.add_file("a", "10d", vec![0xAB; 7], None).unwrap();
211        w.add_file("b", "10d", vec![0xCD; 130], None).unwrap();
212        let bytes = w.build().unwrap();
213        let reader = super::super::reader::BundleReader::parse(&bytes).unwrap();
214        for e in reader.entries() {
215            assert_eq!(
216                e.offset % BUNDLE_ENTRY_ALIGN as u64,
217                0,
218                "entry {} unaligned",
219                e.key
220            );
221        }
222    }
223
224    #[test]
225    fn entries_are_4096_page_aligned_when_enabled() {
226        let mut w = BundleWriter::new().with_page_align_4096(true);
227        w.add_file("a.10d", "10d", vec![0xAB; 7], None).unwrap();
228        w.add_file("b.m64", "m64", vec![0xCD; 130], None).unwrap();
229        let bytes = w.build().unwrap();
230        let reader = super::super::reader::BundleReader::parse(&bytes).unwrap();
231        assert!(reader.is_page_aligned_4096());
232        for e in reader.entries() {
233            assert_eq!(
234                e.offset % BUNDLE_PAGE_ALIGN_4096 as u64,
235                0,
236                "entry {} not 4096-byte aligned",
237                e.key
238            );
239        }
240    }
241}