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    /// Changes phase after checking the active deadlines.
70    ///
71    /// # Errors
72    ///
73    /// Returns [`ExecutionLimitExceeded`] when wall time or no-progress time is exhausted.
74    pub fn enter_phase(&mut self, phase: JobPhase) -> Result<(), ExecutionLimitExceeded> {
75        self.check_time()?;
76        self.phase = phase;
77        Ok(())
78    }
79
80    /// Charges verified completed work using checked arithmetic.
81    ///
82    /// # Errors
83    ///
84    /// Returns [`ExecutionLimitExceeded`] on arithmetic overflow or an exhausted deadline.
85    pub fn progress(&mut self, amount: u64) -> Result<(), ExecutionLimitExceeded> {
86        let completed_units = self
87            .completed_units
88            .checked_add(amount)
89            .ok_or_else(|| self.exceeded(ExecutionResource::WorkUnits, u64::MAX, u64::MAX - 1))?;
90        self.check_time()?;
91        self.completed_units = completed_units;
92        self.last_progress = self.clock.now();
93        Ok(())
94    }
95
96    /// Checks monotonic wall time and time since the last verified progress.
97    ///
98    /// # Errors
99    ///
100    /// Returns [`ExecutionLimitExceeded`] when either effective duration is exhausted.
101    pub fn check_time(&self) -> Result<(), ExecutionLimitExceeded> {
102        let now = self.clock.now();
103        self.check_duration(
104            ExecutionResource::WallTimeMs,
105            now.saturating_sub(self.started),
106            self.policy.max_scan_wall_time_ms,
107        )?;
108        self.check_duration(
109            ExecutionResource::NoProgressTimeMs,
110            now.saturating_sub(self.last_progress),
111            self.policy.max_no_progress_time_ms,
112        )
113    }
114
115    fn check_duration(
116        &self,
117        resource: ExecutionResource,
118        observed: Duration,
119        maximum: u64,
120    ) -> Result<(), ExecutionLimitExceeded> {
121        let observed = u64::try_from(observed.as_millis()).unwrap_or(u64::MAX);
122        if observed > maximum {
123            return Err(self.exceeded(resource, observed, maximum));
124        }
125        Ok(())
126    }
127
128    fn exceeded(
129        &self,
130        resource: ExecutionResource,
131        observed: u64,
132        maximum: u64,
133    ) -> ExecutionLimitExceeded {
134        ExecutionLimitExceeded {
135            run_id: self.run_id.clone(),
136            phase: self.phase,
137            resource,
138            observed,
139            maximum,
140            completed_units: self.completed_units,
141        }
142    }
143}
144
145#[cfg(test)]
146mod tests {
147    use std::sync::Arc;
148    use std::sync::atomic::{AtomicU64, Ordering};
149
150    use super::*;
151
152    #[derive(Debug, Default)]
153    struct FakeClock {
154        milliseconds: AtomicU64,
155    }
156
157    impl FakeClock {
158        fn advance(&self, milliseconds: u64) {
159            self.milliseconds.fetch_add(milliseconds, Ordering::Relaxed);
160        }
161    }
162
163    impl MonotonicClock for FakeClock {
164        fn now(&self) -> Duration {
165            Duration::from_millis(self.milliseconds.load(Ordering::Relaxed))
166        }
167    }
168
169    #[test]
170    fn injected_clock_should_accept_exact_deadline_and_reject_one_unit_over() {
171        let clock = Arc::new(FakeClock::default());
172        let policy = ExecutionPolicy {
173            max_scan_wall_time_ms: 10,
174            max_no_progress_time_ms: 10,
175            ..ExecutionPolicy::default()
176        };
177        let tracker = ScanJobTracker::with_clock("run", policy, clock.clone());
178
179        clock.advance(10);
180        tracker.check_time().expect("exact deadline is inclusive");
181        clock.advance(1);
182        let error = tracker.check_time().expect_err("one over must fail");
183
184        assert_eq!(error.resource, ExecutionResource::WallTimeMs);
185        assert_eq!(error.observed, 11);
186        assert_eq!(error.maximum, 10);
187    }
188
189    #[test]
190    fn phase_changes_should_not_fake_progress() {
191        let clock = Arc::new(FakeClock::default());
192        let policy = ExecutionPolicy {
193            max_scan_wall_time_ms: 100,
194            max_no_progress_time_ms: 5,
195            ..ExecutionPolicy::default()
196        };
197        let mut tracker = ScanJobTracker::with_clock("run", policy, clock.clone());
198
199        clock.advance(5);
200        tracker
201            .enter_phase(JobPhase::Discovery)
202            .expect("exact idle deadline is inclusive");
203        clock.advance(1);
204        let error = tracker
205            .enter_phase(JobPhase::Fingerprinting)
206            .expect_err("phase churn must not renew watchdog");
207
208        assert_eq!(error.resource, ExecutionResource::NoProgressTimeMs);
209    }
210}