Skip to main content

Crate dive_api

Crate dive_api 

Source
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):

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 native and the dive profile’s CheckReport::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§

AnalyzeOptions
Where dive analyze looks for modules besides the root file’s directory.
AnalyzeReport
The outcome of analysing a specification.
CheckReport
The outcome of dive check.
CheckRequest
What to check and how.
ConfigReport
The outcome of reading one cfg file.
CoreWorker
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.
DfidReport
Structured evidence and process disposition for a DFID request.
DfidRequest
Finite DFID request. Depth exhaustion cannot establish model safety.
DistributedOptions
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.
DistributedUsage
Authenticated native distributed pure-safety options and actual work facts. Actual work/retry facts; logical model counters include only ordered commit.
HostAccess
Explicit host category grants. Every profile defaults to no grants. A grant never supplies an implementation or overrides a driver’s refusal.
OriginalAstReport
An in-memory original AST result; it never admits a generated specification.
OriginalAstWriteReport
Original-AST publication result. Available AST bytes are not a translated module or model proof. Successful writes retain pinned -writeAST exit 255.
ParseReport
The outcome of parsing one file.
PeriodicSchedule
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.
RewriteOptions
In-memory replacement limits and explicit overwrite policy.
RewriteReport
Stage-separated replacement report; it never certifies a checked model.
RewriteRequest
Generation settings and in-memory editing policy.
SeenLimits
Limits for full disk keys, entries, probes and collision summaries. Deterministic resource bounds, checked before record allocation or index growth.
SeenOptions
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.
SimulateReport
Concrete sampled traces and independently checked violation evidence.
SimulateRequest
A finite simulation request. The caller must choose a positive trace count.
TranslationPublication
An admitted translation and exact filesystem inputs awaiting explicit publication.
TranslationReport
Stage-separated translation report. Acceptance never means a model proof.
TranslationRequest
Translation mode and explicit resource/module resolution settings.
WorkerInfo
Authenticated native distributed pure-safety options and actual work facts. Authenticated worker process facts, not remote attestation.

Enums§

ActionComposition
Action composition modes (--action-composition). Whether and how A \cdot B (action composition) is evaluated.
ApiError
Errors from the API that are not diagnostics about the source.
BudgetSetting
A run-budget setting: the profile’s default, no limit, or an explicit value.
ChecksumPolicy
Rewriting always computes the body CRC and uses an optional exact algorithm CRC.
ExitConvention
Process status conventions, independently of evaluator semantics.
Store
The store dive check uses.
SymmetryLiveness
Shared whole-run policy for symmetry combined with temporal properties. How a configured SYMMETRY interacts with genuine temporal properties. The TLC-equivalent request is Self::Tlc; its quotient checking remains unsupported. Safety-only roles retain their existing reduction in every mode.
TemporalMode
Temporal checking strategy for a request.
TranslationFairness
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-codes run.
analyze_source
Analyses source text as the root module; other modules come only from options and the standard modules.
check_file
Loads, binds and checks the request with the compiled Core. What Core does not implement is an unsupported verdict 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_OPT gives 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 -config does.
parse_config_source
Reads cfg text. file names it in reports.
parse_file
Reads and parses a TLA+ file.
parse_seed
Parses a seed as TLC’s -seed does (dive check --seed). Parses a seed as TLC’s -seed does (Long.parseLong): an optional + or - and decimal digits, within the range of a 64-bit signed integer.
parse_source
Parses TLA+ source text. file names 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/-nocfg settings 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 -writeAST passes AST.tla in 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.