Expand description
Trace validation: checking a trace against a specification.
A SpecModel is a specification bound to its TLC configuration. It
validates traces in dive’s format (dive_trace::format) or TLC’s
-dumpTrace json, with the independent validator of dive-trace, which
evaluates the next-state relation as a predicate over supplied states and
never runs the model checker’s search. Source-bound Next endpoints may use
the shared evaluator’s ordered generator before its first candidate.
Register-dependent Init
uses an independent ordered single-candidate operation from empty slots.
Named invariant evaluation errors use native trace version 2 with
Ending::InvariantError { name, ec }: ec is the underlying cause, while
the check report retains TLC’s deciding wrapper 2111. Independent replay
requires that exact final invariant/cause after earlier checks pass. All
existing ending kinds retain native version 1; readers also accept version 3
partial candidates and version 4 independently replayed candidate errors.
Neither native payload version changes the report schema version.
This is also how a Rust project checks its own implementation’s
traces: record each state of a run as a JSON object from variable names
to values (in dive’s JSON form, dive_trace::value_json), and validate
the sequence as a Ending::Behavior. The trace must assign every
variable in every complete state. A version-3 terminal partial candidate
is separate from those rows and requires fresh fallible replay.
§Example
use dive_api::trace::{SpecModel, TraceOptions, TraceDoc, Validation};
use serde_json::json;
let spec = "---- MODULE Counter ----\nEXTENDS Naturals\nVARIABLE n\n\
Init == n = 0\nNext == n' = n + 1 \\/ n' = 0\n====\n";
let model = SpecModel::from_source("Counter.tla", spec, "INIT Init\nNEXT Next\n", &TraceOptions::default())?;
// States observed in the implementation, in order.
let observed = vec![json!({"n": 0}), json!({"n": 1}), json!({"n": 2}), json!({"n": 0})];
let report = model.validate(&TraceDoc::behavior(observed).unwrap());
assert_eq!(report.validation, Validation::Valid);
// A bug in the implementation: the counter skipped a value.
let report = model.validate(&TraceDoc::behavior(vec![json!({"n": 0}), json!({"n": 2})]).unwrap());
let Validation::Invalid(f) = &report.validation else { panic!() };
assert_eq!(f.state, 1);Structs§
- Controls
- The result of running the validator’s controls on one counterexample known to be valid (TLC’s, or dive’s): the positive control, and every by-construction mutant.
- Failure
- The first check a trace fails.
- Initial
Invariant Class - Independently reconstructed initial-invariant exception identities.
- Mutant
- A mutant: what was done, and the trace.
- Report
- The verdict with what the validator noticed along the way.
- Spec
Model - A specification bound to its configuration, with immutable original inputs for private startup reconstruction on every validation.
- Trace
- A counterexample (or behavior) read against a model.
- Trace
Doc - A counterexample as data, before its values are read against a model.
- Trace
Options - How the specification is bound.
Enums§
- Check
- Which check failed.
- Control
Mode - Which invalid-by-construction controls the caller’s counterexample supports.
- Ending
- What a trace claims about its end.
- Initial
Error Stage - Actual independently reached initial-error lifecycle, before header matching. A receiver stage requires its separate named-word class proof. The two no-word stages include actual matching diagnostic receiver reconstruction.
- Validation
- The validator’s verdict.
- Validation
RunError - A controlled validation did not produce a validation report.
Constants§
- DEADLOCK_
UNSUPPORTED - The reason given for a deadlock ending whose
ENABLEDcannot be decided. - TRACE_
SCHEMA_ VERSION - Version of the JSON document produced by
report_json.
Functions§
- render_
report - The report in a human-readable form.
- report_
json - The JSON report of a validation, as
dive validate-trace --output jsonprints it.
Type Aliases§
- State
- A state: the value of each of the model’s variables, by
dive_ir::VarId. Every entry isSome. Names must have the text and token of the model’s interner; public typed inputs are checked before evaluation.