Skip to main content

code_system_graph_core/
execution_policy.rs

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
11/// Default maximum wall time for one supervised scan or sync pass.
12pub const DEFAULT_MAX_SCAN_WALL_TIME_MS: u64 = 21_600_000;
13/// Default maximum time without verified forward progress.
14pub const DEFAULT_MAX_NO_PROGRESS_TIME_MS: u64 = 300_000;
15/// Default maximum wall time for one repository-local `CodeGraph` synchronization.
16pub const DEFAULT_MAX_CODEGRAPH_SYNC_WALL_TIME_MS_PER_REPO: u64 = 3_600_000;
17/// Default maximum source-symbol anchors corroborated through `CodeGraph` per repository.
18pub const DEFAULT_MAX_CODEGRAPH_CORROBORATION_ANCHORS_PER_REPO: i64 = 50;
19/// Default maximum resident memory accepted for one worker process.
20pub const DEFAULT_MAX_WORKER_MEMORY_BYTES: u64 = 17_179_869_184;
21/// Default cooperative shutdown grace period before forced termination.
22pub const DEFAULT_GRACEFUL_TERMINATION_MS: u64 = 5_000;
23/// Default inactivity lease for a foreground watch session.
24pub const DEFAULT_WATCH_IDLE_TIMEOUT_MS: u64 = 28_800_000;
25/// Default absolute lifetime for one foreground watch session.
26pub const DEFAULT_MAX_WATCH_SESSION_WALL_TIME_MS: u64 = 86_400_000;
27/// Default minimum delay between watched sync pass starts.
28pub const DEFAULT_MIN_WATCH_RESCAN_INTERVAL_MS: u64 = 10_000;
29/// Default maximum retained historical checkpoint-cache bytes.
30pub const DEFAULT_MAX_CHECKPOINT_CACHE_BYTES: u64 = 10_737_418_240;
31
32/// Effective per-repository limit for source-symbol corroboration through `CodeGraph`.
33///
34/// The workspace manifest keeps `-1` as its portable unlimited sentinel, but resolved policy and
35/// consumers use this type so that sentinel handling does not leak beyond the serde boundary.
36#[derive(Debug, Clone, Copy, PartialEq, Eq, JsonSchema)]
37pub enum CodeGraphCorroborationAnchorLimit {
38    /// Corroborate at most this many source-symbol anchors per repository.
39    Bounded(NonZeroUsize),
40    /// Do not apply a count limit.
41    Unlimited,
42}
43
44impl CodeGraphCorroborationAnchorLimit {
45    /// Returns the bounded limit, or `None` when corroboration is unlimited.
46    #[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/// Optional operator-owned execution-policy overrides from the workspace manifest.
109#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
110#[serde(rename_all = "camelCase", deny_unknown_fields)]
111pub struct ExecutionPolicyOverrides {
112    /// Optional maximum wall time for one scan or sync pass.
113    pub max_scan_wall_time_ms: Option<u64>,
114    /// Optional maximum time without verified forward progress.
115    pub max_no_progress_time_ms: Option<u64>,
116    /// Optional per-repository `CodeGraph` synchronization wall time.
117    #[serde(rename = "maxCodeGraphSyncWallTimeMsPerRepo")]
118    pub max_codegraph_sync_wall_time_ms_per_repo: Option<u64>,
119    /// Optional maximum worker resident memory.
120    pub max_worker_memory_bytes: Option<u64>,
121    /// Optional cooperative shutdown grace period.
122    pub graceful_termination_ms: Option<u64>,
123    /// Optional watcher inactivity lease.
124    pub watch_idle_timeout_ms: Option<u64>,
125    /// Optional absolute watcher-session lifetime.
126    pub max_watch_session_wall_time_ms: Option<u64>,
127    /// Optional minimum delay between watched sync pass starts.
128    pub min_watch_rescan_interval_ms: Option<u64>,
129    /// Optional maximum retained checkpoint-cache bytes.
130    pub max_checkpoint_cache_bytes: Option<u64>,
131}
132
133/// Effective global execution policy for one workspace operation.
134#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
135#[serde(rename_all = "camelCase")]
136pub struct ExecutionPolicy {
137    /// Maximum wall time for one scan or sync pass.
138    pub max_scan_wall_time_ms: u64,
139    /// Maximum time without verified forward progress.
140    pub max_no_progress_time_ms: u64,
141    /// Maximum wall time for one repository-local `CodeGraph` synchronization.
142    #[serde(rename = "maxCodeGraphSyncWallTimeMsPerRepo")]
143    pub max_codegraph_sync_wall_time_ms_per_repo: u64,
144    /// Maximum resident memory accepted for one worker process.
145    pub max_worker_memory_bytes: u64,
146    /// Cooperative shutdown grace period before forced termination.
147    pub graceful_termination_ms: u64,
148    /// Inactivity lease for a foreground watch session.
149    pub watch_idle_timeout_ms: u64,
150    /// Absolute lifetime for one foreground watch session.
151    pub max_watch_session_wall_time_ms: u64,
152    /// Minimum delay between watched sync pass starts.
153    pub min_watch_rescan_interval_ms: u64,
154    /// Maximum retained historical checkpoint-cache bytes.
155    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    /// Resolves a partial global override and validates the effective relationships.
177    ///
178    /// # Errors
179    ///
180    /// Returns [`InvalidExecutionPolicy`] for zero, unrepresentable, or inconsistent values.
181    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    /// Returns the stable canonical fingerprint of the effective operational policy.
293    #[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    /// Returns a fingerprint that also includes the additive `CodeGraph` corroboration bound.
305    #[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/// Invalid operator-owned execution policy.
326#[derive(Debug, Clone, PartialEq, Eq, Error)]
327pub enum InvalidExecutionPolicy {
328    /// One effective value is zero or cannot be represented internally.
329    #[error("execution policy `{field}` must be positive and representable; received {value}")]
330    InvalidValue {
331        /// Manifest field containing the invalid value.
332        field: &'static str,
333        /// Rejected numeric value.
334        value: u64,
335    },
336    /// One subordinate deadline exceeds its containing deadline.
337    #[error("execution policy `{field}` ({value}) must not exceed `{maximum_field}` ({maximum})")]
338    InvalidRelationship {
339        /// Subordinate manifest field.
340        field: &'static str,
341        /// Supplied subordinate value.
342        value: u64,
343        /// Containing manifest field.
344        maximum_field: &'static str,
345        /// Supplied containing value.
346        maximum: u64,
347    },
348}
349
350/// Observable phase of one supervised scan or synchronization pass.
351#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
352#[serde(rename_all = "snake_case")]
353pub enum JobPhase {
354    /// Workspace configuration and checkout validation.
355    Configuration,
356    /// Filesystem artifact discovery.
357    Discovery,
358    /// Bounded content fingerprinting.
359    Fingerprinting,
360    /// Source-owned extraction and batch encoding.
361    Extraction,
362    /// Candidate graph assembly and linking.
363    GraphAssembly,
364    /// Deterministic community analysis.
365    Communities,
366    /// Atomic snapshot persistence.
367    Publication,
368    /// External repository-local `CodeGraph` synchronization.
369    CodeGraphSync,
370}
371
372/// Resource exhausted by one supervised workspace operation.
373#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
374#[serde(rename_all = "snake_case")]
375pub enum ExecutionResource {
376    /// Absolute wall time.
377    WallTimeMs,
378    /// Time without verified forward progress.
379    NoProgressTimeMs,
380    /// Resident worker memory.
381    WorkerMemoryBytes,
382    /// Deterministic work accounting overflow.
383    WorkUnits,
384    /// The worker terminated without a valid final protocol message.
385    WorkerProcess,
386    /// The worker protocol exceeded its byte limit or was malformed.
387    WorkerProtocolBytes,
388    /// The operator or hosting agent requested cancellation.
389    Cancellation,
390}
391
392/// Observable resource accounting attached to a completed scan or sync pass.
393#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
394#[serde(rename_all = "camelCase")]
395pub struct ExecutionSummary {
396    /// Unique identifier assigned by the supervisor to this pass.
397    pub run_id: String,
398    /// Monotonic wall-clock duration observed by the supervisor.
399    pub duration_ms: u64,
400    /// Largest combined resident set observed for the worker process tree.
401    pub peak_worker_memory_bytes: u64,
402    /// Number of completed units reported through the progress protocol.
403    pub completed_work_units: u64,
404    /// Number of deterministic checkpoint records reused by this pass.
405    pub checkpoint_hits: u64,
406    /// Number of complete deterministic checkpoint records written by this pass.
407    pub checkpoints_written: u64,
408    /// Number of artifact-extractor invocations measured by the worker.
409    pub measured_artifacts: u64,
410    /// Median artifact-extractor duration in milliseconds.
411    pub artifact_duration_p50_ms: u64,
412    /// 95th-percentile artifact-extractor duration in milliseconds.
413    pub artifact_duration_p95_ms: u64,
414    /// 99th-percentile artifact-extractor duration in milliseconds.
415    pub artifact_duration_p99_ms: u64,
416}
417
418/// Typed failure produced when one supervised execution resource is exhausted.
419#[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    /// Stable identifier of the supervised operation.
425    pub run_id: String,
426    /// Phase active when the resource was exhausted.
427    pub phase: JobPhase,
428    /// Exhausted resource.
429    pub resource: ExecutionResource,
430    /// Observed resource value.
431    pub observed: u64,
432    /// Effective maximum.
433    pub maximum: u64,
434    /// Verified work units completed before rejection.
435    pub completed_units: u64,
436}
437
438/// Injectable monotonic time source used by execution watchdogs.
439pub trait MonotonicClock: std::fmt::Debug + Send + Sync {
440    /// Duration since an arbitrary stable origin.
441    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/// Monotonic progress tracker used inside one worker process.
464#[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    /// Starts a tracker for one run at configuration validation.
477    #[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    /// Starts a tracker with an injected monotonic clock for deterministic execution tests.
483    #[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    /// Changes phase after checking the active deadlines.
502    ///
503    /// # Errors
504    ///
505    /// Returns [`ExecutionLimitExceeded`] when wall time or no-progress time is exhausted.
506    pub fn enter_phase(&mut self, phase: JobPhase) -> Result<(), ExecutionLimitExceeded> {
507        self.check_time()?;
508        self.phase = phase;
509        Ok(())
510    }
511
512    /// Charges verified completed work using checked arithmetic.
513    ///
514    /// # Errors
515    ///
516    /// Returns [`ExecutionLimitExceeded`] on arithmetic overflow or an exhausted deadline.
517    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    /// Checks monotonic wall time and time since the last verified progress.
529    ///
530    /// # Errors
531    ///
532    /// Returns [`ExecutionLimitExceeded`] when either effective duration is exhausted.
533    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}