Skip to main content

qualia_core_db/entity_view/
bifurcation.rs

1//! Epistemic, temporal and observer-relative bifurcation kernel (§3.6.3 / §3.4).
2//!
3//! Provides the 64-byte cache-aligned `BifurcationContext64` descriptor and
4//! zero-heap filtering primitives (`evaluate_quin_bifurcation`, `filter_quins_bifurcated_into`)
5//! for fine-grained per-element visibility, LOD culling, and epistemic isolation.
6
7use crate::NQuin;
8use bytemuck::{Pod, Zeroable};
9
10/// Epistemic truth status for an element or proposition.
11#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize, Default)]
12#[repr(u8)]
13pub enum EpistemicKind {
14    /// Empirically verified observational or sensor datum.
15    #[default]
16    EmpiricalFact = 0,
17    /// Rigorous, non-fictional scientific inference or theoretical prediction.
18    TheoreticalHypothesis = 1,
19    /// Speculative counterfactual variant.
20    Counterfactual = 2,
21    /// Narrative, fictional, or pedagogical construct.
22    FictionalConstruct = 3,
23    /// Epistemically degraded claim under Socratic qualification gate.
24    SocraticDegraded = 4,
25}
26
27// ── Sensitivity Class Constants ──────────────────────────────────────────
28pub const SENSITIVITY_PUBLIC: u8 = 0;
29pub const SENSITIVITY_RESTRICTED: u8 = 1;
30pub const SENSITIVITY_CLASSIFIED: u8 = 2;
31pub const SENSITIVITY_SANCTUARY: u8 = 3;
32
33// ── Socio-Cognitive Wing Selectors ───────────────────────────────────────
34pub const WING_PUBLIC_TWIN: u8 = 0;
35pub const WING_PERSONAL_TWIN: u8 = 1;
36pub const WING_CLINICAL_DIAGNOSTIC: u8 = 2;
37pub const WING_ENGINEERING_AUDIT: u8 = 3;
38
39// ── Bifurcation Context Flags ────────────────────────────────────────────
40pub const FLAG_REQUIRE_PARITY: u16 = 0x0001;
41pub const FLAG_STRICT_SUBJECT: u16 = 0x0002;
42pub const FLAG_STRICT_EPOCH: u16 = 0x0004;
43pub const FLAG_DEONTIC_FILTER: u16 = 0x0008;
44
45/// 64-byte cache-aligned context for multi-observer epistemic bifurcation.
46///
47/// Guaranteed `Pod + Zeroable` layout with zero internal padding bytes.
48#[repr(C, align(64))]
49#[derive(Clone, Copy, Debug, PartialEq, Eq, Pod, Zeroable)]
50pub struct BifurcationContext64 {
51    /// FNV-1a hash of observer DID.
52    pub observer_did_hash: u64,
53    /// FNV-1a hash of subject entity DID (0 = wildcard / accept any).
54    pub subject_did_hash: u64,
55    /// Cryptographic consent receipt token hash.
56    pub consent_receipt_hash: u64,
57    /// Bitmask of active `ManifoldDomain` indices (bits 0..=12).
58    pub active_manifold_mask: u16,
59    /// Maximum sensitivity class allowed (0=Public..3=Sanctuary).
60    pub max_sensitivity_class: u8,
61    /// Active representation wing selector (0=PublicTwin..3=EngineeringAudit).
62    pub wing_selector: u8,
63    /// Maximum visible quantum state index `q` (0 = ground truth only).
64    pub allowed_q_max: u32,
65    /// Lamport logical clock ceiling / epoch boundary.
66    pub lamport_epoch: u64,
67    /// Affordance permission bitmask.
68    pub affordance_mask: u64,
69    /// Finest permitted spatial LOD tier (0..=7).
70    pub spatial_lod_cap: u8,
71    /// Deontic routing lane filter (0 = passthrough / any).
72    pub deontic_routing_lane: u8,
73    /// Operational flags (`FLAG_REQUIRE_PARITY`, etc.).
74    pub flags: u16,
75    /// Castagnoli CRC-32C of bytes 0..52.
76    pub context_crc32c: u32,
77    /// Reserved for hardware alignment and future extensions.
78    pub reserved: [u8; 8],
79}
80
81// Compile-time layout guarantees
82const _: () = assert!(core::mem::size_of::<BifurcationContext64>() == 64);
83const _: () = assert!(core::mem::align_of::<BifurcationContext64>() == 64);
84
85impl Default for BifurcationContext64 {
86    fn default() -> Self {
87        let mut ctx = Self {
88            observer_did_hash: 0,
89            subject_did_hash: 0,
90            consent_receipt_hash: 0,
91            active_manifold_mask: 0x1FFF, // All 13 manifold domains enabled
92            max_sensitivity_class: SENSITIVITY_PUBLIC,
93            wing_selector: WING_PUBLIC_TWIN,
94            allowed_q_max: u32::MAX,
95            lamport_epoch: 0,
96            affordance_mask: u64::MAX,
97            spatial_lod_cap: 7,
98            deontic_routing_lane: 0,
99            flags: FLAG_REQUIRE_PARITY,
100            context_crc32c: 0,
101            reserved: [0u8; 8],
102        };
103        ctx.seal_crc32c();
104        ctx
105    }
106}
107
108impl BifurcationContext64 {
109    /// Compute the CRC-32C checksum over the 52 header bytes preceding `context_crc32c`.
110    #[inline]
111    pub fn compute_crc32c(&self) -> u32 {
112        let bytes = bytemuck::bytes_of(self);
113        crate::container_10d::crc32c::crc32c(&bytes[..52])
114    }
115
116    /// Update `context_crc32c` in place.
117    #[inline]
118    pub fn seal_crc32c(&mut self) {
119        self.context_crc32c = self.compute_crc32c();
120    }
121
122    /// Check if `context_crc32c` matches the computed checksum.
123    #[inline]
124    pub fn verify_crc32c(&self) -> bool {
125        self.context_crc32c == self.compute_crc32c()
126    }
127}
128
129/// Zero-heap evaluation of an `NQuin` against a `BifurcationContext64`.
130///
131/// Returns `true` if the quin satisfies parity, sensitivity, subject, and epoch constraints.
132#[inline]
133pub fn evaluate_quin_bifurcation(ctx: &BifurcationContext64, quin: &NQuin) -> bool {
134    // 1. ECC parity verification
135    if (ctx.flags & FLAG_REQUIRE_PARITY) != 0 && !quin.verify_ecc_parity() {
136        return false;
137    }
138
139    // 2. Sensitivity ceiling check
140    let quin_sens = quin.get_sensitivity_byte();
141    if quin_sens > ctx.max_sensitivity_class {
142        return false;
143    }
144
145    // 3. Subject DID filtering
146    if (ctx.flags & FLAG_STRICT_SUBJECT) != 0 && ctx.subject_did_hash != 0 {
147        let quin_subj = quin.subject & 0x7FFF_FFFF_FFFF_FFFF;
148        let expected_subj = ctx.subject_did_hash & 0x7FFF_FFFF_FFFF_FFFF;
149        if quin_subj != expected_subj {
150            return false;
151        }
152    }
153
154    // 4. Lamport epoch boundary check
155    if (ctx.flags & FLAG_STRICT_EPOCH) != 0 && ctx.lamport_epoch != 0 {
156        let quin_clock = quin.extract_lamport_clock() as u64;
157        if quin_clock > ctx.lamport_epoch {
158            return false;
159        }
160    }
161
162    // 5. Deontic routing lane filter
163    if (ctx.flags & FLAG_DEONTIC_FILTER) != 0 && ctx.deontic_routing_lane != 0 {
164        let quin_lane = ((quin.metadata >> 61) & 0b11) as u8;
165        if quin_lane != ctx.deontic_routing_lane {
166            return false;
167        }
168    }
169
170    true
171}
172
173/// Filter a slice of `NQuin`s into a caller-supplied fixed buffer without allocating.
174///
175/// Returns the number of quins written into `out`.
176pub fn filter_quins_bifurcated_into(
177    ctx: &BifurcationContext64,
178    quins: &[NQuin],
179    out: &mut [NQuin],
180) -> usize {
181    let mut written = 0;
182    for q in quins {
183        if evaluate_quin_bifurcation(ctx, q) {
184            if written < out.len() {
185                out[written] = *q;
186                written += 1;
187            } else {
188                break;
189            }
190        }
191    }
192    written
193}
194
195#[cfg(test)]
196mod tests {
197    use super::*;
198
199    fn make_valid_quin(subject: u64, pred: u64, obj: u64, ctx: u64, meta: u64) -> NQuin {
200        let parity = NQuin::calculate_parity(subject, pred, obj, ctx, meta);
201        NQuin {
202            subject,
203            predicate: pred,
204            object: obj,
205            context: ctx,
206            metadata: meta,
207            parity,
208        }
209    }
210
211    #[test]
212    fn context_size_and_alignment_are_64() {
213        assert_eq!(core::mem::size_of::<BifurcationContext64>(), 64);
214        assert_eq!(core::mem::align_of::<BifurcationContext64>(), 64);
215    }
216
217    #[test]
218    fn crc32c_sealing_and_verification() {
219        let mut ctx = BifurcationContext64::default();
220        assert!(ctx.verify_crc32c());
221
222        ctx.allowed_q_max = 42;
223        assert!(!ctx.verify_crc32c());
224        ctx.seal_crc32c();
225        assert!(ctx.verify_crc32c());
226    }
227
228    #[test]
229    fn parity_rejection() {
230        let ctx = BifurcationContext64::default();
231        let mut q = make_valid_quin(1, 2, 3, 0, 0);
232        assert!(evaluate_quin_bifurcation(&ctx, &q));
233
234        q.parity ^= 1; // Corrupt parity
235        assert!(!evaluate_quin_bifurcation(&ctx, &q));
236    }
237
238    #[test]
239    fn sensitivity_ceiling_filter() {
240        let mut ctx = BifurcationContext64::default();
241        ctx.max_sensitivity_class = SENSITIVITY_PUBLIC;
242
243        let q_pub = make_valid_quin(1, 2, 3, (SENSITIVITY_PUBLIC as u64) << 56, 0);
244        let q_restr = make_valid_quin(1, 2, 3, (SENSITIVITY_RESTRICTED as u64) << 56, 0);
245
246        assert!(evaluate_quin_bifurcation(&ctx, &q_pub));
247        assert!(!evaluate_quin_bifurcation(&ctx, &q_restr));
248
249        ctx.max_sensitivity_class = SENSITIVITY_RESTRICTED;
250        assert!(evaluate_quin_bifurcation(&ctx, &q_restr));
251    }
252
253    #[test]
254    fn filter_quins_zero_heap_into_buffer() {
255        let ctx = BifurcationContext64::default();
256        let q1 = make_valid_quin(1, 2, 3, 0, 0);
257        let q2 = make_valid_quin(4, 5, 6, 0, 0);
258        let mut q3_corrupted = make_valid_quin(7, 8, 9, 0, 0);
259        q3_corrupted.parity ^= 0xFF;
260
261        let input = [q1, q2, q3_corrupted];
262        let mut out = [NQuin::default(); 4];
263
264        let n = filter_quins_bifurcated_into(&ctx, &input, &mut out);
265        assert_eq!(n, 2);
266        assert_eq!(out[0].subject, 1);
267        assert_eq!(out[1].subject, 4);
268    }
269}