Expand description
dive-api: the embeddable library API and cargo test integration.
It exposes everything the dive command line does as plain Rust calls,
each returning a typed report with a versioned JSON form
(REPORT_SCHEMA_VERSION):
- Parsing TLA+ source (
parse_source,parse_file) into a lossless syntax tree, with SANY’s syntax errors. - Model configurations in TLC’s
.cfgformat (parse_config_file,parse_config_source). - Semantic analysis equivalent to SANY (
analyze_file,analyze_source). - PlusCal translation and checksum rewriting (
translate_file,translate_source,rewrite_file). - Model checking of safety and temporal properties (
check_filewith aCheckRequest, returning aCheckReport), including run budgets, checkpoints (checkpoint) and several workers. - Simulation with a seed (
simulate_file) and depth-first iterative deepening (dfid_file). - Trace validation: checking a counterexample against the
specification with the independent validator (
trace), and temporal checking on its own (temporal).
Anything dive does not implement exactly is reported as
ApiError::Unsupported, naming the feature, rather than approximated.
§Example
let report = dive_api::parse_source("Spec.tla", "---- MODULE Spec ----\nx == 1\n====\n");
assert!(report.accepted());
assert_eq!(report.modules(), ["Spec"]);
let json = report.to_json(false);
assert_eq!(json["schema_version"], dive_api::PARSE_SCHEMA_VERSION);Re-exports§
pub use dive_syntax;pub use dive_sema;
Modules§
- checkpoint
- Native safety checkpoint request and format API.
- debug
- Managed, producer-only debugging of the existing compiled safety checker.
- diagnostics
- Explanations for stable syntax, selected semantic, temporal and command codes.
- exit
- Historical native exit codes, selected by
dive check --exit-codes nativeand the dive profile’sCheckReport::exit_code. The CLI default uses TLC’s deciding status independently of evaluator profile (EC.ExitStatus: 0, 10–14, 75–77, 150, 151, 255). Codes below marked “both” keep their meaning. - host_
inputs - The optional report context for explicit external input assumptions.
- temporal
- Bounded final temporal checking for Rust callers.
- trace
- Trace validation: checking a trace against a specification.
Structs§
- Analyze
Options - Where
dive analyzelooks for modules besides the root file’s directory. - Analyze
Report - The outcome of analysing a specification.
- Check
Report - The outcome of
dive check. - Check
Request - What to check and how.
- Config
Report - The outcome of reading one cfg file.
- Core
Worker - An independently loaded, bound and compiled worker with no received-code or host-I/O grants. Assigned source expansion requires an authenticated session; local constant/ASSUME binding and compilation happen during preparation.
- Dfid
Report - Structured evidence and process disposition for a DFID request.
- Dfid
Request - Finite DFID request. Depth exhaustion cannot establish model safety.
- Distributed
Options - Authenticated native distributed pure-safety options and actual work facts. Explicit coordinator endpoints and resource policy. Key bytes are read from the named local file and never included in reports, arguments or Debug values.
- Distributed
Usage - Authenticated native distributed pure-safety options and actual work facts. Actual work/retry facts; logical model counters include only ordered commit.
- Host
Access - Explicit host category grants. Every profile defaults to no grants. A grant never supplies an implementation or overrides a driver’s refusal.
- Original
AstReport - An in-memory original AST result; it never admits a generated specification.
- Original
AstWrite Report - Original-AST publication result. Available AST bytes are not a translated
module or model proof. Successful writes retain pinned
-writeASTexit 255. - Parse
Report - The outcome of parsing one file.
- Periodic
Schedule - Completed-level schedule for ordinary dive-profile temporal checking. When a completed, nonexhausted level is checked in dive’s default profile; the TLC profile checks once, at the end.
- Rewrite
Options - In-memory replacement limits and explicit overwrite policy.
- Rewrite
Report - Stage-separated replacement report; it never certifies a checked model.
- Rewrite
Request - Generation settings and in-memory editing policy.
- Seen
Limits - Limits for full disk keys, entries, probes and collision summaries. Deterministic resource bounds, checked before record allocation or index growth.
- Seen
Options - Bounded transient disk seen-state safety options. Explicit opt-in transient disk seen-state policy. Default checking retains the original resident store. These bounds cover on-disk membership and key workspaces, not total search/process memory.
- Simulate
Report - Concrete sampled traces and independently checked violation evidence.
- Simulate
Request - A finite simulation request. The caller must choose a positive trace count.
- Translation
Publication - An admitted translation and exact filesystem inputs awaiting explicit publication.
- Translation
Report - Stage-separated translation report. Acceptance never means a model proof.
- Translation
Request - Translation mode and explicit resource/module resolution settings.
- Worker
Info - Authenticated native distributed pure-safety options and actual work facts. Authenticated worker process facts, not remote attestation.
Enums§
- Action
Composition - Action composition modes (
--action-composition). Whether and howA \cdot B(action composition) is evaluated. - ApiError
- Errors from the API that are not diagnostics about the source.
- Budget
Setting - A run-budget setting: the profile’s default, no limit, or an explicit value.
- Checksum
Policy - Rewriting always computes the body CRC and uses an optional exact algorithm CRC.
- Exit
Convention - Process status conventions, independently of evaluator semantics.
- Store
- The store
dive checkuses. - Symmetry
Liveness - Shared whole-run policy for symmetry combined with temporal properties.
How a configured
SYMMETRYinteracts with genuine temporal properties. The TLC-equivalent request isSelf::Tlc; its quotient checking remains unsupported. Safety-only roles retain their existing reduction in every mode. - Temporal
Mode - Temporal checking strategy for a request.
- Translation
Fairness - Native PlusCal fairness selection, including pinned translator option spellings. Pinned translator fairness selection, applied before process normalization.
Constants§
- ANALYZE_
SCHEMA_ VERSION - Version of the JSON document produced by
AnalyzeReport::to_json. - CHECK_
SCHEMA_ VERSION - Version of ordinary safety JSON documents produced by
CheckReport::to_json. - DFID_
SCHEMA_ VERSION - Version of the DFID JSON report.
- PARSE_
SCHEMA_ VERSION - Version of the JSON document produced by
ParseReport::to_json. - REPORT_
SCHEMA_ VERSION - Version of every public operation’s JSON report.
- SIMULATE_
SCHEMA_ VERSION - Version of simulation reports, separate from exhaustive checking reports.
- TEMPORAL_
CHECK_ SCHEMA_ VERSION - Version of temporal JSON documents, shared with all public reports. Temporal claims require their actual final or prefix execution facts.
- TRANSLATE_
SCHEMA_ VERSION - Version of native translation report documents.
Functions§
- analyze_
file - Analyses the specification rooted at
path: module resolution, name resolution, arity and level checking, as SANY’s-error-codesrun. - analyze_
source - Analyses source text as the root module; other modules come only from
optionsand the standard modules. - check_
file - Loads, binds and checks the request with the compiled Core. What Core
does not implement is an
unsupportedverdict naming it. - check_
file_ checkpoint - Runs the native pure-safety checkpoint/recovery slice. It refuses temporal combinations before loading files. Existing frontier/predecessor budgets configure transient storage; native archive work is separately bounded and excluded from both budgets. Recovery uses saved seed/fingerprint defaults when not explicitly supplied; profile/store and all semantic options must match. Actual workers are reported separately.
- check_
file_ core_ opts - Checks with Core under explicit strategy switches, as
DIVE_CORE_OPTgives them (for example-memo,-delta-hash); the environment variable is ignored. Every switch must leave every result unchanged. - check_
file_ tlc_ inputs - Loads and checks files with TLC’s configuration-first input error priority.
- dfid_
file - Loads and runs a DFID model with the compiled Core, independently certifying every violation. A reached refusal stops; there is no fallback.
- original_
ast_ file - Reads bounded module source and returns its original AST entirely in memory.
- original_
ast_ source - Returns normalized original AST bytes for one algorithm in a module.
This explicit in-memory operation neither translates nor writes
AST.tla. It therefore performs no generated-module analysis or model checking. Modern procedure/macro ownership and compound source locations use genuine pre-generation controls; historical fields and full original-stage coverage remain unfinished. No original-stage header checksum is advertised. - parse_
config_ file - Reads and parses a cfg file, as TLC’s
-configdoes. - parse_
config_ source - Reads cfg text.
filenames it in reports. - parse_
file - Reads and parses a TLA+ file.
- parse_
seed - Parses a seed as TLC’s
-seeddoes (dive check --seed). Parses a seed as TLC’s-seeddoes (Long.parseLong): an optional+or-and decimal digits, within the range of a 64-bit signed integer. - parse_
source - Parses TLA+ source text.
filenames the source in reports and is used for SANY’s check that the module name matches the file name. - prepare_
core_ worker - Independently prepares the same pure Core model as a distributed coordinator.
- prepare_
translation_ file - Prepares a bounded PlusCal rewrite and cfg/backup updates without writing files.
Source-option
-noold/-nocfgsettings are effective, and the existing default modified-body protection and TLC overwrite policy are retained. - rewrite_
file - Read a bounded UTF-8 module and return its in-memory replacement plan.
- rewrite_
source - Generate, replace and validate a module in memory. Nothing is written to disk. An unavailable algorithm CRC disables only that value; body CRCs remain real. Existing unverified/modified bodies require an explicit replacement grant.
- simulate_
file - Loads and samples a specification with the compiled Core, and validates every returned trace separately.
- translate_
file - Translates a file in memory without rewriting it or invoking external tools. The file must contain one algorithm in a block comment. An existing translation is replaced in its original location; nothing is written to disk. Generated modules pass native syntax/name/level analysis before acceptance.
- translate_
source - Translates module source in memory. Artifact spans refer to generated body; original spans refer to this exact UTF-8 source. No file mapping/checksum compatibility or complete PlusCal translation coverage is implied.
- write_
original_ ast_ file - Writes the bounded pre-generation original AST to an explicit destination.
CLI
-writeASTpassesAST.tlain the current directory. The input module, its backup and configuration are unchanged; no translation is generated. - write_
translation_ file - Translates and publishes an admitted PlusCal module, backup and configuration.
This is the explicit write counterpart of
crate::rewrite_file.