1use 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
10pub const SIMULATE_SCHEMA_VERSION: u32 = crate::REPORT_SCHEMA_VERSION;
12
13#[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 pub file: PathBuf,
30 pub config: Option<PathBuf>,
32 pub compat_tlc: bool,
34 pub seed: Option<i64>,
36 pub aril: u64,
38 pub depth: Option<usize>,
40 pub traces: u64,
42 pub workers: Option<usize>,
44 pub no_deadlock: bool,
46 pub action_stats: bool,
48 pub generation: bool,
52 pub time_limit: crate::BudgetSetting<std::time::Duration>,
54 pub max_memory: crate::BudgetSetting<u64>,
56 pub library_paths: Vec<PathBuf>,
58 pub module_paths: Vec<PathBuf>,
60}
61
62#[derive(Debug)]
64pub struct SimulateReport {
65 document: Value,
66 exit: u8,
67}
68
69impl SimulateReport {
70 #[must_use]
72 pub fn to_json(&self) -> Value {
73 self.document.clone()
74 }
75
76 #[must_use]
78 pub const fn exit_code(&self) -> u8 {
79 self.exit
80 }
81
82 #[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 #[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 #[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 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#[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 let validated = if matches!(result.outcome, Outcome::Sampled | Outcome::Violation { .. }) {
387 model.validate_sample_mode(&document, control.clone())
388 } else {
389 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 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 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}