Skip to main content

dive_runtime/
options.rs

1//! Checker options. Every option declares its TLC setting, the value
2//! `--compat=tlc` selects.
3
4use dive_eval::{Options, Profile};
5use dive_store::StoreMode;
6
7/// How to run a check.
8#[derive(Clone, Debug)]
9pub struct CheckOptions {
10    /// Optional owned external inputs for source binding. Runtime reads and
11    /// checkpoint/recovery are not implemented; evaluator grants stay explicit.
12    pub inputs: Option<std::sync::Arc<dyn dive_eval::inputs::InputSource>>,
13    /// Opt-in transient fallible disk seen-state retention.
14    /// `None` keeps the seen set resident in memory. Disk runs use an explicitly
15    /// reported inline fallback; this is not a total-memory or recovery budget.
16    pub seen_disk: Option<crate::SeenOptions>,
17    /// Opt-in encoded resident budget per current/next frontier queue. TLC uses
18    /// its disk queue; `None` keeps the in-memory equivalence reference. This
19    /// bounds frontier bytes only, not seen sets, candidates, traces or graphs.
20    pub frontier_memory_bytes: Option<usize>,
21    /// Parent directory for private transient frontier files; system temp by
22    /// default. Files are explicitly cleaned and failures reported.
23    pub frontier_directory: Option<std::path::PathBuf>,
24    /// Encoded candidate bytes per worker under explicit Core safety BFS.
25    /// None is the resident TLC-equivalent reference; zero immediately spills.
26    /// Active evaluator roots, codec scratch and accepted Store are outside it.
27    pub candidate_memory_bytes: Option<usize>,
28    /// Parent for private transient candidate files; requires a candidate budget.
29    pub candidate_directory: Option<std::path::PathBuf>,
30    /// Completed-level measured Store-byte trigger for explicit pure Core safety.
31    /// Zero forces each boundary; None is TLC-equivalent. This is not a hard cap.
32    pub store_compact_bytes: Option<usize>,
33    /// Separate retained predecessor capacity budget. `None` preserves the
34    /// in-memory TLC counterpart; zero immediately spills native records.
35    /// Seen sets, frontiers, candidates, graphs and reconstructed paths are
36    /// outside this limit. Only ordinary safety BFS is admitted.
37    pub predecessor_memory_bytes: Option<usize>,
38    /// Parent of private transient predecessor directories. Requires a budget;
39    /// omitted uses the system temporary directory. Not a checkpoint location.
40    pub predecessor_directory: Option<std::path::PathBuf>,
41    /// The profile: dive's default or `--compat=tlc`.
42    pub profile: Profile,
43    /// Whole-run symmetry policy for genuine temporal properties. TLC checks a
44    /// symmetry-reduced graph, which can miss or invent liveness violations.
45    /// TLC-equivalent: `Tlc`; unsupported quotient checking still refuses.
46    pub symmetry_liveness: dive_model::SymmetryLiveness,
47    /// Evaluation options (`Options::tlc()` under `--compat=tlc`).
48    pub eval: Options,
49    /// Fingerprint mode (the default, as in TLC) or exact mode
50    /// (`--store exact`, full states with an unconditional exhaustiveness
51    /// claim). TLC setting: fingerprint.
52    pub store: StoreMode,
53    /// TLC's fingerprint polynomial index (`-fp`), `0..131`. TLC setting:
54    /// random per run unless given; the default profile fixes it at 0.
55    pub fp_index: usize,
56    /// Whether to key the fingerprint set on TLC's own state fingerprints in
57    /// TLC's variable order (`StateFingerprinter::tlc`), or on dive's cheaper
58    /// two-level fingerprints (`StateFingerprinter::new`: cached FP64 value
59    /// fingerprints combined by a non-linear, position-keyed mixer chain).
60    /// TLC setting: `true`, which `--compat=tlc` uses so that
61    /// the fingerprint set and the "actual" collision figure are TLC's; the
62    /// default profile uses dive's. Result-preserving: only a collision could
63    /// tell them apart.
64    pub tlc_fingerprints: bool,
65    /// The run's seed (always reported, so `--seed` replays the run).
66    pub seed: i64,
67    /// TLC's `-deadlock` flag: do not check deadlock, whatever the
68    /// configuration says.
69    pub no_deadlock: bool,
70    /// Worker threads (`--workers`). Results are identical at every count.
71    /// TLC setting: 1, TLC's default; a spec that depends on
72    /// TLC's sequential side effects runs with one logical worker whatever
73    /// this says (sequential mode), and the result says so.
74    /// Final/short graph capture expands at most
75    /// [`crate::capture::MAX_EXPANSION_UNITS`] source units concurrently even
76    /// with a wider pool; its scratch admission bound is reported separately.
77    pub workers: usize,
78    /// Run every level inline on one thread, as sequential mode does, even
79    /// when the specification does not need it. For tests and diagnosis
80    /// (`--sequential`); results are identical either way.
81    pub sequential: bool,
82    /// Test-only chaos (`--chaos SEED`, hidden): randomize block sizes, the
83    /// order in which workers claim blocks and shards, the split of narrow
84    /// levels, whether small phases run inline, and insert random yields.
85    /// Results must not change; any change is a determinism bug.
86    pub chaos: Option<u64>,
87    /// The run's time and memory limits. A run arms an unarmed
88    /// budget for itself; a caller that runs several stages
89    /// (capture, then temporal analysis) arms it once with
90    /// [`crate::budget::Budget::start`] so the stages share one clock.
91    /// Unlimited here; `dive_api` resolves the profile's defaults. TLC
92    /// setting: no time limit, memory bounded by its heap.
93    pub budget: crate::budget::Budget,
94    /// Maximum admitted distinct in-model identities; `None` is TLC-equivalent.
95    /// Duplicate states do not consume this budget.
96    pub max_states: Option<u64>,
97    /// Maximum breadth-first discovery depth; initial states have depth one.
98    /// `None` is TLC-equivalent; TLC's simulation `-depth` is unrelated.
99    pub max_depth: Option<u64>,
100}
101
102impl CheckOptions {
103    /// `--compat=tlc` with `-fp index` and `-seed seed`.
104    #[must_use]
105    pub const fn tlc(fp_index: usize, seed: i64) -> Self {
106        Self {
107            inputs: None,
108            seen_disk: None,
109            frontier_memory_bytes: None,
110            frontier_directory: None,
111            candidate_memory_bytes: None,
112            candidate_directory: None,
113            store_compact_bytes: None,
114            predecessor_memory_bytes: None,
115            predecessor_directory: None,
116            profile: Profile::Tlc,
117            symmetry_liveness: dive_model::SymmetryLiveness::Tlc,
118            eval: Options::tlc(),
119            store: StoreMode::Fingerprint,
120            fp_index,
121            tlc_fingerprints: true,
122            seed,
123            no_deadlock: false,
124            workers: 1,
125            sequential: false,
126            chaos: None,
127            budget: crate::budget::Budget::unlimited(),
128            max_states: None,
129            max_depth: None,
130        }
131    }
132
133    /// dive's default profile with `seed`.
134    #[must_use]
135    pub const fn dive(seed: i64) -> Self {
136        Self {
137            inputs: None,
138            seen_disk: None,
139            frontier_memory_bytes: None,
140            frontier_directory: None,
141            candidate_memory_bytes: None,
142            candidate_directory: None,
143            store_compact_bytes: None,
144            predecessor_memory_bytes: None,
145            predecessor_directory: None,
146            profile: Profile::Dive,
147            symmetry_liveness: dive_model::SymmetryLiveness::Unreduced,
148            eval: Options::dive(),
149            store: StoreMode::Fingerprint,
150            fp_index: 0,
151            tlc_fingerprints: false,
152            seed,
153            no_deadlock: false,
154            workers: 1,
155            sequential: false,
156            chaos: None,
157            budget: crate::budget::Budget::unlimited(),
158            max_states: None,
159            max_depth: None,
160        }
161    }
162}