Skip to main content

qualia_core_db/net/qdnf/economics/
meters.rs

1//! Independent resource meters (E18.2–E18.3). Unknown is not Measured and not zero.
2
3use crate::net::qdnf::authority::{ObservationQuality, ResourceKind};
4use crate::net::qdnf::errors::QdnfError;
5
6use super::Quantity;
7
8/// Meter kinds. Byte-time and network bytes stay distinct from joules, time and compute.
9#[repr(u8)]
10#[derive(Clone, Copy, Debug, PartialEq, Eq)]
11pub enum MeterKind {
12    EnergyJoules = 1,
13    TimeSeconds = 2,
14    TypedCompute = 3,
15    ByteTime = 4,
16    NetBytes = 5,
17}
18
19impl MeterKind {
20    /// Builds `MeterKind` from `resource`.
21    pub fn from_resource(kind: ResourceKind) -> Self {
22        match kind {
23            ResourceKind::EnergyJoules => Self::EnergyJoules,
24            ResourceKind::TimeSeconds => Self::TimeSeconds,
25            ResourceKind::TypedCompute => Self::TypedCompute,
26        }
27    }
28}
29
30/// One observed meter. Quality is independent of milli_units.
31#[repr(C)]
32#[derive(Clone, Copy, Debug, PartialEq, Eq)]
33pub struct MeterReading {
34    pub kind: MeterKind,
35    pub milli_units: u64,
36    pub quality: ObservationQuality,
37}
38
39impl MeterReading {
40    /// Adds an entry.
41    pub fn add(self, other: Self) -> Result<Self, QdnfError> {
42        if self.kind != other.kind {
43            return Err(QdnfError::Malformed);
44        }
45        Ok(Self {
46            kind: self.kind,
47            milli_units: self
48                .milli_units
49                .checked_add(other.milli_units)
50                .ok_or(QdnfError::Range)?,
51            quality: match (self.quality, other.quality) {
52                (ObservationQuality::Unknown, _) | (_, ObservationQuality::Unknown) => {
53                    ObservationQuality::Unknown
54                }
55                (ObservationQuality::Estimated, _) | (_, ObservationQuality::Estimated) => {
56                    ObservationQuality::Estimated
57                }
58                _ => ObservationQuality::Measured,
59            },
60        })
61    }
62
63    /// Unknown quality is Incomplete, never a measured zero.
64    pub fn value(self) -> Result<u64, QdnfError> {
65        match self.quality {
66            ObservationQuality::Unknown => Err(QdnfError::Incomplete),
67            ObservationQuality::Measured | ObservationQuality::Estimated => Ok(self.milli_units),
68        }
69    }
70}
71
72/// Unknown observation is not Measured.
73#[inline]
74pub fn unknown_quality_is_measured(q: ObservationQuality) -> bool {
75    matches!(q, ObservationQuality::Measured)
76}
77
78/// Unknown meter is not billed as zero.
79#[inline]
80pub fn unknown_meter_as_zero(reading: MeterReading) -> bool {
81    let _ = reading;
82    false
83}
84
85/// Unknown quality cannot admit funded service. Measured and estimated may.
86pub fn meter_admits_service(reading: MeterReading) -> Result<u64, QdnfError> {
87    if unknown_meter_as_zero(reading) {
88        return Err(QdnfError::Malformed);
89    }
90    reading.value()
91}
92
93/// Map a Quantity into a meter of the same ResourceKind.
94pub fn reading_from_quantity(q: Quantity) -> MeterReading {
95    MeterReading {
96        kind: MeterKind::from_resource(q.kind),
97        milli_units: q.milli_units,
98        quality: q.quality,
99    }
100}
101
102#[cfg(test)]
103mod tests {
104    use super::*;
105
106    fn measured(kind: MeterKind, n: u64) -> MeterReading {
107        MeterReading {
108            kind,
109            milli_units: n,
110            quality: ObservationQuality::Measured,
111        }
112    }
113
114    #[test]
115    fn kinds_are_independent_and_unknown_is_not_zero() {
116        assert_ne!(MeterKind::EnergyJoules, MeterKind::ByteTime);
117        assert_ne!(MeterKind::TimeSeconds, MeterKind::NetBytes);
118        assert_ne!(MeterKind::TypedCompute, MeterKind::ByteTime);
119        assert_eq!(
120            measured(MeterKind::EnergyJoules, 1).add(measured(MeterKind::TimeSeconds, 1)),
121            Err(QdnfError::Malformed)
122        );
123        assert_eq!(
124            measured(MeterKind::ByteTime, 1).add(measured(MeterKind::NetBytes, 1)),
125            Err(QdnfError::Malformed)
126        );
127        let unknown = MeterReading {
128            kind: MeterKind::EnergyJoules,
129            milli_units: 0,
130            quality: ObservationQuality::Unknown,
131        };
132        assert!(!unknown_quality_is_measured(unknown.quality));
133        assert!(!unknown_meter_as_zero(unknown));
134        assert_eq!(unknown.value(), Err(QdnfError::Incomplete));
135        let added = unknown.add(measured(MeterKind::EnergyJoules, 5)).unwrap();
136        assert_eq!(added.quality, ObservationQuality::Unknown);
137        assert_eq!(added.value(), Err(QdnfError::Incomplete));
138    }
139
140    #[test]
141    fn quantity_maps_without_collapsing_kinds() {
142        let q = Quantity {
143            kind: ResourceKind::TypedCompute,
144            milli_units: 9,
145            quality: ObservationQuality::Estimated,
146        };
147        let r = reading_from_quantity(q);
148        assert_eq!(r.kind, MeterKind::TypedCompute);
149        assert_eq!(r.value().unwrap(), 9);
150        assert_eq!(meter_admits_service(r).unwrap(), 9);
151        let unknown = MeterReading {
152            kind: MeterKind::NetBytes,
153            milli_units: 4,
154            quality: ObservationQuality::Unknown,
155        };
156        assert_eq!(meter_admits_service(unknown), Err(QdnfError::Incomplete));
157    }
158}