ruvector/examples/prime-radiant

Prime-Radiant: Universal Coherence Engine

Advanced Mathematical Framework for AI Safety, Hallucination Detection, and Structural Consistency Verification

Prime-Radiant implements a universal coherence engine using sheaf Laplacian mathematics to provide structural consistency guarantees across domains. Rather than trying to make better predictions, Prime-Radiant proves when the world still fits together and when it does not.

---

Table of Contents

1. Overview
2. Six Mathematical Directions
3. Installation
4. Quick Start
5. API Reference
6. Performance Characteristics
7. Use Cases
8. Architecture

---

Overview

Prime-Radiant provides a single underlying coherence object that can be interpreted across multiple domains:

Domain	Nodes Are	Edges Are	Residual Becomes	Gate Becomes
AI Agents	Facts, hypotheses, beliefs	Citations, logical implication	Contradiction energy	Hallucination refusal
Finance	Trades, positions, signals	Market dependencies, arbitrage	Regime mismatch	Trading throttle
Medical	Vitals, diagnoses, treatments	Physiological causality	Clinical disagreement	Escalation trigger
Robotics	Sensor readings, goals, plans	Physics, kinematics	Motion impossibility	Safety stop
Security	Identities, permissions, actions	Policy rules, trust chains	Authorization violation	Access denial
Science	Hypotheses, observations, models	Experimental evidence	Theory inconsistency	Pruning signal

Core Mathematical Formula

The coherence energy is computed as:

E(S) = sum(w_e * ||r_e||^2)

where r_e = rho_u(x_u) - rho_v(x_v)

• rho: Restriction map (linear transform defining how states constrain each other)
• r_e: Residual at edge (measures local inconsistency)
• w_e: Edge weight
• E(S): Global incoherence measure

---

Six Mathematical Directions

Prime-Radiant implements six advanced mathematical frameworks for coherence analysis:

1. Sheaf Cohomology for AI Coherence

Sheaf theory provides the mathematical foundation for understanding local-to-global consistency:

• Stalks: Fixed-dimensional state vectors at each node
• Restriction Maps: Constraints defining how states relate
• Global Sections: Coherent assignments across the entire graph
• Cohomology Groups: Obstruction measures for global consistency

ADR-001: Sheaf Cohomology

2. Category Theory and Topos-Theoretic Belief Models

Functorial retrieval and higher category structures enable:

• Functorial Retrieval: Structure-preserving knowledge access
• Topos Models: Intuitionistic logic for belief systems
• Higher Categories: Multi-level coherence laws
• Natural Transformations: Systematic relationship mapping

ADR-002: Category and Topos Theory

3. Homotopy Type Theory for Verified Reasoning

HoTT provides verified reasoning with proof transport:

• Univalence Axiom: Equivalent structures are identical
• Path Induction: Proofs follow identity paths
• Higher Inductive Types: Complex data structures with equalities
• Proof Transport: Transfer proofs across equivalent structures

ADR-003: Homotopy Type Theory

4. Spectral Invariants for Cut Prediction

Spectral analysis of the sheaf Laplacian enables:

• Cheeger Bounds: Relationship between spectral gap and graph cuts
• Algebraic Connectivity: Second eigenvalue measures graph cohesion
• Early Warning Systems: Detect structural weakening before failure
• Drift Detection: Identify fundamental structural shifts

ADR-004: Spectral Invariants

5. Causal Abstraction for Consistency

Causal reasoning distinguishes correlation from causation:

• Do-Calculus: Intervention-based causal reasoning
• Structural Causal Models: Explicit causal relationships
• Abstraction Verification: Ensure high-level models match low-level
• Counterfactual Analysis: "What if" reasoning support

ADR-005: Causal Abstraction

6. Quantum Topology for Coherence Invariants

Topological methods provide robust coherence measures:

• Persistent Homology: Multi-scale topological features
• Betti Numbers: Counts of topological holes
• Quantum-Inspired Encodings: Superposition-based representations
• Stability Theorems: Robustness guarantees for features

ADR-006: Quantum Topology

---

Installation

Rust (Native)

Add to your Cargo.toml:

[dependencies]
prime-radiant = "0.1.0"

# Full feature set
prime-radiant = { version = "0.1.0", features = ["full"] }

Feature Flags

Feature	Default	Description
tiles	No	cognitum-gate-kernel 256-tile WASM fabric
sona	No	Self-optimizing threshold tuning (SONA)
learned-rho	No	GNN-learned restriction maps
hyperbolic	No	Hierarchy-aware Poincare energy
mincut	No	Subpolynomial n^o(1) graph partitioning
neural-gate	No	Biologically-inspired gating
attention	No	Topology-gated attention, MoE, PDE diffusion
distributed	No	Raft-based multi-node coherence
spectral	No	nalgebra-based eigenvalue computation
simd	No	SIMD-optimized residual calculation
gpu	No	wgpu-based parallel computation
ruvllm	No	LLM serving integration
full	No	All features enabled

WASM

# Install wasm-pack
cargo install wasm-pack

# Build for web
wasm-pack build --target web

# Build for Node.js
wasm-pack build --target nodejs

---

Quick Start

Basic Coherence Computation

use prime_radiant::prelude::*;

fn main() -> Result<(), CoherenceError> {
    // Create a sheaf graph
    let mut graph = SheafGraph::new();

    // Add nodes with state vectors
    let fact1 = SheafNode::new(vec![1.0, 0.0, 0.0, 0.5]);
    let fact2 = SheafNode::new(vec![0.9, 0.1, 0.0, 0.4]);

    let id1 = graph.add_node(fact1);
    let id2 = graph.add_node(fact2);

    // Add edge with restriction map
    let rho = RestrictionMap::identity(4);
    graph.add_edge(SheafEdge::new(id1, id2, rho.clone(), rho, 1.0))?;

    // Compute coherence energy
    let energy = graph.compute_energy();
    println!("Total coherence energy: {}", energy.total);

    Ok(())
}

Coherence Gate with Compute Ladder

use prime_radiant::{CoherenceGate, ComputeLane, EnergySnapshot};

fn main() {
    let policy = PolicyBundleRef::placeholder();
    let mut gate = CoherenceGate::with_defaults(policy);

    let energy = EnergySnapshot::new(0.15, 0.12, ScopeId::new("test"));
    let (decision, witness) = gate.evaluate_with_witness(&action, &energy);

    match decision.lane {
        ComputeLane::Reflex => println!("Approved (<1ms)"),
        ComputeLane::Retrieval => println!("Evidence needed (~10ms)"),
        ComputeLane::Heavy => println!("Heavy processing (~100ms)"),
        ComputeLane::Human => println!("Human review required"),
    }
}

Spectral Drift Detection

use prime_radiant::coherence::{SpectralAnalyzer, SpectralConfig};

let mut analyzer = SpectralAnalyzer::new(SpectralConfig::default());

analyzer.record_eigenvalues(vec![0.0, 0.5, 1.2, 2.1]);
analyzer.record_eigenvalues(vec![0.0, 0.3, 0.9, 1.8]); // Drift!

if let Some(drift) = analyzer.detect_drift() {
    println!("Drift: {:?}, severity: {:?}", drift.description, drift.severity);
}

---

API Reference

Core Types

Type	Description
SheafGraph	Graph with nodes, edges, and restriction maps
SheafNode	Vertex with state vector (stalk)
SheafEdge	Edge with restriction maps and weight
RestrictionMap	Linear transform for state constraints
CoherenceEnergy	Global incoherence measure
CoherenceGate	Threshold-based action gating
GateDecision	Allow/deny with compute lane
WitnessRecord	Immutable audit record

Compute Ladder

Lane	Latency	Use Case
Reflex	<1ms	Low-energy automatic approval
Retrieval	~10ms	Evidence fetching
Heavy	~100ms	Multi-step planning
Human	Unbounded	Sustained incoherence review

---

Performance Characteristics

Operation	Target
Single residual	< 1us
Full energy (10K nodes)	< 10ms
Incremental update	< 100us
Gate evaluation	< 500us
SONA adaptation	< 0.05ms
MinCut update	n^o(1) subpolynomial
Hyperbolic distance	< 500ns

---

Use Cases

• AI Safety: Detect hallucinations via structural inconsistency
• Finance: Regime change detection and arbitrage validation
• Medical: Clinical decision consistency verification
• Robotics: Kinematic constraint enforcement
• Security: Policy rule coherence checking

---

Architecture

+-----------------------------------------------------------------------------+
|                           APPLICATION LAYER                                  |
|  LLM Guards | Fraud Detection | Compliance Proofs | Robotics Safety         |
+-----------------------------------------------------------------------------+
                                    |
+-----------------------------------------------------------------------------+
|                           COHERENCE GATE                                     |
|  Lane 0 (Reflex) | Lane 1 (Retrieval) | Lane 2 (Heavy) | Lane 3 (Human)     |
+-----------------------------------------------------------------------------+
                                    |
+-----------------------------------------------------------------------------+
|                           COHERENCE COMPUTATION                              |
|  Residual Calculator | Energy Aggregator | Spectral Analyzer                |
+-----------------------------------------------------------------------------+
                                    |
+-----------------------------------------------------------------------------+
|                           KNOWLEDGE SUBSTRATE                                |
|  Sheaf Graph | Node States | Edge Constraints | Restriction Maps           |
+-----------------------------------------------------------------------------+

---

Documentation

• ADR-001: Sheaf Cohomology
• ADR-002: Category and Topos Theory
• ADR-003: Homotopy Type Theory
• ADR-004: Spectral Invariants
• ADR-005: Causal Abstraction
• ADR-006: Quantum Topology
• Domain Model

---

References

1. Hansen, J., & Ghrist, R. (2019). "Toward a spectral theory of cellular sheaves."
2. Robinson, M. (2014). "Topological Signal Processing."
3. Curry, J. (2014). "Sheaves, Cosheaves and Applications."
4. Univalent Foundations Program. "Homotopy Type Theory."

---

License

MIT OR Apache-2.0

---

Prime-Radiant: Where mathematics meets machine safety.