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