Skip to main content

costroid_power/
error.rs

1//! Typed errors for the local-inference economics crate.
2//!
3//! Per the repo invariant (CLAUDE.md golden rules + the ⚑ Readiness gate, D) there is **no
4//! `unwrap`/`expect`/`panic!`** in this crate's library code: every failure mode — an
5//! unreadable/absent sensor, a zero-duration or zero-token run, an invalid hardware profile —
6//! is surfaced as a [`PowerError`] variant the caller can handle and the UI can stamp.
7
8use thiserror::Error;
9
10/// Anything that can go wrong while sampling power or computing local-inference economics.
11#[derive(Debug, Error)]
12pub enum PowerError {
13    /// The selected power source is not available on this host (e.g. the amdgpu hwmon
14    /// `power1_average` node is absent under WSL2, or the `power` feature is off). The
15    /// runtime selector treats this as "fall through to the next source", never a crash.
16    #[error("power sensor unavailable: {0}")]
17    SensorUnavailable(String),
18
19    /// A sensor node existed but could not be read or parsed (I/O error, non-integer
20    /// microwatt value, transient permission failure).
21    #[error("failed to read power sensor at {path}: {reason}")]
22    SensorRead { path: String, reason: String },
23
24    /// Energy/cost math was asked to divide by a zero (or negative) run duration. A run must
25    /// have positive wall-clock seconds to integrate power into energy.
26    #[error("run duration must be positive, got {0} s")]
27    NonPositiveDuration(f64),
28
29    /// Per-token economics were requested for a run that produced zero tokens — the
30    /// `$/token` figure is undefined, so the caller must handle it rather than emit ∞/NaN.
31    #[error("token count must be positive to compute per-token cost")]
32    ZeroTokens,
33
34    /// A hardware/power profile carried a non-physical value (negative price, zero lifetime,
35    /// utilization outside (0, 1]).
36    #[error("invalid hardware profile: {0}")]
37    InvalidProfile(String),
38}