Skip to main content

qualia_core_db/query/
geometry_asset_shacl.rs

1//! Zero-heap SHACL/ShEx validation engine for holistic twins and geometry assets (ยง2.8 / Appended Spec).
2//!
3//! Validates `NQuin` slices against structural invariants defined in `schemas/holistic-twin.shex`
4//! and `schemas/geometry-asset.shacl.ttl` without dynamic heap allocations.
5
6use crate::entity_view::bifurcation::BifurcationContext64;
7use crate::q42::spatial_predicates::*;
8use crate::q_hash;
9use crate::NQuin;
10
11/// Violations discovered during holistic twin and geometry asset validation.
12#[derive(Debug, Clone, Copy, PartialEq, Eq)]
13pub enum GeometryShaclViolation {
14    /// Parity verification failed.
15    InvalidParity { subject: u64, predicate: u64 },
16    /// Quin sensitivity exceeded context ceiling.
17    SensitivityCeilingExceeded { declared: u8, max_permitted: u8 },
18    /// Quantum branch exceeded permitted ceiling.
19    QuantumRangeViolation { branch_q: u32, allowed_q_max: u32 },
20    /// Scale tier is out of valid range [0..=7].
21    ScaleTierOutOfRange { tier: u8 },
22    /// Topology class is out of valid range [0..=6].
23    TopologyClassOutOfRange { class_id: u8 },
24    /// Vertex count is out of valid range [1..=2^22].
25    VertexCountOutOfRange { count: u32, max: u32 },
26    /// Triangle count is out of valid range [1..=2^22].
27    TriangleCountOutOfRange { count: u32, max: u32 },
28    /// Bounding box min coordinate exceeds max along the given axis (0=x, 1=y, 2=z).
29    InvertedBbox { axis: u8 },
30    /// Claimed CRC-32C did not match container digest.
31    CompiledDigestMismatch { claimed: u32, actual: u32 },
32}
33
34/// Conformance verdict for holistic twin SHACL/ShEx validation.
35#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
36pub struct GeometryShaclVerdict {
37    /// True if zero violations were recorded.
38    pub is_valid: bool,
39    /// Total count of violations written into output slice.
40    pub violations_count: usize,
41    /// Total count of quins evaluated.
42    pub checked_quins_count: usize,
43    /// Verified compiled digest (if observed).
44    pub verified_digest: u32,
45}
46
47const P_VERTEX_COUNT: u64 = q_hash("geo:vertexCount");
48const P_TRIANGLE_COUNT: u64 = q_hash("geo:triangleCount");
49const P_COMPILED_DIGEST: u64 = q_hash("geo:compiledDigest");
50
51/// Zero-heap conformance validator over an `NQuin` slice with optional `BifurcationContext64`
52/// and container CRC-32C verification.
53pub fn validate_holistic_twin_quins_zero_heap(
54    quins: &[NQuin],
55    bifurcation_ctx: Option<&BifurcationContext64>,
56    actual_container_crc32c: Option<u32>,
57    violations_out: &mut [GeometryShaclViolation],
58) -> GeometryShaclVerdict {
59    let mut written = 0;
60    let mut verified_digest = 0u32;
61
62    let mut record_violation = |v: GeometryShaclViolation, w: &mut usize| {
63        if *w < violations_out.len() {
64            violations_out[*w] = v;
65            *w += 1;
66        }
67    };
68
69    let mut bbox_min_obj: Option<u64> = None;
70    let mut bbox_max_obj: Option<u64> = None;
71
72    for q in quins {
73        // 1. ECC Parity
74        if !q.verify_ecc_parity() {
75            record_violation(
76                GeometryShaclViolation::InvalidParity {
77                    subject: q.subject,
78                    predicate: q.predicate,
79                },
80                &mut written,
81            );
82        }
83
84        // 2. Sensitivity Ceiling
85        if let Some(ctx) = bifurcation_ctx {
86            let sens = q.get_sensitivity_byte();
87            if sens > ctx.max_sensitivity_class {
88                record_violation(
89                    GeometryShaclViolation::SensitivityCeilingExceeded {
90                        declared: sens,
91                        max_permitted: ctx.max_sensitivity_class,
92                    },
93                    &mut written,
94                );
95            }
96        }
97
98        // 3. Predicate Invariants
99        match q.predicate {
100            PRED_GEO_HAS_SCALE_TIER => {
101                let tier = (q.object & 0xFF) as u8;
102                if tier > 7 {
103                    record_violation(
104                        GeometryShaclViolation::ScaleTierOutOfRange { tier },
105                        &mut written,
106                    );
107                }
108            }
109            PRED_GEO_HAS_TOPOLOGY_CLASS => {
110                let class_id = (q.object & 0xFF) as u8;
111                if class_id > 6 {
112                    record_violation(
113                        GeometryShaclViolation::TopologyClassOutOfRange { class_id },
114                        &mut written,
115                    );
116                }
117            }
118            PRED_EPI_HAS_QUANTUM_RANGE => {
119                let branch_q = q.object as u32;
120                if let Some(ctx) = bifurcation_ctx {
121                    if branch_q > ctx.allowed_q_max {
122                        record_violation(
123                            GeometryShaclViolation::QuantumRangeViolation {
124                                branch_q,
125                                allowed_q_max: ctx.allowed_q_max,
126                            },
127                            &mut written,
128                        );
129                    }
130                }
131            }
132            P_VERTEX_COUNT => {
133                let count = q.object as u32;
134                if count == 0 || count > (1 << 22) {
135                    record_violation(
136                        GeometryShaclViolation::VertexCountOutOfRange {
137                            count,
138                            max: 1 << 22,
139                        },
140                        &mut written,
141                    );
142                }
143            }
144            P_TRIANGLE_COUNT => {
145                let count = q.object as u32;
146                if count == 0 || count > (1 << 22) {
147                    record_violation(
148                        GeometryShaclViolation::TriangleCountOutOfRange {
149                            count,
150                            max: 1 << 22,
151                        },
152                        &mut written,
153                    );
154                }
155            }
156            P_COMPILED_DIGEST | PRED_Q42_HAS_CONTAINER_10D => {
157                let claimed = q.object as u32;
158                verified_digest = claimed;
159                if let Some(actual) = actual_container_crc32c {
160                    if claimed != actual {
161                        record_violation(
162                            GeometryShaclViolation::CompiledDigestMismatch { claimed, actual },
163                            &mut written,
164                        );
165                    }
166                }
167            }
168            PRED_GEO_HAS_PACKED_BBOX_MIN => {
169                bbox_min_obj = Some(q.object);
170            }
171            PRED_GEO_HAS_PACKED_BBOX_MAX => {
172                bbox_max_obj = Some(q.object);
173            }
174            _ => {}
175        }
176    }
177
178    // 4. Bounding Box Inversion Check
179    if let (Some(min_raw), Some(max_raw)) = (bbox_min_obj, bbox_max_obj) {
180        let (min_x, min_y, min_z, _) = unpack_coord_with_scale(min_raw);
181        let (max_x, max_y, max_z, _) = unpack_coord_with_scale(max_raw);
182        if min_x > max_x {
183            record_violation(GeometryShaclViolation::InvertedBbox { axis: 0 }, &mut written);
184        }
185        if min_y > max_y {
186            record_violation(GeometryShaclViolation::InvertedBbox { axis: 1 }, &mut written);
187        }
188        if min_z > max_z {
189            record_violation(GeometryShaclViolation::InvertedBbox { axis: 2 }, &mut written);
190        }
191    }
192
193    GeometryShaclVerdict {
194        is_valid: written == 0,
195        violations_count: written,
196        checked_quins_count: quins.len(),
197        verified_digest,
198    }
199}
200
201#[cfg(test)]
202mod tests {
203    use super::*;
204
205    fn make_valid_quin(subject: u64, pred: u64, obj: u64, ctx: u64, meta: u64) -> NQuin {
206        let parity = NQuin::calculate_parity(subject, pred, obj, ctx, meta);
207        NQuin {
208            subject,
209            predicate: pred,
210            object: obj,
211            context: ctx,
212            metadata: meta,
213            parity,
214        }
215    }
216
217    #[test]
218    fn valid_holistic_twin_quins_pass() {
219        let q1 = make_valid_quin(1, PRED_GEO_HAS_SCALE_TIER, 3, 0, 0);
220        let q2 = make_valid_quin(1, PRED_GEO_HAS_TOPOLOGY_CLASS, 2, 0, 0);
221        let q3 = make_valid_quin(1, P_COMPILED_DIGEST, 0xAABBCCDD, 0, 0);
222
223        let quins = [q1, q2, q3];
224        let mut violations = [GeometryShaclViolation::ScaleTierOutOfRange { tier: 0 }; 8];
225
226        let verdict = validate_holistic_twin_quins_zero_heap(
227            &quins,
228            None,
229            Some(0xAABBCCDD),
230            &mut violations,
231        );
232        assert!(verdict.is_valid);
233        assert_eq!(verdict.violations_count, 0);
234        assert_eq!(verdict.checked_quins_count, 3);
235        assert_eq!(verdict.verified_digest, 0xAABBCCDD);
236    }
237
238    #[test]
239    fn invalid_scale_tier_is_caught() {
240        let q = make_valid_quin(1, PRED_GEO_HAS_SCALE_TIER, 9, 0, 0);
241        let quins = [q];
242        let mut violations = [GeometryShaclViolation::ScaleTierOutOfRange { tier: 0 }; 4];
243
244        let verdict = validate_holistic_twin_quins_zero_heap(
245            &quins,
246            None,
247            None,
248            &mut violations,
249        );
250        assert!(!verdict.is_valid);
251        assert_eq!(verdict.violations_count, 1);
252        assert_eq!(
253            violations[0],
254            GeometryShaclViolation::ScaleTierOutOfRange { tier: 9 }
255        );
256    }
257
258    #[test]
259    fn compiled_digest_mismatch_is_caught() {
260        let q = make_valid_quin(1, P_COMPILED_DIGEST, 0x11112222, 0, 0);
261        let quins = [q];
262        let mut violations = [GeometryShaclViolation::ScaleTierOutOfRange { tier: 0 }; 4];
263
264        let verdict = validate_holistic_twin_quins_zero_heap(
265            &quins,
266            None,
267            Some(0x33334444),
268            &mut violations,
269        );
270        assert!(!verdict.is_valid);
271        assert_eq!(verdict.violations_count, 1);
272        assert_eq!(
273            violations[0],
274            GeometryShaclViolation::CompiledDigestMismatch {
275                claimed: 0x11112222,
276                actual: 0x33334444,
277            }
278        );
279    }
280
281    #[test]
282    fn inverted_bbox_is_caught() {
283        let min_raw = pack_coord_with_scale(10.0, 0.0, 0.0, 0);
284        let max_raw = pack_coord_with_scale(5.0, 0.0, 0.0, 0); // min_x > max_x
285
286        let q1 = make_valid_quin(1, PRED_GEO_HAS_PACKED_BBOX_MIN, min_raw, 0, 0);
287        let q2 = make_valid_quin(1, PRED_GEO_HAS_PACKED_BBOX_MAX, max_raw, 0, 0);
288
289        let quins = [q1, q2];
290        let mut violations = [GeometryShaclViolation::ScaleTierOutOfRange { tier: 0 }; 4];
291
292        let verdict = validate_holistic_twin_quins_zero_heap(
293            &quins,
294            None,
295            None,
296            &mut violations,
297        );
298        assert!(!verdict.is_valid);
299        assert_eq!(verdict.violations_count, 1);
300        assert_eq!(violations[0], GeometryShaclViolation::InvertedBbox { axis: 0 });
301    }
302}