Skip to main content

qualia_core_db/q42/m64_matter/
lut_entry.rs

1//! 64-Byte Universal Constituent LUT Entry (`Q42ConstituentLutEntry`).
2//!
3//! Encodes multi-physics material parameters (optical BRDF, Kubelka-Munk pigment
4//! diffusion, geotechnical mechanics, Darcy hydrology, electromagnetics, and
5//! passive biocultural/open-commons provenance DID hashes).
6
7use super::chunk_directory::M64Error;
8use crate::container_10d::crc32c::crc32c;
9
10pub const CONSTITUENT_LUT_ENTRY_BYTES: usize = 64;
11
12/// Computes the canonical 64-bit FNV-1a material hash for a `did:q42` or ontology material IRI.
13#[inline]
14pub const fn canonical_q42_material_hash(iri: &str) -> u64 {
15    let bytes = iri.as_bytes();
16    let mut hash: u64 = 0xcbf29ce484222325;
17    let mut i = 0;
18    while i < bytes.len() {
19        hash ^= bytes[i] as u64;
20        hash = hash.wrapping_mul(0x100000001b3);
21        i += 1;
22    }
23    hash
24}
25
26/// Fixed 64-Byte Constituent Look-Up Table Entry.
27#[repr(C, align(64))]
28#[derive(Copy, Clone, Debug, PartialEq, bytemuck::Pod, bytemuck::Zeroable)]
29pub struct Q42ConstituentLutEntry {
30    // --- 1. Optical & Radiometric Properties (14B) ---
31    /// 6B: Diffuse albedo in linear RGB (f16 half-floats).
32    pub albedo_rgb_f16: [u16; 3],
33    /// 2B: Surface microfacet roughness (f16 half-float).
34    pub roughness_f16: u16,
35    /// 4B: Kubelka-Munk absorption (K) and scattering (S) coefficients (f16).
36    pub kubelka_munk_k_s: [u16; 2],
37    /// 2B: Real refractive index n * 100 (e.g. 154 = 1.54 for Quartz).
38    pub refractive_index_x100: u16,
39
40    // --- 2. Physical & Geotechnical Mechanics (18B) ---
41    /// 2B: Solid grain density in kg/m³ (e.g. 2650 for Quartz, 1000 for Water).
42    pub bulk_density_kg_m3: u16,
43    /// 1B: Material porosity ratio φ (0..100%).
44    pub porosity_pct: u8,
45    /// 1B: Internal friction angle φ_friction in degrees (e.g. 34° for sand).
46    pub friction_angle_deg: u8,
47    /// 2B: Mohr-Coulomb cohesion c in kPa (e.g. 0 for sand, 25 for stiff clay).
48    pub cohesion_kpa: u16,
49    /// 2B: Young's Modulus E in MPa (e.g. 35000 MPa for granite).
50    pub youngs_modulus_mpa: u16,
51    /// 1B: Poisson's ratio ν * 100 (e.g. 25 = 0.25).
52    pub poissons_ratio_x100: u8,
53    /// 1B: Padding for alignment.
54    pub _pad0: u8,
55
56    // --- 3. Hydrodynamic & Electromagnetic Properties (16B) ---
57    /// 2B: Hydraulic permeability κ in 0.01 Darcy units (e.g. 150 = 1.50 Darcy).
58    pub permeability_darcy_x100: u16,
59    /// 2B: Capillary suction head in mm.
60    pub suction_head_mm: u16,
61    /// 2B: van Genuchten empirical exponent n * 100.
62    pub van_genuchten_n_x100: u16,
63    /// 2B: Real relative dielectric permittivity ε_r * 100 (e.g. 450 = 4.5 for quartz).
64    pub dielectric_permittivity_x100: u16,
65    /// 2B: Electrical conductivity in mS/m.
66    pub electrical_conductivity_ms_m: u16,
67    /// 2B: Biot poroelastic P-wave acoustic velocity in m/s.
68    pub acoustic_p_wave_m_s: u16,
69    /// 4B: Biocultural/ceremonial permissions & customary access mask.
70    pub ceremonial_permission_mask: u32,
71
72    // --- 4. Semantic Identity & Provenance (16B) ---
73    /// 8B: Canonical FNV-1a hash of the `did:q42` mineral/material IRI.
74    pub canonical_q42_material_hash: u64,
75    /// 8B: FNV-1a hash of the provenance DID / author custodian.
76    pub provenance_did_hash: u64,
77
78    // --- 5. Integrity & Alignment (8B) ---
79    /// 4B: Explicit zero reserved.
80    pub _reserved: [u8; 4],
81    /// 4B: CRC-32C checksum of bytes 0..59 (Total = 64B).
82    pub entry_crc32c: u32,
83}
84
85impl Default for Q42ConstituentLutEntry {
86    fn default() -> Self {
87        Self {
88            albedo_rgb_f16: [0x3800, 0x3800, 0x3800], // 0.5 in f16
89            roughness_f16: 0x3800,                     // 0.5 in f16
90            kubelka_munk_k_s: [0x3000, 0x3800],
91            refractive_index_x100: 150,
92            bulk_density_kg_m3: 2650,
93            porosity_pct: 35,
94            friction_angle_deg: 32,
95            cohesion_kpa: 10,
96            youngs_modulus_mpa: 25000,
97            poissons_ratio_x100: 25,
98            _pad0: 0,
99            permeability_darcy_x100: 100,
100            suction_head_mm: 100,
101            van_genuchten_n_x100: 180,
102            dielectric_permittivity_x100: 450,
103            electrical_conductivity_ms_m: 5,
104            acoustic_p_wave_m_s: 2200,
105            ceremonial_permission_mask: 0,
106            canonical_q42_material_hash: 0,
107            provenance_did_hash: 0,
108            _reserved: [0; 4],
109            entry_crc32c: 0,
110        }
111    }
112}
113
114impl Q42ConstituentLutEntry {
115    /// Compute the CRC-32C over the first 60 bytes of the record.
116    #[inline]
117    pub fn compute_crc32c(&self) -> u32 {
118        let bytes: &[u8; CONSTITUENT_LUT_ENTRY_BYTES] = bytemuck::cast_ref(self);
119        crc32c(&bytes[..60])
120    }
121
122    /// Update `entry_crc32c` with the computed CRC-32C.
123    #[inline]
124    pub fn update_crc(&mut self) {
125        self.entry_crc32c = self.compute_crc32c();
126    }
127
128    /// Validate the CRC-32C of this LUT entry.
129    #[inline]
130    pub fn validate(&self) -> Result<(), M64Error> {
131        let computed = self.compute_crc32c();
132        if self.entry_crc32c == computed {
133            Ok(())
134        } else {
135            Err(M64Error::ChecksumMismatch {
136                stored: self.entry_crc32c,
137                computed,
138            })
139        }
140    }
141}