Skip to main content

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}