prime-radiant-advanced-wasm

A Real-Time Coherence Gate for Autonomous Systems

Prime-Radiant is infrastructure for AI safety — a mathematical gate that proves whether a system's beliefs, facts, and claims are internally consistent before allowing action.

Instead of asking "How confident am I?" (which can be wrong), Prime-Radiant asks "Are there any contradictions?" — and provides mathematical proof of the answer.

┌─────────────────────────────────────────────────────────────────┐
│  "The meeting is at 3pm"  ←──────→  "The meeting is at 4pm"    │
│         (Memory A)           ✗            (Memory B)            │
│                                                                 │
│  Energy = 0.92  →  HIGH INCOHERENCE  →  Block / Escalate       │
└─────────────────────────────────────────────────────────────────┘

Why This Matters

| Traditional AI | Prime-Radiant | |----------------|---------------| | "I'm 95% confident" (but wrong) | "These facts contradict each other" (provably) | | Hallucinations pass through | Contradictions get caught | | Trust the model's self-assessment | Trust mathematical invariants | | Fails silently | Fails loudly with proof |

The core insight: Confidence scores lie. Coherence scores don't.

An LLM can be 99% confident while citing contradictory sources. Prime-Radiant catches this by measuring the mathematical structure of the information, not the model's opinion about it.

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                    PRIME-RADIANT PIPELINE                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Input         Coherence         Decision          Output      │
│   ─────         ─────────         ────────          ──────      │
│                                                                 │
│   Memories  →   Sheaf       →    Energy    →   ✓ Proceed       │
│   Facts         Laplacian        < 0.3          (coherent)      │
│   Claims                                                        │
│                                  Energy    →   ✗ Block          │
│                                  > 0.7          (contradicts)   │
│                                                                 │
│                                  Energy    →   ⚠ Escalate       │
│                                  0.3-0.7       (uncertain)      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

The Sheaf Laplacian measures how well local information "glues together" globally. High energy = information doesn't fit together = contradiction detected.

Installation

npm install prime-radiant-advanced-wasm

Quick Start: The Coherence Gate

import init, { CohomologyEngine } from 'prime-radiant-advanced-wasm';

await init();

// Create a coherence gate for 768-dimensional embeddings
const gate = new CohomologyEngine(768);

// Add facts/memories as nodes with their embeddings
gate.add_node('fact1', embed("The meeting is scheduled for 3pm"));
gate.add_node('fact2', embed("John confirmed 3pm works for him"));
gate.add_node('fact3', embed("The meeting was moved to 4pm"));  // Contradiction!

// Connect related facts
gate.add_edge('fact1', 'fact2', 0.9);  // High similarity
gate.add_edge('fact2', 'fact3', 0.7);  // Related but conflicting
gate.add_edge('fact1', 'fact3', 0.3);  // Low similarity (contradiction signal)

// Compute coherence energy
const energy = gate.sheaf_laplacian_energy();

// Make gated decision
if (energy < 0.3) {
  console.log('✓ COHERENT - Safe to proceed');
  executeAction();
} else if (energy > 0.7) {
  console.log('✗ INCOHERENT - Blocking action');
  console.log('  Contradiction detected. Escalating to human review.');
  escalateToHuman();
} else {
  console.log('⚠ UNCERTAIN - Requesting clarification');
  requestMoreContext();
}

Real-World Applications

1. RAG Hallucination Prevention

Problem: Your RAG system retrieves contradictory documents and the LLM confidently synthesizes nonsense.

const gate = new CohomologyEngine(768);

// After retrieval, before generation
retrievedDocs.forEach((doc, i) => {
  gate.add_node(`doc${i}`, doc.embedding);
});

// Build coherence graph
for (let i = 0; i < retrievedDocs.length; i++) {
  for (let j = i + 1; j < retrievedDocs.length; j++) {
    gate.add_edge(`doc${i}`, `doc${j}`, cosineSim(docs[i], docs[j]));
  }
}

const energy = gate.sheaf_laplacian_energy();

if (energy > 0.5) {
  // Don't generate from contradictory sources!
  return "I found conflicting information. Let me clarify: [show conflicts]";
}

2. Multi-Agent Consensus Verification

Problem: Your agent swarm reached "consensus" but agents actually disagree.

const gate = new CohomologyEngine(768);

// Each agent's conclusion as a node
agents.forEach(agent => {
  gate.add_node(agent.id, embed(agent.conclusion));
});

// Connect agents that communicated
communications.forEach(comm => {
  gate.add_edge(comm.from, comm.to, comm.agreementScore);
});

const energy = gate.sheaf_laplacian_energy();

if (energy > 0.4) {
  console.log('⚠ FALSE CONSENSUS - Agents have hidden disagreements');
  // Force explicit reconciliation before proceeding
}

3. Memory Consistency for Long-Running Agents

Problem: Your agent's memories drift and contradict over time.

const gate = new CohomologyEngine(768);

// Periodically audit agent memory
agent.memories.forEach((memory, i) => {
  gate.add_node(`mem${i}`, memory.embedding);
});

// Connect temporally adjacent memories
for (let i = 0; i < memories.length - 1; i++) {
  gate.add_edge(`mem${i}`, `mem${i+1}`, temporalSimilarity(i, i+1));
}

const energy = gate.sheaf_laplacian_energy();

if (energy > 0.6) {
  console.log('⚠ MEMORY DRIFT - Agent beliefs have become inconsistent');
  // Trigger memory consolidation or reset
}

4. Autonomous Vehicle Decision Gate

Problem: Sensor fusion produces conflicting interpretations.

const gate = new CohomologyEngine(128);

// Each sensor's interpretation
gate.add_node('lidar', embed(lidarInterpretation));
gate.add_node('camera', embed(cameraInterpretation));
gate.add_node('radar', embed(radarInterpretation));

// Sensor agreement edges
gate.add_edge('lidar', 'camera', lidarCameraAgreement);
gate.add_edge('camera', 'radar', cameraRadarAgreement);
gate.add_edge('lidar', 'radar', lidarRadarAgreement);

const energy = gate.sheaf_laplacian_energy();

if (energy > 0.5) {
  // STOP - sensors disagree about the environment
  emergencyBrake();
}

Beyond Coherence: The Full Toolkit

Prime-Radiant provides 6 mathematical engines for AI safety:

| Engine | What It Detects | Safety Application | |--------|-----------------|-------------------| | CohomologyEngine | Contradictions in beliefs/facts | Gate actions on consistency | | SpectralEngine | System instability | Predict failures before they happen | | CausalEngine | Spurious correlations | Ensure decisions are causally grounded | | QuantumEngine | Structural anomalies | Detect out-of-distribution inputs | | CategoryEngine | Type mismatches | Verify pipeline correctness | | HottEngine | Logical inconsistencies | Formal verification of reasoning |

Comparison: Approaches to AI Safety

| Approach | Method | Limitation | Prime-Radiant Advantage | |----------|--------|------------|------------------------| | Confidence Thresholds | Reject if P < 0.8 | Confident errors pass | Catches contradictions regardless of confidence | | Output Filtering | Block bad outputs | Reactive, not preventive | Prevents bad reasoning upstream | | RLHF | Train away bad behavior | Can be fooled/jailbroken | Mathematical invariants can't be talked around | | Constitutional AI | Self-critique | Model critiques itself | External mathematical proof | | Ensemble Voting | Majority wins | Correlated failures | Detects hidden disagreement structure |

Comparison: This Package vs Alternatives

| Feature | prime-radiant | LangChain | LlamaIndex | Custom | |---------|--------------|-----------|------------|--------| | Coherence detection | Native (Sheaf theory) | None | None | Manual | | Contradiction proofs | Mathematical | Heuristic | Heuristic | Varies | | Collapse prediction | Spectral analysis | None | None | Manual | | Bundle size | 92 KB | 2MB+ | 1.5MB+ | Varies | | Zero dependencies | Yes | No | No | Varies | | Runs in browser | WASM | Node only | Node only | Varies |

API Reference

CohomologyEngine (The Core Gate)

const gate = new CohomologyEngine(embeddingDim);

// Build the coherence graph
gate.add_node(id, embedding);              // Add a fact/belief/memory
gate.add_edge(from, to, similarity);       // Connect related items

// Measure coherence
gate.sheaf_laplacian_energy();             // 0 = perfect coherence, 1 = total contradiction
gate.compute_cohomology_dimension(1);      // Count of "holes" (unresolvable conflicts)

SpectralEngine (Stability Prediction)

const monitor = new SpectralEngine();

monitor.add_node(id);
monitor.add_edge(from, to, strength);

monitor.predict_collapse_risk();           // 0-1 risk score
monitor.compute_fiedler_value();           // Connectivity strength
monitor.compute_cheeger_constant();        // Partition resistance

CausalEngine (Causal Grounding)

const causal = new CausalEngine();

causal.add_variable(name, isObserved);
causal.add_causal_edge(cause, effect);

causal.is_identifiable(treatment, outcome);  // Can we measure this effect?
causal.get_adjustment_set(treatment, outcome); // What to control for
causal.compute_ate(treatment, outcome);      // Actual causal effect

QuantumEngine (Structural Analysis)

const topology = new QuantumEngine();

topology.add_point(coordinates);

topology.get_betti_numbers(scale);           // [components, holes, voids]
topology.compute_persistence(maxDim);        // Feature lifetimes

import init, { CohomologyEngine, SpectralEngine } from 'prime-radiant-advanced-wasm';

await init();

class CoherenceGatedAgent {
  constructor(embeddingDim = 768) {
    this.coherenceGate = new CohomologyEngine(embeddingDim);
    this.stabilityMonitor = new SpectralEngine();
    this.memories = [];
    this.thresholds = {
      coherence: 0.4,      // Block if energy > this
      stability: 0.6,      // Alert if risk > this
    };
  }

  // Add a new memory/belief
  remember(content, embedding) {
    const id = `mem_${this.memories.length}`;
    this.memories.push({ id, content, embedding, timestamp: Date.now() });

    // Rebuild coherence graph
    this.rebuildCoherenceGraph();

    // Check if this memory creates contradictions
    const energy = this.coherenceGate.sheaf_laplacian_energy();

    if (energy > this.thresholds.coherence) {
      console.warn(`⚠ New memory creates contradiction (energy: ${energy.toFixed(3)})`);
      return { accepted: false, reason: 'contradiction', energy };
    }

    return { accepted: true, energy };
  }

  rebuildCoherenceGraph() {
    this.coherenceGate = new CohomologyEngine(768);

    // Add all memories as nodes
    this.memories.forEach(mem => {
      this.coherenceGate.add_node(mem.id, mem.embedding);
    });

    // Connect memories by similarity
    for (let i = 0; i < this.memories.length; i++) {
      for (let j = i + 1; j < this.memories.length; j++) {
        const sim = this.cosineSim(
          this.memories[i].embedding,
          this.memories[j].embedding
        );
        if (sim > 0.2) {
          this.coherenceGate.add_edge(
            this.memories[i].id,
            this.memories[j].id,
            sim
          );
        }
      }
    }
  }

  // Gate an action on coherence
  async act(action, context) {
    // Build context graph
    const contextGate = new CohomologyEngine(768);

    context.facts.forEach((fact, i) => {
      contextGate.add_node(`fact_${i}`, fact.embedding);
    });

    for (let i = 0; i < context.facts.length; i++) {
      for (let j = i + 1; j < context.facts.length; j++) {
        const sim = this.cosineSim(
          context.facts[i].embedding,
          context.facts[j].embedding
        );
        contextGate.add_edge(`fact_${i}`, `fact_${j}`, sim);
      }
    }

    const energy = contextGate.sheaf_laplacian_energy();

    // GATE DECISION
    if (energy > this.thresholds.coherence) {
      return {
        executed: false,
        reason: 'Context contains contradictions',
        energy,
        recommendation: 'Resolve conflicts before proceeding'
      };
    }

    // Safe to proceed
    const result = await action();

    return {
      executed: true,
      result,
      energy,
      coherenceVerified: true
    };
  }

  // Periodic health check
  healthCheck() {
    const energy = this.coherenceGate.sheaf_laplacian_energy();
    const holes = this.coherenceGate.compute_cohomology_dimension(1);

    return {
      status: energy < 0.3 ? 'healthy' : energy < 0.6 ? 'warning' : 'critical',
      coherenceEnergy: energy,
      contradictionCount: holes,
      memoryCount: this.memories.length,
      recommendation: this.getRecommendation(energy, holes)
    };
  }

  getRecommendation(energy, holes) {
    if (energy > 0.7) {
      return 'CRITICAL: Multiple contradictions detected. Memory consolidation required.';
    }
    if (holes > 0) {
      return `WARNING: ${holes} unresolvable conflict(s) in memory. Review flagged memories.`;
    }
    if (energy > 0.4) {
      return 'CAUTION: Some tension in beliefs. Monitor for drift.';
    }
    return 'All systems nominal.';
  }

  cosineSim(a, b) {
    let dot = 0, normA = 0, normB = 0;
    for (let i = 0; i < a.length; i++) {
      dot += a[i] * b[i];
      normA += a[i] * a[i];
      normB += b[i] * b[i];
    }
    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
  }
}

// Usage
const agent = new CoherenceGatedAgent();

// Add memories
agent.remember("The project deadline is Friday", embedFriday);
agent.remember("John is leading the project", embedJohn);

// This will be flagged as contradictory:
const result = agent.remember("The project deadline is next Monday", embedMonday);
// result.accepted = false, result.reason = 'contradiction'

// Gate an action
const actionResult = await agent.act(
  () => sendEmail("Reminder: deadline Friday"),
  { facts: [fridayDeadline, johnLeading] }
);
// actionResult.executed = true (coherent context)

// Health check
const health = agent.healthCheck();
// health.status = 'warning', health.recommendation = '...'

The Sheaf Laplacian

A sheaf assigns vector spaces to nodes and linear maps to edges. For AI:

• Nodes = facts, memories, beliefs (as embeddings)
• Edges = relationships between them
• Sheaf maps = how information should transform across relationships

The Sheaf Laplacian L_F generalizes the graph Laplacian:

L_F = δ*δ + δδ*

where δ is the coboundary operator

Key insight: The quadratic form x^T L_F x measures how much the data fails to be globally consistent.

• Energy = 0: Perfect coherence. All local data glues together.
• Energy > 0: Incoherence. Some information doesn't match up.
• High energy: Major contradictions. Information fundamentally conflicts.

Why This Works

Traditional approaches check pairwise similarity:

"Is A similar to B?" → Yes
"Is B similar to C?" → Yes
Therefore coherent? → NOT NECESSARILY

The sheaf approach checks global consistency:

"Does A→B→C→A form a consistent cycle?" → No! (A→C might conflict)

This catches transitive contradictions that pairwise methods miss.

Cohomology Groups

The cohomology groups H^n detect "holes" in coherence:

• H^0: Connected components (fragmented beliefs)
• H^1: Cycles that don't close (circular contradictions)
• H^2: Higher-order inconsistencies

A non-zero H^1 dimension means there's a fundamental contradiction that can't be resolved by local adjustments.

Performance

| Operation | 10 items | 100 items | 1,000 items | |-----------|----------|-----------|-------------| | Coherence gate | <1ms | ~2ms | ~15ms | | Full analysis | ~1ms | ~5ms | ~40ms |

Fast enough for real-time gating of every LLM call.

Browser & Runtime Support

| Environment | Support | |-------------|---------| | Chrome 57+ | Full | | Firefox 52+ | Full | | Safari 11+ | Full | | Edge 16+ | Full | | Node.js 12+ | Full | | Deno | Full | | Cloudflare Workers | Full |

Related

• ruvector — High-performance vector operations
• ruvector-attention-wasm — Attention mechanisms

License

MIT OR Apache-2.0

Contributing

Issues and PRs welcome at github.com/ruvnet/ruvector

"Don't trust confidence. Trust coherence."