Skip to main content

qualia_core_db/net/qdnf/harness/
clock.rs

1//! Deterministic fake clock. Monotonic, wall, and energy stay independent.
2
3use crate::net::qdnf::authority::ObservationQuality;
4use crate::net::qdnf::errors::QdnfError;
5
6/// Test clock with two time domains and an energy sample that is never inferred.
7#[derive(Clone, Copy, Debug)]
8pub struct FakeClock {
9    /// Steady elapsed time. Never converted into unix seconds.
10    pub monotonic_micros: u64,
11    /// Explicit wall seconds. Not derived from monotonic advances.
12    pub unix_seconds: u64,
13    /// Set when monotonic advances without a matching wall update.
14    pub wall_uncertain: bool,
15    energy_milli_joules: u64,
16    energy_quality: ObservationQuality,
17}
18
19impl FakeClock {
20    /// Creates a default `FakeClock`.
21    pub const fn new(unix_seconds: u64) -> Self {
22        Self {
23            monotonic_micros: 0,
24            unix_seconds,
25            wall_uncertain: false,
26            energy_milli_joules: 0,
27            energy_quality: ObservationQuality::Unknown,
28        }
29    }
30
31    /// Advance the monotonic domain only. Wall is not implied; energy is unchanged.
32    pub fn advance_micros(&mut self, delta: u64) {
33        if delta == 0 {
34            return;
35        }
36        self.monotonic_micros = self.monotonic_micros.saturating_add(delta);
37        self.wall_uncertain = true;
38    }
39
40    /// Advance wall time explicitly. Does not move monotonic or energy.
41    pub fn advance_unix_seconds(&mut self, delta: u64) {
42        self.unix_seconds = self.unix_seconds.saturating_add(delta);
43        self.wall_uncertain = false;
44    }
45
46    /// Marks wall-clock reads uncertain.
47    pub fn mark_wall_uncertain(&mut self) {
48        self.wall_uncertain = true;
49    }
50
51    /// Feeds a measured energy reading (mJ).
52    pub fn set_energy_measured(&mut self, milli_joules: u64) {
53        self.energy_milli_joules = milli_joules;
54        self.energy_quality = ObservationQuality::Measured;
55    }
56
57    /// Feeds an estimated energy reading (mJ).
58    pub fn set_energy_estimated(&mut self, milli_joules: u64) {
59        self.energy_milli_joules = milli_joules;
60        self.energy_quality = ObservationQuality::Estimated;
61    }
62
63    /// Marks energy unknown.
64    pub fn set_energy_unknown(&mut self) {
65        self.energy_quality = ObservationQuality::Unknown;
66    }
67
68    /// `FakeClock::energy_quality`.
69    pub const fn energy_quality(self) -> ObservationQuality {
70        self.energy_quality
71    }
72
73    /// Unknown energy is incomplete, never treated as zero joules.
74    pub fn energy_milli_joules(self) -> Result<u64, QdnfError> {
75        match self.energy_quality {
76            ObservationQuality::Unknown => Err(QdnfError::Incomplete),
77            ObservationQuality::Measured | ObservationQuality::Estimated => {
78                Ok(self.energy_milli_joules)
79            }
80        }
81    }
82}
83
84#[cfg(test)]
85mod tests {
86    use super::*;
87
88    #[test]
89    fn clock_domains_distinct() {
90        let mut clock = FakeClock::new(1_700_000_000);
91        clock.advance_micros(1_500_000);
92        assert_eq!(clock.monotonic_micros, 1_500_000);
93        assert_eq!(clock.unix_seconds, 1_700_000_000);
94        assert!(clock.wall_uncertain);
95
96        clock.advance_unix_seconds(3);
97        assert_eq!(clock.unix_seconds, 1_700_000_003);
98        assert_eq!(clock.monotonic_micros, 1_500_000);
99        assert!(!clock.wall_uncertain);
100    }
101
102    #[test]
103    fn advance_micros_does_not_zero_unknown_energy() {
104        let mut clock = FakeClock::new(10);
105        clock.set_energy_unknown();
106        clock.advance_micros(2_000_000);
107        assert_eq!(clock.energy_quality(), ObservationQuality::Unknown);
108        assert_eq!(clock.energy_milli_joules(), Err(QdnfError::Incomplete));
109        assert_eq!(clock.unix_seconds, 10);
110    }
111
112    #[test]
113    fn measured_energy_survives_time_advance() {
114        let mut clock = FakeClock::new(0);
115        clock.set_energy_measured(42);
116        clock.advance_micros(5);
117        clock.advance_unix_seconds(9);
118        assert_eq!(clock.energy_milli_joules(), Ok(42));
119        assert_eq!(clock.energy_quality(), ObservationQuality::Measured);
120    }
121}