Crate topological_coherence 

Topological Coherence

Rust implementation of topological constraints for coherent inference. Based on: “Topological Constraints for Coherent Language Models” (Cormier, 2026)

Theory

Hallucination is a geometry problem: unconstrained latent dynamics permit arbitrary drift through latent space. Topological constraints (specifically toroidal manifolds with constant spectral gap) bound this drift.

Hierarchy

mHC (Birkhoff) ⊂ ERLHS (Hamiltonian) ⊂ Karmonic (Toroidal + Spectral)

Key Results (from validation experiment)

Condition	Drift Rate	Interpretation
Toroidal	0.006	40% lower than baseline
Random	0.167	28x worse (proves topology matters)

Usage

use topological_coherence::{Tonnetz, ToroidalMask};

// Create 12x12 Tonnetz (standard musical topology)
let tonnetz = Tonnetz::<12>::new();

// Distance on torus
let d = tonnetz.distance((0, 0), (5, 7));

// Attention mask with locality radius 2
let mask = ToroidalMask::new(64, 2.0, 1.0);

Structs

AdjacencyLoss

Adjacency loss computation.

CoherenceConfig

Configuration for coherence validation (for pallet storage).

CoherenceResult

Result of coherence validation (for on-chain reporting).

DriftMeter

Drift measurement utilities.

GroundingDecomposition

Result of decomposing a vector into grounded and hallucinated components.

GroundingProjector

Orthogonal grounding projector G = A(AᵀA)⁻¹Aᵀ.

KarmonicFilter

Karmonic spectral filter for training-time regularization.

LearnedProjection

Learned toroidal projection parameters.

MultiScaleTonnetz

Multi-scale Tonnetz configuration.

SparseMask

Sparse mask in CSR (Compressed Sparse Row) format.

Tonnetz

Tonnetz topology on a 2D torus of size N x N.

ToroidalMask

Toroidal attention mask generator.

ToroidalPosition

Position on the Tonnetz torus (for on-chain storage).

Torus3D

3D Torus topology (T^3).

Enums

MaskType

Mask type variants for different use cases.

Functions

angles_to_grid

Angles to torus position: quantize continuous angles to grid coordinates.

fourier_expand

Fourier torus projection: map angles to Fourier coordinates.

is_doubly_stochastic

Check if matrix is approximately doubly-stochastic.

sinkhorn_knopp

Sinkhorn-Knopp algorithm: project matrix to doubly-stochastic.