1use std::fmt::Write as _;
2use std::num::NonZeroUsize;
3use std::time::{Duration, Instant};
4
5use code_system_graph_model::stable_id;
6use schemars::JsonSchema;
7use serde::{Deserialize, Serialize};
8use thiserror::Error;
9
10mod tracker;
11
12pub use tracker::{MonotonicClock, ScanJobTracker};
13
14pub const DEFAULT_MAX_SCAN_WALL_TIME_MS: u64 = 21_600_000;
16pub const DEFAULT_MAX_NO_PROGRESS_TIME_MS: u64 = 300_000;
18pub const DEFAULT_MAX_CODEGRAPH_SYNC_WALL_TIME_MS_PER_REPO: u64 = 3_600_000;
20pub const DEFAULT_MAX_CODEGRAPH_CORROBORATION_ANCHORS_PER_REPO: i64 = 50;
22pub const DEFAULT_MAX_WORKER_MEMORY_BYTES: u64 = 17_179_869_184;
24pub const DEFAULT_GRACEFUL_TERMINATION_MS: u64 = 5_000;
26pub const DEFAULT_WATCH_IDLE_TIMEOUT_MS: u64 = 28_800_000;
28pub const DEFAULT_MAX_WATCH_SESSION_WALL_TIME_MS: u64 = 86_400_000;
30pub const DEFAULT_MIN_WATCH_RESCAN_INTERVAL_MS: u64 = 10_000;
32pub const DEFAULT_MAX_CHECKPOINT_CACHE_BYTES: u64 = 10_737_418_240;
34pub const DEFAULT_MAX_EXTRACTION_WORKERS: u64 = 8;
37pub const MAX_EXTRACTION_WORKERS_CEILING: u64 = 256;
39pub const DEFAULT_MAX_EXPLORE_WALL_TIME_MS: u64 = 8_000;
40pub const DEFAULT_MAX_EXPLORE_CODEGRAPH_OPERATIONS: u64 = 8;
41pub const DEFAULT_MAX_EXPLORE_CONCURRENT_CODEGRAPH_PROCESSES: u64 = 2;
42pub const DEFAULT_MAX_EXPLORE_SOURCE_FILES: u64 = 25;
43pub const DEFAULT_MAX_EXPLORE_RESOLVED_SYMBOLS: u64 = 5;
44pub const DEFAULT_MAX_EXPLORE_ANCHORS: u64 = 3;
45pub const DEFAULT_MAX_EXPLORE_NEIGHBORS_PER_DIRECTION: u64 = 8;
46pub const DEFAULT_MAX_EXPLORE_LOCAL_RELATIONSHIPS: u64 = 48;
47pub const DEFAULT_MAX_EXPLORE_FEDERATED_HANDOFFS_PER_ANCHOR: u64 = 10;
48pub const DEFAULT_MAX_EXPLORE_FEDERATED_HANDOFFS: u64 = 30;
49pub const DEFAULT_MAX_EXPLORE_EVIDENCE_LOCATIONS_PER_HANDOFF: u64 = 4;
50pub const DEFAULT_MAX_EXPLORE_SOURCE_MARKDOWN_BYTES: u64 = 262_144;
51pub const DEFAULT_MAX_EXPLORE_ENRICHMENT_BYTES: u64 = 65_536;
52pub const DEFAULT_MAX_AGENT_NEXT_ACTIONS_PER_RESPONSE: u64 = 12;
53pub const DEFAULT_MAX_QUERY_REPOSITORY_SUGGESTIONS: u64 = 20;
54pub const DEFAULT_MAX_MCP_TOOL_RESPONSE_BYTES: u64 = 524_288;
55pub const DEFAULT_MAX_MCP_RESOURCE_ITEMS: u64 = 100;
56pub const DEFAULT_MAX_MCP_RESOURCE_BYTES: u64 = 262_144;
57pub const DEFAULT_MAX_MCP_SCHEMA_CATALOG_BYTES: u64 = 2_097_152;
58pub const MIN_MCP_MARKDOWN_BYTES: u64 = 256;
60
61macro_rules! with_agent_policy_fields {
65 ($consumer:ident) => {
66 $consumer! {
67 max_explore_wall_time_ms: DEFAULT_MAX_EXPLORE_WALL_TIME_MS => "maxExploreWallTimeMs";
68 max_explore_codegraph_operations: DEFAULT_MAX_EXPLORE_CODEGRAPH_OPERATIONS => "maxExploreCodeGraphOperations";
69 max_explore_concurrent_codegraph_processes: DEFAULT_MAX_EXPLORE_CONCURRENT_CODEGRAPH_PROCESSES => "maxExploreConcurrentCodeGraphProcesses";
70 max_explore_source_files: DEFAULT_MAX_EXPLORE_SOURCE_FILES => "maxExploreSourceFiles";
71 max_explore_resolved_symbols: DEFAULT_MAX_EXPLORE_RESOLVED_SYMBOLS => "maxExploreResolvedSymbols";
72 max_explore_anchors: DEFAULT_MAX_EXPLORE_ANCHORS => "maxExploreAnchors";
73 max_explore_neighbors_per_direction: DEFAULT_MAX_EXPLORE_NEIGHBORS_PER_DIRECTION => "maxExploreNeighborsPerDirection";
74 max_explore_local_relationships: DEFAULT_MAX_EXPLORE_LOCAL_RELATIONSHIPS => "maxExploreLocalRelationships";
75 max_explore_federated_handoffs_per_anchor: DEFAULT_MAX_EXPLORE_FEDERATED_HANDOFFS_PER_ANCHOR => "maxExploreFederatedHandoffsPerAnchor";
76 max_explore_federated_handoffs: DEFAULT_MAX_EXPLORE_FEDERATED_HANDOFFS => "maxExploreFederatedHandoffs";
77 max_explore_evidence_locations_per_handoff: DEFAULT_MAX_EXPLORE_EVIDENCE_LOCATIONS_PER_HANDOFF => "maxExploreEvidenceLocationsPerHandoff";
78 max_explore_source_markdown_bytes: DEFAULT_MAX_EXPLORE_SOURCE_MARKDOWN_BYTES => "maxExploreSourceMarkdownBytes";
79 max_explore_enrichment_bytes: DEFAULT_MAX_EXPLORE_ENRICHMENT_BYTES => "maxExploreEnrichmentBytes";
80 max_agent_next_actions_per_response: DEFAULT_MAX_AGENT_NEXT_ACTIONS_PER_RESPONSE => "maxAgentNextActionsPerResponse";
81 max_query_repository_suggestions: DEFAULT_MAX_QUERY_REPOSITORY_SUGGESTIONS => "maxQueryRepositorySuggestions";
82 max_mcp_tool_response_bytes: DEFAULT_MAX_MCP_TOOL_RESPONSE_BYTES => "maxMcpToolResponseBytes";
83 max_mcp_resource_items: DEFAULT_MAX_MCP_RESOURCE_ITEMS => "maxMcpResourceItems";
84 max_mcp_resource_bytes: DEFAULT_MAX_MCP_RESOURCE_BYTES => "maxMcpResourceBytes";
85 max_mcp_schema_catalog_bytes: DEFAULT_MAX_MCP_SCHEMA_CATALOG_BYTES => "maxMcpSchemaCatalogBytes";
86 }
87 };
88}
89
90#[derive(Debug, Clone, Copy, PartialEq, Eq, JsonSchema)]
95pub enum CodeGraphCorroborationAnchorLimit {
96 Bounded(NonZeroUsize),
98 Unlimited,
100}
101
102impl CodeGraphCorroborationAnchorLimit {
103 #[must_use]
105 pub const fn bounded(self) -> Option<NonZeroUsize> {
106 match self {
107 Self::Bounded(limit) => Some(limit),
108 Self::Unlimited => None,
109 }
110 }
111}
112
113impl TryFrom<i64> for CodeGraphCorroborationAnchorLimit {
114 type Error = InvalidExecutionPolicy;
115
116 fn try_from(value: i64) -> Result<Self, Self::Error> {
117 if value == -1 {
118 return Ok(Self::Unlimited);
119 }
120 let limit = usize::try_from(value)
121 .ok()
122 .and_then(NonZeroUsize::new)
123 .ok_or(InvalidExecutionPolicy::InvalidValue {
124 field: "maxCodeGraphCorroborationAnchorsPerRepo",
125 value: value.unsigned_abs(),
126 })?;
127 Ok(Self::Bounded(limit))
128 }
129}
130
131impl Serialize for CodeGraphCorroborationAnchorLimit {
132 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
133 where
134 S: serde::Serializer,
135 {
136 let value = match self {
137 Self::Bounded(limit) => i64::try_from(limit.get()).map_err(|_| {
138 serde::ser::Error::custom("CodeGraph corroboration anchor limit exceeds i64")
139 })?,
140 Self::Unlimited => -1,
141 };
142 serializer.serialize_i64(value)
143 }
144}
145
146impl<'de> Deserialize<'de> for CodeGraphCorroborationAnchorLimit {
147 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
148 where
149 D: serde::Deserializer<'de>,
150 {
151 i64::deserialize(deserializer)?
152 .try_into()
153 .map_err(serde::de::Error::custom)
154 }
155}
156
157impl std::fmt::Display for CodeGraphCorroborationAnchorLimit {
158 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
159 match self {
160 Self::Bounded(limit) => limit.fmt(formatter),
161 Self::Unlimited => formatter.write_str("-1"),
162 }
163 }
164}
165
166#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
168#[serde(rename_all = "camelCase", deny_unknown_fields)]
169pub struct ExecutionPolicyOverrides {
170 pub max_scan_wall_time_ms: Option<u64>,
172 pub max_no_progress_time_ms: Option<u64>,
174 #[serde(rename = "maxCodeGraphSyncWallTimeMsPerRepo")]
176 pub max_codegraph_sync_wall_time_ms_per_repo: Option<u64>,
177 pub max_worker_memory_bytes: Option<u64>,
179 pub graceful_termination_ms: Option<u64>,
181 pub watch_idle_timeout_ms: Option<u64>,
183 pub max_watch_session_wall_time_ms: Option<u64>,
185 pub min_watch_rescan_interval_ms: Option<u64>,
187 pub max_checkpoint_cache_bytes: Option<u64>,
189 pub max_extraction_workers: Option<u64>,
191 #[serde(rename = "maxCodeGraphCorroborationAnchorsPerRepo")]
193 pub max_codegraph_corroboration_anchors_per_repo: Option<i64>,
194 pub max_explore_wall_time_ms: Option<u64>,
196 #[serde(rename = "maxExploreCodeGraphOperations")]
198 pub max_explore_codegraph_operations: Option<u64>,
199 #[serde(rename = "maxExploreConcurrentCodeGraphProcesses")]
201 pub max_explore_concurrent_codegraph_processes: Option<u64>,
202 pub max_explore_source_files: Option<u64>,
204 pub max_explore_resolved_symbols: Option<u64>,
206 pub max_explore_anchors: Option<u64>,
208 pub max_explore_neighbors_per_direction: Option<u64>,
210 pub max_explore_local_relationships: Option<u64>,
212 pub max_explore_federated_handoffs_per_anchor: Option<u64>,
214 pub max_explore_federated_handoffs: Option<u64>,
216 pub max_explore_evidence_locations_per_handoff: Option<u64>,
218 pub max_explore_source_markdown_bytes: Option<u64>,
220 pub max_explore_enrichment_bytes: Option<u64>,
222 pub max_agent_next_actions_per_response: Option<u64>,
224 pub max_query_repository_suggestions: Option<u64>,
226 pub max_mcp_tool_response_bytes: Option<u64>,
228 pub max_mcp_resource_items: Option<u64>,
230 pub max_mcp_resource_bytes: Option<u64>,
232 pub max_mcp_schema_catalog_bytes: Option<u64>,
234}
235
236#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
238#[serde(rename_all = "camelCase")]
239pub struct ExecutionPolicy {
240 pub max_scan_wall_time_ms: u64,
242 pub max_no_progress_time_ms: u64,
244 #[serde(rename = "maxCodeGraphSyncWallTimeMsPerRepo")]
246 pub max_codegraph_sync_wall_time_ms_per_repo: u64,
247 pub max_worker_memory_bytes: u64,
249 pub graceful_termination_ms: u64,
251 pub watch_idle_timeout_ms: u64,
253 pub max_watch_session_wall_time_ms: u64,
255 pub min_watch_rescan_interval_ms: u64,
257 pub max_checkpoint_cache_bytes: u64,
259 pub max_extraction_workers: u64,
261 #[serde(rename = "maxCodeGraphCorroborationAnchorsPerRepo")]
263 #[schemars(with = "i64")]
264 pub max_codegraph_corroboration_anchors_per_repo: CodeGraphCorroborationAnchorLimit,
265 pub max_explore_wall_time_ms: u64,
267 #[serde(rename = "maxExploreCodeGraphOperations")]
269 pub max_explore_codegraph_operations: u64,
270 #[serde(rename = "maxExploreConcurrentCodeGraphProcesses")]
272 pub max_explore_concurrent_codegraph_processes: u64,
273 pub max_explore_source_files: u64,
275 pub max_explore_resolved_symbols: u64,
277 pub max_explore_anchors: u64,
279 pub max_explore_neighbors_per_direction: u64,
281 pub max_explore_local_relationships: u64,
283 pub max_explore_federated_handoffs_per_anchor: u64,
285 pub max_explore_federated_handoffs: u64,
287 pub max_explore_evidence_locations_per_handoff: u64,
289 pub max_explore_source_markdown_bytes: u64,
291 pub max_explore_enrichment_bytes: u64,
293 pub max_agent_next_actions_per_response: u64,
295 pub max_query_repository_suggestions: u64,
297 pub max_mcp_tool_response_bytes: u64,
299 pub max_mcp_resource_items: u64,
301 pub max_mcp_resource_bytes: u64,
303 pub max_mcp_schema_catalog_bytes: u64,
305}
306
307impl Default for ExecutionPolicy {
308 fn default() -> Self {
309 macro_rules! policy_defaults {
310 ($($field:ident: $default:ident => $external:literal;)*) => {
311 Self {
312 max_scan_wall_time_ms: DEFAULT_MAX_SCAN_WALL_TIME_MS,
313 max_no_progress_time_ms: DEFAULT_MAX_NO_PROGRESS_TIME_MS,
314 max_codegraph_sync_wall_time_ms_per_repo:
315 DEFAULT_MAX_CODEGRAPH_SYNC_WALL_TIME_MS_PER_REPO,
316 max_worker_memory_bytes: DEFAULT_MAX_WORKER_MEMORY_BYTES,
317 graceful_termination_ms: DEFAULT_GRACEFUL_TERMINATION_MS,
318 watch_idle_timeout_ms: DEFAULT_WATCH_IDLE_TIMEOUT_MS,
319 max_watch_session_wall_time_ms: DEFAULT_MAX_WATCH_SESSION_WALL_TIME_MS,
320 min_watch_rescan_interval_ms: DEFAULT_MIN_WATCH_RESCAN_INTERVAL_MS,
321 max_checkpoint_cache_bytes: DEFAULT_MAX_CHECKPOINT_CACHE_BYTES,
322 max_extraction_workers: DEFAULT_MAX_EXTRACTION_WORKERS,
323 max_codegraph_corroboration_anchors_per_repo:
324 CodeGraphCorroborationAnchorLimit::try_from(
325 DEFAULT_MAX_CODEGRAPH_CORROBORATION_ANCHORS_PER_REPO,
326 )
327 .expect("the built-in corroboration limit is valid"),
328 $($field: $default,)*
329 }
330 };
331 }
332 with_agent_policy_fields!(policy_defaults)
333 }
334}
335
336impl ExecutionPolicy {
337 pub fn resolve(
343 overrides: Option<&ExecutionPolicyOverrides>,
344 ) -> Result<Self, InvalidExecutionPolicy> {
345 let mut policy = Self::default();
346 if let Some(values) = overrides {
347 macro_rules! apply {
348 ($field:ident) => {
349 if let Some(value) = values.$field {
350 policy.$field = value;
351 }
352 };
353 }
354 apply!(max_scan_wall_time_ms);
355 apply!(max_no_progress_time_ms);
356 apply!(max_codegraph_sync_wall_time_ms_per_repo);
357 apply!(max_worker_memory_bytes);
358 apply!(graceful_termination_ms);
359 apply!(watch_idle_timeout_ms);
360 apply!(max_watch_session_wall_time_ms);
361 apply!(min_watch_rescan_interval_ms);
362 apply!(max_checkpoint_cache_bytes);
363 apply!(max_extraction_workers);
364 if let Some(value) = values.max_codegraph_corroboration_anchors_per_repo {
365 policy.max_codegraph_corroboration_anchors_per_repo = value.try_into()?;
366 }
367 macro_rules! apply_agent_overrides {
368 ($($field:ident: $default:ident => $external:literal;)*) => {
369 $(apply!($field);)*
370 };
371 }
372 with_agent_policy_fields!(apply_agent_overrides);
373 }
374 policy.validate()?;
375 Ok(policy)
376 }
377
378 fn validate(&self) -> Result<(), InvalidExecutionPolicy> {
379 self.validate_scalar_values()?;
380 self.validate_mcp_minimums()?;
381 self.validate_scan_relationships()?;
382 self.validate_explore_relationships()
383 }
384
385 fn validate_mcp_minimums(&self) -> Result<(), InvalidExecutionPolicy> {
386 for (field, value) in [
387 ("maxMcpToolResponseBytes", self.max_mcp_tool_response_bytes),
388 ("maxMcpResourceBytes", self.max_mcp_resource_bytes),
389 (
390 "maxMcpSchemaCatalogBytes",
391 self.max_mcp_schema_catalog_bytes,
392 ),
393 ] {
394 if value < MIN_MCP_MARKDOWN_BYTES {
395 return Err(InvalidExecutionPolicy::BelowMinimum {
396 field,
397 value,
398 minimum: MIN_MCP_MARKDOWN_BYTES,
399 });
400 }
401 }
402 Ok(())
403 }
404
405 fn validate_scalar_values(&self) -> Result<(), InvalidExecutionPolicy> {
406 for (field, value) in self
407 .scan_canonical_values()
408 .into_iter()
409 .chain(self.agent_canonical_values())
410 {
411 let invalid_bytes = field.ends_with("Bytes") && usize::try_from(value).is_err();
412 let invalid_count = !field.ends_with("Ms") && usize::try_from(value).is_err();
413 let invalid_sqlite_quota =
414 field == "maxCheckpointCacheBytes" && i64::try_from(value).is_err();
415 let invalid_deadline = field.ends_with("Ms")
416 && Instant::now()
417 .checked_add(Duration::from_millis(value))
418 .is_none();
419 if value == 0
420 || invalid_bytes
421 || invalid_count
422 || invalid_sqlite_quota
423 || invalid_deadline
424 {
425 return Err(InvalidExecutionPolicy::InvalidValue { field, value });
426 }
427 }
428 if self.max_extraction_workers == 0
429 || self.max_extraction_workers > MAX_EXTRACTION_WORKERS_CEILING
430 {
431 return Err(InvalidExecutionPolicy::InvalidValue {
432 field: "maxExtractionWorkers",
433 value: self.max_extraction_workers,
434 });
435 }
436 Ok(())
437 }
438
439 #[must_use]
441 pub fn effective_extraction_workers(&self) -> usize {
442 let available = std::thread::available_parallelism().map_or(1, NonZeroUsize::get);
443 usize::try_from(self.max_extraction_workers)
444 .unwrap_or(usize::MAX)
445 .clamp(1, available.max(1))
446 }
447
448 fn validate_scan_relationships(&self) -> Result<(), InvalidExecutionPolicy> {
449 Self::require_not_greater(
450 "maxNoProgressTimeMs",
451 self.max_no_progress_time_ms,
452 "maxScanWallTimeMs",
453 self.max_scan_wall_time_ms,
454 )?;
455 Self::require_not_greater(
456 "maxCodeGraphSyncWallTimeMsPerRepo",
457 self.max_codegraph_sync_wall_time_ms_per_repo,
458 "maxScanWallTimeMs",
459 self.max_scan_wall_time_ms,
460 )?;
461 Self::require_not_greater(
462 "gracefulTerminationMs",
463 self.graceful_termination_ms,
464 "maxNoProgressTimeMs",
465 self.max_no_progress_time_ms,
466 )?;
467 Self::require_not_greater(
468 "watchIdleTimeoutMs",
469 self.watch_idle_timeout_ms,
470 "maxWatchSessionWallTimeMs",
471 self.max_watch_session_wall_time_ms,
472 )?;
473 Self::require_not_greater(
474 "minWatchRescanIntervalMs",
475 self.min_watch_rescan_interval_ms,
476 "watchIdleTimeoutMs",
477 self.watch_idle_timeout_ms,
478 )
479 }
480
481 fn validate_explore_relationships(&self) -> Result<(), InvalidExecutionPolicy> {
482 Self::require_not_greater(
483 "maxExploreAnchors",
484 self.max_explore_anchors,
485 "maxExploreResolvedSymbols",
486 self.max_explore_resolved_symbols,
487 )?;
488 Self::require_not_greater(
489 "maxExploreConcurrentCodeGraphProcesses",
490 self.max_explore_concurrent_codegraph_processes,
491 "maxExploreCodeGraphOperations",
492 self.max_explore_codegraph_operations,
493 )?;
494 let local_ceiling = self
495 .max_explore_anchors
496 .checked_mul(2)
497 .and_then(|value| value.checked_mul(self.max_explore_neighbors_per_direction))
498 .ok_or(InvalidExecutionPolicy::ArithmeticOverflow {
499 expression: "maxExploreAnchors × 2 × maxExploreNeighborsPerDirection",
500 })?;
501 Self::require_not_greater(
502 "maxExploreLocalRelationships",
503 self.max_explore_local_relationships,
504 "anchor neighbor capacity",
505 local_ceiling,
506 )?;
507 let handoff_ceiling = self
508 .max_explore_anchors
509 .checked_mul(self.max_explore_federated_handoffs_per_anchor)
510 .ok_or(InvalidExecutionPolicy::ArithmeticOverflow {
511 expression: "maxExploreAnchors × maxExploreFederatedHandoffsPerAnchor",
512 })?;
513 Self::require_not_greater(
514 "maxExploreFederatedHandoffs",
515 self.max_explore_federated_handoffs,
516 "anchor handoff capacity",
517 handoff_ceiling,
518 )?;
519 Self::require_not_greater(
520 "maxExploreSourceMarkdownBytes",
521 self.max_explore_source_markdown_bytes,
522 "maxMcpToolResponseBytes",
523 self.max_mcp_tool_response_bytes,
524 )?;
525 Self::require_not_greater(
526 "maxExploreEnrichmentBytes",
527 self.max_explore_enrichment_bytes,
528 "maxMcpToolResponseBytes",
529 self.max_mcp_tool_response_bytes,
530 )
531 }
532
533 fn require_not_greater(
534 field: &'static str,
535 value: u64,
536 maximum_field: &'static str,
537 maximum: u64,
538 ) -> Result<(), InvalidExecutionPolicy> {
539 if value > maximum {
540 return Err(InvalidExecutionPolicy::InvalidRelationship {
541 field,
542 value,
543 maximum_field,
544 maximum,
545 });
546 }
547 Ok(())
548 }
549
550 fn scan_canonical_values(&self) -> [(&'static str, u64); 9] {
551 [
552 ("maxScanWallTimeMs", self.max_scan_wall_time_ms),
553 ("maxNoProgressTimeMs", self.max_no_progress_time_ms),
554 (
555 "maxCodeGraphSyncWallTimeMsPerRepo",
556 self.max_codegraph_sync_wall_time_ms_per_repo,
557 ),
558 ("maxWorkerMemoryBytes", self.max_worker_memory_bytes),
559 ("gracefulTerminationMs", self.graceful_termination_ms),
560 ("watchIdleTimeoutMs", self.watch_idle_timeout_ms),
561 (
562 "maxWatchSessionWallTimeMs",
563 self.max_watch_session_wall_time_ms,
564 ),
565 (
566 "minWatchRescanIntervalMs",
567 self.min_watch_rescan_interval_ms,
568 ),
569 ("maxCheckpointCacheBytes", self.max_checkpoint_cache_bytes),
570 ]
571 }
572
573 fn agent_canonical_values(&self) -> Vec<(&'static str, u64)> {
574 macro_rules! canonical_agent_values {
575 ($($field:ident: $default:ident => $external:literal;)*) => {
576 vec![$(($external, self.$field),)*]
577 };
578 }
579 with_agent_policy_fields!(canonical_agent_values)
580 }
581
582 #[must_use]
584 pub fn scan_fingerprint(&self) -> String {
585 let mut canonical = self
586 .scan_canonical_values()
587 .into_iter()
588 .map(|(name, value)| format!("{name}={value}"))
589 .collect::<Vec<_>>()
590 .join(";");
591 write!(
592 canonical,
593 ";maxCodeGraphCorroborationAnchorsPerRepo={}",
594 self.max_codegraph_corroboration_anchors_per_repo
595 )
596 .expect("writing to a String cannot fail");
597 stable_id("execution-policy", &canonical)
598 }
599
600 #[must_use]
602 pub fn fingerprint_with_codegraph_limit(
603 &self,
604 limit: CodeGraphCorroborationAnchorLimit,
605 ) -> String {
606 let mut canonical = self
607 .scan_canonical_values()
608 .into_iter()
609 .map(|(name, value)| format!("{name}={value}"))
610 .collect::<Vec<_>>()
611 .join(";");
612 write!(
613 canonical,
614 ";maxCodeGraphCorroborationAnchorsPerRepo={limit}"
615 )
616 .expect("writing to a String cannot fail");
617 stable_id("execution-policy", &canonical)
618 }
619
620 #[must_use]
622 pub fn agent_delivery_fingerprint(&self) -> String {
623 let mut canonical = String::new();
624 for (index, (name, value)) in self.agent_canonical_values().into_iter().enumerate() {
625 if index > 0 {
626 canonical.push(';');
627 }
628 write!(canonical, "{name}={value}").expect("writing to a String cannot fail");
629 }
630 stable_id("agent-delivery-policy", &canonical)
631 }
632}
633
634#[derive(Debug, Clone, PartialEq, Eq, Error)]
636pub enum InvalidExecutionPolicy {
637 #[error("execution policy `{field}` must be positive and representable; received {value}")]
639 InvalidValue {
640 field: &'static str,
642 value: u64,
644 },
645 #[error("execution policy `{field}` must be at least {minimum}; received {value}")]
647 BelowMinimum {
648 field: &'static str,
650 value: u64,
652 minimum: u64,
654 },
655 #[error("execution policy `{field}` ({value}) must not exceed `{maximum_field}` ({maximum})")]
657 InvalidRelationship {
658 field: &'static str,
660 value: u64,
662 maximum_field: &'static str,
664 maximum: u64,
666 },
667 #[error("execution policy arithmetic overflow in `{expression}`")]
669 ArithmeticOverflow {
670 expression: &'static str,
672 },
673}
674
675#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
677#[serde(rename_all = "snake_case")]
678pub enum JobPhase {
679 Configuration,
681 Discovery,
683 Fingerprinting,
685 Extraction,
687 GraphAssembly,
689 Communities,
691 Publication,
693 CodeGraphSync,
695}
696
697#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
699#[serde(rename_all = "snake_case")]
700pub enum ExecutionResource {
701 WallTimeMs,
703 NoProgressTimeMs,
705 WorkerMemoryBytes,
707 WorkUnits,
709 WorkerProcess,
711 WorkerProtocolBytes,
713 Cancellation,
715}
716
717#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
719#[serde(rename_all = "camelCase")]
720pub struct ExecutionSummary {
721 pub run_id: String,
723 pub duration_ms: u64,
725 pub peak_worker_memory_bytes: u64,
727 pub completed_work_units: u64,
729 pub checkpoint_hits: u64,
731 pub checkpoints_written: u64,
733 pub measured_artifacts: u64,
735 pub artifact_duration_p50_ms: u64,
737 pub artifact_duration_p95_ms: u64,
739 pub artifact_duration_p99_ms: u64,
741 pub stat_cache_hits: u64,
743 pub content_bytes_read: u64,
745 pub published_rows: u64,
747 pub extraction_workers: u64,
749 pub phases: Vec<PhaseTelemetry>,
751}
752
753#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
755#[serde(rename_all = "camelCase")]
756pub struct PhaseTelemetry {
757 pub phase: JobPhase,
759 pub duration_ms: u64,
761 pub resident_memory_bytes: u64,
763}
764
765#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema, Error)]
767#[error(
768 "execution `{run_id}` exceeded {resource:?} during {phase:?}: observed {observed}, maximum {maximum}, completed {completed_units} units"
769)]
770pub struct ExecutionLimitExceeded {
771 pub run_id: String,
773 pub phase: JobPhase,
775 pub resource: ExecutionResource,
777 pub observed: u64,
779 pub maximum: u64,
781 pub completed_units: u64,
783}
784
785#[cfg(test)]
786mod tests {
787 use super::*;
788
789 #[test]
790 fn defaults_should_be_generous_and_finite() {
791 let policy = ExecutionPolicy::default();
792
793 assert_eq!(policy.max_scan_wall_time_ms, 21_600_000);
794 assert_eq!(
795 CodeGraphCorroborationAnchorLimit::try_from(
796 DEFAULT_MAX_CODEGRAPH_CORROBORATION_ANCHORS_PER_REPO
797 )
798 .expect("default anchor limit")
799 .bounded()
800 .map(NonZeroUsize::get),
801 Some(50)
802 );
803 assert_eq!(policy.max_worker_memory_bytes, 17_179_869_184);
804 assert_eq!(policy.max_checkpoint_cache_bytes, 10_737_418_240);
805 }
806
807 #[test]
808 fn partial_override_should_preserve_other_defaults() {
809 let policy = ExecutionPolicy::resolve(Some(&ExecutionPolicyOverrides {
810 max_scan_wall_time_ms: Some(28_800_000),
811 ..ExecutionPolicyOverrides::default()
812 }))
813 .expect("valid override");
814
815 assert_eq!(policy.max_scan_wall_time_ms, 28_800_000);
816 assert_eq!(policy.max_no_progress_time_ms, 300_000);
817 }
818
819 #[test]
820 fn zero_should_be_rejected() {
821 let error = ExecutionPolicy::resolve(Some(&ExecutionPolicyOverrides {
822 max_worker_memory_bytes: Some(0),
823 ..ExecutionPolicyOverrides::default()
824 }))
825 .expect_err("zero must fail");
826
827 assert!(matches!(
828 error,
829 InvalidExecutionPolicy::InvalidValue {
830 field: "maxWorkerMemoryBytes",
831 value: 0
832 }
833 ));
834 }
835
836 #[test]
837 fn corroboration_anchor_limit_should_accept_positive_or_unlimited() {
838 let bounded =
839 CodeGraphCorroborationAnchorLimit::try_from(12).expect("positive anchor limit");
840 let unlimited =
841 CodeGraphCorroborationAnchorLimit::try_from(-1).expect("unlimited anchor limit");
842
843 assert_eq!(bounded.bounded().map(NonZeroUsize::get), Some(12));
844 assert_eq!(unlimited.bounded(), None);
845 assert_ne!(
846 ExecutionPolicy::default().fingerprint_with_codegraph_limit(bounded),
847 ExecutionPolicy::default().fingerprint_with_codegraph_limit(unlimited)
848 );
849 assert_eq!(
850 serde_json::to_value(bounded).expect("bounded limit serializes"),
851 serde_json::json!(12)
852 );
853 assert_eq!(
854 serde_json::to_value(unlimited).expect("unlimited limit serializes"),
855 serde_json::json!(-1)
856 );
857 }
858
859 #[test]
860 fn corroboration_anchor_limit_should_reject_zero_and_values_below_sentinel() {
861 for value in [0, -2] {
862 let error = CodeGraphCorroborationAnchorLimit::try_from(value)
863 .expect_err("invalid anchor limit");
864
865 assert!(matches!(
866 error,
867 InvalidExecutionPolicy::InvalidValue {
868 field: "maxCodeGraphCorroborationAnchorsPerRepo",
869 value: observed
870 } if observed == value.unsigned_abs()
871 ));
872 }
873 }
874
875 #[test]
876 fn technically_unrepresentable_values_should_be_rejected() {
877 let quota = ExecutionPolicy::resolve(Some(&ExecutionPolicyOverrides {
878 max_checkpoint_cache_bytes: Some(u64::MAX),
879 ..ExecutionPolicyOverrides::default()
880 }))
881 .expect_err("SQLite quota overflow must fail");
882
883 assert!(matches!(quota, InvalidExecutionPolicy::InvalidValue { .. }));
884 }
885
886 #[test]
887 fn mcp_markdown_budgets_should_enforce_the_control_block_minimum() {
888 for overrides in [
889 ExecutionPolicyOverrides {
890 max_mcp_tool_response_bytes: Some(MIN_MCP_MARKDOWN_BYTES - 1),
891 ..ExecutionPolicyOverrides::default()
892 },
893 ExecutionPolicyOverrides {
894 max_mcp_resource_bytes: Some(MIN_MCP_MARKDOWN_BYTES - 1),
895 ..ExecutionPolicyOverrides::default()
896 },
897 ExecutionPolicyOverrides {
898 max_mcp_schema_catalog_bytes: Some(MIN_MCP_MARKDOWN_BYTES - 1),
899 ..ExecutionPolicyOverrides::default()
900 },
901 ] {
902 assert!(matches!(
903 ExecutionPolicy::resolve(Some(&overrides)),
904 Err(InvalidExecutionPolicy::BelowMinimum {
905 minimum: MIN_MCP_MARKDOWN_BYTES,
906 ..
907 })
908 ));
909 }
910
911 let minimum = ExecutionPolicy::resolve(Some(&ExecutionPolicyOverrides {
912 max_mcp_tool_response_bytes: Some(MIN_MCP_MARKDOWN_BYTES),
913 max_mcp_resource_bytes: Some(MIN_MCP_MARKDOWN_BYTES),
914 max_mcp_schema_catalog_bytes: Some(MIN_MCP_MARKDOWN_BYTES),
915 max_explore_source_markdown_bytes: Some(MIN_MCP_MARKDOWN_BYTES),
916 max_explore_enrichment_bytes: Some(MIN_MCP_MARKDOWN_BYTES),
917 ..ExecutionPolicyOverrides::default()
918 }));
919 assert!(minimum.is_ok());
920 }
921
922 #[test]
923 fn subordinate_deadline_should_not_exceed_scan_deadline() {
924 let error = ExecutionPolicy::resolve(Some(&ExecutionPolicyOverrides {
925 max_scan_wall_time_ms: Some(1_000),
926 max_no_progress_time_ms: Some(1_001),
927 max_codegraph_sync_wall_time_ms_per_repo: Some(1_000),
928 graceful_termination_ms: Some(500),
929 ..ExecutionPolicyOverrides::default()
930 }))
931 .expect_err("relationship must fail");
932
933 assert!(matches!(
934 error,
935 InvalidExecutionPolicy::InvalidRelationship {
936 field: "maxNoProgressTimeMs",
937 ..
938 }
939 ));
940 }
941
942 #[test]
943 fn fingerprint_should_ignore_yaml_field_order() {
944 let first = ExecutionPolicy::default();
945 let second = ExecutionPolicy::resolve(Some(&ExecutionPolicyOverrides::default()))
946 .expect("defaults valid");
947
948 assert_eq!(first.scan_fingerprint(), second.scan_fingerprint());
949 }
950
951 #[test]
952 fn agent_delivery_limits_should_not_change_scan_fingerprint() {
953 let baseline = ExecutionPolicy::default();
954 let changed = ExecutionPolicy::resolve(Some(&ExecutionPolicyOverrides {
955 max_mcp_tool_response_bytes: Some(600_000),
956 max_explore_source_markdown_bytes: Some(300_000),
957 ..ExecutionPolicyOverrides::default()
958 }))
959 .expect("agent-only override is valid");
960
961 assert_eq!(baseline.scan_fingerprint(), changed.scan_fingerprint());
962 assert_ne!(
963 baseline.agent_delivery_fingerprint(),
964 changed.agent_delivery_fingerprint()
965 );
966 }
967
968 #[test]
969 fn explore_capacity_relationships_should_be_checked() {
970 for overrides in [
971 ExecutionPolicyOverrides {
972 max_explore_anchors: Some(6),
973 ..ExecutionPolicyOverrides::default()
974 },
975 ExecutionPolicyOverrides {
976 max_explore_concurrent_codegraph_processes: Some(9),
977 ..ExecutionPolicyOverrides::default()
978 },
979 ExecutionPolicyOverrides {
980 max_explore_local_relationships: Some(49),
981 ..ExecutionPolicyOverrides::default()
982 },
983 ExecutionPolicyOverrides {
984 max_explore_federated_handoffs: Some(31),
985 ..ExecutionPolicyOverrides::default()
986 },
987 ExecutionPolicyOverrides {
988 max_explore_source_markdown_bytes: Some(524_289),
989 ..ExecutionPolicyOverrides::default()
990 },
991 ] {
992 assert!(matches!(
993 ExecutionPolicy::resolve(Some(&overrides)),
994 Err(InvalidExecutionPolicy::InvalidRelationship { .. })
995 ));
996 }
997 }
998}