Skip to main content

qualia_core_db/tensor/
quantum.rs

1//! Quantum context (q) for epistemic superposition and wavefunction collapse
2
3use serde::{Deserialize, Serialize};
4
5/// Quantum context state
6#[repr(C)]
7#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
8pub enum QuantumState {
9    /// Collapsed Ground Truth (q = 0)
10    GroundTruth = 0,
11    /// Parallel epistemic context (q > 0)
12    ParallelContext = 1,
13    /// Pending GSR resolution ("In Escrow")
14    InEscrow = 2,
15    /// Sandbox evaluation (e.g., isolated q=999)
16    Sandbox = 3,
17}
18
19impl Default for QuantumState {
20    fn default() -> Self {
21        QuantumState::GroundTruth
22    }
23}
24
25impl QuantumState {
26    /// Builds `QuantumState` from `q_value`.
27    pub fn from_q_value(q: f32) -> Self {
28        if q == 0.0 {
29            QuantumState::GroundTruth
30        } else if q >= 999.0 {
31            QuantumState::Sandbox
32        } else {
33            QuantumState::ParallelContext
34        }
35    }
36
37    /// Converts to `q_value`.
38    pub fn to_q_value(&self) -> f32 {
39        match self {
40            QuantumState::GroundTruth => 0.0,
41            QuantumState::ParallelContext => 1.0,
42            QuantumState::InEscrow => 2.0,
43            QuantumState::Sandbox => 999.0,
44        }
45    }
46}
47
48/// Five-band quantum context range (ยง2.1)
49#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
50pub enum QuantumContextRange {
51    /// Empirical Ground Truth (q == 0)
52    EmpiricalGroundTruth,
53    /// Theoretical Hypothesis (q in 1..=998, branch ID)
54    TheoreticalHypothesis(u16),
55    /// Epistemic Escrow (q == 999, isolated quarantine / unverified LLM output)
56    EpistemicEscrow,
57    /// Fictional Construct (q in 1000..=65535, universe / world ID)
58    FictionalConstruct(u16),
59    /// Quantum Eigenstate (q >= 65536, packed (n, l, m) or Fock state ID)
60    QuantumEigenstate(u32),
61}
62
63impl Default for QuantumContextRange {
64    fn default() -> Self {
65        Self::EmpiricalGroundTruth
66    }
67}
68
69impl QuantumContextRange {
70    /// Builds `QuantumContextRange` from continuous `q` value.
71    pub fn from_q_value(q: f32) -> Self {
72        if q <= 0.0 || q.abs() < 1e-6 {
73            Self::EmpiricalGroundTruth
74        } else if q < 998.5 {
75            let branch = q.round().clamp(1.0, 998.0) as u16;
76            Self::TheoreticalHypothesis(branch)
77        } else if q < 999.5 {
78            Self::EpistemicEscrow
79        } else if q < 65535.5 {
80            let world = q.round().clamp(1000.0, 65535.0) as u16;
81            Self::FictionalConstruct(world)
82        } else {
83            Self::QuantumEigenstate(q.round().max(65536.0) as u32)
84        }
85    }
86
87    /// Converts to canonical continuous `q` value.
88    pub fn to_q_value(&self) -> f32 {
89        match self {
90            Self::EmpiricalGroundTruth => 0.0,
91            Self::TheoreticalHypothesis(b) => *b as f32,
92            Self::EpistemicEscrow => 999.0,
93            Self::FictionalConstruct(u) => *u as f32,
94            Self::QuantumEigenstate(id) => {
95                if *id >= 65536 {
96                    *id as f32
97                } else {
98                    (*id + 65536) as f32
99                }
100            }
101        }
102    }
103
104    /// Pack hydrogenic quantum numbers `(n, l, m)` into `QuantumEigenstate`.
105    ///
106    /// Principal quantum number `n >= 1` (bits 16..23).
107    /// Orbital angular momentum `0 <= l < n` (bits 8..15).
108    /// Magnetic quantum number `-l <= m <= l` (bits 0..7 as two's-complement `i8`).
109    /// With `n >= 1`, the packed value is naturally `>= 65536`.
110    pub fn pack_hydrogenic_nlm(n: u8, l: u8, m: i8) -> Self {
111        let n_eff = n.max(1) as u32;
112        let l_eff = (l as u32) & 0xFF;
113        let m_eff = (m as u8 as u32) & 0xFF;
114        let packed = (n_eff << 16) | (l_eff << 8) | m_eff;
115        Self::QuantumEigenstate(packed)
116    }
117
118    /// Unpack hydrogenic quantum numbers `(n, l, m)` if this is a valid hydrogenic eigenstate.
119    pub fn unpack_hydrogenic_nlm(&self) -> Option<(u8, u8, i8)> {
120        match self {
121            Self::QuantumEigenstate(packed) => {
122                let n = ((packed >> 16) & 0xFF) as u8;
123                let l = ((packed >> 8) & 0xFF) as u8;
124                let m = (packed & 0xFF) as u8 as i8;
125                if n >= 1 && l < n && m >= -(l as i8) && m <= (l as i8) {
126                    Some((n, l, m))
127                } else {
128                    None
129                }
130            }
131            _ => None,
132        }
133    }
134}
135
136#[cfg(test)]
137mod tests {
138    use super::*;
139
140    #[test]
141    fn test_all_five_bands() {
142        assert_eq!(
143            QuantumContextRange::from_q_value(0.0),
144            QuantumContextRange::EmpiricalGroundTruth
145        );
146        assert_eq!(
147            QuantumContextRange::from_q_value(1.0),
148            QuantumContextRange::TheoreticalHypothesis(1)
149        );
150        assert_eq!(
151            QuantumContextRange::from_q_value(500.0),
152            QuantumContextRange::TheoreticalHypothesis(500)
153        );
154        assert_eq!(
155            QuantumContextRange::from_q_value(998.0),
156            QuantumContextRange::TheoreticalHypothesis(998)
157        );
158        assert_eq!(
159            QuantumContextRange::from_q_value(999.0),
160            QuantumContextRange::EpistemicEscrow
161        );
162        assert_eq!(
163            QuantumContextRange::from_q_value(1000.0),
164            QuantumContextRange::FictionalConstruct(1000)
165        );
166        assert_eq!(
167            QuantumContextRange::from_q_value(65535.0),
168            QuantumContextRange::FictionalConstruct(65535)
169        );
170        assert_eq!(
171            QuantumContextRange::from_q_value(65536.0),
172            QuantumContextRange::QuantumEigenstate(65536)
173        );
174    }
175
176    #[test]
177    fn test_to_q_value_round_trips() {
178        let cases = [
179            QuantumContextRange::EmpiricalGroundTruth,
180            QuantumContextRange::TheoreticalHypothesis(12),
181            QuantumContextRange::EpistemicEscrow,
182            QuantumContextRange::FictionalConstruct(4200),
183            QuantumContextRange::QuantumEigenstate(70000),
184        ];
185        for case in cases {
186            let q = case.to_q_value();
187            let recovered = QuantumContextRange::from_q_value(q);
188            assert_eq!(case, recovered);
189        }
190    }
191
192    #[test]
193    fn test_hydrogenic_nlm_packing_round_trips() {
194        let test_orbitals = [
195            (1u8, 0u8, 0i8),    // 1s
196            (2u8, 0u8, 0i8),    // 2s
197            (2u8, 1u8, -1i8),   // 2p_-1
198            (2u8, 1u8, 0i8),    // 2p_0
199            (2u8, 1u8, 1i8),    // 2p_+1
200            (3u8, 2u8, -2i8),   // 3d_-2
201            (3u8, 2u8, 2i8),    // 3d_+2
202            (4u8, 3u8, -3i8),   // 4f_-3
203        ];
204        for (n, l, m) in test_orbitals {
205            let state = QuantumContextRange::pack_hydrogenic_nlm(n, l, m);
206            let q = state.to_q_value();
207            assert!(q >= 65536.0, "Eigenstate q must be >= 65536");
208            let recovered_range = QuantumContextRange::from_q_value(q);
209            let unpacked = recovered_range.unpack_hydrogenic_nlm();
210            assert_eq!(unpacked, Some((n, l, m)));
211        }
212    }
213
214    #[test]
215    fn test_invalid_nlm_unpacks_none() {
216        assert_eq!(
217            QuantumContextRange::EmpiricalGroundTruth.unpack_hydrogenic_nlm(),
218            None
219        );
220        // l >= n is invalid
221        let invalid = QuantumContextRange::QuantumEigenstate((1 << 16) | (1 << 8));
222        assert_eq!(invalid.unpack_hydrogenic_nlm(), None);
223    }
224}