1use std::fmt::Write as _;
2use std::num::NonZeroUsize;
3use std::sync::Arc;
4use std::time::{Duration, Instant};
5
6use code_system_graph_model::stable_id;
7use schemars::JsonSchema;
8use serde::{Deserialize, Serialize};
9use thiserror::Error;
10
11pub const DEFAULT_MAX_SCAN_WALL_TIME_MS: u64 = 21_600_000;
13pub const DEFAULT_MAX_NO_PROGRESS_TIME_MS: u64 = 300_000;
15pub const DEFAULT_MAX_CODEGRAPH_SYNC_WALL_TIME_MS_PER_REPO: u64 = 3_600_000;
17pub const DEFAULT_MAX_CODEGRAPH_CORROBORATION_ANCHORS_PER_REPO: i64 = 50;
19pub const DEFAULT_MAX_WORKER_MEMORY_BYTES: u64 = 17_179_869_184;
21pub const DEFAULT_GRACEFUL_TERMINATION_MS: u64 = 5_000;
23pub const DEFAULT_WATCH_IDLE_TIMEOUT_MS: u64 = 28_800_000;
25pub const DEFAULT_MAX_WATCH_SESSION_WALL_TIME_MS: u64 = 86_400_000;
27pub const DEFAULT_MIN_WATCH_RESCAN_INTERVAL_MS: u64 = 10_000;
29pub const DEFAULT_MAX_CHECKPOINT_CACHE_BYTES: u64 = 10_737_418_240;
31
32#[derive(Debug, Clone, Copy, PartialEq, Eq, JsonSchema)]
37pub enum CodeGraphCorroborationAnchorLimit {
38 Bounded(NonZeroUsize),
40 Unlimited,
42}
43
44impl CodeGraphCorroborationAnchorLimit {
45 #[must_use]
47 pub const fn bounded(self) -> Option<NonZeroUsize> {
48 match self {
49 Self::Bounded(limit) => Some(limit),
50 Self::Unlimited => None,
51 }
52 }
53}
54
55impl TryFrom<i64> for CodeGraphCorroborationAnchorLimit {
56 type Error = InvalidExecutionPolicy;
57
58 fn try_from(value: i64) -> Result<Self, Self::Error> {
59 if value == -1 {
60 return Ok(Self::Unlimited);
61 }
62 let limit = usize::try_from(value)
63 .ok()
64 .and_then(NonZeroUsize::new)
65 .ok_or(InvalidExecutionPolicy::InvalidValue {
66 field: "maxCodeGraphCorroborationAnchorsPerRepo",
67 value: value.unsigned_abs(),
68 })?;
69 Ok(Self::Bounded(limit))
70 }
71}
72
73impl Serialize for CodeGraphCorroborationAnchorLimit {
74 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
75 where
76 S: serde::Serializer,
77 {
78 let value = match self {
79 Self::Bounded(limit) => i64::try_from(limit.get()).map_err(|_| {
80 serde::ser::Error::custom("CodeGraph corroboration anchor limit exceeds i64")
81 })?,
82 Self::Unlimited => -1,
83 };
84 serializer.serialize_i64(value)
85 }
86}
87
88impl<'de> Deserialize<'de> for CodeGraphCorroborationAnchorLimit {
89 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
90 where
91 D: serde::Deserializer<'de>,
92 {
93 i64::deserialize(deserializer)?
94 .try_into()
95 .map_err(serde::de::Error::custom)
96 }
97}
98
99impl std::fmt::Display for CodeGraphCorroborationAnchorLimit {
100 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
101 match self {
102 Self::Bounded(limit) => limit.fmt(formatter),
103 Self::Unlimited => formatter.write_str("-1"),
104 }
105 }
106}
107
108#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
110#[serde(rename_all = "camelCase", deny_unknown_fields)]
111pub struct ExecutionPolicyOverrides {
112 pub max_scan_wall_time_ms: Option<u64>,
114 pub max_no_progress_time_ms: Option<u64>,
116 #[serde(rename = "maxCodeGraphSyncWallTimeMsPerRepo")]
118 pub max_codegraph_sync_wall_time_ms_per_repo: Option<u64>,
119 pub max_worker_memory_bytes: Option<u64>,
121 pub graceful_termination_ms: Option<u64>,
123 pub watch_idle_timeout_ms: Option<u64>,
125 pub max_watch_session_wall_time_ms: Option<u64>,
127 pub min_watch_rescan_interval_ms: Option<u64>,
129 pub max_checkpoint_cache_bytes: Option<u64>,
131}
132
133#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
135#[serde(rename_all = "camelCase")]
136pub struct ExecutionPolicy {
137 pub max_scan_wall_time_ms: u64,
139 pub max_no_progress_time_ms: u64,
141 #[serde(rename = "maxCodeGraphSyncWallTimeMsPerRepo")]
143 pub max_codegraph_sync_wall_time_ms_per_repo: u64,
144 pub max_worker_memory_bytes: u64,
146 pub graceful_termination_ms: u64,
148 pub watch_idle_timeout_ms: u64,
150 pub max_watch_session_wall_time_ms: u64,
152 pub min_watch_rescan_interval_ms: u64,
154 pub max_checkpoint_cache_bytes: u64,
156}
157
158impl Default for ExecutionPolicy {
159 fn default() -> Self {
160 Self {
161 max_scan_wall_time_ms: DEFAULT_MAX_SCAN_WALL_TIME_MS,
162 max_no_progress_time_ms: DEFAULT_MAX_NO_PROGRESS_TIME_MS,
163 max_codegraph_sync_wall_time_ms_per_repo:
164 DEFAULT_MAX_CODEGRAPH_SYNC_WALL_TIME_MS_PER_REPO,
165 max_worker_memory_bytes: DEFAULT_MAX_WORKER_MEMORY_BYTES,
166 graceful_termination_ms: DEFAULT_GRACEFUL_TERMINATION_MS,
167 watch_idle_timeout_ms: DEFAULT_WATCH_IDLE_TIMEOUT_MS,
168 max_watch_session_wall_time_ms: DEFAULT_MAX_WATCH_SESSION_WALL_TIME_MS,
169 min_watch_rescan_interval_ms: DEFAULT_MIN_WATCH_RESCAN_INTERVAL_MS,
170 max_checkpoint_cache_bytes: DEFAULT_MAX_CHECKPOINT_CACHE_BYTES,
171 }
172 }
173}
174
175impl ExecutionPolicy {
176 pub fn resolve(
182 overrides: Option<&ExecutionPolicyOverrides>,
183 ) -> Result<Self, InvalidExecutionPolicy> {
184 let mut policy = Self::default();
185 if let Some(values) = overrides {
186 macro_rules! apply {
187 ($field:ident) => {
188 if let Some(value) = values.$field {
189 policy.$field = value;
190 }
191 };
192 }
193 apply!(max_scan_wall_time_ms);
194 apply!(max_no_progress_time_ms);
195 apply!(max_codegraph_sync_wall_time_ms_per_repo);
196 apply!(max_worker_memory_bytes);
197 apply!(graceful_termination_ms);
198 apply!(watch_idle_timeout_ms);
199 apply!(max_watch_session_wall_time_ms);
200 apply!(min_watch_rescan_interval_ms);
201 apply!(max_checkpoint_cache_bytes);
202 }
203 policy.validate()?;
204 Ok(policy)
205 }
206
207 fn validate(&self) -> Result<(), InvalidExecutionPolicy> {
208 for (field, value) in self.canonical_values() {
209 let invalid_bytes = field.ends_with("Bytes") && usize::try_from(value).is_err();
210 let invalid_sqlite_quota =
211 field == "maxCheckpointCacheBytes" && i64::try_from(value).is_err();
212 let invalid_deadline = field.ends_with("Ms")
213 && Instant::now()
214 .checked_add(Duration::from_millis(value))
215 .is_none();
216 if value == 0 || invalid_bytes || invalid_sqlite_quota || invalid_deadline {
217 return Err(InvalidExecutionPolicy::InvalidValue { field, value });
218 }
219 }
220 Self::require_not_greater(
221 "maxNoProgressTimeMs",
222 self.max_no_progress_time_ms,
223 "maxScanWallTimeMs",
224 self.max_scan_wall_time_ms,
225 )?;
226 Self::require_not_greater(
227 "maxCodeGraphSyncWallTimeMsPerRepo",
228 self.max_codegraph_sync_wall_time_ms_per_repo,
229 "maxScanWallTimeMs",
230 self.max_scan_wall_time_ms,
231 )?;
232 Self::require_not_greater(
233 "gracefulTerminationMs",
234 self.graceful_termination_ms,
235 "maxNoProgressTimeMs",
236 self.max_no_progress_time_ms,
237 )?;
238 Self::require_not_greater(
239 "watchIdleTimeoutMs",
240 self.watch_idle_timeout_ms,
241 "maxWatchSessionWallTimeMs",
242 self.max_watch_session_wall_time_ms,
243 )?;
244 Self::require_not_greater(
245 "minWatchRescanIntervalMs",
246 self.min_watch_rescan_interval_ms,
247 "watchIdleTimeoutMs",
248 self.watch_idle_timeout_ms,
249 )
250 }
251
252 fn require_not_greater(
253 field: &'static str,
254 value: u64,
255 maximum_field: &'static str,
256 maximum: u64,
257 ) -> Result<(), InvalidExecutionPolicy> {
258 if value > maximum {
259 return Err(InvalidExecutionPolicy::InvalidRelationship {
260 field,
261 value,
262 maximum_field,
263 maximum,
264 });
265 }
266 Ok(())
267 }
268
269 fn canonical_values(&self) -> [(&'static str, u64); 9] {
270 [
271 ("maxScanWallTimeMs", self.max_scan_wall_time_ms),
272 ("maxNoProgressTimeMs", self.max_no_progress_time_ms),
273 (
274 "maxCodeGraphSyncWallTimeMsPerRepo",
275 self.max_codegraph_sync_wall_time_ms_per_repo,
276 ),
277 ("maxWorkerMemoryBytes", self.max_worker_memory_bytes),
278 ("gracefulTerminationMs", self.graceful_termination_ms),
279 ("watchIdleTimeoutMs", self.watch_idle_timeout_ms),
280 (
281 "maxWatchSessionWallTimeMs",
282 self.max_watch_session_wall_time_ms,
283 ),
284 (
285 "minWatchRescanIntervalMs",
286 self.min_watch_rescan_interval_ms,
287 ),
288 ("maxCheckpointCacheBytes", self.max_checkpoint_cache_bytes),
289 ]
290 }
291
292 #[must_use]
294 pub fn fingerprint(&self) -> String {
295 let canonical = self
296 .canonical_values()
297 .into_iter()
298 .map(|(name, value)| format!("{name}={value}"))
299 .collect::<Vec<_>>()
300 .join(";");
301 stable_id("execution-policy", &canonical)
302 }
303
304 #[must_use]
306 pub fn fingerprint_with_codegraph_limit(
307 &self,
308 limit: CodeGraphCorroborationAnchorLimit,
309 ) -> String {
310 let mut canonical = self
311 .canonical_values()
312 .into_iter()
313 .map(|(name, value)| format!("{name}={value}"))
314 .collect::<Vec<_>>()
315 .join(";");
316 write!(
317 canonical,
318 ";maxCodeGraphCorroborationAnchorsPerRepo={limit}"
319 )
320 .expect("writing to a String cannot fail");
321 stable_id("execution-policy", &canonical)
322 }
323}
324
325#[derive(Debug, Clone, PartialEq, Eq, Error)]
327pub enum InvalidExecutionPolicy {
328 #[error("execution policy `{field}` must be positive and representable; received {value}")]
330 InvalidValue {
331 field: &'static str,
333 value: u64,
335 },
336 #[error("execution policy `{field}` ({value}) must not exceed `{maximum_field}` ({maximum})")]
338 InvalidRelationship {
339 field: &'static str,
341 value: u64,
343 maximum_field: &'static str,
345 maximum: u64,
347 },
348}
349
350#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
352#[serde(rename_all = "snake_case")]
353pub enum JobPhase {
354 Configuration,
356 Discovery,
358 Fingerprinting,
360 Extraction,
362 GraphAssembly,
364 Communities,
366 Publication,
368 CodeGraphSync,
370}
371
372#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
374#[serde(rename_all = "snake_case")]
375pub enum ExecutionResource {
376 WallTimeMs,
378 NoProgressTimeMs,
380 WorkerMemoryBytes,
382 WorkUnits,
384 WorkerProcess,
386 WorkerProtocolBytes,
388 Cancellation,
390}
391
392#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
394#[serde(rename_all = "camelCase")]
395pub struct ExecutionSummary {
396 pub run_id: String,
398 pub duration_ms: u64,
400 pub peak_worker_memory_bytes: u64,
402 pub completed_work_units: u64,
404 pub checkpoint_hits: u64,
406 pub checkpoints_written: u64,
408 pub measured_artifacts: u64,
410 pub artifact_duration_p50_ms: u64,
412 pub artifact_duration_p95_ms: u64,
414 pub artifact_duration_p99_ms: u64,
416}
417
418#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema, Error)]
420#[error(
421 "execution `{run_id}` exceeded {resource:?} during {phase:?}: observed {observed}, maximum {maximum}, completed {completed_units} units"
422)]
423pub struct ExecutionLimitExceeded {
424 pub run_id: String,
426 pub phase: JobPhase,
428 pub resource: ExecutionResource,
430 pub observed: u64,
432 pub maximum: u64,
434 pub completed_units: u64,
436}
437
438pub trait MonotonicClock: std::fmt::Debug + Send + Sync {
440 fn now(&self) -> Duration;
442}
443
444#[derive(Debug)]
445struct SystemMonotonicClock {
446 origin: Instant,
447}
448
449impl SystemMonotonicClock {
450 fn new() -> Self {
451 Self {
452 origin: Instant::now(),
453 }
454 }
455}
456
457impl MonotonicClock for SystemMonotonicClock {
458 fn now(&self) -> Duration {
459 self.origin.elapsed()
460 }
461}
462
463#[derive(Debug)]
465pub struct ScanJobTracker {
466 run_id: String,
467 policy: ExecutionPolicy,
468 clock: Arc<dyn MonotonicClock>,
469 started: Duration,
470 last_progress: Duration,
471 phase: JobPhase,
472 completed_units: u64,
473}
474
475impl ScanJobTracker {
476 #[must_use]
478 pub fn new(run_id: impl Into<String>, policy: ExecutionPolicy) -> Self {
479 Self::with_clock(run_id, policy, Arc::new(SystemMonotonicClock::new()))
480 }
481
482 #[must_use]
484 pub fn with_clock(
485 run_id: impl Into<String>,
486 policy: ExecutionPolicy,
487 clock: Arc<dyn MonotonicClock>,
488 ) -> Self {
489 let now = clock.now();
490 Self {
491 run_id: run_id.into(),
492 policy,
493 clock,
494 started: now,
495 last_progress: now,
496 phase: JobPhase::Configuration,
497 completed_units: 0,
498 }
499 }
500
501 pub fn enter_phase(&mut self, phase: JobPhase) -> Result<(), ExecutionLimitExceeded> {
507 self.check_time()?;
508 self.phase = phase;
509 Ok(())
510 }
511
512 pub fn progress(&mut self, amount: u64) -> Result<(), ExecutionLimitExceeded> {
518 let completed_units = self
519 .completed_units
520 .checked_add(amount)
521 .ok_or_else(|| self.exceeded(ExecutionResource::WorkUnits, u64::MAX, u64::MAX - 1))?;
522 self.check_time()?;
523 self.completed_units = completed_units;
524 self.last_progress = self.clock.now();
525 Ok(())
526 }
527
528 pub fn check_time(&self) -> Result<(), ExecutionLimitExceeded> {
534 let now = self.clock.now();
535 self.check_duration(
536 ExecutionResource::WallTimeMs,
537 now.saturating_sub(self.started),
538 self.policy.max_scan_wall_time_ms,
539 )?;
540 self.check_duration(
541 ExecutionResource::NoProgressTimeMs,
542 now.saturating_sub(self.last_progress),
543 self.policy.max_no_progress_time_ms,
544 )
545 }
546
547 fn check_duration(
548 &self,
549 resource: ExecutionResource,
550 observed: Duration,
551 maximum: u64,
552 ) -> Result<(), ExecutionLimitExceeded> {
553 let observed = u64::try_from(observed.as_millis()).unwrap_or(u64::MAX);
554 if observed > maximum {
555 return Err(self.exceeded(resource, observed, maximum));
556 }
557 Ok(())
558 }
559
560 fn exceeded(
561 &self,
562 resource: ExecutionResource,
563 observed: u64,
564 maximum: u64,
565 ) -> ExecutionLimitExceeded {
566 ExecutionLimitExceeded {
567 run_id: self.run_id.clone(),
568 phase: self.phase,
569 resource,
570 observed,
571 maximum,
572 completed_units: self.completed_units,
573 }
574 }
575}
576
577#[cfg(test)]
578mod tests {
579 use std::sync::atomic::{AtomicU64, Ordering};
580
581 use super::*;
582
583 #[derive(Debug, Default)]
584 struct FakeClock {
585 milliseconds: AtomicU64,
586 }
587
588 impl FakeClock {
589 fn advance(&self, milliseconds: u64) {
590 self.milliseconds.fetch_add(milliseconds, Ordering::Relaxed);
591 }
592 }
593
594 impl MonotonicClock for FakeClock {
595 fn now(&self) -> Duration {
596 Duration::from_millis(self.milliseconds.load(Ordering::Relaxed))
597 }
598 }
599
600 #[test]
601 fn defaults_should_be_generous_and_finite() {
602 let policy = ExecutionPolicy::default();
603
604 assert_eq!(policy.max_scan_wall_time_ms, 21_600_000);
605 assert_eq!(
606 CodeGraphCorroborationAnchorLimit::try_from(
607 DEFAULT_MAX_CODEGRAPH_CORROBORATION_ANCHORS_PER_REPO
608 )
609 .expect("default anchor limit")
610 .bounded()
611 .map(NonZeroUsize::get),
612 Some(50)
613 );
614 assert_eq!(policy.max_worker_memory_bytes, 17_179_869_184);
615 assert_eq!(policy.max_checkpoint_cache_bytes, 10_737_418_240);
616 }
617
618 #[test]
619 fn partial_override_should_preserve_other_defaults() {
620 let policy = ExecutionPolicy::resolve(Some(&ExecutionPolicyOverrides {
621 max_scan_wall_time_ms: Some(28_800_000),
622 ..ExecutionPolicyOverrides::default()
623 }))
624 .expect("valid override");
625
626 assert_eq!(policy.max_scan_wall_time_ms, 28_800_000);
627 assert_eq!(policy.max_no_progress_time_ms, 300_000);
628 }
629
630 #[test]
631 fn zero_should_be_rejected() {
632 let error = ExecutionPolicy::resolve(Some(&ExecutionPolicyOverrides {
633 max_worker_memory_bytes: Some(0),
634 ..ExecutionPolicyOverrides::default()
635 }))
636 .expect_err("zero must fail");
637
638 assert!(matches!(
639 error,
640 InvalidExecutionPolicy::InvalidValue {
641 field: "maxWorkerMemoryBytes",
642 value: 0
643 }
644 ));
645 }
646
647 #[test]
648 fn corroboration_anchor_limit_should_accept_positive_or_unlimited() {
649 let bounded =
650 CodeGraphCorroborationAnchorLimit::try_from(12).expect("positive anchor limit");
651 let unlimited =
652 CodeGraphCorroborationAnchorLimit::try_from(-1).expect("unlimited anchor limit");
653
654 assert_eq!(bounded.bounded().map(NonZeroUsize::get), Some(12));
655 assert_eq!(unlimited.bounded(), None);
656 assert_ne!(
657 ExecutionPolicy::default().fingerprint_with_codegraph_limit(bounded),
658 ExecutionPolicy::default().fingerprint_with_codegraph_limit(unlimited)
659 );
660 assert_eq!(
661 serde_json::to_value(bounded).expect("bounded limit serializes"),
662 serde_json::json!(12)
663 );
664 assert_eq!(
665 serde_json::to_value(unlimited).expect("unlimited limit serializes"),
666 serde_json::json!(-1)
667 );
668 }
669
670 #[test]
671 fn corroboration_anchor_limit_should_reject_zero_and_values_below_sentinel() {
672 for value in [0, -2] {
673 let error = CodeGraphCorroborationAnchorLimit::try_from(value)
674 .expect_err("invalid anchor limit");
675
676 assert!(matches!(
677 error,
678 InvalidExecutionPolicy::InvalidValue {
679 field: "maxCodeGraphCorroborationAnchorsPerRepo",
680 value: observed
681 } if observed == value.unsigned_abs()
682 ));
683 }
684 }
685
686 #[test]
687 fn technically_unrepresentable_values_should_be_rejected() {
688 let quota = ExecutionPolicy::resolve(Some(&ExecutionPolicyOverrides {
689 max_checkpoint_cache_bytes: Some(u64::MAX),
690 ..ExecutionPolicyOverrides::default()
691 }))
692 .expect_err("SQLite quota overflow must fail");
693
694 assert!(matches!(quota, InvalidExecutionPolicy::InvalidValue { .. }));
695 }
696
697 #[test]
698 fn subordinate_deadline_should_not_exceed_scan_deadline() {
699 let error = ExecutionPolicy::resolve(Some(&ExecutionPolicyOverrides {
700 max_scan_wall_time_ms: Some(1_000),
701 max_no_progress_time_ms: Some(1_001),
702 max_codegraph_sync_wall_time_ms_per_repo: Some(1_000),
703 graceful_termination_ms: Some(500),
704 ..ExecutionPolicyOverrides::default()
705 }))
706 .expect_err("relationship must fail");
707
708 assert!(matches!(
709 error,
710 InvalidExecutionPolicy::InvalidRelationship {
711 field: "maxNoProgressTimeMs",
712 ..
713 }
714 ));
715 }
716
717 #[test]
718 fn fingerprint_should_ignore_yaml_field_order() {
719 let first = ExecutionPolicy::default();
720 let second = ExecutionPolicy::resolve(Some(&ExecutionPolicyOverrides::default()))
721 .expect("defaults valid");
722
723 assert_eq!(first.fingerprint(), second.fingerprint());
724 }
725
726 #[test]
727 fn injected_clock_should_accept_exact_deadline_and_reject_one_unit_over() {
728 let clock = Arc::new(FakeClock::default());
729 let policy = ExecutionPolicy {
730 max_scan_wall_time_ms: 10,
731 max_no_progress_time_ms: 10,
732 ..ExecutionPolicy::default()
733 };
734 let tracker = ScanJobTracker::with_clock("run", policy, clock.clone());
735
736 clock.advance(10);
737 tracker.check_time().expect("exact deadline is inclusive");
738 clock.advance(1);
739 let error = tracker.check_time().expect_err("one over must fail");
740
741 assert_eq!(error.resource, ExecutionResource::WallTimeMs);
742 assert_eq!(error.observed, 11);
743 assert_eq!(error.maximum, 10);
744 }
745
746 #[test]
747 fn phase_changes_should_not_fake_progress() {
748 let clock = Arc::new(FakeClock::default());
749 let policy = ExecutionPolicy {
750 max_scan_wall_time_ms: 100,
751 max_no_progress_time_ms: 5,
752 ..ExecutionPolicy::default()
753 };
754 let mut tracker = ScanJobTracker::with_clock("run", policy, clock.clone());
755
756 clock.advance(5);
757 tracker
758 .enter_phase(JobPhase::Discovery)
759 .expect("exact idle deadline is inclusive");
760 clock.advance(1);
761 let error = tracker
762 .enter_phase(JobPhase::Fingerprinting)
763 .expect_err("phase churn must not renew watchdog");
764
765 assert_eq!(error.resource, ExecutionResource::NoProgressTimeMs);
766 }
767}