Skip to main content

Module trace

Module trace 

Source
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.
InitialInvariantClass
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.
SpecModel
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.
TraceDoc
A counterexample as data, before its values are read against a model.
TraceOptions
How the specification is bound.

Enums§

Check
Which check failed.
ControlMode
Which invalid-by-construction controls the caller’s counterexample supports.
Ending
What a trace claims about its end.
InitialErrorStage
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.
ValidationRunError
A controlled validation did not produce a validation report.

Constants§

DEADLOCK_UNSUPPORTED
The reason given for a deadlock ending whose ENABLED cannot 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 json prints it.

Type Aliases§

State
A state: the value of each of the model’s variables, by dive_ir::VarId. Every entry is Some. Names must have the text and token of the model’s interner; public typed inputs are checked before evaluation.