Module coherence 

Coherence gate — refuse to spend polynomial-time work on a near-singular system whose residual signal-to-noise ratio is too low to produce a useful answer.

Implements roadmap item #3 from ADR-001: Complexity as Architecture:

Before any solve, the system checks coherence: coherence(A, b) = min_i |diag(A)[i]| / Σ_{j≠i} |A[i,j]| (the diagonal-dominance margin). If coherence drops below a configurable threshold (default 0.05), the solver refuses and returns Err(SolverError::Incoherent { coherence, threshold }).

Why this matters in the ADR’s stack:

• Cognitum reflex loops running on a Pi Zero 2W have a joules-per- decision budget. Spending 50 ms on a near-singular system to produce an ε-quality answer the agent will discard anyway is strictly worse than refusing in <1 µs.
• RuView change detection wants to know fast whether a system is degenerate; the coherence score itself is a useful diagnostic before any solve runs.
• Ruflo bounded planning can fall back to a cached / heuristic answer on incoherent inputs without burning a J/decision quota.

The check is opt-in — SolverOptions::coherence_threshold defaults to 0.0, which means “never reject for incoherence”. Setting it to 0.05 enables the gate. This keeps the change wire-compatible with every existing caller.

Structs

CoherenceCache

Incremental coherence cache for streaming matrix-update workloads.

Constants

FULLY_COHERENT_MARGIN

Minimum diagonal-dominance margin we report as “perfectly coherent”. Used by coherence_score to normalise the result into [0, 1].

Functions

approximate_spectral_radius

Estimate the spectral radius of D⁻¹O (the Neumann iteration matrix) via power iteration. Tighter than the 1 - coherence upper bound that optimal_neumann_terms uses by default.

check_coherence_or_reject

Verify that a matrix’s coherence meets or exceeds the configured threshold; otherwise return SolverError::Incoherent.

coherence_score

Compute the diagonal-dominance margin of a sparse matrix.

delta_below_solve_threshold

Fast-path coherence-gated event filter. Returns true iff the supplied delta is small enough that, given the matrix’s (coherence, min_diag) pair, the induced change in x is guaranteed below tolerance — so a downstream solve can safely be skipped.

delta_inf_bound

Upper bound on ‖A⁻¹ · δ‖_∞, derived from the coherence margin.

optimal_neumann_terms

Minimum number of Neumann terms required to hit tolerance on a single-entry solve, given the matrix’s coherence margin and the magnitudes of the RHS and any perturbation.

optimal_neumann_terms_with_rho

Variant of optimal_neumann_terms that takes a caller-supplied spectral-radius rho directly instead of inferring it from coherence. Use this with approximate_spectral_radius for tight auto-tuning on matrices where the 1 - coherence bound is loose.