Skip to main content

dive_api/
simulate.rs

1//! Finite seeded safety simulation with independent trace validation.
2
3use crate::trace::{Ending, SpecModel, TraceDoc, TraceOptions};
4use dive_sim::{Options, Outcome};
5use dive_stdlib::random::RandomMode;
6use serde_json::{Value, json};
7use std::fmt::Write as _;
8use std::path::PathBuf;
9
10/// Version of simulation reports, separate from exhaustive checking reports.
11pub const SIMULATE_SCHEMA_VERSION: u32 = crate::REPORT_SCHEMA_VERSION;
12
13/// A finite simulation request. The caller must choose a positive trace count.
14///
15/// ```
16/// let request = dive_api::SimulateRequest {
17///     file: "Counter.tla".into(), seed: Some(7), traces: 10,
18///     depth: Some(100), ..Default::default()
19/// };
20/// assert_eq!(request.traces, 10);
21/// ```
22#[derive(Clone, Debug, Default)]
23#[allow(
24    clippy::struct_excessive_bools,
25    reason = "independent public simulation options retain their existing boolean API"
26)]
27pub struct SimulateRequest {
28    /// Root specification.
29    pub file: PathBuf,
30    /// Configuration; defaults to the specification's `.cfg` sibling.
31    pub config: Option<PathBuf>,
32    /// TLC's value semantics; exact random draws are not a parity obligation.
33    pub compat_tlc: bool,
34    /// Run seed; generated and reported when omitted.
35    pub seed: Option<i64>,
36    /// TLC's simulation seed adjustment; zero outside TLC mode.
37    pub aril: u64,
38    /// Maximum transitions per trace; `None` selects TLC's depth 100.
39    pub depth: Option<usize>,
40    /// Positive, finite number of traces, required by the API and CLI.
41    pub traces: u64,
42    /// Requested workers; only one is supported in this initial slice.
43    pub workers: Option<usize>,
44    /// TLC's `-deadlock`: disable deadlock checking.
45    pub no_deadlock: bool,
46    /// Collect source-location action flows, corresponding to TLC `stats=basic`.
47    pub action_stats: bool,
48    /// Construct one successor per selected action instead of retaining all
49    /// candidates. This is finite sampling, never exhaustive checking.
50    /// `true` corresponds to TLC `-generate num=N`; `false` to `-simulate num=N`.
51    pub generation: bool,
52    /// Time limit; the profile default matches `dive check`. `Unlimited` is TLC-equivalent.
53    pub time_limit: crate::BudgetSetting<std::time::Duration>,
54    /// Sampled process-memory ceiling; the default is half physical memory.
55    pub max_memory: crate::BudgetSetting<u64>,
56    /// Modules searched before standard modules.
57    pub library_paths: Vec<PathBuf>,
58    /// Modules searched after standard modules.
59    pub module_paths: Vec<PathBuf>,
60}
61
62/// Concrete sampled traces and independently checked violation evidence.
63#[derive(Debug)]
64pub struct SimulateReport {
65    document: Value,
66    exit: u8,
67}
68
69impl SimulateReport {
70    /// Versioned JSON. `exhaustive` and `model_proved` are always false.
71    #[must_use]
72    pub fn to_json(&self) -> Value {
73        self.document.clone()
74    }
75
76    /// Profile-specific exit status; sampling without an error exits zero.
77    #[must_use]
78    pub const fn exit_code(&self) -> u8 {
79        self.exit
80    }
81
82    /// Process status under an explicit convention, independently of value
83    /// semantics. Refusals, resource stops and internal errors keep their status.
84    #[must_use]
85    pub fn exit_code_for(&self, convention: crate::ExitConvention) -> u8 {
86        let code = self.document["tlc_code"]
87            .as_u64()
88            .and_then(|code| u32::try_from(code).ok());
89        match (self.document["result"].as_str(), code) {
90            (Some("violation"), Some(code)) => match convention {
91                crate::ExitConvention::Tlc => tlc_exit(code),
92                crate::ExitConvention::Native => {
93                    if code == 2114 {
94                        11
95                    } else {
96                        10
97                    }
98                }
99            },
100            (Some("evaluation-error"), Some(code)) => match convention {
101                crate::ExitConvention::Tlc => tlc_exit(code),
102                crate::ExitConvention::Native => 13,
103            },
104            _ => self.exit,
105        }
106    }
107
108    /// Versioned report with an explicitly selected process-status convention.
109    /// The simulation remains non-exhaustive under either convention.
110    #[must_use]
111    pub fn to_json_with_exit_convention(&self, convention: crate::ExitConvention) -> Value {
112        let mut document = self.to_json();
113        document["exit_code"] = json!(self.exit_code_for(convention));
114        document["options"]["exit_codes"] = json!(match convention {
115            crate::ExitConvention::Native => "native",
116            crate::ExitConvention::Tlc => "tlc",
117        });
118        document
119    }
120
121    /// Human-readable sampling summary that never claims a proof.
122    #[must_use]
123    pub fn render_human(&self) -> String {
124        let mut text = String::new();
125        for field in ["startup_output", "runtime_output"] {
126            if let Some(events) = self.document[field].as_array() {
127                for event in events {
128                    if let Some(line) = event["text"].as_str() {
129                        text.push_str(line);
130                        text.push('\n');
131                    }
132                }
133            }
134        }
135        let _ = write!(
136            text,
137            "simulation: {} ({} traces, {} generated states; no exhaustive proof)\nseed: {}\n",
138            self.document["result"].as_str().unwrap_or("internal-error"),
139            self.document["statistics"]["traces_started"],
140            self.document["statistics"]["generated"],
141            self.document["options"]["seed"]
142        );
143        // A refusal, limit or error names its reason, as in the JSON `message`.
144        if let (Some(result), Some(message)) = (
145            self.document["result"].as_str(),
146            self.document["message"].as_str(),
147        ) {
148            let _ = writeln!(text, "{result}: {message}");
149        }
150        if let Some(transitions) = self.document["action_flow"]["transitions"].as_array() {
151            text.push_str("action flow (chosen transitions):\n");
152            for edge in transitions {
153                let _ = writeln!(
154                    text,
155                    "  group {} -> group {}: {}",
156                    edge["from"], edge["to"], edge["count"]
157                );
158            }
159        }
160        if let Some(notes) = self.document["notes"].as_array() {
161            for note in notes.iter().filter_map(Value::as_str) {
162                let _ = writeln!(text, "note: {note}");
163            }
164        }
165        text
166    }
167}
168
169/// Loads and samples a specification with the compiled Core, and validates
170/// every returned trace separately.
171///
172/// What Core does not implement is a named refusal, and a reached refusal
173/// never reruns effects.
174///
175/// # Errors
176/// Unreadable/rejected files, unimplemented binding, or worker-thread failure.
177#[allow(
178    clippy::too_many_lines,
179    reason = "report construction keeps the simulation and independent validation evidence together"
180)]
181pub fn simulate_file(req: &SimulateRequest) -> Result<SimulateReport, crate::ApiError> {
182    let seed = req.seed.unwrap_or_else(dive_stdlib::random::fresh_seed);
183    let options = Options::new(
184        seed,
185        if req.compat_tlc {
186            RandomMode::Tlc
187        } else {
188            RandomMode::Dive
189        },
190        req.depth.unwrap_or(100),
191        req.traces,
192    );
193    let options = Options {
194        action_stats: req.action_stats,
195        generation: req.generation,
196        aril: if req.compat_tlc && req.seed.is_none() {
197            0
198        } else {
199            req.aril
200        },
201        ..options
202    };
203    let config = req
204        .config
205        .clone()
206        .unwrap_or_else(|| req.file.with_extension("cfg"));
207    let runtime = dive_sim::Runtime::new(options.clone());
208    let model = SpecModel::load_hosted(
209        &req.file,
210        &config,
211        &TraceOptions {
212            compat_tlc: req.compat_tlc,
213            no_deadlock: req.no_deadlock,
214            run: Some((seed, 0)),
215            library_paths: req.library_paths.clone(),
216            module_paths: req.module_paths.clone(),
217            ..TraceOptions::default()
218        },
219        Some(runtime.host()),
220    )?;
221    runtime.set_config(Some(crate::trace::make_run_config(model.model(), seed, 0)));
222    let mut run_budget = crate::mode_budget::ModeBudget::start(
223        dive_runtime::budget::Phase::Simulation,
224        req.time_limit,
225        req.max_memory,
226    )?;
227    let control = run_budget.control()?;
228    let control_scope =
229        control
230            .enter(&model.model().evaluator)
231            .map_err(|error| crate::ApiError::Rejected {
232                message: error.to_string(),
233            })?;
234    let mut native = None;
235    let mut setup_failure = None;
236    if req.workers.is_none_or(|workers| workers == 1) {
237        if let Some(outcome) = dive_sim::preflight(model.model(), &options) {
238            setup_failure = Some(outcome);
239        } else {
240            match crate::core_modes::Native::probe(
241                &model,
242                seed,
243                options.mode,
244                &run_budget.budget,
245                control.clone(),
246            ) {
247                Ok(prepared) => native = Some(prepared),
248                Err(error) => setup_failure = Some(error.simulation()),
249            }
250        }
251    }
252    let result = if let Some(outcome) = setup_failure {
253        crate::core_modes::preflight_report(outcome)
254    } else if req.workers.is_some_and(|n| n != 1) {
255        dive_sim::Report {
256            stage: "preflight",
257            outcome: Outcome::Unsupported("parallel simulation workers".to_owned()),
258            generated: 0,
259            initial_candidates: 0,
260            pending_violation: None,
261            traces_started: 0,
262            traces: Vec::new(),
263            action_flow: None,
264            runtime_output: Vec::new(),
265        }
266    } else {
267        let executed = std::thread::scope(|scope| {
268            std::thread::Builder::new()
269                .stack_size(dive_eval::RECOMMENDED_STACK)
270                .spawn_scoped(scope, || {
271                    let poll = || run_budget.budget.poll() != Ok(None);
272                    if let Some(native) = &mut native {
273                        native.simulate(model.model(), &options, &runtime, &poll)
274                    } else {
275                        crate::core_modes::preflight_report(Outcome::Internal(
276                            "Core simulation was neither prepared nor refused".to_owned(),
277                        ))
278                    }
279                })
280                .map_err(|e| (0_u8, format!("cannot start simulation worker: {e}")))?
281                .join()
282                .map_err(|_| {
283                    (
284                        1_u8,
285                        "simulation worker failed internally; statistics unavailable".to_owned(),
286                    )
287                })
288        });
289        match executed {
290            Ok(result) => result,
291            Err((workers_used, message)) => {
292                return Ok(SimulateReport {
293                    exit: 4,
294                    document: json!({
295                        "schema_version": SIMULATE_SCHEMA_VERSION, "command": "simulate",
296                        "file": req.file.display().to_string(), "config": config.display().to_string(),
297                        "profile": if req.compat_tlc { if matches!(req.time_limit, crate::BudgetSetting::Explicit(_)) { "tlc+overrides" } else { "tlc" } } else { "dive" },
298                        "result": "internal-error", "exhaustive": false, "model_proved": false,
299                        "message": message, "exit_code": 4, "violation_validated": false,
300                        "options": { "seed": seed, "seed_given": req.seed.is_some(),
301                            "aril": options.aril, "aril_requested": req.aril,
302                            "action_stats": req.action_stats,
303                            "depth": options.depth, "traces": options.traces,
304                            "workers_requested": req.workers.unwrap_or(1), "workers_used": workers_used,
305                            "execution_stage": if workers_used == 0 { "worker-start" } else { "worker-failure" } },
306                        "statistics": { "scope": "unavailable", "generated": null, "traces_started": null },
307                        "traces": [],
308                    }),
309                });
310            }
311        }
312    };
313    let (kind, code, message, default_exit) = match &result.outcome {
314        Outcome::Sampled => ("sampled", None, None, 0),
315        Outcome::Violation { code, .. } => (
316            "violation",
317            Some(*code),
318            None,
319            if *code == 2114 { 11 } else { 10 },
320        ),
321        Outcome::Error { code, message } => {
322            ("evaluation-error", Some(*code), Some(message.clone()), 13)
323        }
324        Outcome::Unsupported(s) => ("unsupported", None, Some(s.clone()), 3),
325        Outcome::Limit(s) => ("resource-limit", None, Some(s.clone()), 3),
326        Outcome::Cancelled => (
327            "resource-limit",
328            None,
329            Some("simulation cancelled by caller".to_owned()),
330            3,
331        ),
332        Outcome::Internal(s) => ("internal-error", None, Some(s.clone()), 4),
333    };
334    let mut traces = Vec::new();
335    let mut trace_refusal = None;
336    'documents: for (number, trace) in result.traces.iter().enumerate() {
337        if run_budget.budget.poll() != Ok(None) {
338            break;
339        }
340        let states: Result<Vec<_>, _> = trace
341            .states
342            .iter()
343            .map(|state| {
344                if run_budget.budget.poll() != Ok(None) {
345                    return Err("run budget exhausted during trace serialization".to_owned());
346                }
347                let mut object = serde_json::Map::new();
348                for (var, value) in model.model().ir.vars().iter().zip(state.iter()) {
349                    let value = value
350                        .as_ref()
351                        .ok_or_else(|| "incomplete sampled trace".to_owned())?;
352                    object.insert(
353                        model.model().ir.decl(*var).name.clone(),
354                        dive_trace::value_json::to_json(
355                            value,
356                            model.model().evaluator.options().ctx,
357                        )?,
358                    );
359                }
360                Ok::<_, String>(Value::Object(object))
361            })
362            .collect();
363        let states = match states {
364            Ok(states) => states,
365            Err(feature) => {
366                trace_refusal = Some(format!(
367                    "simulation concrete trace serialization: {feature}"
368                ));
369                break;
370            }
371        };
372        let ending = match &result.outcome {
373            Outcome::Violation {
374                kind, name, trace, ..
375            } if *trace == number => match *kind {
376                "invariant" => Ending::Invariant(name.clone().unwrap_or_default()),
377                "property" => Ending::Property(name.clone().unwrap_or_default()),
378                _ => Ending::Deadlock,
379            },
380            _ => Ending::Behavior,
381        };
382        let document = TraceDoc::behavior(states)
383            .map_err(|message| crate::ApiError::Rejected { message })?
384            .with_ending(ending);
385        // Validation replays the given states; it never reruns the simulation.
386        let validated = if matches!(result.outcome, Outcome::Sampled | Outcome::Violation { .. }) {
387            model.validate_sample_mode(&document, control.clone())
388        } else {
389            // Diagnostic error prefixes can include the actual failing row.
390            // They carry no claim that every safety obligation passed there.
391            model.validate_mode(&document, control.clone())
392        };
393        let validation = match validated {
394            Ok(validation) => validation,
395            Err(error) => {
396                trace_refusal = Some(format!("simulation trace validation interrupted: {error}"));
397                break;
398            }
399        };
400        let mut compressed = Vec::<usize>::new();
401        for (index, state) in trace.states.iter().enumerate() {
402            if run_budget.budget.poll() != Ok(None) {
403                break 'documents;
404            }
405            let same = if let Some(&previous) = compressed.last() {
406                let mut equal = true;
407                for (left, right) in trace.states[previous].iter().zip(state.iter()) {
408                    if let (Some(left), Some(right)) = (left, right) {
409                        match model.model().evaluator.equal_values(left, right) {
410                            Ok(same) => equal &= same,
411                            Err(error) => {
412                                trace_refusal =
413                                    Some(format!("simulation trace compression: {error}"));
414                                break 'documents;
415                            }
416                        }
417                    }
418                }
419                equal
420            } else {
421                false
422            };
423            if !same {
424                compressed.push(index);
425            }
426        }
427        let tlc_states: Vec<_> = compressed
428            .iter()
429            .map(|&i| document.states[i].clone())
430            .collect();
431        traces.push(json!({ "id": trace.id, "document": document.to_json(), "tlc_states": tlc_states, "validation": crate::trace::report_json(&validation) }));
432    }
433    let validation_failed = traces
434        .iter()
435        .any(|t| t["validation"]["result"] == "invalid");
436    let violation_validated = match &result.outcome {
437        Outcome::Violation { trace, .. } => traces
438            .get(*trace)
439            .is_some_and(|t| t["validation"]["result"] == "valid"),
440        _ => false,
441    };
442    let undecidable = trace_refusal.is_some()
443        || (matches!(result.outcome, Outcome::Violation { .. }) && !violation_validated)
444        || (matches!(result.outcome, Outcome::Sampled)
445            && traces.iter().any(|t| t["validation"]["result"] != "valid"));
446    let (reported_kind, reported_code, reported_message) = if validation_failed {
447        (
448            "internal-error",
449            None,
450            Some("independent simulation trace validation rejected the candidate".to_owned()),
451        )
452    } else if let Some(feature) = trace_refusal {
453        ("unsupported", None, Some(feature))
454    } else if undecidable {
455        let reasons: Vec<_> = traces
456            .iter()
457            .filter_map(|t| t["validation"]["unsupported"].as_str())
458            .collect();
459        (
460            "unsupported",
461            None,
462            Some(format!(
463                "independent simulation trace validation: {}",
464                reasons.join("; ")
465            )),
466        )
467    } else {
468        (kind, code, message)
469    };
470    let mut exit = if validation_failed {
471        4
472    } else if undecidable {
473        3
474    } else if req.compat_tlc {
475        code.map_or(default_exit, tlc_exit)
476    } else {
477        default_exit
478    };
479    let startup: Vec<_> = model
480        .model()
481        .output
482        .iter()
483        .map(|m| match m {
484            dive_model::Message::Print(text) => json!({"kind": "print", "text": text}),
485            dive_model::Message::Warning { code, message } => {
486                json!({"kind": "warning", "code": code.code(), "text": message})
487            }
488        })
489        .collect();
490    let violation = match &result.outcome {
491        Outcome::Violation {
492            kind, name, trace, ..
493        } => Some(json!({"kind": kind, "name": name, "trace": trace})),
494        _ => None,
495    };
496    let pending_violation = result.pending_violation.as_ref().map(|pending| {
497        json!({"kind": pending.kind, "name": pending.name, "tlc_code": pending.code,
498            "validation": "unavailable", "reason": "complete trace exceeds retained-state bound"})
499    });
500    let action_flow = result.action_flow.as_ref().map(|flow| {
501        let actions: Vec<_> = flow.actions.iter().map(|action| json!({
502            "id": action.id, "name": action.name, "label": action.label,
503            "initial": action.initial, "bound_action_ids": action.bound_action_ids,
504            "location": {"module": action.location.file.map(|f| &model.model().ir.files()[f.index()].module),
505                "begin": action.location.begin, "end": action.location.end},
506        })).collect();
507        let transitions: Vec<_> = flow.transitions.iter().map(|(&(from, to), &count)| {
508            json!({"from": from, "to": to, "count": count})
509        }).collect();
510        json!({"mode": "basic", "scope": "chosen-transitions", "actions": actions,
511            "transitions": transitions})
512    });
513    let mut document = json!({
514        "schema_version": SIMULATE_SCHEMA_VERSION, "command": "simulate",
515        "file": req.file.display().to_string(), "config": config.display().to_string(),
516        "profile": if req.compat_tlc { if matches!(req.time_limit, crate::BudgetSetting::Explicit(_)) { "tlc+overrides" } else { "tlc" } } else { "dive" },
517        "result": reported_kind, "observed_result": kind, "observed_tlc_code": code, "exhaustive": false, "model_proved": false,
518        "tlc_code": reported_code, "message": reported_message, "exit_code": exit,
519        "violation_validated": violation_validated, "observed_violation": violation, "pending_violation": pending_violation, "startup_output": startup,
520        "options": { "seed": seed, "seed_given": req.seed.is_some(), "aril": options.aril, "aril_requested": req.aril,
521            "depth": options.depth, "traces": options.traces, "workers_requested": req.workers.unwrap_or(1),
522            "workers_used": u8::from(result.stage != "preflight"),
523            "execution_stage": result.stage, "execution_scope": "simulation-backend",
524            "mode": "finite-safety", "probabilistic": req.generation,
525            "algorithm": if req.generation { "constructive" } else { "enumerating" },
526            "action_stats": req.action_stats,
527            "max_output_events": options.max_output_events, "max_output_bytes": options.max_output_bytes },
528        "statistics": { "generated": result.generated, "initial_candidates": result.initial_candidates, "traces_started": result.traces_started,
529            "scope": if matches!(result.outcome, Outcome::Sampled) { "complete-request" } else { "completed-prefix" } },
530        "traces": traces, "action_flow": action_flow,
531        "runtime_output": result.runtime_output.iter().map(|event| json!({
532            "kind": if event.warning { "warning" } else { "print" }, "text": event.text,
533        })).collect::<Vec<_>>(),
534    });
535    // ALIAS is not applied, as in checking:
536    // the traces show the states themselves, and the report says so.
537    let mut notes = Vec::new();
538    if !traces.is_empty()
539        && let Some(Ok(alias)) = &model.model().alias
540    {
541        notes.push(format!(
542            "ALIAS {} is not applied: the traces show the states themselves (not implemented yet).",
543            alias.name
544        ));
545    }
546    document["notes"] = json!(notes);
547    document["engine"] = json!("core");
548    document["engine_requested"] = json!("core");
549    // Retained in report schema 3; there is no automatic fallback.
550    document["engine_fallback"] = Value::Null;
551    document["options"]["execution_scope"] = json!("compiled-plan-simulation");
552    drop(control_scope);
553    run_budget.finish(
554        &mut document,
555        &mut exit,
556        matches!(result.outcome, Outcome::Cancelled),
557    )?;
558    Ok(SimulateReport { document, exit })
559}
560
561fn tlc_exit(code: u32) -> u8 {
562    match code {
563        2107 | 2110 => 12,
564        2112 | 2113 => 13,
565        2114 => 11,
566        2104 | 2105 => 10,
567        2109 => 75,
568        2111 => 76,
569        _ => 255,
570    }
571}