Skip to main content

vvv_engine/capabilities/
validation.rs

1//! Explicit check commands and evidence tied to an applied plan's source versions.
2pub(crate) mod baseline;
3mod process;
4use crate::graph::query_snapshot::QuerySnapshot;
5use crate::{
6    ContentId, Engine, EngineError, PlanId, PlanReceipt, RelPath, SnapshotId, SourceVersion,
7};
8use serde::{Deserialize, Serialize};
9use std::{
10    collections::BTreeMap,
11    time::{Duration, Instant},
12};
13
14#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
15#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
16#[serde(deny_unknown_fields)]
17pub struct CheckCommand {
18    /// A caller-defined label, such as formatting, compilation, or unit tests.
19    pub name: String,
20    /// Executed directly, without implicit shell parsing.
21    pub program: String,
22    #[serde(default)]
23    pub args: Vec<String>,
24}
25#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
26#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
27#[serde(default, deny_unknown_fields)]
28pub struct ValidationBudget {
29    /// Deadline for the command batch, including between-command captures.
30    /// Initial and final input capture and process cleanup are outside this limit.
31    #[cfg_attr(feature = "schema", schemars(range(min = 1, max = 300000)))]
32    pub timeout_ms: u64,
33    #[cfg_attr(feature = "schema", schemars(range(min = 4096, max = 1048576)))]
34    pub max_bytes: usize,
35}
36impl Default for ValidationBudget {
37    fn default() -> Self {
38        Self {
39            timeout_ms: 60_000,
40            max_bytes: 16_384,
41        }
42    }
43}
44impl ValidationBudget {
45    fn validate(&self) -> Result<(), EngineError> {
46        if !(1..=300_000).contains(&self.timeout_ms)
47            || !(4096..=1_048_576).contains(&self.max_bytes)
48        {
49            return Err(EngineError::InvalidBudget);
50        }
51        Ok(())
52    }
53}
54#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
55#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
56#[serde(deny_unknown_fields)]
57pub struct ValidatePlanQuery {
58    pub plan_id: PlanId,
59    #[cfg_attr(feature = "schema", schemars(length(min = 1, max = 4)))]
60    pub checks: Vec<CheckCommand>,
61    /// Explicit hidden/ignored inputs, in addition to workspace-visible files.
62    #[serde(default)]
63    #[cfg_attr(feature = "schema", schemars(length(max = 32)))]
64    pub extra_inputs: Vec<RelPath>,
65    #[serde(default)]
66    pub budget: ValidationBudget,
67}
68#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
69#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
70pub struct ValidationReport {
71    pub plan_id: PlanId,
72    pub history_id: u64,
73    /// Monotonically increasing within this retained plan.
74    pub run: u64,
75    pub sources: Vec<SourceVersion>,
76    pub before: SnapshotId,
77    pub after: Option<SnapshotId>,
78    pub input_files: usize,
79    pub extra_inputs: Vec<RelPath>,
80    pub source_state: ValidationSourceState,
81    /// True only when every command succeeded and observed inputs stayed unchanged.
82    pub passed: bool,
83    pub checks: Vec<CheckResult>,
84}
85#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
86#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
87#[serde(rename_all = "snake_case")]
88pub enum ValidationSourceState {
89    Unchanged,
90    Changed,
91    Unavailable,
92}
93#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
94#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
95#[serde(rename_all = "snake_case")]
96pub enum CheckOutcome {
97    NotRun,
98    Passed,
99    Failed,
100    TimedOut,
101    Cancelled,
102    Error,
103}
104#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
105#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
106pub struct CheckResult {
107    pub command: CheckCommand,
108    pub outcome: CheckOutcome,
109    pub exit_code: Option<i32>,
110    pub duration_ms: u64,
111    pub stdout: CheckOutput,
112    pub stderr: CheckOutput,
113    pub failure: Option<CheckFailure>,
114}
115#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
116#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
117pub struct CheckOutput {
118    pub text: String,
119    pub bytes_seen: u64,
120    pub truncated: bool,
121    /// False when capture stopped before EOF or a read failed.
122    pub complete: bool,
123}
124#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
125#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
126pub struct CheckFailure {
127    pub operation: CheckOperation,
128    pub os_code: Option<i32>,
129}
130#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
131#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
132#[serde(rename_all = "snake_case")]
133pub enum CheckOperation {
134    Spawn,
135    Capture,
136    Wait,
137    Terminate,
138}
139#[cfg(any(
140    windows,
141    target_os = "linux",
142    target_os = "android",
143    target_os = "macos",
144    target_os = "ios",
145    target_os = "freebsd",
146    target_os = "dragonfly",
147    target_os = "netbsd"
148))]
149impl CheckFailure {
150    fn io(operation: CheckOperation, error: std::io::Error) -> Self {
151        Self {
152            operation,
153            os_code: error.raw_os_error(),
154        }
155    }
156}
157impl CheckResult {
158    fn pending(command: CheckCommand) -> Self {
159        Self {
160            command,
161            outcome: CheckOutcome::NotRun,
162            exit_code: None,
163            duration_ms: 0,
164            stdout: CheckOutput::default(),
165            stderr: CheckOutput::default(),
166            failure: None,
167        }
168    }
169}
170impl ValidatePlanQuery {
171    pub(crate) fn available(engine: &Engine) -> bool {
172        process::CheckProcess::supported() && engine.workspace().execution_root().is_some()
173    }
174    pub fn execute(self, engine: &Engine) -> Result<ValidationReport, EngineError> {
175        let _operation = engine.operation();
176        self.execute_in(engine)
177    }
178    pub(crate) fn execute_in(self, engine: &Engine) -> Result<ValidationReport, EngineError> {
179        self.validate()?;
180        let root = engine
181            .workspace()
182            .execution_root()
183            .ok_or(EngineError::ValidationUnavailable)?;
184        if !process::CheckProcess::supported() {
185            return Err(EngineError::ValidationUnavailable);
186        }
187        let (receipt, baseline, run) = engine.plans().validation(&self.plan_id, Instant::now())?;
188        baseline.validate(engine).map_err(|error| match error {
189            EngineError::StaleQuery | EngineError::StaleSource { .. } => EngineError::StalePlan,
190            other => other,
191        })?;
192        let before = ValidationInputs::capture(engine, &self.extra_inputs, &baseline)?;
193        // Capture again before launching to reject inconsistent reads during capture.
194        if !before.matches_baseline(&baseline)
195            || before != ValidationInputs::capture(engine, &self.extra_inputs, &baseline)?
196        {
197            return Err(EngineError::StalePlan);
198        }
199        let mut report = ValidationReport::new(
200            receipt,
201            run,
202            &before,
203            self.extra_inputs.clone(),
204            self.checks,
205        );
206        report.preflight(self.budget.max_bytes)?;
207        engine
208            .plans()
209            .reserve_validation(&self.plan_id, self.budget.max_bytes)?;
210        let started = Instant::now();
211        let deadline = started + Duration::from_millis(self.budget.timeout_ms);
212        let limit = self.budget.max_bytes / (report.checks.len() * 16);
213        for check in &mut report.checks {
214            if engine.cancellation().is_some_and(|c| c.is_cancelled()) {
215                check.outcome = CheckOutcome::Cancelled;
216                break;
217            }
218            if Instant::now() >= deadline {
219                check.outcome = CheckOutcome::TimedOut;
220                break;
221            }
222            // A prior check must not change the inputs seen by the next one.
223            if ValidationInputs::capture(engine, &self.extra_inputs, &baseline)
224                .is_ok_and(|current| current == before)
225            {
226                *check = process::CheckProcess::run(
227                    &check.command,
228                    root,
229                    deadline,
230                    limit,
231                    engine.cancellation(),
232                );
233            } else {
234                break;
235            }
236        }
237        // Cancellation must not discard the evidence of commands that already ran.
238        let observed = engine.without_cancellation();
239        match ValidationInputs::capture(&observed, &self.extra_inputs, &baseline) {
240            Ok(after) => {
241                report.source_state = if after == before {
242                    ValidationSourceState::Unchanged
243                } else {
244                    ValidationSourceState::Changed
245                };
246                report.after = Some(after.identity());
247            }
248            Err(_) => report.source_state = ValidationSourceState::Unavailable,
249        }
250        report.passed = report.source_state == ValidationSourceState::Unchanged
251            && report
252                .checks
253                .iter()
254                .all(|check| check.outcome == CheckOutcome::Passed);
255        report.fit(self.budget.max_bytes);
256        // External checks can create files; never leave a trusted graph after them.
257        engine.touched();
258        engine
259            .plans()
260            .record_validation(&self.plan_id, report.clone());
261        Ok(report)
262    }
263    fn validate(&self) -> Result<(), EngineError> {
264        self.budget.validate()?;
265        if self.checks.is_empty() || self.checks.len() > 4 || self.extra_inputs.len() > 32 {
266            return Err(EngineError::InvalidValidation);
267        }
268        let mut bytes = 0usize;
269        for check in &self.checks {
270            if check.name.is_empty()
271                || check.name.len() > 128
272                || check.program.is_empty()
273                || check.program.contains('\0')
274                || check.args.len() > 64
275                || check.args.iter().any(|arg| arg.contains('\0'))
276            {
277                return Err(EngineError::InvalidValidation);
278            }
279            bytes = bytes
280                .saturating_add(check.name.len())
281                .saturating_add(check.program.len())
282                .saturating_add(check.args.iter().map(String::len).sum::<usize>());
283        }
284        if bytes > 8192 {
285            return Err(EngineError::InvalidValidation);
286        }
287        for path in &self.extra_inputs {
288            if path.as_os_str().is_empty()
289                || path.is_absolute()
290                || path
291                    .components()
292                    .any(|c| !matches!(c, std::path::Component::Normal(_)))
293            {
294                return Err(EngineError::InvalidValidation);
295            }
296        }
297        Ok(())
298    }
299}
300#[derive(Debug, PartialEq, Eq, Serialize)]
301struct ValidationInputs {
302    files: BTreeMap<RelPath, ContentId>,
303    #[serde(skip_serializing_if = "Option::is_none")]
304    moves: Option<baseline::MoveObservation>,
305}
306impl ValidationInputs {
307    fn capture(
308        engine: &Engine,
309        extra: &[RelPath],
310        baseline: &baseline::ValidationBaseline,
311    ) -> Result<Self, EngineError> {
312        let (_, current) = QuerySnapshot::capture(engine)?;
313        let mut files = BTreeMap::new();
314        for path in engine.workspace().files()? {
315            engine.check_read()?;
316            let relative: RelPath = engine.workspace().relative(&path).into();
317            if relative
318                .components()
319                .next()
320                .is_some_and(|c| c.as_os_str() == ".vvv")
321            {
322                continue;
323            }
324            let bytes = engine.workspace().vfs().read_bytes(&path)?;
325            files.insert(relative, ContentId::of_bytes(&bytes));
326        }
327        for path in extra
328            .iter()
329            .chain(baseline.inputs().keys())
330            .chain(current.inputs().keys())
331        {
332            engine.check_read()?;
333            let bytes = engine
334                .workspace()
335                .vfs()
336                .read_bytes(&engine.workspace().absolute(path))?;
337            let content = ContentId::of_bytes(&bytes);
338            if files.get(path).is_some_and(|previous| previous != &content) {
339                return Err(EngineError::StalePlan);
340            }
341            files.insert(path.clone(), content);
342        }
343        Ok(Self {
344            files,
345            moves: baseline.observe(engine)?,
346        })
347    }
348    fn matches_baseline(&self, baseline: &baseline::ValidationBaseline) -> bool {
349        baseline
350            .inputs()
351            .iter()
352            .all(|(path, content)| self.files.get(path) == Some(content))
353            && baseline.matches(self.moves.as_ref())
354    }
355    fn identity(&self) -> SnapshotId {
356        ContentId::of(&serde_json::to_string(self).expect("inputs serialize")).into()
357    }
358}
359impl ValidationReport {
360    fn new(
361        receipt: PlanReceipt,
362        run: u64,
363        inputs: &ValidationInputs,
364        extra_inputs: Vec<RelPath>,
365        checks: Vec<CheckCommand>,
366    ) -> Self {
367        Self {
368            plan_id: receipt.plan_id,
369            history_id: receipt.history_id,
370            run,
371            sources: receipt.files,
372            before: inputs.identity(),
373            after: None,
374            input_files: inputs.files.len(),
375            extra_inputs,
376            source_state: ValidationSourceState::Unavailable,
377            passed: false,
378            checks: checks.into_iter().map(CheckResult::pending).collect(),
379        }
380    }
381    fn preflight(&self, max_bytes: usize) -> Result<(), EngineError> {
382        // Reserve fixed metadata growth (exit codes, timings, failure data and after id).
383        let required_bytes = serde_json::to_vec(self)
384            .expect("report serializes")
385            .len()
386            .saturating_add(1024);
387        if required_bytes > max_bytes {
388            return Err(EngineError::OutputLimit {
389                max_bytes,
390                required_bytes,
391            });
392        }
393        Ok(())
394    }
395    fn fit(&mut self, max_bytes: usize) {
396        while serde_json::to_vec(self).expect("report serializes").len() > max_bytes {
397            let output = self
398                .checks
399                .iter_mut()
400                .flat_map(|check| [&mut check.stdout, &mut check.stderr])
401                .max_by_key(|output| output.text.len())
402                .expect("nonempty checks");
403            assert!(!output.text.is_empty(), "preflight reserved metadata");
404            let mut end = output.text.len() / 2;
405            while !output.text.is_char_boundary(end) {
406                end -= 1;
407            }
408            output.text.truncate(end);
409            output.truncated = true;
410        }
411    }
412}
413impl crate::report::Document {
414    pub(crate) fn validation(report: &ValidationReport) -> Self {
415        use crate::protocol::display::{Line, Role};
416        let mut doc = Self::new();
417        doc.body([Line::single(
418            Role::Strong,
419            if report.passed {
420                "Validation passed"
421            } else {
422                "Validation did not pass"
423            },
424        )]);
425        for check in &report.checks {
426            let status = match check.outcome {
427                CheckOutcome::NotRun => "not run",
428                CheckOutcome::Passed => "passed",
429                CheckOutcome::Failed => "failed",
430                CheckOutcome::TimedOut => "timed out",
431                CheckOutcome::Cancelled => "cancelled",
432                CheckOutcome::Error => "could not complete",
433            };
434            doc.body([Line::single(Role::Plain, &check.command.name)
435                .and(Role::Plain, format!(": {status}"))]);
436            doc.body(
437                check
438                    .stdout
439                    .text
440                    .lines()
441                    .chain(check.stderr.text.lines())
442                    .map(|line| Line::single(Role::Plain, line)),
443            );
444        }
445        if report.source_state != ValidationSourceState::Unchanged {
446            doc.notes([Line::single(Role::Dim, "Source inputs changed or could not be verified; these results do not validate the current workspace")]);
447        }
448        doc
449    }
450}