Skip to main content

dive_api/
trace.rs

1//! Trace validation: checking a trace against a specification.
2//!
3//! A [`SpecModel`] is a specification bound to its TLC configuration. It
4//! validates traces in dive's format ([`dive_trace::format`]) or TLC's
5//! `-dumpTrace json`, with the independent validator of `dive-trace`, which
6//! evaluates the next-state relation as a predicate over supplied states and
7//! never runs the model checker's search. Source-bound Next endpoints may use
8//! the shared evaluator's ordered generator before its first candidate.
9//! Register-dependent Init
10//! uses an independent ordered single-candidate operation from empty slots.
11//!
12//! Named invariant evaluation errors use native trace version 2 with
13//! `Ending::InvariantError { name, ec }`: `ec` is the underlying cause, while
14//! the check report retains TLC's deciding wrapper 2111. Independent replay
15//! requires that exact final invariant/cause after earlier checks pass. All
16//! existing ending kinds retain native version 1; readers also accept version 3
17//! partial candidates and version 4 independently replayed candidate errors.
18//! Neither native payload version changes the report schema version.
19//!
20//! This is also how a Rust project checks its *own implementation's*
21//! traces: record each state of a run as a JSON object from variable names
22//! to values (in dive's JSON form, [`dive_trace::value_json`]), and validate
23//! the sequence as a [`Ending::Behavior`]. The trace must assign every
24//! variable in every complete state. A version-3 terminal partial candidate
25//! is separate from those rows and requires fresh fallible replay.
26//!
27//! # Example
28//!
29//! ```
30//! use dive_api::trace::{SpecModel, TraceOptions, TraceDoc, Validation};
31//! use serde_json::json;
32//!
33//! let spec = "---- MODULE Counter ----\nEXTENDS Naturals\nVARIABLE n\n\
34//!             Init == n = 0\nNext == n' = n + 1 \\/ n' = 0\n====\n";
35//! let model = SpecModel::from_source("Counter.tla", spec, "INIT Init\nNEXT Next\n", &TraceOptions::default())?;
36//!
37//! // States observed in the implementation, in order.
38//! let observed = vec![json!({"n": 0}), json!({"n": 1}), json!({"n": 2}), json!({"n": 0})];
39//! let report = model.validate(&TraceDoc::behavior(observed).unwrap());
40//! assert_eq!(report.validation, Validation::Valid);
41//!
42//! // A bug in the implementation: the counter skipped a value.
43//! let report = model.validate(&TraceDoc::behavior(vec![json!({"n": 0}), json!({"n": 2})]).unwrap());
44//! let Validation::Invalid(f) = &report.validation else { panic!() };
45//! assert_eq!(f.state, 1);
46//! # Ok::<(), dive_api::ApiError>(())
47//! ```
48
49use std::path::{Path, PathBuf};
50use std::sync::Arc;
51
52pub use dive_trace::mutate::{ControlMode, Mutant};
53pub use dive_trace::{
54    Check, DEADLOCK_UNSUPPORTED, Ending, Failure, InitialErrorStage, InitialInvariantClass, Report,
55    State, Trace, TraceDoc, Validation, ValidationRunError,
56};
57use serde_json::{Value, json};
58
59use crate::ApiError;
60
61/// Version of the JSON document produced by [`report_json`].
62pub const TRACE_SCHEMA_VERSION: u32 = crate::REPORT_SCHEMA_VERSION;
63
64/// How the specification is bound.
65#[derive(Debug, Clone, Default, PartialEq, Eq)]
66pub struct TraceOptions {
67    /// Explicit recorded external assumptions. Source binding replays exact
68    /// operation/argument order without operating-system access. Categories
69    /// come from this context; absent inputs never grant host access.
70    pub inputs: Option<dive_eval::inputs::RecordedInputs>,
71    /// `--compat=tlc`: evaluate with every option at its TLC setting (32-bit
72    /// integers, TLC's value order and comparisons). Otherwise dive's
73    /// default profile.
74    pub compat_tlc: bool,
75    /// Explicit independent symmetry/liveness binding policy; omitted selects
76    /// the semantic profile default. No trace annotation supplies this policy.
77    pub symmetry_liveness: Option<dive_model::SymmetryLiveness>,
78    /// TLC's `-deadlock` flag: the model does not check for deadlock.
79    pub no_deadlock: bool,
80    /// The checking run's `-seed` and `-fp` index, when known (the TLC
81    /// goldens use `-seed 0 -fp 0`): `TLCGet("config")` reports them, and
82    /// constant definitions draw from the run's start-up stream (TLC's
83    /// seeding under `compat_tlc`, dive's replayable seeding otherwise).
84    /// Without them,
85    /// startup random operations need a producer host to bind. Native finite
86    /// validation independently proves finite source-defined choice support,
87    /// rebinding every alternative; it does not reproduce the run's RNG draws.
88    /// Deferred domains, register-dependent random prefixes, random ENABLED and
89    /// temporal/error-endpoint interactions retain named refusal boundaries.
90    pub run: Option<(i64, usize)>,
91    /// Modules searched before the standard modules.
92    pub library_paths: Vec<PathBuf>,
93    /// Modules searched after the standard modules (TLC's classpath).
94    pub module_paths: Vec<PathBuf>,
95}
96
97/// A specification bound to its configuration, with immutable original inputs
98/// for private startup reconstruction on every validation.
99#[derive(Debug, Clone)]
100pub struct SpecModel {
101    model: dive_model::Model,
102    model_values: Vec<String>,
103    session: dive_trace::Session,
104    recipe: dive_model::Recipe,
105}
106
107pub(crate) fn make_run_config(
108    model: &dive_model::Model,
109    seed: i64,
110    fp_index: usize,
111) -> dive_eval::RunConfig {
112    dive_eval::RunConfig {
113        deadlock: model.settings.check_deadlock,
114        workers: 1,
115        seed,
116        fingerprint: i64::from_ne_bytes(
117            dive_value::fp64::POLYS
118                .get(fp_index)
119                .copied()
120                .unwrap_or(0)
121                .to_ne_bytes(),
122        ),
123        install: std::env::current_exe()
124            .map(|path| path.display().to_string())
125            .unwrap_or_default(),
126    }
127}
128
129impl SpecModel {
130    /// Loads the specification rooted at `spec` and binds it to the
131    /// configuration file `cfg`.
132    ///
133    /// # Errors
134    /// [`ApiError::Io`] if a file cannot be read, [`ApiError::Rejected`] if
135    /// the specification or configuration has errors, and
136    /// [`ApiError::Unsupported`] if dive cannot bind it exactly.
137    pub fn load(spec: &Path, cfg: &Path, opts: &TraceOptions) -> Result<Self, ApiError> {
138        Self::load_hosted(spec, cfg, opts, None)
139    }
140
141    pub(crate) fn load_hosted(
142        spec: &Path,
143        cfg: &Path,
144        opts: &TraceOptions,
145        host: Option<Arc<dyn dive_eval::Host>>,
146    ) -> Result<Self, ApiError> {
147        let sema = sema_options(opts);
148        let shown = spec.display().to_string();
149        let analysis = dive_sema::analyze_file(spec, &sema).map_err(|error| ApiError::Io {
150            path: shown.clone(),
151            error,
152        })?;
153        let text = std::fs::read(cfg).map_err(|error| ApiError::Io {
154            path: cfg.display().to_string(),
155            error,
156        })?;
157        let (_, parsed) = dive_config::parse_bytes(&text);
158        Self::bind_hosted(&shown, &analysis, parsed, opts, host)
159    }
160
161    /// Binds specification source text (the root module; others come from
162    /// the search path) to configuration text.
163    ///
164    /// # Errors
165    /// As [`SpecModel::load`].
166    pub fn from_source(
167        file: &str,
168        source: &str,
169        cfg: &str,
170        opts: &TraceOptions,
171    ) -> Result<Self, ApiError> {
172        let analysis = dive_sema::analyze_source(file, source, &sema_options(opts));
173        Self::bind(file, &analysis, dive_config::parse(cfg), opts)
174    }
175
176    fn bind(
177        file: &str,
178        analysis: &dive_sema::Analysis,
179        cfg: dive_config::ConfigParse,
180        opts: &TraceOptions,
181    ) -> Result<Self, ApiError> {
182        Self::bind_hosted(file, analysis, cfg, opts, None)
183    }
184
185    #[allow(
186        clippy::too_many_lines,
187        reason = "one ordered startup transaction retains source, host, replay cursor and config ownership"
188    )]
189    fn bind_hosted(
190        file: &str,
191        analysis: &dive_sema::Analysis,
192        cfg: dive_config::ConfigParse,
193        opts: &TraceOptions,
194        owned_host: Option<Arc<dyn dive_eval::Host>>,
195    ) -> Result<Self, ApiError> {
196        if owned_host.is_some() && opts.inputs.is_some() {
197            return Err(ApiError::Unsupported {
198                feature: "owned simulation external input replay is not implemented".into(),
199            });
200        }
201        if !analysis.accepted() {
202            return Err(ApiError::Rejected {
203                message: format!("{file} has errors; `dive analyze` lists them"),
204            });
205        }
206        let Some(cfg) = cfg.into_config() else {
207            return Err(ApiError::Rejected {
208                message: "the configuration has errors; `dive parse --config` lists them"
209                    .to_owned(),
210            });
211        };
212        let ir = dive_ir::lower(analysis).map_err(|e| ApiError::Unsupported {
213            feature: e.to_string(),
214        })?;
215        let ir = Arc::new(ir);
216        dive_eval::validate_ir(&ir).map_err(|error| ApiError::Unsupported {
217            feature: error.to_string(),
218        })?;
219        if let Some(feature) = dive_model::transformed_randomness(&ir, &cfg) {
220            return Err(ApiError::Unsupported {
221                feature: feature.to_owned(),
222            });
223        }
224        let mode = if opts.compat_tlc {
225            dive_stdlib::random::RandomMode::Tlc
226        } else {
227            dive_stdlib::random::RandomMode::Dive
228        };
229        let streams = match opts.run {
230            Some((seed, fp_index)) => {
231                if fp_index >= dive_value::fp64::POLYS.len() {
232                    return Err(ApiError::Rejected {
233                        message: format!(
234                            "fingerprint polynomial index {fp_index} is out of range (0..{})",
235                            dive_value::fp64::POLYS.len()
236                        ),
237                    });
238                }
239                Some(dive_stdlib::random::Streams::new(seed, mode))
240            }
241            None => None,
242        };
243        let replay = opts
244            .inputs
245            .as_ref()
246            .map(|inputs| dive_eval::inputs::InputReplay::new(inputs.clone()).map(Arc::new))
247            .transpose()
248            .map_err(|error| ApiError::Unsupported {
249                feature: error.message,
250            })?;
251        let host = streams.map(|s| {
252            let host = dive_stdlib::host::RunHost::new(s, None);
253            Arc::new(if let Some(replay) = &replay {
254                host.with_inputs(replay.clone())
255            } else {
256                host
257            })
258        });
259        let mut bind_opts = dive_model::BindOptions {
260            no_deadlock: opts.no_deadlock,
261            host: owned_host
262                .or_else(|| host.clone().map(|h| -> Arc<dyn dive_eval::Host> { h }))
263                .or_else(|| {
264                    replay
265                        .clone()
266                        .map(|replay| -> Arc<dyn dive_eval::Host> { replay })
267                }),
268            ..if opts.compat_tlc {
269                dive_model::BindOptions::tlc()
270            } else {
271                dive_model::BindOptions::dive()
272            }
273        };
274        if let Some(inputs) = &opts.inputs {
275            bind_opts.eval.host_access = inputs.grants;
276        }
277        if let Some(policy) = opts.symmetry_liveness {
278            bind_opts.symmetry_liveness = policy;
279        }
280        let model_values = cfg.model_values.clone();
281        let recipe =
282            dive_model::Recipe::new(ir.clone(), cfg.clone(), bind_opts.eval, opts.no_deadlock)
283                .with_symmetry_liveness(bind_opts.symmetry_liveness);
284        let bound = on_big_stack(move || dive_model::bind(ir, &cfg, &bind_opts))?;
285        if let Some(replay) = &replay {
286            replay
287                .finish_binding()
288                .map_err(|error| ApiError::Unsupported {
289                    feature: error.message,
290                })?;
291        }
292        let mut run_config = None;
293        if let (Ok(model), Some((seed, fp_index))) = (&bound, opts.run) {
294            model.evaluator.intern_checker_names();
295            let config = make_run_config(model, seed, fp_index);
296            model.evaluator.intern_bfs_config(&config);
297            if let Some(host) = &host {
298                host.set_config(Some(config.clone()));
299            }
300            run_config = Some(config);
301        }
302        match bound {
303            Ok(model) => Ok(Self {
304                model,
305                model_values,
306                recipe: recipe.clone(),
307                session: {
308                    let session = dive_trace::Session::new(
309                        recipe.clone(),
310                        run_config.or_else(|| {
311                            host.as_ref()
312                                .and_then(|host| dive_eval::Host::config(&**host))
313                        }),
314                    );
315                    if let Some(inputs) = &opts.inputs {
316                        session.with_inputs(inputs.clone())
317                    } else {
318                        session
319                    }
320                },
321            }),
322            Err(f) => match &f.error.kind {
323                dive_model::ErrorKind::Unsupported { feature } => Err(ApiError::Unsupported {
324                    feature: feature.clone(),
325                }),
326                _ => Err(ApiError::Rejected {
327                    message: f.error.to_string(),
328                }),
329            },
330        }
331    }
332
333    /// The bound model.
334    #[must_use]
335    pub fn model(&self) -> &dive_model::Model {
336        &self.model
337    }
338
339    /// Private feasibility runtime: fixed inputs, fresh names/caches and no ASSUMEs.
340    pub(crate) fn preparation_model(
341        &self,
342        seed: i64,
343        mode: dive_stdlib::random::RandomMode,
344        control: Arc<dyn dive_eval::HostControl>,
345    ) -> Result<dive_model::Model, String> {
346        let host = Arc::new(dive_stdlib::host::RunHost::new(
347            dive_stdlib::random::Streams::new(seed, mode),
348            None,
349        ));
350        let model = on_big_stack(|| self.recipe.bind_next_fallible(host.clone(), Some(control)))
351            .map_err(|error| error.to_string())?
352            .map_err(|error| error.to_string())?;
353        if let Some(config) = self.model.evaluator.host().and_then(|host| host.config()) {
354            model.evaluator.intern_checker_names();
355            model.evaluator.intern_bfs_config(&config);
356            host.set_config(Some(config));
357        }
358        Ok(model)
359    }
360
361    /// The configuration's model value names.
362    #[must_use]
363    pub fn model_values(&self) -> &[String] {
364        &self.model_values
365    }
366
367    /// Validates a trace document (either format). A TLC document needs its
368    /// ending set ([`TraceDoc::with_ending`]).
369    #[must_use]
370    pub fn validate(&self, doc: &TraceDoc) -> Report {
371        self.read(doc).0
372    }
373
374    /// Replays a finite mode's native word on a fresh source-bound runtime
375    /// under the caller's existing run control.
376    pub(crate) fn validate_mode(
377        &self,
378        doc: &TraceDoc,
379        control: Arc<dyn dive_eval::HostControl>,
380    ) -> Result<Report, ValidationRunError> {
381        on_big_stack(|| {
382            self.session
383                .read_controlled(doc, control)
384                .map(|(report, _)| report)
385        })
386        .map_err(|error| ValidationRunError::ThreadFailure(error.to_string()))?
387    }
388
389    /// Validates finite simulation samples; deciding diagnostic endpoints keep
390    /// their ordinary operation through `validate_mode` instead. A simulation
391    /// deadlock is a state with no successor inside the model's constraints.
392    pub(crate) fn validate_sample_mode(
393        &self,
394        doc: &TraceDoc,
395        control: Arc<dyn dive_eval::HostControl>,
396    ) -> Result<Report, ValidationRunError> {
397        on_big_stack(|| {
398            if doc.ending == Some(Ending::Behavior) {
399                self.session.read_sampled(doc, Some(control))
400            } else if doc.ending == Some(Ending::Deadlock) {
401                self.session.read_sampled_deadlock(doc, Some(control))
402            } else {
403                self.session.read_controlled(doc, control)
404            }
405            .map(|(report, _)| report)
406        })
407        .map_err(|error| ValidationRunError::ThreadFailure(error.to_string()))?
408    }
409
410    /// Independently checks every finite sampled row, including configured
411    /// constraints, invariants and implied finite properties, on fresh source.
412    /// Unlike ordinary behavior validity, this operation rejects a prefix that
413    /// passed a deciding safety violation. It proves no exhaustive result.
414    /// A `deadlock` ending is checked as a simulation deadlock: no successor
415    /// of the last state satisfies every constraint.
416    ///
417    /// ```no_run
418    /// # fn sample(source: &dive_api::trace::SpecModel,
419    /// # word: &dive_api::trace::TraceDoc)
420    /// # -> Result<(), dive_api::trace::ValidationRunError> {
421    /// let report = source.try_validate_sample(word)?;
422    /// # let _ = report; Ok(()) }
423    /// ```
424    ///
425    /// # Errors
426    /// Typed interruption, resource exhaustion or isolated validation failure.
427    pub fn try_validate_sample(&self, doc: &TraceDoc) -> Result<Report, ValidationRunError> {
428        on_big_stack(|| {
429            if doc.ending == Some(Ending::Deadlock) {
430                self.session.read_sampled_deadlock(doc, None)
431            } else {
432                self.session.read_sampled(doc, None)
433            }
434            .map(|(report, _)| report)
435        })
436        .map_err(|error| ValidationRunError::ThreadFailure(error.to_string()))?
437    }
438
439    /// Validates a trace document and also returns the trace as read (see
440    /// [`dive_trace::validate_doc`]).
441    #[must_use]
442    pub fn read(&self, doc: &TraceDoc) -> (Report, Option<Trace>) {
443        on_big_stack(|| {
444            let (report, plain) = self.session.read(doc);
445            let trace = plain.and_then(|doc| Trace::decode(&self.model, &doc).ok());
446            (report, trace)
447        })
448        .unwrap_or_else(|e| (thread_failed(&e, doc.states.len()), None))
449    }
450
451    /// Validates with resource/execution exceptions outside the report.
452    /// Endpoint documents require this fallible entrypoint; no resource failure
453    /// is relabeled as a completed unsupported validation result.
454    ///
455    /// ```no_run
456    /// # fn check(model: &dive_api::trace::SpecModel, doc: &dive_api::trace::TraceDoc)
457    /// # -> Result<(), dive_api::trace::ValidationRunError> {
458    /// let report = model.try_validate(doc)?;
459    /// # let _ = report; Ok(()) }
460    /// ```
461    ///
462    /// # Errors
463    /// Resource exhaustion, typed interruption, control conflict or isolated
464    /// thread failure; in each case there is no completed validation report.
465    pub fn try_validate(&self, doc: &TraceDoc) -> Result<Report, ValidationRunError> {
466        self.try_read(doc).map(|(report, _)| report)
467    }
468
469    /// Reads through fresh private source reconstruction with fallible transport.
470    /// Other document forms retain their existing reading semantics.
471    ///
472    /// # Errors
473    /// As [`Self::try_validate`].
474    pub fn try_read(&self, doc: &TraceDoc) -> Result<(Report, Option<Trace>), ValidationRunError> {
475        if !matches!(
476            doc.ending,
477            Some(
478                Ending::TemporalStateError { .. }
479                    | Ending::TemporalSourceError { .. }
480                    | Ending::NextStateError { .. }
481                    | Ending::ViewSourceError { .. }
482                    | Ending::CandidateStateError { .. }
483                    | Ending::PartialNext { .. }
484                    | Ending::PartialInit { .. }
485            )
486        ) {
487            return Ok(self.read(doc));
488        }
489        on_big_stack(|| {
490            let (report, plain) = self.session.try_read(doc)?;
491            let trace = plain.and_then(|doc| Trace::decode(&self.model, &doc).ok());
492            Ok((report, trace))
493        })
494        .map_err(|error| ValidationRunError::ThreadFailure(error.to_string()))?
495    }
496
497    /// Validates a named invariant-error word and separately reconstructs its
498    /// actual first-Init diagnostic classification on a fresh private runtime.
499    /// A valid word alone does not grant a deciding-wrapper certificate.
500    ///
501    /// ```no_run
502    /// # fn check(model: &dive_api::trace::SpecModel, doc: &dive_api::trace::TraceDoc)
503    /// # -> Result<(), dive_api::trace::ValidationRunError> {
504    /// let (word, class) = model.initial_invariant_class(doc, None)?;
505    /// if let Some(class) = class {
506    ///     assert_eq!(class.deciding_code(), 2147);
507    /// }
508    /// # let _ = word; Ok(()) }
509    /// ```
510    ///
511    /// # Errors
512    /// Resource exhaustion, actual host interruption, control conflict or
513    /// isolated thread failure; no completed class proof is returned then.
514    pub fn initial_invariant_class(
515        &self,
516        doc: &TraceDoc,
517        control: Option<Arc<dyn dive_eval::HostControl>>,
518    ) -> Result<(Report, Option<dive_trace::InitialInvariantClass>), ValidationRunError> {
519        on_big_stack(|| self.session.initial_invariant_class(doc, control))
520            .map_err(|error| ValidationRunError::ThreadFailure(error.to_string()))?
521    }
522
523    /// Validates a named successor invariant error and separately executes its
524    /// bounded Init/source admission and diagnostic lifecycle on a fresh runtime.
525    /// Ordinary word validity alone grants no diagnostic identity.
526    ///
527    /// # Errors
528    /// Actual interruption, resource/internal failure, control or thread failure.
529    pub fn invariant_error_class(
530        &self,
531        doc: &TraceDoc,
532        control: Option<Arc<dyn dive_eval::HostControl>>,
533    ) -> Result<(Report, Option<dive_trace::InvariantErrorClass>), ValidationRunError> {
534        on_big_stack(|| self.session.invariant_error_class(doc, control))
535            .map_err(|error| ValidationRunError::ThreadFailure(error.to_string()))?
536    }
537
538    /// Independently reconstructs the actual first initial error stage on a
539    /// fresh source-bound runtime. Header fields do not select this route.
540    /// An invariant-receiver stage still needs its auxiliary word and separate
541    /// [`Self::initial_invariant_class`] proof before a wrapper is established.
542    ///
543    /// # Errors
544    /// Actual interruption, resource, binding, control or isolated-thread failure.
545    pub fn initial_error_stage(
546        &self,
547        control: Option<Arc<dyn dive_eval::HostControl>>,
548    ) -> Result<(Report, Option<dive_trace::InitialErrorStage>), ValidationRunError> {
549        on_big_stack(|| self.session.initial_error_stage(control))
550            .map_err(|error| ValidationRunError::ThreadFailure(error.to_string()))?
551    }
552
553    /// Validates a trace already read against this model.
554    #[must_use]
555    pub fn validate_trace(&self, trace: &Trace) -> Report {
556        on_big_stack(|| {
557            // Preserve the typed-input ownership guard before transport by text.
558            for state in &trace.states {
559                for value in state.iter().flatten() {
560                    if let Err(error) = value.validate_names(&self.model.names) {
561                        return thread_failed(
562                            &ApiError::Unsupported {
563                                feature: error.to_string(),
564                            },
565                            trace.states.len(),
566                        );
567                    }
568                }
569            }
570            match trace.to_doc(&self.model) {
571                Ok(doc) => self.session.read(&doc).0,
572                Err(message) => thread_failed(&ApiError::Rejected { message }, trace.states.len()),
573            }
574        })
575        .unwrap_or_else(|e| thread_failed(&e, trace.states.len()))
576    }
577
578    /// The by-construction invalid mutants of a valid shortest trace
579    /// ([`dive_trace::mutate`]): negative controls, without random redraws.
580    #[must_use]
581    pub fn mutants(&self, trace: &Trace) -> Vec<Mutant> {
582        self.mutants_with_mode(trace, ControlMode::ShortestBfs)
583    }
584
585    /// The invalid-by-construction mutants supported by the known valid
586    /// counterexample's explicit producer contract. This does not infer
587    /// shortestness or explore alternative paths.
588    #[must_use]
589    pub fn mutants_with_mode(&self, trace: &Trace, mode: ControlMode) -> Vec<Mutant> {
590        on_big_stack(|| dive_trace::mutate::mutants_with_mode(&self.model, trace, mode))
591            .unwrap_or_default()
592    }
593
594    /// The trace in dive's format.
595    ///
596    /// # Errors
597    /// If a value has no JSON form.
598    pub fn to_doc(&self, trace: &Trace) -> Result<TraceDoc, ApiError> {
599        trace
600            .to_doc(&self.model)
601            .map_err(|message| ApiError::Rejected { message })
602    }
603}
604
605fn sema_options(opts: &TraceOptions) -> dive_sema::Options {
606    dive_sema::Options {
607        search: dive_sema::SearchPath {
608            library_paths: opts.library_paths.clone(),
609            after_standard: opts.module_paths.clone(),
610        },
611        ..dive_sema::Options::default()
612    }
613}
614
615fn thread_failed(e: &ApiError, length: usize) -> Report {
616    Report {
617        validation: Validation::Unsupported(format!("internal error: {e}")),
618        notes: Vec::new(),
619        length,
620    }
621}
622
623/// Runs `f` on a thread with the evaluator's recommended stack.
624fn on_big_stack<T: Send>(f: impl FnOnce() -> T + Send) -> Result<T, ApiError> {
625    std::thread::scope(|s| {
626        std::thread::Builder::new()
627            .stack_size(dive_eval::RECOMMENDED_STACK)
628            .spawn_scoped(s, f)
629            .ok()
630            .and_then(|h| h.join().ok())
631    })
632    .ok_or_else(|| ApiError::Unsupported {
633        feature: "internal error: the evaluation thread could not run or panicked".to_owned(),
634    })
635}
636
637/// The JSON report of a validation, as `dive validate-trace --output json`
638/// prints it.
639#[must_use]
640pub fn report_json(report: &Report) -> Value {
641    let mut j = json!({
642        "schema_version": TRACE_SCHEMA_VERSION,
643        "command": "validate-trace",
644        "result": report.validation.kind(),
645        "length": report.length,
646        "notes": report.notes,
647    });
648    match &report.validation {
649        Validation::Invalid(f) => {
650            j["failure"] = json!({"state": f.state, "check": f.check.name(), "detail": f.detail});
651        }
652        Validation::Unsupported(u) => j["unsupported"] = Value::from(u.as_str()),
653        // Valid: the result kind says everything.
654        _ => {}
655    }
656    j
657}
658
659/// The report in a human-readable form.
660#[must_use]
661pub fn render_report(report: &Report) -> String {
662    use std::fmt::Write as _;
663    let mut s = match &report.validation {
664        Validation::Valid => format!("valid: the {}-state trace validates\n", report.length),
665        Validation::Invalid(f) => format!(
666            "invalid: state {} of {} (numbered from 1, as TLC prints traces), check `{}`: {}\n",
667            f.state + 1,
668            report.length,
669            f.check.name(),
670            f.detail
671        ),
672        Validation::Unsupported(u) => format!("unsupported: {u}\n"),
673        other => format!("{}\n", other.kind()),
674    };
675    for n in &report.notes {
676        let _ = writeln!(s, "note: {n}");
677    }
678    s
679}
680
681/// The result of running the validator's controls on one counterexample
682/// known to be valid (TLC's, or dive's): the positive control, and every
683/// by-construction mutant.
684#[derive(Debug, Clone)]
685pub struct Controls {
686    /// The original trace's report.
687    pub positive: Report,
688    /// The trace as read, written in dive's format and validated again: it
689    /// must agree with the positive control.
690    pub dive_format: Option<Validation>,
691    /// Each mutant's name and verdict. Every one must be invalid.
692    pub mutants: Vec<(String, Validation)>,
693}
694
695impl Controls {
696    /// Whether the positive control validated: `valid`, or, for a deadlock,
697    /// every check but the unverifiable claim.
698    #[must_use]
699    pub fn positive_ok(&self) -> bool {
700        match &self.positive.validation {
701            Validation::Valid => true,
702            Validation::Unsupported(u) => u == dive_trace::DEADLOCK_UNSUPPORTED,
703            _ => false,
704        }
705    }
706
707    /// Every failed control, described.
708    #[must_use]
709    pub fn failures(&self) -> Vec<String> {
710        let mut out = Vec::new();
711        if !self.positive_ok() {
712            out.push(format!(
713                "positive control: {}",
714                render_report(&self.positive).trim_end()
715            ));
716        }
717        if let Some(v) = &self.dive_format
718            && *v != self.positive.validation
719        {
720            out.push(format!(
721                "the trace in dive's format gives {}, not {}",
722                v.kind(),
723                self.positive.validation.kind()
724            ));
725        }
726        if self.mutants.is_empty() {
727            out.push("no negative controls generated".to_owned());
728        }
729        for (name, v) in &self.mutants {
730            if !matches!(v, Validation::Invalid(_)) {
731                out.push(format!("mutant {name} is not rejected: {}", v.kind()));
732            }
733        }
734        out
735    }
736}
737
738impl SpecModel {
739    /// Runs the controls on a known valid shortest BFS counterexample.
740    ///
741    /// Compatibility wrapper for [`Self::controls_with_mode`] with
742    /// [`ControlMode::ShortestBfs`]. Other producers must select their mode
743    /// explicitly.
744    #[must_use]
745    pub fn controls(&self, doc: &TraceDoc) -> Controls {
746        self.controls_with_mode(doc, ControlMode::ShortestBfs)
747    }
748
749    /// Runs positive, document round-trip and negative controls using the
750    /// known valid counterexample's explicit producer contract. Every
751    /// generated mutant must be invalid both directly and through dive's
752    /// format; an empty negative suite receives no coverage credit.
753    ///
754    /// ```
755    /// use dive_api::trace::{ControlMode, Ending, SpecModel, TraceDoc, TraceOptions};
756    /// use serde_json::json;
757    ///
758    /// let model = SpecModel::from_source("Loop.tla",
759    ///     "---- MODULE Loop ----\nVARIABLE x\nInit == x=0\nNext == x'=0 \\/ x'=1\nInv == x=0\n====\n",
760    ///     "INIT Init\nNEXT Next\nINVARIANT Inv\n", &TraceOptions::default())?;
761    /// let doc = TraceDoc::behavior(vec![json!({"x":0}), json!({"x":0}), json!({"x":1})])?
762    ///     .with_ending(Ending::Invariant("Inv".to_owned()));
763    /// let controls = model.controls_with_mode(&doc, ControlMode::Counterexample);
764    /// assert!(controls.failures().is_empty());
765    /// let (_, trace) = model.read(&doc);
766    /// let mutants = model.mutants_with_mode(&trace.ok_or("trace missing")?, ControlMode::Counterexample);
767    /// assert_eq!(mutants.len(), 3);
768    /// # Ok::<(), Box<dyn std::error::Error>>(())
769    /// ```
770    #[must_use]
771    pub fn controls_with_mode(&self, doc: &TraceDoc, mode: ControlMode) -> Controls {
772        let (positive, trace) = self.read(doc);
773        let mut mutants = Vec::new();
774        let mut dive_format = None;
775        if let Some(trace) = trace.filter(|_| {
776            matches!(
777                positive.validation,
778                Validation::Valid | Validation::Unsupported(_)
779            )
780        }) {
781            dive_format = Some(match self.to_doc(&trace) {
782                Ok(d) => self.validate(&d).validation,
783                Err(e) => Validation::Unsupported(e.to_string()),
784            });
785            for m in self.mutants_with_mode(&trace, mode) {
786                let direct = self.validate_trace(&m.trace).validation;
787                let via_format = match self.to_doc(&m.trace) {
788                    Ok(d) => self.validate(&d).validation,
789                    Err(e) => Validation::Unsupported(e.to_string()),
790                };
791                let v = if matches!(direct, Validation::Invalid(_)) {
792                    via_format
793                } else {
794                    direct
795                };
796                mutants.push((m.name, v));
797            }
798        }
799        Controls {
800            positive,
801            dive_format,
802            mutants,
803        }
804    }
805}