shivya_hodge/error.rs
1/// Recoverable math failures surface through this enum instead of `panic!`.
2///
3/// The substrate's runtime layers (orchestrator, ensemble, daemon, reconciler)
4/// treat every variant as a soft signal — either by retrying with regularised
5/// inputs or by gracefully degrading to a no-op so a degenerate telemetry
6/// sample never kills the daemon process.
7///
8/// Lives in `shivya-hodge` (Layer 0) because both the discrete-exterior-calculus
9/// operators and the higher-layer matrix inverter need a shared error vocabulary;
10/// `shivya-flux` re-exports it so existing call sites keep working.
11#[derive(Debug, Clone)]
12pub enum SubstrateError {
13 /// Covariance / precision matrix was singular at the listed size.
14 /// `det` is the determinant at the point of failure.
15 SingularMatrix { size: usize, det: f64 },
16 /// Even after a ridge of `ridge` the matrix remained ill-conditioned;
17 /// the math path fell back to the identity (= maximum-entropy prior).
18 StabilizationFailed { size: usize, ridge: f64 },
19 /// Combining vectors/matrices with mismatched extents.
20 DimensionMismatch { expected: usize, actual: usize },
21}
22
23impl std::fmt::Display for SubstrateError {
24 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
25 match self {
26 SubstrateError::SingularMatrix { size, det } => {
27 write!(f, "singular {0}x{0} matrix (det={1:.3e})", size, det)
28 }
29 SubstrateError::StabilizationFailed { size, ridge } => {
30 write!(f, "ridge {0:.1e} insufficient to stabilise {1}x{1} matrix", ridge, size)
31 }
32 SubstrateError::DimensionMismatch { expected, actual } => {
33 write!(f, "dimension mismatch: expected {}, got {}", expected, actual)
34 }
35 }
36 }
37}
38
39impl std::error::Error for SubstrateError {}