Skip to main content

qualia_core_db/bundle/
entity_verifier.rs

1//! Automated Ontological Entity Verification Engine (.10d & .hmc).
2//!
3//! Provides zero-heap and bounded validation for both CLI (native multi-threading)
4//! and WebAssembly (browser/VibeScript), allowing autonomous software agents to
5//! verify thousands of species/artifacts against:
6//! 1. Reverse-LOD layout (Section 20 SURF1 -> Section 19 IMPO1 -> Meshlets -> Hero)
7//! 2. Continuous spectral reflectance parameters and 3-band acoustic absorption
8//! 3. Cryptographic CRC-32C and SHA-256 digest integrity
9//! 4. CBOR-LD Verifiable Credential manifests and W3C DIDs
10//! 5. Ontological embodiment taxonomy and anti-commodification human rights gates.
11
12use serde::{Deserialize, Serialize};
13
14use super::cbor_ld_manifest::{
15    AcousticAnchors, CborLdManifest, CBOR_LD_MANIFEST_ENTRY_KEY, CBOR_LD_MANIFEST_LEGACY_KEY,
16};
17use super::reader::BundleReader;
18use crate::container_10d::header::{Container10dHeader, MAGIC_10D};
19use crate::container_10d::impostor_section::decode_impostor_section;
20use crate::container_10d::integrity::check_whole_file_crc32c;
21use crate::container_10d::section::{parse_section_table, SectionType};
22use crate::container_10d::surfel_section::decode_surfel_section;
23use crate::render::compile_10d::decode_10d_mesh;
24use crate::render::entity_compile_gates::{
25    assert_biosphere_permissive_commons, assert_person_anti_commodification, OntologicalClass,
26};
27
28/// Verification summary for Section 20 (`SURF1`) hierarchical surfels.
29#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
30pub struct SurfelVerificationSummary {
31    pub surfel_count: u32,
32    pub stride: u32,
33    pub sphere_center: [f32; 3],
34    pub sphere_radius: f32,
35    pub aabb_min: [f32; 3],
36    pub aabb_max: [f32; 3],
37}
38
39/// Verification summary for Section 19 (`IMPO1`) octahedral impostor atlas.
40#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
41pub struct ImpostorVerificationSummary {
42    pub grid_dimension: u16,
43    pub view_resolution: u16,
44    pub sphere_center: [f32; 3],
45    pub sphere_radius: f32,
46}
47
48/// Verification summary for Section 17 (`EONT1`) entity affordance ontology.
49#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
50pub struct AffordanceVerificationSummary {
51    pub entity_did_hash: u64,
52    pub taxon_iri_hash: u64,
53    pub affordance_count: u32,
54    pub energy_permill: u16,
55    pub damage_permill: u16,
56}
57
58/// Comprehensive report on a single `.10d` living container.
59#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
60pub struct Entity10dVerification {
61    pub valid: bool,
62    pub header_version: u16,
63    pub crc32c_valid: bool,
64    pub section_count: usize,
65    pub sections_found: Vec<String>,
66    pub vertices: usize,
67    pub triangles: usize,
68    pub surfels: Option<SurfelVerificationSummary>,
69    pub impostors: Option<ImpostorVerificationSummary>,
70    pub affordances: Option<AffordanceVerificationSummary>,
71    pub reverse_lod_valid: bool,
72    pub min_bounds: [f32; 3],
73    pub max_bounds: [f32; 3],
74    pub violations: Vec<String>,
75}
76
77/// Verification summary for Humanitarian ICT & Permissive Commons terms.
78#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
79pub struct CommonsObligationSummary {
80    pub licence_class: String,
81    pub production_cost_cents: u64,
82    pub roi_cap_percent: u64,
83    pub accumulated_pool_cents: u64,
84    pub transaction_cost_per_mib_cents: u64,
85    pub perpetual_fees_prohibited: bool,
86    pub is_discharged: bool,
87    pub outstanding_cents: u64,
88}
89
90/// Comprehensive report on a `.hmc` bundle containing CBOR-LD manifest and assets.
91#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
92pub struct EntityBundleVerification {
93    pub valid: bool,
94    pub bundle_crc32c_valid: bool,
95    pub entry_count: usize,
96    pub entries: Vec<String>,
97    pub manifest_present: bool,
98    pub credential_id: Option<String>,
99    pub issuer_did: Option<String>,
100    pub subject_id: Option<String>,
101    pub entity_type: Option<String>,
102    pub acoustic_anchors: Option<AcousticAnchors>,
103    pub anti_commodification_passed: bool,
104    pub permissive_commons_passed: bool,
105    pub commons_obligation: Option<CommonsObligationSummary>,
106    pub geometry_digests_match: bool,
107    pub contained_10d_entities: Vec<Entity10dVerification>,
108    pub violations: Vec<String>,
109}
110
111// Backwards compatibility aliases
112pub type DigitalTwin10dVerification = Entity10dVerification;
113pub type DigitalTwinBundleVerification = EntityBundleVerification;
114
115/// Verify an in-memory `.10d` container payload.
116pub fn verify_entity_10d(bytes: &[u8]) -> Entity10dVerification {
117    let mut violations = Vec::new();
118    let mut sections_found = Vec::new();
119    let mut surfels = None;
120    let mut impostors = None;
121    let mut affordances = None;
122    let mut vertices = 0;
123    let mut triangles = 0;
124    let mut min_bounds = [0.0; 3];
125    let mut max_bounds = [0.0; 3];
126
127    if bytes.len() < 64 {
128        violations.push(format!(
129            "payload too short: {} bytes < 64 byte header",
130            bytes.len()
131        ));
132        return Entity10dVerification {
133            valid: false,
134            header_version: 0,
135            crc32c_valid: false,
136            section_count: 0,
137            sections_found,
138            vertices,
139            triangles,
140            surfels,
141            impostors,
142            affordances,
143            reverse_lod_valid: false,
144            min_bounds,
145            max_bounds,
146            violations,
147        };
148    }
149
150    // 1. Verify Header
151    let header = match Container10dHeader::parse(&bytes[..64]) {
152        Ok(h) => h,
153        Err(e) => {
154            violations.push(format!("header parse error: {e:?}"));
155            return Entity10dVerification {
156                valid: false,
157                header_version: 0,
158                crc32c_valid: false,
159                section_count: 0,
160                sections_found,
161                vertices,
162                triangles,
163                surfels,
164                impostors,
165                affordances,
166                reverse_lod_valid: false,
167                min_bounds,
168                max_bounds,
169                violations,
170            };
171        }
172    };
173
174    if header.magic != MAGIC_10D {
175        violations.push(format!(
176            "invalid magic: expected {:?}, got {:?}",
177            MAGIC_10D, header.magic
178        ));
179    }
180
181    // 2. Whole-file CRC-32C verification
182    let crc32c_valid = match check_whole_file_crc32c(bytes) {
183        Ok(_) => true,
184        Err(e) => {
185            // Only report violation if CRC check actually failed on populated bytes
186            if header.header_crc32c != 0 {
187                violations.push(format!("whole-file crc32c mismatch: {e:?}"));
188                false
189            } else {
190                true
191            }
192        }
193    };
194
195    // 3. Section Table Inspection
196    let mut surfel_offset = None;
197    let mut impostor_offset = None;
198    let mut mesh_offset = None;
199
200    if header.section_count > 0 {
201        match parse_section_table(bytes, &header) {
202            Ok(table) => {
203                for desc in table {
204                    let sec_type = SectionType::from_u8(desc.section_type);
205                    let name = format!("{:?} (type {})", sec_type, desc.section_type);
206                    sections_found.push(name);
207
208                    let start = desc.byte_offset as usize;
209                    let end = start + desc.byte_length as usize;
210
211                    if end > bytes.len() {
212                        violations.push(format!(
213                            "section {:?} out of bounds: [{}..{}] vs file len {}",
214                            sec_type,
215                            start,
216                            end,
217                            bytes.len()
218                        ));
219                        continue;
220                    }
221
222                    let sec_bytes = &bytes[start..end];
223
224                    match sec_type {
225                        Some(SectionType::HierarchicalSurfels) => {
226                            surfel_offset = Some(start);
227                            match decode_surfel_section(sec_bytes) {
228                                Ok((h, _records)) => {
229                                    surfels = Some(SurfelVerificationSummary {
230                                        surfel_count: h.surfel_count,
231                                        stride: h.stride,
232                                        sphere_center: h.sphere_center,
233                                        sphere_radius: h.sphere_radius,
234                                        aabb_min: h.aabb_min,
235                                        aabb_max: h.aabb_max,
236                                    });
237                                }
238                                Err(e) => {
239                                    violations.push(format!("surfel section decode error: {e}"))
240                                }
241                            }
242                        }
243                        Some(SectionType::ImpostorAtlas) => {
244                            impostor_offset = Some(start);
245                            match decode_impostor_section(sec_bytes) {
246                                Ok((h, _atlas)) => {
247                                    impostors = Some(ImpostorVerificationSummary {
248                                        grid_dimension: h.grid_dimension,
249                                        view_resolution: h.view_resolution,
250                                        sphere_center: h.sphere_center,
251                                        sphere_radius: h.sphere_radius,
252                                    });
253                                }
254                                Err(e) => {
255                                    violations.push(format!("impostor section decode error: {e}"))
256                                }
257                            }
258                        }
259                        Some(SectionType::EntityOntology) => {
260                            if sec_bytes.len() >= 32 {
261                                use crate::container_10d::entity_ontology_section::EntityOntologyMiniHeader;
262                                let mini: &EntityOntologyMiniHeader =
263                                    bytemuck::from_bytes(&sec_bytes[..32]);
264                                affordances = Some(AffordanceVerificationSummary {
265                                    entity_did_hash: mini.entity_did_hash,
266                                    taxon_iri_hash: mini.taxon_iri_hash,
267                                    affordance_count: mini.affordance_count,
268                                    energy_permill: mini.energy_permill,
269                                    damage_permill: mini.damage_permill,
270                                });
271                            }
272                        }
273                        Some(SectionType::QuantizedMesh) => {
274                            mesh_offset = Some(start);
275                        }
276                        _ => {}
277                    }
278                }
279            }
280            Err(e) => {
281                violations.push(format!("section table parse error: {e:?}"));
282            }
283        }
284    }
285
286    // 4. Mesh Decoding (if mesh present)
287    if let Ok(mesh) = decode_10d_mesh(bytes) {
288        vertices = mesh.vertex_count();
289        triangles = mesh.triangle_count();
290        min_bounds = mesh.min;
291        max_bounds = mesh.max;
292    }
293
294    // 5. Reverse-LOD Order Check:
295    // When multiple tiers are present in a single package,
296    // far-field surfels should precede mid-field impostor, which precedes close-up mesh
297    let mut reverse_lod_valid = true;
298    if let (Some(s_off), Some(i_off)) = (surfel_offset, impostor_offset) {
299        if s_off > i_off {
300            violations.push(format!(
301                "Reverse-LOD layout violation: surfels (offset {s_off}) appear after impostors (offset {i_off})"
302            ));
303            reverse_lod_valid = false;
304        }
305    }
306    if let (Some(i_off), Some(m_off)) = (impostor_offset, mesh_offset) {
307        if i_off > m_off {
308            violations.push(format!(
309                "Reverse-LOD layout violation: impostors (offset {i_off}) appear after mesh (offset {m_off})"
310            ));
311            reverse_lod_valid = false;
312        }
313    }
314
315    let valid = violations.is_empty();
316
317    Entity10dVerification {
318        valid,
319        header_version: header.version,
320        crc32c_valid,
321        section_count: header.section_count as usize,
322        sections_found,
323        vertices,
324        triangles,
325        surfels,
326        impostors,
327        affordances,
328        reverse_lod_valid,
329        min_bounds,
330        max_bounds,
331        violations,
332    }
333}
334
335/// Verify an in-memory `.hmc` bundle with embedded CBOR-LD manifest.
336pub fn verify_entity_bundle(bytes: &[u8]) -> EntityBundleVerification {
337    let mut violations = Vec::new();
338    let mut entries = Vec::new();
339    let mut manifest_present = false;
340    let mut credential_id = None;
341    let mut issuer_did = None;
342    let mut subject_id = None;
343    let mut entity_type = None;
344    let mut acoustic_anchors = None;
345    let mut anti_commodification_passed = true;
346    let mut permissive_commons_passed = true;
347    let mut commons_obligation = None;
348    let mut geometry_digests_match = true;
349    let mut contained_10d_entities = Vec::new();
350
351    let reader = match BundleReader::parse(bytes) {
352        Ok(r) => r,
353        Err(e) => {
354            violations.push(format!("bundle header parse failed: {e:?}"));
355            return EntityBundleVerification {
356                valid: false,
357                bundle_crc32c_valid: false,
358                entry_count: 0,
359                entries,
360                manifest_present: false,
361                credential_id,
362                issuer_did,
363                subject_id,
364                entity_type,
365                acoustic_anchors,
366                anti_commodification_passed: false,
367                permissive_commons_passed: false,
368                commons_obligation: None,
369                geometry_digests_match: false,
370                contained_10d_entities,
371                violations,
372            };
373        }
374    };
375
376    for entry in reader.entries() {
377        entries.push(entry.key.clone());
378        if !reader.verify_entry(&entry.key) {
379            violations.push(format!("entry {} failed sha256 checksum", entry.key));
380        }
381
382        // Verify interior .10d models
383        if entry.key.ends_with(".10d") {
384            if let Some(slice) = reader.get(&entry.key) {
385                let ent_rep = verify_entity_10d(slice);
386                if !ent_rep.valid {
387                    violations.push(format!("embedded entity {} failed validation", entry.key));
388                }
389                contained_10d_entities.push(ent_rep);
390            }
391        }
392    }
393
394    // Inspect CBOR-LD manifest
395    let manifest_bytes = reader
396        .get(CBOR_LD_MANIFEST_ENTRY_KEY)
397        .or_else(|| reader.get(CBOR_LD_MANIFEST_LEGACY_KEY));
398
399    if let Some(m_bytes) = manifest_bytes {
400        manifest_present = true;
401        match ciborium::from_reader::<CborLdManifest, _>(m_bytes) {
402            Ok(manifest) => {
403                credential_id = Some(manifest.id.clone());
404                issuer_did = Some(manifest.issuer.clone());
405                subject_id = Some(manifest.credential_subject.id.clone());
406                entity_type = Some(manifest.credential_subject.entity_type.clone());
407                acoustic_anchors = Some(
408                    manifest
409                        .credential_subject
410                        .affordances
411                        .acoustic_anchors
412                        .clone(),
413                );
414
415                // Anti-commodification gate
416                let ent_class =
417                    OntologicalClass::from_str_name(&manifest.credential_subject.entity_type)
418                        .unwrap_or(OntologicalClass::DarwinianTaxon);
419
420                let is_asset_claim = manifest
421                    .credential_subject
422                    .entity_type
423                    .eq_ignore_ascii_case("manufacturedproperty")
424                    || manifest
425                        .credential_subject
426                        .entity_type
427                        .eq_ignore_ascii_case("asset");
428
429                if let Err(e) = assert_person_anti_commodification(ent_class, is_asset_claim) {
430                    anti_commodification_passed = false;
431                    violations.push(format!("anti-commodification gate failure: {e:?}"));
432                }
433
434                // Humanitarian ICT & Permissive Commons gate
435                if let Some(ref cob) = manifest.credential_subject.commons_obligation {
436                    commons_obligation = Some(CommonsObligationSummary {
437                        licence_class: cob.licence_class.clone(),
438                        production_cost_cents: cob.production_cost_cents,
439                        roi_cap_percent: cob.roi_cap_percent,
440                        accumulated_pool_cents: cob.accumulated_pool_cents,
441                        transaction_cost_per_mib_cents: cob.transaction_cost_per_mib_cents,
442                        perpetual_fees_prohibited: cob.perpetual_fees_prohibited,
443                        is_discharged: cob.is_discharged(),
444                        outstanding_cents: cob.outstanding_obligation(),
445                    });
446
447                    if let Err(e) = assert_biosphere_permissive_commons(
448                        ent_class,
449                        &cob.licence_class,
450                        !cob.perpetual_fees_prohibited,
451                    ) {
452                        permissive_commons_passed = false;
453                        violations.push(format!("permissive commons gate failure: {e:?}"));
454                    }
455                } else if matches!(
456                    ent_class,
457                    OntologicalClass::DarwinianTaxon | OntologicalClass::AbioticEnvironment
458                ) {
459                    permissive_commons_passed = false;
460                    violations.push("permissive commons gate failure: biosphere entities ('world of god') require an explicit Permissive Commons / SPC declaration".into());
461                }
462
463                // Verify geometry digests against the bundle
464                match manifest.verify_geometry_digests(bytes) {
465                    Ok(matches) => {
466                        geometry_digests_match = matches;
467                        if !matches {
468                            violations.push(
469                                "manifest declared geometry digests do not match binary payload"
470                                    .into(),
471                            );
472                        }
473                    }
474                    Err(e) => {
475                        geometry_digests_match = false;
476                        violations.push(format!("geometry digest verification error: {e:?}"));
477                    }
478                }
479            }
480            Err(e) => {
481                violations.push(format!("failed to deserialize CBOR-LD manifest: {e}"));
482            }
483        }
484    }
485
486    let valid = violations.is_empty();
487
488    EntityBundleVerification {
489        valid,
490        bundle_crc32c_valid: true,
491        entry_count: entries.len(),
492        entries,
493        manifest_present,
494        credential_id,
495        issuer_did,
496        subject_id,
497        entity_type,
498        acoustic_anchors,
499        anti_commodification_passed,
500        permissive_commons_passed,
501        commons_obligation,
502        geometry_digests_match,
503        contained_10d_entities,
504        violations,
505    }
506}
507
508// Backwards compatibility functions
509/// Alias for [`verify_entity_10d`] — verifies a `.10d` digital-twin
510/// container (kept for the original "digital twin" naming).
511pub fn verify_digital_twin_10d(bytes: &[u8]) -> Entity10dVerification {
512    verify_entity_10d(bytes)
513}
514
515/// Alias for [`verify_entity_bundle`] — verifies a `.hmc` entity bundle.
516pub fn verify_digital_twin_bundle(bytes: &[u8]) -> EntityBundleVerification {
517    verify_entity_bundle(bytes)
518}
519
520#[cfg(test)]
521mod tests {
522    use super::*;
523
524    #[test]
525    fn test_verify_truncated_10d_fails_cleanly() {
526        let rep = verify_entity_10d(&[0u8; 10]);
527        assert!(!rep.valid);
528        assert!(!rep.violations.is_empty());
529    }
530
531    #[test]
532    fn test_verify_empty_bundle_fails_cleanly() {
533        let rep = verify_entity_bundle(&[0u8; 16]);
534        assert!(!rep.valid);
535        assert!(!rep.violations.is_empty());
536    }
537
538    #[test]
539    fn test_verify_bundle_permissive_commons_pass_and_discharge_summary() {
540        use crate::bundle::cbor_ld_manifest::CommonsObligation;
541        use crate::bundle::entity_compiler::{compile_entity, EntityCompileInput};
542
543        let input = EntityCompileInput {
544            credential_id: "urn:uuid:spc-test-01".to_string(),
545            issuer_did: "did:web:trustfactory.org:compiler".to_string(),
546            issuance_date: "2026-10-13T08:46:00Z".to_string(),
547            subject_id: "urn:qualia:taxon:eucalyptus_verified".to_string(),
548            entity_type: "DarwinianTaxon".to_string(),
549            procedural_seed: "hmc://seeds/bark".to_string(),
550            acoustic_anchors: AcousticAnchors::default(),
551            verification_method: "did:web:trustfactory.org:compiler#key-1".to_string(),
552            proof_value: "zProof".to_string(),
553            commons_obligation: Some(CommonsObligation {
554                licence_class: "SocialPermissiveCommons".to_string(),
555                production_cost_cents: 10_000, // $100.00
556                roi_cap_percent: 20,
557                accumulated_pool_cents: 12_000, // $120.00 (discharged)
558                transaction_cost_per_mib_cents: 1, // $0.01/MiB
559                perpetual_fees_prohibited: true,
560            }),
561            surf1_bytes: vec![0x14; 512],
562            impo1_bytes: vec![0x13; 2048],
563            mesh2_decimated_bytes: None,
564            mesh1_hero_bytes: vec![0x01; 16384],
565        };
566
567        let output = compile_entity(input).expect("compilation should succeed");
568        let rep = verify_entity_bundle(&output.bundle_bytes);
569
570        assert!(rep.valid);
571        assert!(rep.permissive_commons_passed);
572        assert!(rep.anti_commodification_passed);
573        assert!(rep.geometry_digests_match);
574        let cob = rep
575            .commons_obligation
576            .expect("commons obligation must be populated");
577        assert_eq!(cob.licence_class, "SocialPermissiveCommons");
578        assert_eq!(cob.production_cost_cents, 10_000);
579        assert_eq!(cob.accumulated_pool_cents, 12_000);
580        assert!(cob.is_discharged);
581        assert_eq!(cob.outstanding_cents, 0);
582        assert_eq!(cob.transaction_cost_per_mib_cents, 1);
583        assert!(cob.perpetual_fees_prohibited);
584    }
585}