Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/crates/ruvector-solver/src/events.rs

@@ -0,0 +1,86 @@
+//! Event sourcing for solver operations.
+//!
+//! Every solver emits [`SolverEvent`]s to an event log, enabling full
+//! observability of the solve pipeline: what was requested, how many
+//! iterations ran, whether convergence was reached, and whether fallback
+//! algorithms were invoked.
+
+use std::time::Duration;
+
+use serde::{Deserialize, Serialize};
+
+use crate::types::{Algorithm, ComputeLane};
+
+/// Events emitted during a solver invocation.
+///
+/// Events are tagged with `#[serde(tag = "type")]` so they serialise as
+/// `{ "type": "SolveRequested", ... }` for easy ingestion into event stores.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type")]
+pub enum SolverEvent {
+    /// A solve request was received and is about to begin.
+    SolveRequested {
+        /// Algorithm that will be attempted first.
+        algorithm: Algorithm,
+        /// Matrix dimension (number of rows).
+        matrix_rows: usize,
+        /// Number of non-zeros.
+        matrix_nnz: usize,
+        /// Compute lane.
+        lane: ComputeLane,
+    },
+
+    /// One iteration of the solver completed.
+    IterationCompleted {
+        /// Iteration number (0-indexed).
+        iteration: usize,
+        /// Current residual norm.
+        residual: f64,
+        /// Wall time elapsed since the solve began.
+        elapsed: Duration,
+    },
+
+    /// The solver converged successfully.
+    SolveConverged {
+        /// Algorithm that produced the result.
+        algorithm: Algorithm,
+        /// Total iterations executed.
+        iterations: usize,
+        /// Final residual norm.
+        residual: f64,
+        /// Total wall time.
+        wall_time: Duration,
+    },
+
+    /// The solver fell back from one algorithm to another (e.g. Neumann
+    /// series spectral radius too high, falling back to CG).
+    AlgorithmFallback {
+        /// Algorithm that failed or was deemed unsuitable.
+        from: Algorithm,
+        /// Algorithm that will be tried next.
+        to: Algorithm,
+        /// Human-readable reason for the fallback.
+        reason: String,
+    },
+
+    /// The compute budget was exhausted before convergence.
+    BudgetExhausted {
+        /// Algorithm that was running when the budget was hit.
+        algorithm: Algorithm,
+        /// Which budget limit was hit.
+        limit: BudgetLimit,
+        /// Wall time elapsed.
+        elapsed: Duration,
+    },
+}
+
+/// Which budget limit was exhausted.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum BudgetLimit {
+    /// Wall-clock time limit.
+    WallTime,
+    /// Iteration count limit.
+    Iterations,
+    /// Memory allocation limit.
+    Memory,
+}