qubit_fs_testkit/contract_run.rs
1// =============================================================================
2// Copyright (c) 2026 Haixing Hu.
3//
4// SPDX-License-Identifier: Apache-2.0
5//
6// Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Results owned by a single filesystem contract execution session.
9
10use crate::ContractFailure;
11use crate::ContractReport;
12
13/// Retains contract evidence and execution diagnostics in the borrowing suite.
14///
15/// A completed run may fail its requirements. Completion means only that
16/// execution and its automatic cleanup attempt returned.
17///
18/// # Examples
19///
20/// ```
21/// # mod support { include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/common/rustdoc_support.rs")); }
22/// # use support::RustdocSyncFixture;
23/// use qubit_fs_testkit::{FileSystemContract, FileSystemContractSuite};
24///
25/// let fixture = RustdocSyncFixture::new();
26/// let mut suite = FileSystemContractSuite::new(&fixture);
27/// suite.run_contract(FileSystemContract::Properties);
28/// let run = suite.run();
29/// assert!(!run.was_interrupted());
30/// assert!(!run.report().checks().is_empty());
31/// ```
32#[must_use]
33pub struct ContractRun {
34 /// Checks and evidence recorded during the contract execution.
35 pub(crate) report: ContractReport,
36 /// Cleanup completion and failures retained for this run.
37 pub(crate) cleanup: crate::CleanupReport,
38 /// Execution failures retained in observation order.
39 pub(crate) failures: Vec<ContractFailure>,
40 /// Whether execution started and may have been interrupted.
41 pub(crate) started: bool,
42 /// Whether execution returned and completed its cleanup attempt.
43 pub(crate) completed: bool,
44}
45
46impl ContractRun {
47 /// Creates the evidence container before any provider operation runs.
48 pub(crate) const fn new() -> Self {
49 Self {
50 report: ContractReport::new(),
51 cleanup: crate::CleanupReport::new(),
52 failures: Vec::new(),
53 started: false,
54 completed: false,
55 }
56 }
57
58 /// Returns the registered checks and their evidence.
59 ///
60 /// # Returns
61 ///
62 /// The report containing every check and its evidence.
63 #[must_use = "inspect the contract report"]
64 #[inline]
65 pub const fn report(&self) -> &ContractReport {
66 &self.report
67 }
68
69 /// Returns cleanup evidence and the history of all attempts.
70 ///
71 /// # Returns
72 ///
73 /// The cleanup report retained by this run.
74 #[must_use = "inspect the cleanup report"]
75 #[inline]
76 pub const fn cleanup(&self) -> &crate::CleanupReport {
77 &self.cleanup
78 }
79
80 /// Returns preserved failures in observation order.
81 ///
82 /// # Returns
83 ///
84 /// The failures recorded while executing the contract.
85 #[inline]
86 pub fn failures(&self) -> &[ContractFailure] {
87 &self.failures
88 }
89
90 /// Reports that a started session was dropped before returning its result.
91 ///
92 /// The runner exclusively borrows the suite while active. Callers can
93 /// inspect this retained state only after that borrow ends, including when
94 /// a pending execution or cleanup future is cancelled.
95 ///
96 /// # Returns
97 ///
98 /// `true` when the session started but did not complete.
99 #[must_use]
100 #[inline]
101 pub const fn was_interrupted(&self) -> bool {
102 self.started && !self.completed
103 }
104
105 /// Returns whether execution ended and every required check has evidence.
106 ///
107 /// # Returns
108 ///
109 /// `true` when execution, required evidence, and cleanup all succeeded.
110 #[must_use]
111 pub fn requirements_satisfied(&self) -> bool {
112 self.requirements_satisfied_with(&[])
113 }
114
115 /// Also requires evidence for caller-selected optional probes.
116 ///
117 /// Missing selections outside this run fail rather than being ignored.
118 ///
119 /// # Parameters
120 ///
121 /// * `required` - Optional check identities that must have evidence.
122 ///
123 /// # Returns
124 ///
125 /// `true` when execution and cleanup succeeded and every selected check
126 /// has evidence.
127 #[must_use]
128 pub fn requirements_satisfied_with(&self, required: &[crate::ContractCheckId]) -> bool {
129 self.execution_satisfied() && self.report.requirements_satisfied_with(required)
130 }
131
132 /// Includes every applicable optional probe in the evidence requirement.
133 ///
134 /// # Returns
135 ///
136 /// `true` when execution and cleanup succeeded and all applicable checks
137 /// have evidence.
138 #[must_use]
139 pub fn all_applicable_checks_verified(&self) -> bool {
140 self.execution_satisfied() && self.report.all_applicable_checks_verified()
141 }
142
143 /// Asserts the run's requirements and prints retained safe diagnostics.
144 ///
145 /// # Panics
146 /// Panics if execution, contract evidence, or cleanup did not succeed.
147 #[track_caller]
148 pub fn assert_satisfied(&self) {
149 self.assert_satisfied_with(&[]);
150 }
151
152 /// Asserts the run including caller-selected optional probes.
153 ///
154 /// # Panics
155 /// Panics for execution or cleanup failures and missing required evidence.
156 ///
157 /// # Parameters
158 ///
159 /// * `required` - Optional check identities that must have evidence.
160 #[track_caller]
161 pub fn assert_satisfied_with(&self, required: &[crate::ContractCheckId]) {
162 let diagnostics = self
163 .failures
164 .iter()
165 .chain(self.cleanup.failures().iter())
166 .map(ToString::to_string)
167 .collect::<Vec<_>>()
168 .join("; ");
169 assert!(
170 self.execution_satisfied(),
171 "[fs-testkit:run] completed={} cleanup_completed={}: {diagnostics}",
172 self.completed,
173 self.cleanup.completed()
174 );
175 self.report.assert_satisfied_with(required);
176 }
177
178 /// Keeps cleanup and lifecycle requirements identical for every policy.
179 #[must_use]
180 fn execution_satisfied(&self) -> bool {
181 self.completed && self.failures.is_empty() && self.cleanup.completed() && self.cleanup.failures().is_empty()
182 }
183}