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}