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.

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

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.