Skip to main content

Crate dive_trace

Crate dive_trace 

Source
Expand description

dive-trace: the counterexample format and the independent trace validator.

The validator checks a counterexample as data against a bound dive_model::Model: that its first state satisfies the initial predicate, that every step satisfies the next-state relation, evaluated as a predicate over the two given states, that the states the search must have explored are inside the model and violate nothing earlier, and that the trace ends as it claims. It shares only the dive-eval evaluator, the value library and the binding stage with the checker, never the search, store or liveness graph. This is deliberate: code such as the scoped temporal walk in temporal duplicates what dive-liveness does rather than sharing it, so that a checker bug cannot also hide itself from validation. Whether a state has a successor (ENABLED, deadlock and fairness) is the dive-eval evaluator’s ENABLED; the states and steps of the counterexample are still replayed and checked here.

Named pure periodic words (TraceDoc::with_properties) also check all behavior temporal conjuncts and the complete violated-property set. Fairness is decided with the dive-eval evaluator’s ENABLED. VIEW/symmetry closing evidence and unnamed periodic claims from older documents remain explicit refusals.

  • format: the versioned trace format (also TLC’s -dumpTrace json).
  • value_json: dive’s tagged JSON values, with documented representation and mixed-set round-trip limitations.
  • validate(): the checks, giving Validation::Valid, Validation::Invalid (the first failing state and check) or Validation::Unsupported (naming what cannot be checked). A random draw is refused by name (RANDOM_UNSUPPORTED), and so is a string created at run time when strings follow encounter order (RUNTIME_NAMES_UNSUPPORTED). TLC register reads and writes are refused (REGISTERS_UNSUPPORTED) because their contents can depend on evaluations outside the trace. Session reconstructs immutable source/config inputs privately and supports startup registers through a single-candidate Init operation; every later register access retains that refusal.
  • tlc: reading TLC’s lossy JSON by interpretation.
  • mutate: by-construction invalid mutants, the negative controls.

Evaluation recurses on the caller’s stack: run validation on a thread with dive_eval::RECOMMENDED_STACK, as dive-api does.

§Example

use std::sync::Arc;
use dive_trace::{TraceDoc, Validation, validate_doc};

let src = "---- MODULE M ----\nEXTENDS Naturals\nVARIABLE x\n\
           Init == x = 0\nNext == x' = x + 1\nInv == x < 2\n====\n";
let analysis = dive_sema::analyze_source("M.tla", src, &dive_sema::Options::default());
let ir = Arc::new(dive_ir::lower(&analysis).unwrap());
let cfg = dive_config::parse("INIT Init\nNEXT Next\nINVARIANT Inv\n").into_config().unwrap();
let model = dive_model::bind(ir, &cfg, &dive_model::BindOptions::tlc()).unwrap();

let doc = TraceDoc::parse(r#"{"format": "dive-trace", "version": 1, "variables": ["x"],
    "states": [{"action": null, "values": {"x": 0}},
               {"action": {"name": "Next"}, "values": {"x": 1}},
               {"action": {"name": "Next"}, "values": {"x": 2}}],
    "ending": {"kind": "invariant", "name": "Inv"}}"#).unwrap();
let (report, _) = validate_doc(&model, &doc, &cfg.model_values);
assert_eq!(report.validation, Validation::Valid);

// Skipping a state is not a step of the specification.
let doc = TraceDoc::behavior(vec![
    serde_json::json!({"x": 0}),
    serde_json::json!({"x": 2}),
]).unwrap();
let (report, _) = validate_doc(&model, &doc, &cfg.model_values);
let Validation::Invalid(failure) = report.validation else { panic!() };
assert_eq!((failure.state, failure.check), (1, dive_trace::Check::Next));

Re-exports§

pub use format::Ending;
pub use format::Label;
pub use format::Source;
pub use format::TraceDoc;

Modules§

enabled
ENABLED and successor existence on a given state, decided by the dive-eval evaluator’s ENABLED. The validator replays and checks the counterexample’s states and steps itself; whether an action has some successor is decided with the shared evaluator, with a pure bounded TLA composition path and independent cache ownership.
format
Counterexample transports: dive’s format (versions 1 through 6) and TLC’s JSON.
mutate
Negative controls: mutants of a valid counterexample that are invalid by construction.
temporal
Direct temporal semantics on an ultimately periodic word.
tlc
Reading TLC’s -dumpTrace json values against a model.
value_json
dive’s JSON values (trace format version 1).

Structs§

CandidateStateEndpoint
Untrusted candidate-side primary and diagnostic identities. This never selects an expression, action or candidate during independent execution.
Failure
The first check a trace fails.
InitialInvariantClass
Independently reconstructed initial-invariant exception identities.
InvariantErrorClass
Independently executed successor invariant primary and diagnostic identities. Only a fresh crate::Session::invariant_error_class constructs this value; it is never serialized or accepted as producer evidence.
NextStateEndpoint
Untrusted original source context for a Next error before any successor. The fresh validator enumerates the real configured actions independently; this descriptor selects no expression, action, scope or cached value.
PartialStateEndpoint
Untrusted terminal partial bindings, distinct from every complete prefix row. The source names the actual generating action; it selects no replay action.
Report
The verdict with what the validator noticed along the way.
Session
Immutable validation inputs. Every interpretation gets a freshly bound runtime. The caller’s caches, registers, host and atoms are never copied.
ShapeError
Why a document could not be read as a trace of the model: the state, and what is wrong.
TemporalSourceEndpoint
Untrusted source of the first post-Next temporal-row error (native version 5). Fresh replay reconstructs Next and the complete ordered demand lifecycle; this descriptor contains no predicate selector or diagnostic-suppression flag.
TemporalStateEndpoint
A request to validate the first source-state temporal demand error.
Trace
A counterexample (or behavior) read against a model.
ValidationProgress
Actual progress before cooperative validation interruption.
ViewSourceEndpoint
Untrusted source of a VIEW failure while expanding the last complete row. Native version 6 preserves that source-final word; actual fresh prefix and diagnostic execution supply the candidate, admission history and identities.

Enums§

CandidateErrorSite
The independently discovered candidate-side error site.
Check
Which check failed.
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§

COMPOSITION_UNSUPPORTED
Composition outside independent replay’s pure, complete, deterministic-tail slice.
DEADLOCK_UNSUPPORTED
The reason given for a deadlock ending whose ENABLED cannot be decided.
RANDOM_UNSUPPORTED
The reason given when a check draws a random value.
REGISTERS_UNSUPPORTED
The reason given when a check accesses search-dependent TLC registers.
RUNTIME_NAMES_UNSUPPORTED
The reason given when the trace or a check created a name after the model was bound, under an order where names compare by encounter.

Functions§

validate
Validates a trace already read against model. Random draws are refused by name (RANDOM_UNSUPPORTED).
validate_controlled
Validates supplied states with a generic cooperative host capability.
validate_doc
Reads a document in either format against model and validates it. model_values are the configuration’s model value names (dive_config::ModelConfig::model_values), which reading TLC’s format needs. Returns the report and the trace as read (for a TLC document, the interpretation the verdict is about; see tlc). Random draws are refused by name (RANDOM_UNSUPPORTED).
variables
The model’s variable names, by dive_ir::VarId.

Type Aliases§

PartialNextEndpoint
Compatibility name for the original Next partial request.
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.