dive_eval/options.rs
1//! Evaluation options: the run's value semantics plus the evaluator's own
2//! profile-dependent choices.
3
4use dive_value::{Ctx, IntMode, ValueOrder};
5
6/// The two profiles: dive's default and `--compat=tlc`.
7#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
8pub enum Profile {
9 /// dive's default profile: TLC-compatible except where dive has a better
10 /// default (big integers, canonical value order, TLA+ comparisons, TLA+
11 /// action composition).
12 #[default]
13 Dive,
14 /// `--compat=tlc`: every behaviour exactly TLC's.
15 Tlc,
16}
17
18/// In which order the evaluator *explores* sets: the bound sets of `\E` and
19/// `\A`, set filters `{x \in S : P}`, set maps `{e : x \in S}`, function
20/// constructors and (in `dive_eval::next`) `x' \in S`.
21///
22/// `CHOOSE` always follows the run's [`ValueOrder`]. Exploration follows it
23/// too in the default profile, so the default profile is independent of the
24/// module text; `--compat=tlc` keeps TLC's order. The two can report a
25/// different one of several violations at the same depth.
26#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
27pub enum ExplorationOrder {
28 /// TLC's normalized order (names by intern token), whatever the run's
29 /// [`ValueOrder`]. `--explore-order=tlc`; part of `--compat=tlc`.
30 #[default]
31 Tlc,
32 /// The run's [`ValueOrder`] (canonical in the default profile):
33 /// `--explore-order=value`. The default profile's setting.
34 Value,
35}
36
37/// How `=` and `\in` treat values that TLC refuses to compare.
38///
39/// TLC's rules are asymmetric and order-dependent: `[a |-> 1, b |-> 1] =
40/// <<1>>` is an error while `<<1>> = [a |-> 1, b |-> 1]` is `FALSE`.
41/// `--comparisons=tla` answers such tests as TLA+ defines them. It is
42/// result-changing and is the default profile's setting; `--compat=tlc`
43/// keeps TLC's rules.
44#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
45pub enum Comparisons {
46 /// TLC's checked `equals` and `member`, with TLC's errors.
47 /// `--comparisons=tlc`; part of `--compat=tlc`.
48 #[default]
49 Tlc,
50 /// TLA+'s answers for `=` and `\in` between functions (including records
51 /// and tuples) and sets: symmetric and independent of element order. The
52 /// error is kept only where TLA+ leaves the answer unspecified (`1 = "a"`,
53 /// `{1} = 1`). `--comparisons=tla`; the default profile's setting.
54 Tla,
55}
56
57/// Whether and how `A \cdot B` (action composition) is evaluated.
58///
59/// TLC refuses action composition unless the JVM runs with
60/// `-Dtlc2.tool.impl.Tool.cdot=true`, which enables what TLC calls an
61/// incomplete implementation (`Tool.java`, `OPCODE_cdot`). dive implements the
62/// operator by default, with its TLA+ meaning: `s -(A \cdot B)-> u` iff some
63/// state `t` has `s -A-> t` and `t -B-> u`.
64#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
65pub enum ActionComposition {
66 /// TLC without the switch: every use is TLC's error
67 /// (`--action-composition=off`; part of `--compat=tlc`).
68 Off,
69 /// TLC with `-Dtlc2.tool.impl.Tool.cdot=true`, reproduced exactly
70 /// (`--action-composition=tlc`): the intermediate states count as
71 /// generated (so a state whose only `A` steps have no `B` step is not a
72 /// deadlock), the rest of an enclosing conjunction is evaluated after `A`
73 /// as well as after `B`, and a variable the conjunction already assigned
74 /// is pre-set in the intermediate state to its current value.
75 Tlc,
76 /// The TLA+ meaning (`--action-composition=tla`, the default profile's
77 /// setting): only composed successors are generated, and a composition
78 /// whose result TLC's algorithm would distort (one with a continuation or
79 /// with variables already assigned) is refused by name, never
80 /// approximated.
81 #[default]
82 Tla,
83}
84
85/// The evaluator's options.
86#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
87pub struct Options {
88 /// Explicit host categories; empty in both profile defaults, so a
89 /// specification gets host access only when the run grants it.
90 pub host_access: crate::inputs::HostAccess,
91 /// The value semantics: integer mode and value (`CHOOSE`) order.
92 pub ctx: Ctx,
93 /// The exploration order.
94 pub exploration: ExplorationOrder,
95 /// Comparison semantics.
96 pub comparisons: Comparisons,
97 /// The maximum evaluation depth (nested operator applications, function
98 /// applications and set constructions). Exceeding it is a resource limit
99 /// naming the construct, never a stack overflow.
100 pub max_depth: u32,
101 /// TLC's warning switch (`TLCGlobals.warn`; `-nowarning` turns it off).
102 /// Besides printing warnings, it enables TLC's all-assigned fast path in
103 /// successor generation (`Tool.getNextStatesAllAssigned`), which changes
104 /// how many successors are generated, so it is part of the semantics.
105 /// `true` in both profiles, as in TLC.
106 pub warnings: bool,
107 /// Action composition (`\cdot`).
108 pub action_composition: ActionComposition,
109}
110
111/// The stack size evaluation needs at [`DEFAULT_MAX_DEPTH`], with room to
112/// spare, in an unoptimized build. Run evaluation on a thread with at least
113/// this much stack (workers run on threads with large stacks).
114pub const RECOMMENDED_STACK: usize = 256 << 20;
115
116/// The default evaluation depth limit. Evaluation runs on the caller's stack;
117/// callers that raise this must provide a correspondingly large stack.
118pub const DEFAULT_MAX_DEPTH: u32 = 400;
119
120impl Options {
121 /// `--compat=tlc`: every option at its TLC setting.
122 #[must_use]
123 pub const fn tlc() -> Self {
124 Self {
125 host_access: crate::inputs::HostAccess::NONE,
126 ctx: Ctx::tlc(),
127 exploration: ExplorationOrder::Tlc,
128 comparisons: Comparisons::Tlc,
129 max_depth: DEFAULT_MAX_DEPTH,
130 warnings: true,
131 action_composition: ActionComposition::Off,
132 }
133 }
134
135 /// dive's default profile.
136 ///
137 /// - Big integers and canonical `CHOOSE` order.
138 /// - Exploration in the canonical order.
139 /// - TLA+ comparison answers.
140 /// - Action composition with its TLA+ meaning.
141 #[must_use]
142 pub const fn dive() -> Self {
143 Self {
144 host_access: crate::inputs::HostAccess::NONE,
145 ctx: Ctx::dive(),
146 exploration: ExplorationOrder::Value,
147 comparisons: Comparisons::Tla,
148 max_depth: DEFAULT_MAX_DEPTH,
149 warnings: true,
150 action_composition: ActionComposition::Tla,
151 }
152 }
153
154 /// Whether every option is at its TLC setting (a pure `--compat=tlc` run).
155 #[must_use]
156 pub fn is_tlc(&self) -> bool {
157 self.ctx.int_mode == IntMode::Tlc
158 && self.ctx.order == ValueOrder::Tlc
159 && self.exploration == ExplorationOrder::Tlc
160 && self.comparisons == Comparisons::Tlc
161 && self.action_composition != ActionComposition::Tla
162 }
163
164 /// The order sets are explored in.
165 #[must_use]
166 pub(crate) fn explore_order(self) -> ValueOrder {
167 match self.exploration {
168 ExplorationOrder::Tlc => ValueOrder::Tlc,
169 ExplorationOrder::Value => self.ctx.order,
170 }
171 }
172}
173
174impl Default for Options {
175 fn default() -> Self {
176 Self::dive()
177 }
178}
179
180#[cfg(test)]
181mod tests {
182 use super::*;
183
184 #[test]
185 fn tlc_profile_is_pure_tlc() {
186 assert!(Options::tlc().is_tlc());
187 assert!(!Options::dive().is_tlc());
188 }
189
190 #[test]
191 fn owner_decisions_set_the_default_profile() {
192 // Open questions 9 and 12, answered 2026-10-08: canonical
193 // exploration (D-010) and TLA+ comparisons (D-009) by default;
194 // `--compat=tlc` keeps TLC's behaviour.
195 assert_eq!(Options::dive().exploration, ExplorationOrder::Value);
196 assert_eq!(Options::dive().comparisons, Comparisons::Tla);
197 assert_eq!(Options::tlc().exploration, ExplorationOrder::Tlc);
198 assert_eq!(Options::tlc().comparisons, Comparisons::Tlc);
199 }
200}