Skip to main content

code_system_graph_core/execution_policy/
tracker.rs

1use std::sync::Arc;
2use std::time::{Duration, Instant};
3
4use super::{ExecutionLimitExceeded, ExecutionPolicy, ExecutionResource, JobPhase};
5
6/// Injectable monotonic time source used by execution watchdogs.
7pub trait MonotonicClock: std::fmt::Debug + Send + Sync {
8    /// Duration since an arbitrary stable origin.
9    fn now(&self) -> Duration;
10}
11
12#[derive(Debug)]
13struct SystemMonotonicClock {
14    origin: Instant,
15}
16
17impl SystemMonotonicClock {
18    fn new() -> Self {
19        Self {
20            origin: Instant::now(),
21        }
22    }
23}
24
25impl MonotonicClock for SystemMonotonicClock {
26    fn now(&self) -> Duration {
27        self.origin.elapsed()
28    }
29}
30
31/// Monotonic progress tracker used inside one worker process.
32#[derive(Debug)]
33pub struct ScanJobTracker {
34    run_id: String,
35    policy: ExecutionPolicy,
36    clock: Arc<dyn MonotonicClock>,
37    started: Duration,
38    last_progress: Duration,
39    phase: JobPhase,
40    completed_units: u64,
41}
42
43impl ScanJobTracker {
44    /// Starts a tracker for one run at configuration validation.
45    #[must_use]
46    pub fn new(run_id: impl Into<String>, policy: ExecutionPolicy) -> Self {
47        Self::with_clock(run_id, policy, Arc::new(SystemMonotonicClock::new()))
48    }
49
50    /// Starts a tracker with an injected monotonic clock for deterministic execution tests.
51    #[must_use]
52    pub fn with_clock(
53        run_id: impl Into<String>,
54        policy: ExecutionPolicy,
55        clock: Arc<dyn MonotonicClock>,
56    ) -> Self {
57        let now = clock.now();
58        Self {
59            run_id: run_id.into(),
60            policy,
61            clock,
62            started: now,
63            last_progress: now,
64            phase: JobPhase::Configuration,
65            completed_units: 0,
66        }
67    }
68
69    /// Phase of the most recent progress or phase change.
70    #[must_use]
71    pub const fn phase(&self) -> JobPhase {
72        self.phase
73    }
74
75    /// Changes phase after checking the active deadlines.
76    ///
77    /// # Errors
78    ///
79    /// Returns [`ExecutionLimitExceeded`] when wall time or no-progress time is exhausted.
80    pub fn enter_phase(&mut self, phase: JobPhase) -> Result<(), ExecutionLimitExceeded> {
81        self.check_time()?;
82        self.phase = phase;
83        Ok(())
84    }
85
86    /// Charges verified completed work using checked arithmetic.
87    ///
88    /// # Errors
89    ///
90    /// Returns [`ExecutionLimitExceeded`] on arithmetic overflow or an exhausted deadline.
91    pub fn progress(&mut self, amount: u64) -> Result<(), ExecutionLimitExceeded> {
92        let completed_units = self
93            .completed_units
94            .checked_add(amount)
95            .ok_or_else(|| self.exceeded(ExecutionResource::WorkUnits, u64::MAX, u64::MAX - 1))?;
96        self.check_time()?;
97        self.completed_units = completed_units;
98        self.last_progress = self.clock.now();
99        Ok(())
100    }
101
102    /// Checks monotonic wall time and time since the last verified progress.
103    ///
104    /// # Errors
105    ///
106    /// Returns [`ExecutionLimitExceeded`] when either effective duration is exhausted.
107    pub fn check_time(&self) -> Result<(), ExecutionLimitExceeded> {
108        let now = self.clock.now();
109        self.check_duration(
110            ExecutionResource::WallTimeMs,
111            now.saturating_sub(self.started),
112            self.policy.max_scan_wall_time_ms,
113        )?;
114        self.check_duration(
115            ExecutionResource::NoProgressTimeMs,
116            now.saturating_sub(self.last_progress),
117            self.policy.max_no_progress_time_ms,
118        )
119    }
120
121    fn check_duration(
122        &self,
123        resource: ExecutionResource,
124        observed: Duration,
125        maximum: u64,
126    ) -> Result<(), ExecutionLimitExceeded> {
127        let observed = u64::try_from(observed.as_millis()).unwrap_or(u64::MAX);
128        if observed > maximum {
129            return Err(self.exceeded(resource, observed, maximum));
130        }
131        Ok(())
132    }
133
134    fn exceeded(
135        &self,
136        resource: ExecutionResource,
137        observed: u64,
138        maximum: u64,
139    ) -> ExecutionLimitExceeded {
140        ExecutionLimitExceeded {
141            run_id: self.run_id.clone(),
142            phase: self.phase,
143            resource,
144            observed,
145            maximum,
146            completed_units: self.completed_units,
147        }
148    }
149}
150
151#[cfg(test)]
152mod tests {
153    use std::sync::Arc;
154    use std::sync::atomic::{AtomicU64, Ordering};
155
156    use super::*;
157
158    #[derive(Debug, Default)]
159    struct FakeClock {
160        milliseconds: AtomicU64,
161    }
162
163    impl FakeClock {
164        fn advance(&self, milliseconds: u64) {
165            self.milliseconds.fetch_add(milliseconds, Ordering::Relaxed);
166        }
167    }
168
169    impl MonotonicClock for FakeClock {
170        fn now(&self) -> Duration {
171            Duration::from_millis(self.milliseconds.load(Ordering::Relaxed))
172        }
173    }
174
175    #[test]
176    fn injected_clock_should_accept_exact_deadline_and_reject_one_unit_over() {
177        let clock = Arc::new(FakeClock::default());
178        let policy = ExecutionPolicy {
179            max_scan_wall_time_ms: 10,
180            max_no_progress_time_ms: 10,
181            ..ExecutionPolicy::default()
182        };
183        let tracker = ScanJobTracker::with_clock("run", policy, clock.clone());
184
185        clock.advance(10);
186        tracker.check_time().expect("exact deadline is inclusive");
187        clock.advance(1);
188        let error = tracker.check_time().expect_err("one over must fail");
189
190        assert_eq!(error.resource, ExecutionResource::WallTimeMs);
191        assert_eq!(error.observed, 11);
192        assert_eq!(error.maximum, 10);
193    }
194
195    #[test]
196    fn phase_changes_should_not_fake_progress() {
197        let clock = Arc::new(FakeClock::default());
198        let policy = ExecutionPolicy {
199            max_scan_wall_time_ms: 100,
200            max_no_progress_time_ms: 5,
201            ..ExecutionPolicy::default()
202        };
203        let mut tracker = ScanJobTracker::with_clock("run", policy, clock.clone());
204
205        clock.advance(5);
206        tracker
207            .enter_phase(JobPhase::Discovery)
208            .expect("exact idle deadline is inclusive");
209        clock.advance(1);
210        let error = tracker
211            .enter_phase(JobPhase::Fingerprinting)
212            .expect_err("phase churn must not renew watchdog");
213
214        assert_eq!(error.resource, ExecutionResource::NoProgressTimeMs);
215    }
216}