Skip to main content

qualia_core_db/specialized_libs/
mod.rs

1//! Specialized Libraries Module
2//!
3//! This module contains high-performance specialized mathematical and scientific libraries
4//! that leverage Phase 2 architectural enhancements for unprecedented performance and capabilities.
5//!
6//! # Cold Domain Decoupling and Module Caller Audit
7//!
8//! Cold scientific and hardware domains are staged for opt-in feature gating:
9//! - `chemistry_modeling`: Quantum chemistry, DFT, and Roothaan-Hall SCF. Referenced by
10//!   `mcp::mcp_tool_impls::chemistry` and `poet_host::invoke::science::chem`.
11//! - `financial_modeling`: Option pricing, Black-Scholes, and portfolio risk. Referenced
12//!   by `poet_host::invoke::econ::{ml_finance, portfolio}`.
13//! - `qpu_bridge`: Quantum processing unit job scheduler and driver interfaces. Referenced
14//!   by `mcp::mcp_stub_impls`.
15//! - `quantum_biology`: Biological quantum coherence and state synchronization. A true
16//!   leaf module with zero external callers across `qualia-core-db`. Gated cleanly under
17//!   `all(not(target_arch = "wasm32"), not(feature = "minimal-fast-build"))`.
18//!
19//! All public module re-exports are 100% preserved under default/monolith builds.
20//! Use [`active_specialized_lib_mask`] to query active modules with zero heap allocations.
21
22#[cfg(not(target_arch = "wasm32"))]
23pub mod category_theory;
24#[cfg(not(target_arch = "wasm32"))]
25pub mod chemistry_modeling;
26/// Computational economics and finance coordination layer: capability matrices,
27/// shared categorical transforms, and native economics kernels. Kept available
28/// to WASM because the first layer is metadata + zero-dependency utilities.
29pub mod computational_economics;
30/// Native computational geometry: robust predicates, topology/graph structures,
31/// Q42/10D adapters, and the computational-geometry algorithm families. Unlike the older
32/// specialized libraries this module is available to browser/WASM builds.
33pub mod computational_geometry;
34pub mod computer_vision;
35#[cfg(any(not(target_arch = "wasm32"), feature = "wasm-scientific"))]
36pub mod constructibility;
37#[cfg(not(target_arch = "wasm32"))]
38pub mod cryptographic_library;
39#[cfg(not(target_arch = "wasm32"))]
40pub mod engineering_analysis;
41#[cfg(not(target_arch = "wasm32"))]
42pub mod financial_modeling;
43#[cfg(any(
44    not(target_arch = "wasm32"),
45    feature = "portal",
46    feature = "wasm-webcivics",
47    feature = "device-harness",
48    feature = "wasm-logic",
49    feature = "wasm-scientific"
50))]
51pub mod linear_algebra;
52#[cfg(not(target_arch = "wasm32"))]
53pub mod machine_learning;
54#[cfg(any(
55    not(target_arch = "wasm32"),
56    feature = "device-harness",
57    feature = "portal",
58    feature = "wasm-logic",
59    feature = "wasm-scientific"
60))]
61pub mod medical_computing;
62#[cfg(any(not(target_arch = "wasm32"), feature = "wasm-scientific"))]
63pub mod multivar_calculus;
64#[cfg(any(not(target_arch = "wasm32"), feature = "wasm-scientific"))]
65pub mod physics_simulation;
66#[cfg(any(not(target_arch = "wasm32"), feature = "wasm-scientific"))]
67pub mod polynomial_algebra;
68#[cfg(not(target_arch = "wasm32"))]
69pub mod qpu_bridge;
70#[cfg(all(not(target_arch = "wasm32"), not(feature = "minimal-fast-build")))]
71pub mod quantum_biology;
72#[cfg(not(target_arch = "wasm32"))]
73pub mod statistical_computing;
74pub mod symbolic_algebra;
75#[cfg(any(not(target_arch = "wasm32"), feature = "wasm-scientific"))]
76pub mod symbolic_assumptions;
77#[cfg(any(not(target_arch = "wasm32"), feature = "wasm-scientific"))]
78pub mod symbolic_integration;
79#[cfg(any(not(target_arch = "wasm32"), feature = "wasm-scientific"))]
80pub mod symbolic_limits;
81#[cfg(any(not(target_arch = "wasm32"), feature = "wasm-scientific"))]
82pub mod symbolic_ode;
83#[cfg(any(not(target_arch = "wasm32"), feature = "wasm-scientific"))]
84pub mod symbolic_series;
85#[cfg(any(not(target_arch = "wasm32"), feature = "wasm-scientific"))]
86pub mod symbolic_solve;
87#[cfg(any(not(target_arch = "wasm32"), feature = "wasm-scientific"))]
88pub mod symbolic_trig;
89
90// Shared zero-heap utilities
91#[cfg(any(
92    not(target_arch = "wasm32"),
93    feature = "portal",
94    feature = "wasm-logic",
95    feature = "wasm-scientific"
96))]
97pub mod shared;
98#[cfg(any(
99    not(target_arch = "wasm32"),
100    feature = "portal",
101    feature = "wasm-logic",
102    feature = "wasm-scientific"
103))]
104pub use shared::{FixedArray, FixedQueue, FixedStack, RingBuffer};
105
106// ── Library Bitmask Constants (1 << N) ───────────────────────────────────────
107
108pub const LIB_CATEGORY_THEORY: u32 = 1 << 0;
109pub const LIB_CHEMISTRY_MODELING: u32 = 1 << 1;
110pub const LIB_COMPUTATIONAL_ECONOMICS: u32 = 1 << 2;
111pub const LIB_COMPUTATIONAL_GEOMETRY: u32 = 1 << 3;
112pub const LIB_COMPUTER_VISION: u32 = 1 << 4;
113pub const LIB_CONSTRUCTIBILITY: u32 = 1 << 5;
114pub const LIB_CRYPTOGRAPHIC_LIBRARY: u32 = 1 << 6;
115pub const LIB_ENGINEERING_ANALYSIS: u32 = 1 << 7;
116pub const LIB_FINANCIAL_MODELING: u32 = 1 << 8;
117pub const LIB_LINEAR_ALGEBRA: u32 = 1 << 9;
118pub const LIB_MACHINE_LEARNING: u32 = 1 << 10;
119pub const LIB_MEDICAL_COMPUTING: u32 = 1 << 11;
120pub const LIB_MULTIVAR_CALCULUS: u32 = 1 << 12;
121pub const LIB_PHYSICS_SIMULATION: u32 = 1 << 13;
122pub const LIB_POLYNOMIAL_ALGEBRA: u32 = 1 << 14;
123pub const LIB_QPU_BRIDGE: u32 = 1 << 15;
124pub const LIB_QUANTUM_BIOLOGY: u32 = 1 << 16;
125pub const LIB_STATISTICAL_COMPUTING: u32 = 1 << 17;
126pub const LIB_SYMBOLIC_ALGEBRA: u32 = 1 << 18;
127pub const LIB_SYMBOLIC_ASSUMPTIONS: u32 = 1 << 19;
128pub const LIB_SYMBOLIC_INTEGRATION: u32 = 1 << 20;
129pub const LIB_SYMBOLIC_LIMITS: u32 = 1 << 21;
130pub const LIB_SYMBOLIC_ODE: u32 = 1 << 22;
131pub const LIB_SYMBOLIC_SERIES: u32 = 1 << 23;
132pub const LIB_SYMBOLIC_SOLVE: u32 = 1 << 24;
133pub const LIB_SYMBOLIC_TRIG: u32 = 1 << 25;
134pub const LIB_SHARED: u32 = 1 << 26;
135
136// ── Zero-Heap Capability Query Functions ─────────────────────────────────────
137
138/// Returns the 32-bit bitmask of active specialized libraries compiled into this binary.
139///
140/// Pure `const fn` executing with zero heap allocations (Tier-1 contract).
141#[inline(always)]
142pub const fn active_specialized_lib_mask() -> u32 {
143    let mut mask = 0u32;
144
145    #[cfg(not(target_arch = "wasm32"))]
146    {
147        mask |= LIB_CATEGORY_THEORY;
148        mask |= LIB_CHEMISTRY_MODELING;
149        mask |= LIB_CRYPTOGRAPHIC_LIBRARY;
150        mask |= LIB_ENGINEERING_ANALYSIS;
151        mask |= LIB_FINANCIAL_MODELING;
152        mask |= LIB_MACHINE_LEARNING;
153        mask |= LIB_QPU_BRIDGE;
154        mask |= LIB_STATISTICAL_COMPUTING;
155    }
156
157    #[cfg(all(not(target_arch = "wasm32"), not(feature = "minimal-fast-build")))]
158    {
159        mask |= LIB_QUANTUM_BIOLOGY;
160    }
161
162    // Always available (native and WASM)
163    mask |= LIB_COMPUTATIONAL_ECONOMICS;
164    mask |= LIB_COMPUTATIONAL_GEOMETRY;
165    mask |= LIB_COMPUTER_VISION;
166    mask |= LIB_SYMBOLIC_ALGEBRA;
167
168    #[cfg(any(not(target_arch = "wasm32"), feature = "wasm-scientific"))]
169    {
170        mask |= LIB_CONSTRUCTIBILITY;
171        mask |= LIB_MULTIVAR_CALCULUS;
172        mask |= LIB_PHYSICS_SIMULATION;
173        mask |= LIB_POLYNOMIAL_ALGEBRA;
174        mask |= LIB_SYMBOLIC_ASSUMPTIONS;
175        mask |= LIB_SYMBOLIC_INTEGRATION;
176        mask |= LIB_SYMBOLIC_LIMITS;
177        mask |= LIB_SYMBOLIC_ODE;
178        mask |= LIB_SYMBOLIC_SERIES;
179        mask |= LIB_SYMBOLIC_SOLVE;
180        mask |= LIB_SYMBOLIC_TRIG;
181    }
182
183    #[cfg(any(
184        not(target_arch = "wasm32"),
185        feature = "portal",
186        feature = "wasm-webcivics",
187        feature = "device-harness",
188        feature = "wasm-logic",
189        feature = "wasm-scientific"
190    ))]
191    {
192        mask |= LIB_LINEAR_ALGEBRA;
193    }
194
195    #[cfg(any(
196        not(target_arch = "wasm32"),
197        feature = "device-harness",
198        feature = "portal",
199        feature = "wasm-logic",
200        feature = "wasm-scientific"
201    ))]
202    {
203        mask |= LIB_MEDICAL_COMPUTING;
204    }
205
206    #[cfg(any(
207        not(target_arch = "wasm32"),
208        feature = "portal",
209        feature = "wasm-logic",
210        feature = "wasm-scientific"
211    ))]
212    {
213        mask |= LIB_SHARED;
214    }
215
216    mask
217}
218
219/// Checks whether a specific specialized library capability bit is active in the current build.
220#[inline(always)]
221pub const fn is_specialized_lib_active(lib_bit: u32) -> bool {
222    (active_specialized_lib_mask() & lib_bit) != 0
223}
224
225/// Returns the canonical snake_case name of a specialized library capability bit.
226pub const fn specialized_lib_name(lib_bit: u32) -> &'static str {
227    match lib_bit {
228        LIB_CATEGORY_THEORY => "category_theory",
229        LIB_CHEMISTRY_MODELING => "chemistry_modeling",
230        LIB_COMPUTATIONAL_ECONOMICS => "computational_economics",
231        LIB_COMPUTATIONAL_GEOMETRY => "computational_geometry",
232        LIB_COMPUTER_VISION => "computer_vision",
233        LIB_CONSTRUCTIBILITY => "constructibility",
234        LIB_CRYPTOGRAPHIC_LIBRARY => "cryptographic_library",
235        LIB_ENGINEERING_ANALYSIS => "engineering_analysis",
236        LIB_FINANCIAL_MODELING => "financial_modeling",
237        LIB_LINEAR_ALGEBRA => "linear_algebra",
238        LIB_MACHINE_LEARNING => "machine_learning",
239        LIB_MEDICAL_COMPUTING => "medical_computing",
240        LIB_MULTIVAR_CALCULUS => "multivar_calculus",
241        LIB_PHYSICS_SIMULATION => "physics_simulation",
242        LIB_POLYNOMIAL_ALGEBRA => "polynomial_algebra",
243        LIB_QPU_BRIDGE => "qpu_bridge",
244        LIB_QUANTUM_BIOLOGY => "quantum_biology",
245        LIB_STATISTICAL_COMPUTING => "statistical_computing",
246        LIB_SYMBOLIC_ALGEBRA => "symbolic_algebra",
247        LIB_SYMBOLIC_ASSUMPTIONS => "symbolic_assumptions",
248        LIB_SYMBOLIC_INTEGRATION => "symbolic_integration",
249        LIB_SYMBOLIC_LIMITS => "symbolic_limits",
250        LIB_SYMBOLIC_ODE => "symbolic_ode",
251        LIB_SYMBOLIC_SERIES => "symbolic_series",
252        LIB_SYMBOLIC_SOLVE => "symbolic_solve",
253        LIB_SYMBOLIC_TRIG => "symbolic_trig",
254        LIB_SHARED => "shared",
255        _ => "unknown",
256    }
257}
258
259// ── Antigravity Unit Tests ───────────────────────────────────────────────────
260
261#[cfg(test)]
262mod tests {
263    use super::*;
264
265    #[cfg(all(target_arch = "wasm32", feature = "device-harness"))]
266    #[test]
267    fn harness_libraries_are_reported_active() {
268        assert!(is_specialized_lib_active(LIB_LINEAR_ALGEBRA));
269        assert!(is_specialized_lib_active(LIB_MEDICAL_COMPUTING));
270    }
271
272    #[test]
273    fn test_active_specialized_lib_mask_native() {
274        let mask = active_specialized_lib_mask();
275        // In native builds without minimal-fast-build, all 27 flags must be active
276        #[cfg(not(target_arch = "wasm32"))]
277        {
278            assert_eq!(
279                mask.count_ones(),
280                27,
281                "Native builds must include all 27 specialized libraries"
282            );
283            assert!(mask & LIB_CHEMISTRY_MODELING != 0);
284            assert!(mask & LIB_FINANCIAL_MODELING != 0);
285            assert!(mask & LIB_QPU_BRIDGE != 0);
286            assert!(mask & LIB_QUANTUM_BIOLOGY != 0);
287        }
288    }
289
290    #[test]
291    fn test_is_specialized_lib_active_positive() {
292        assert!(is_specialized_lib_active(LIB_COMPUTATIONAL_GEOMETRY));
293        assert!(is_specialized_lib_active(LIB_COMPUTATIONAL_ECONOMICS));
294        assert!(is_specialized_lib_active(LIB_COMPUTER_VISION));
295        assert!(is_specialized_lib_active(LIB_SYMBOLIC_ALGEBRA));
296    }
297
298    #[test]
299    fn test_is_specialized_lib_active_negative_unused_bits() {
300        // Bits 27 to 31 are unused
301        assert!(!is_specialized_lib_active(1 << 27));
302        assert!(!is_specialized_lib_active(1 << 28));
303        assert!(!is_specialized_lib_active(1 << 31));
304        assert!(!is_specialized_lib_active(0));
305    }
306
307    #[test]
308    fn test_specialized_lib_name_mapping() {
309        assert_eq!(specialized_lib_name(LIB_CATEGORY_THEORY), "category_theory");
310        assert_eq!(specialized_lib_name(LIB_CHEMISTRY_MODELING), "chemistry_modeling");
311        assert_eq!(specialized_lib_name(LIB_FINANCIAL_MODELING), "financial_modeling");
312        assert_eq!(specialized_lib_name(LIB_QPU_BRIDGE), "qpu_bridge");
313        assert_eq!(specialized_lib_name(LIB_QUANTUM_BIOLOGY), "quantum_biology");
314        assert_eq!(specialized_lib_name(LIB_SHARED), "shared");
315    }
316
317    #[test]
318    fn test_specialized_lib_name_unknown() {
319        assert_eq!(specialized_lib_name(0), "unknown");
320        assert_eq!(specialized_lib_name(1 << 28), "unknown");
321        assert_eq!(
322            specialized_lib_name(LIB_CATEGORY_THEORY | LIB_CHEMISTRY_MODELING),
323            "unknown"
324        );
325    }
326
327    #[test]
328    fn test_specialized_lib_bits_disjoint_powers_of_two() {
329        let all_bits = [
330            LIB_CATEGORY_THEORY,
331            LIB_CHEMISTRY_MODELING,
332            LIB_COMPUTATIONAL_ECONOMICS,
333            LIB_COMPUTATIONAL_GEOMETRY,
334            LIB_COMPUTER_VISION,
335            LIB_CONSTRUCTIBILITY,
336            LIB_CRYPTOGRAPHIC_LIBRARY,
337            LIB_ENGINEERING_ANALYSIS,
338            LIB_FINANCIAL_MODELING,
339            LIB_LINEAR_ALGEBRA,
340            LIB_MACHINE_LEARNING,
341            LIB_MEDICAL_COMPUTING,
342            LIB_MULTIVAR_CALCULUS,
343            LIB_PHYSICS_SIMULATION,
344            LIB_POLYNOMIAL_ALGEBRA,
345            LIB_QPU_BRIDGE,
346            LIB_QUANTUM_BIOLOGY,
347            LIB_STATISTICAL_COMPUTING,
348            LIB_SYMBOLIC_ALGEBRA,
349            LIB_SYMBOLIC_ASSUMPTIONS,
350            LIB_SYMBOLIC_INTEGRATION,
351            LIB_SYMBOLIC_LIMITS,
352            LIB_SYMBOLIC_ODE,
353            LIB_SYMBOLIC_SERIES,
354            LIB_SYMBOLIC_SOLVE,
355            LIB_SYMBOLIC_TRIG,
356            LIB_SHARED,
357        ];
358        for (i, &b1) in all_bits.iter().enumerate() {
359            assert!(b1.is_power_of_two(), "Lib bit {b1} must be a power of two");
360            for (j, &b2) in all_bits.iter().enumerate() {
361                if i != j {
362                    assert_eq!(
363                        b1 & b2,
364                        0,
365                        "Lib bits {b1} and {b2} must be strictly disjoint"
366                    );
367                }
368            }
369        }
370    }
371
372    #[test]
373    fn test_quantum_biology_fast_build_leaf_isolation() {
374        // Quantum biology is an isolated leaf with no external callers in the monolith.
375        // Ensure its constant is properly bounded within the 32-bit word.
376        assert_eq!(LIB_QUANTUM_BIOLOGY, 1 << 16);
377        assert!(LIB_QUANTUM_BIOLOGY < (1 << 27));
378    }
379}