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}