Skip to main content

qualia_core_db/render/
compile_10d_manifest.rs

1//! Opt-in attachment of identity-v2 metadata to an already compiled `.10d` asset.
2//!
3//! Existing compiler outputs remain byte-identical unless callers explicitly invoke this
4//! adapter. It preserves every existing section payload and descriptor contract, adds the
5//! identity section, validates all field references, and seals the resulting whole-file CRC.
6
7use crate::container_10d::header::{Container10dHeader, MAX_SECTION_COUNT};
8use crate::container_10d::integrity::{compute_whole_file_crc32c, seal_whole_file_crc32c};
9use crate::container_10d::manifold_identity_container::{
10    encode_container_with_manifold_identity_extensions, ManifoldContainerError,
11};
12use crate::container_10d::manifold_identity_v2::{ManifoldIdentityV2, TypedFieldRecord};
13use crate::container_10d::section::{
14    parse_section_table, AlignmentTier, SectionInput, SectionTableError, SectionType,
15};
16use crate::render::assets::Mesh;
17use crate::render::compile_10d::{compile_mesh_to_10d, Compile10dError};
18
19#[derive(Debug, PartialEq, Eq)]
20pub enum CompileWithIdentityError {
21    Compile(Compile10dError),
22    Attach(ManifestAttachError),
23}
24
25/// Compile a mesh using the established legacy pipeline, then explicitly attach the v2 identity
26/// section. Existing `compile_mesh_to_10d` functions and their byte output remain unchanged.
27pub fn compile_mesh_to_10d_with_identity(
28    mesh: &Mesh,
29    identity: &ManifoldIdentityV2,
30    fields: &[TypedFieldRecord],
31    supported_extension_kinds: &[u16],
32) -> Result<Vec<u8>, CompileWithIdentityError> {
33    let container = compile_mesh_to_10d(mesh).map_err(CompileWithIdentityError::Compile)?;
34    let mut output = [];
35    let needed = match attach_with_workspace(
36        &container,
37        identity,
38        fields,
39        supported_extension_kinds,
40        &mut output,
41    ) {
42        Ok(written) => written,
43        Err(ManifestAttachError::Manifest(ManifoldContainerError::Sections(
44            SectionTableError::OutputBufferTooSmall { needed, .. },
45        ))) => needed,
46        Err(error) => return Err(CompileWithIdentityError::Attach(error)),
47    };
48    let mut output = vec![0u8; needed];
49    let written = attach_with_workspace(
50        &container,
51        identity,
52        fields,
53        supported_extension_kinds,
54        &mut output,
55    )
56    .map_err(CompileWithIdentityError::Attach)?;
57    output.truncate(written);
58    Ok(output)
59}
60
61fn attach_with_workspace(
62    container: &[u8],
63    identity: &ManifoldIdentityV2,
64    fields: &[TypedFieldRecord],
65    supported_extension_kinds: &[u16],
66    out: &mut [u8],
67) -> Result<usize, ManifestAttachError> {
68    let mut manifest_scratch =
69        [0u8; crate::container_10d::manifold_identity_v2::MANIFOLD_IDENTITY_V2_MAX_BYTES];
70    let placeholder = SectionInput {
71        section_type: SectionType::QuantizedMesh,
72        alignment_tier: AlignmentTier::Word,
73        stride: 0,
74        element_count: 0,
75        payload: &[],
76    };
77    let mut section_scratch = [placeholder; MAX_SECTION_COUNT as usize];
78    attach_manifold_identity_v2_into(
79        container,
80        identity,
81        fields,
82        supported_extension_kinds,
83        &mut manifest_scratch,
84        &mut section_scratch,
85        out,
86    )
87}
88
89#[derive(Debug, Clone, PartialEq, Eq)]
90pub enum ManifestAttachError {
91    BadHeader,
92    WholeFileCrcMismatch { expected: u32, actual: u32 },
93    Section(SectionTableError),
94    Manifest(ManifoldContainerError),
95    IdentityAlreadyPresent,
96    ScratchCapacity { needed: usize, capacity: usize },
97    InvalidSectionRange { section_type: u8 },
98}
99
100impl From<SectionTableError> for ManifestAttachError {
101    fn from(value: SectionTableError) -> Self {
102        Self::Section(value)
103    }
104}
105
106impl From<ManifoldContainerError> for ManifestAttachError {
107    fn from(value: ManifoldContainerError) -> Self {
108        Self::Manifest(value)
109    }
110}
111
112/// Attach an identity-v2 manifest to a verified compiled container using caller-owned buffers.
113///
114/// `section_scratch` needs one slot for each existing section. The underlying envelope writer
115/// validates output capacity before writing, so errors leave `out` unchanged. A source container
116/// that already has an identity-v2 section is rejected instead of silently replacing identity.
117pub fn attach_manifold_identity_v2_into<'a>(
118    container: &'a [u8],
119    identity: &ManifoldIdentityV2,
120    fields: &[TypedFieldRecord],
121    supported_extension_kinds: &[u16],
122    manifest_scratch: &'a mut [u8],
123    section_scratch: &mut [SectionInput<'a>],
124    out: &mut [u8],
125) -> Result<usize, ManifestAttachError> {
126    let header =
127        Container10dHeader::parse(container).map_err(|_| ManifestAttachError::BadHeader)?;
128    if container.len() < 56 {
129        return Err(ManifestAttachError::BadHeader);
130    }
131    let expected = u32::from_le_bytes(
132        container[52..56]
133            .try_into()
134            .map_err(|_| ManifestAttachError::BadHeader)?,
135    );
136    let actual = compute_whole_file_crc32c(container);
137    if actual != expected {
138        return Err(ManifestAttachError::WholeFileCrcMismatch { expected, actual });
139    }
140
141    let descriptors = parse_section_table(container, &header)?;
142    if descriptors
143        .iter()
144        .any(|descriptor| descriptor.typ() == Some(SectionType::ManifoldIdentityV2))
145    {
146        return Err(ManifestAttachError::IdentityAlreadyPresent);
147    }
148    let needed_sections =
149        descriptors
150            .len()
151            .checked_add(1)
152            .ok_or(ManifestAttachError::ScratchCapacity {
153                needed: usize::MAX,
154                capacity: section_scratch.len(),
155            })?;
156    if needed_sections > MAX_SECTION_COUNT as usize {
157        return Err(ManifestAttachError::ScratchCapacity {
158            needed: needed_sections,
159            capacity: MAX_SECTION_COUNT as usize,
160        });
161    }
162    if section_scratch.len() < needed_sections {
163        return Err(ManifestAttachError::ScratchCapacity {
164            needed: needed_sections,
165            capacity: section_scratch.len(),
166        });
167    }
168
169    let placeholder = SectionInput {
170        section_type: SectionType::QuantizedMesh,
171        alignment_tier: AlignmentTier::Word,
172        stride: 0,
173        element_count: 0,
174        payload: &[],
175    };
176    let mut existing_sections = [placeholder; MAX_SECTION_COUNT as usize];
177    for (slot, descriptor) in existing_sections.iter_mut().zip(descriptors.iter()) {
178        let section_type = descriptor
179            .typ()
180            .ok_or(ManifestAttachError::InvalidSectionRange {
181                section_type: descriptor.section_type,
182            })?;
183        let alignment_tier = descriptor
184            .tier()
185            .ok_or(ManifestAttachError::InvalidSectionRange {
186                section_type: descriptor.section_type,
187            })?;
188        let start = descriptor.byte_offset as usize;
189        let end = start.checked_add(descriptor.byte_length as usize).ok_or(
190            ManifestAttachError::InvalidSectionRange {
191                section_type: descriptor.section_type,
192            },
193        )?;
194        let payload =
195            container
196                .get(start..end)
197                .ok_or(ManifestAttachError::InvalidSectionRange {
198                    section_type: descriptor.section_type,
199                })?;
200        *slot = SectionInput {
201            section_type,
202            alignment_tier,
203            stride: descriptor.stride,
204            element_count: descriptor.element_count,
205            payload,
206        };
207    }
208
209    let written = encode_container_with_manifold_identity_extensions(
210        &header,
211        &existing_sections[..descriptors.len()],
212        identity,
213        fields,
214        supported_extension_kinds,
215        manifest_scratch,
216        section_scratch,
217        out,
218    )?;
219    seal_whole_file_crc32c(&mut out[..written]);
220    Ok(written)
221}
222
223#[cfg(test)]
224mod tests {
225    use super::*;
226    use crate::container_10d::integrity::{seal_whole_file_crc32c, verify_whole_file_crc32c};
227    use crate::container_10d::manifold_identity_container::decode_container_manifold_identity;
228    use crate::container_10d::manifold_identity_v2::{
229        IntegrityIndexDigest, StableEntityId, FIELD_KIND_ELECTROMAGNETIC,
230        MANIFOLD_IDENTITY_V2_MAX_BYTES,
231    };
232    use crate::container_10d::section::{encode_container, SectionInput};
233
234    fn base_container() -> Vec<u8> {
235        let header = Container10dHeader::proposed();
236        let payload = [3u8, 1, 4, 1, 5, 9];
237        let inputs = [SectionInput {
238            section_type: SectionType::FieldSidecar,
239            alignment_tier: AlignmentTier::Word,
240            stride: 0,
241            element_count: 0,
242            payload: &payload,
243        }];
244        let mut bytes = [0; 4096];
245        let length = encode_container(&header, &inputs, &mut bytes).unwrap();
246        seal_whole_file_crc32c(&mut bytes[..length]);
247        bytes[..length].to_vec()
248    }
249
250    fn sample_identity() -> ManifoldIdentityV2 {
251        ManifoldIdentityV2 {
252            entity_id: StableEntityId(*b"compile-q42-0001"),
253            profile_id: 1,
254            domain_id: 2,
255            coordinate_convention_id: 3,
256            coordinates: [0.0; 10],
257            external_digest: Some(IntegrityIndexDigest([0xA5; 16])),
258        }
259    }
260
261    #[test]
262    fn attachment_preserves_payload_and_emits_sealed_resolvable_identity() {
263        let source_storage = base_container();
264        let source = source_storage.as_slice();
265        let fields = [TypedFieldRecord {
266            field_id: 1,
267            kind: FIELD_KIND_ELECTROMAGNETIC,
268            flags: 0,
269            unit_id: 42,
270            payload_section_id: SectionType::FieldSidecar as u32,
271            payload_offset: 1,
272            payload_length: 4,
273        }];
274        let mut manifest = [0; MANIFOLD_IDENTITY_V2_MAX_BYTES];
275        let mut sections = [SectionInput {
276            section_type: SectionType::FieldSidecar,
277            alignment_tier: AlignmentTier::Word,
278            stride: 0,
279            element_count: 0,
280            payload: &[],
281        }; 2];
282        let mut output = [0; 8192];
283        let written = attach_manifold_identity_v2_into(
284            source,
285            &sample_identity(),
286            &fields,
287            &[],
288            &mut manifest,
289            &mut sections,
290            &mut output,
291        )
292        .unwrap();
293
294        let output_header = Container10dHeader::parse(&output[..written]).unwrap();
295        verify_whole_file_crc32c(&mut output[..written]).unwrap();
296        let descriptors = parse_section_table(&output[..written], &output_header).unwrap();
297        let preserved = descriptors
298            .iter()
299            .find(|descriptor| descriptor.typ() == Some(SectionType::FieldSidecar))
300            .unwrap();
301        let start = preserved.byte_offset as usize;
302        assert_eq!(&output[start..start + 6], &[3, 1, 4, 1, 5, 9]);
303
304        let mut field_scratch = [TypedFieldRecord::default(); 1];
305        let mut decoded_fields = [TypedFieldRecord::default(); 1];
306        let (decoded, count) = decode_container_manifold_identity(
307            &output[..written],
308            &output_header,
309            &[],
310            &mut field_scratch,
311            &mut decoded_fields,
312        )
313        .unwrap();
314        assert_eq!(decoded, sample_identity());
315        assert_eq!(count, 1);
316        assert_eq!(decoded_fields, fields);
317    }
318
319    #[test]
320    fn attachment_rejects_bad_source_crc_without_touching_output() {
321        let mut source = base_container();
322        source[64] ^= 0x40;
323        let mut manifest = [0; MANIFOLD_IDENTITY_V2_MAX_BYTES];
324        let mut sections = [SectionInput {
325            section_type: SectionType::FieldSidecar,
326            alignment_tier: AlignmentTier::Word,
327            stride: 0,
328            element_count: 0,
329            payload: &[],
330        }; 2];
331        let mut output = [0xA5; 8192];
332        assert!(matches!(
333            attach_manifold_identity_v2_into(
334                &source,
335                &sample_identity(),
336                &[],
337                &[],
338                &mut manifest,
339                &mut sections,
340                &mut output,
341            ),
342            Err(ManifestAttachError::WholeFileCrcMismatch { .. })
343        ));
344        assert!(output.iter().all(|byte| *byte == 0xA5));
345    }
346}