Skip to main content

qubit_fs_testkit/
contract_check_id.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//! Exhaustive typed identities for provider contract evidence.
9//!
10//! Adding a variant is a source-level change for downstream exhaustive matches.
11//! Stable string names are intended for selection and diagnostics, but callers
12//! that match this enum exhaustively must account for newly added checks.
13
14use std::fmt::Display;
15use std::fmt::Formatter;
16use std::fmt::Result as FmtResult;
17
18/// Identifies one independently reported provider contract check.
19///
20/// Stable names are intended for test selection and diagnostics. A report
21/// cannot invent a name outside this set; execution and evidence use the same
22/// identity even when synchronous and asynchronous drivers differ. Adding a
23/// variant can require downstream exhaustive matches to be updated.
24///
25/// # Examples
26///
27/// ```
28/// use qubit_fs_testkit::ContractCheckId;
29/// let check = ContractCheckId::WriteCancelOpen;
30/// assert_eq!(check.as_str(), "write/cancel-open");
31/// assert!(ContractCheckId::ALL.contains(&check));
32/// ```
33#[must_use]
34#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
35pub enum ContractCheckId {
36    /// Evidence for the `append/basic` contract.
37    AppendBasic,
38    /// Evidence for the `async-copy/cancel-commit` contract.
39    AsyncCopyCancelCommit,
40    /// Evidence for the `async-copy/cancel-native-attempt` contract.
41    AsyncCopyCancelNativeAttempt,
42    /// Evidence for the `async-copy/cancel-reader` contract.
43    AsyncCopyCancelReader,
44    /// Evidence for the `async-copy/cancel-writer` contract.
45    AsyncCopyCancelWriter,
46    /// Evidence for the `copy/atomic-file` contract.
47    CopyAtomicFile,
48    /// Evidence for the `copy/atomic-tree` contract.
49    CopyAtomicTree,
50    /// Evidence for the `copy/basic` contract.
51    CopyBasic,
52    /// Evidence for the `copy/durable-file` contract.
53    CopyDurableFile,
54    /// Evidence for the `copy/durable-tree` contract.
55    CopyDurableTree,
56    /// Evidence for the `copy/fallback-overwrite-rejected` contract.
57    CopyFallbackOverwriteRejected,
58    /// Evidence that a non-empty file is copied by the native method.
59    CopyNativeNonEmpty,
60    /// Evidence for the `copy/repeated-execute` contract.
61    CopyRepeatedExecute,
62    /// Evidence for the `copy/server-side` contract.
63    CopyServerSide,
64    /// Evidence for the `delete/basic` contract.
65    DeleteBasic,
66    /// Evidence for the `delete/if-match` contract.
67    DeleteIfMatch,
68    /// Evidence for the `delete/missing-ok` contract.
69    DeleteMissingOk,
70    /// Evidence for the `delete/tree` contract.
71    DeleteTree,
72    /// Evidence for the `directory/create` contract.
73    DirectoryCreate,
74    /// Evidence for the `directory/recursive` contract.
75    DirectoryRecursive,
76    /// Evidence for the `error/context` contract.
77    ErrorContext,
78    /// Evidence for the `list/basic` contract.
79    ListBasic,
80    /// Evidence for the `list/literal-prefix` contract.
81    ListLiteralPrefix,
82    /// Evidence for the `list/namespace` contract.
83    ListNamespace,
84    /// Evidence for the `list/raw-root-prefix` contract.
85    ListRawRootPrefix,
86    /// Evidence for the `list/pagination` contract.
87    ListPagination,
88    /// Evidence for the `list/prefix` contract.
89    ListPrefix,
90    /// Evidence for the `properties/capability-dependencies` contract.
91    PropertiesCapabilityDependencies,
92    /// Evidence for the `properties/limit-component-admission` contract.
93    PropertiesLimitComponentAdmission,
94    /// Evidence for the `properties/limit-list-page` contract.
95    PropertiesLimitListPage,
96    /// Evidence for the `properties/limit-path-admission` contract.
97    PropertiesLimitPathAdmission,
98    /// Evidence for the `properties/limits` contract.
99    PropertiesLimits,
100    /// Evidence for the `properties/path-constraints` contract.
101    PropertiesPathConstraints,
102    /// Evidence for the `properties/snapshot` contract.
103    PropertiesSnapshot,
104    /// Evidence for the `properties/symlink-policy` contract.
105    PropertiesSymlinkPolicy,
106    /// Evidence for the `read/basic` contract.
107    ReadBasic,
108    /// Evidence for the `read/checksum` contract.
109    ReadChecksum,
110    /// Evidence for the `read/checksum-corruption` contract.
111    ReadChecksumCorruption,
112    /// Evidence for the `read/if-match-current` contract.
113    ReadIfMatchCurrent,
114    /// Evidence for the `read/if-match-stale` contract.
115    ReadIfMatchStale,
116    /// Evidence for the `read/if-none-match-current` contract.
117    ReadIfNoneMatchCurrent,
118    /// Evidence for the `read/if-none-match-stale` contract.
119    ReadIfNoneMatchStale,
120    /// Evidence for the `read/range` contract.
121    ReadRange,
122    /// Evidence for the `read/range-limit` contract.
123    ReadRangeLimit,
124    /// Evidence for the `read/random-access-basic` contract.
125    RandomAccessBasic,
126    /// Evidence for the `read/random-access-bounds` contract.
127    RandomAccessBounds,
128    /// Evidence for the `read/random-access-range-limit` contract.
129    RandomAccessRangeLimit,
130    /// Evidence for the `read/random-access-identity` contract.
131    RandomAccessIdentity,
132    /// Evidence for the `read/random-access-cancel` contract.
133    RandomAccessCancel,
134    /// Evidence for the `rename/atomic` contract.
135    RenameAtomic,
136    /// Evidence for the `rename/basic` contract.
137    RenameBasic,
138    /// Evidence for the `rename/conflict` contract.
139    RenameConflict,
140    /// Evidence for the `rename/durable` contract.
141    RenameDurable,
142    /// Evidence for the `representation/empty` contract.
143    RepresentationEmpty,
144    /// Evidence for the `representation/symlink` contract.
145    RepresentationSymlink,
146    /// Evidence for the `stat/basic` contract.
147    StatBasic,
148    /// Evidence for the `stat/file-kind` contract.
149    StatFileKind,
150    /// Evidence for the `temp/atomic` contract.
151    TempAtomic,
152    /// Evidence for the `temp/directory` contract.
153    TempDirectory,
154    /// Evidence for the `temp/file` contract.
155    TempFile,
156    /// Evidence for the `temp/repeated-lifecycle` contract.
157    TempRepeatedLifecycle,
158    /// Evidence for the `write/atomic-replace-existing` contract.
159    WriteAtomicReplaceExisting,
160    /// Evidence for the `write/basic` contract.
161    WriteBasic,
162    /// Evidence for the `write/create-conflict` contract.
163    WriteCreateConflict,
164    /// Evidence for the `write/replace` contract.
165    WriteReplace,
166    /// Evidence for the `write/abort` contract.
167    WriteAbort,
168    /// Evidence for the `write/cancel-commit` contract.
169    WriteCancelCommit,
170    /// Evidence for the `write/cancel-flush` contract.
171    WriteCancelFlush,
172    /// Evidence for the `write/cancel-open` contract.
173    WriteCancelOpen,
174    /// Evidence for the `write/cancel-write` contract.
175    WriteCancelWrite,
176    /// Evidence for the `write/durable` contract.
177    WriteDurable,
178    /// Evidence for the `write/if-absent` contract.
179    WriteIfAbsent,
180    /// Evidence for the `write/if-match` contract.
181    WriteIfMatch,
182    /// Evidence for the `write/limit` contract.
183    WriteLimit,
184    /// Evidence for the `write/owning-operation` contract.
185    WriteOwningOperation,
186    /// Evidence for the `write/repeated-execute` contract.
187    WriteRepeatedExecute,
188}
189
190impl ContractCheckId {
191    /// Every recognized identity, including runtime-specific optional probes.
192    pub const ALL: &[Self] = &[
193        Self::AppendBasic,
194        Self::AsyncCopyCancelCommit,
195        Self::AsyncCopyCancelNativeAttempt,
196        Self::AsyncCopyCancelReader,
197        Self::AsyncCopyCancelWriter,
198        Self::CopyAtomicFile,
199        Self::CopyAtomicTree,
200        Self::CopyBasic,
201        Self::CopyDurableFile,
202        Self::CopyDurableTree,
203        Self::CopyFallbackOverwriteRejected,
204        Self::CopyNativeNonEmpty,
205        Self::CopyRepeatedExecute,
206        Self::CopyServerSide,
207        Self::DeleteBasic,
208        Self::DeleteIfMatch,
209        Self::DeleteMissingOk,
210        Self::DeleteTree,
211        Self::DirectoryCreate,
212        Self::DirectoryRecursive,
213        Self::ErrorContext,
214        Self::ListBasic,
215        Self::ListLiteralPrefix,
216        Self::ListNamespace,
217        Self::ListRawRootPrefix,
218        Self::ListPagination,
219        Self::ListPrefix,
220        Self::PropertiesCapabilityDependencies,
221        Self::PropertiesLimitComponentAdmission,
222        Self::PropertiesLimitListPage,
223        Self::PropertiesLimitPathAdmission,
224        Self::PropertiesLimits,
225        Self::PropertiesPathConstraints,
226        Self::PropertiesSnapshot,
227        Self::PropertiesSymlinkPolicy,
228        Self::ReadBasic,
229        Self::ReadChecksum,
230        Self::ReadChecksumCorruption,
231        Self::ReadIfMatchCurrent,
232        Self::ReadIfMatchStale,
233        Self::ReadIfNoneMatchCurrent,
234        Self::ReadIfNoneMatchStale,
235        Self::ReadRange,
236        Self::ReadRangeLimit,
237        Self::RandomAccessBasic,
238        Self::RandomAccessBounds,
239        Self::RandomAccessRangeLimit,
240        Self::RandomAccessIdentity,
241        Self::RandomAccessCancel,
242        Self::RenameAtomic,
243        Self::RenameBasic,
244        Self::RenameConflict,
245        Self::RenameDurable,
246        Self::RepresentationEmpty,
247        Self::RepresentationSymlink,
248        Self::StatBasic,
249        Self::StatFileKind,
250        Self::TempAtomic,
251        Self::TempDirectory,
252        Self::TempFile,
253        Self::TempRepeatedLifecycle,
254        Self::WriteAtomicReplaceExisting,
255        Self::WriteBasic,
256        Self::WriteCreateConflict,
257        Self::WriteReplace,
258        Self::WriteAbort,
259        Self::WriteCancelCommit,
260        Self::WriteCancelFlush,
261        Self::WriteCancelOpen,
262        Self::WriteCancelWrite,
263        Self::WriteDurable,
264        Self::WriteIfAbsent,
265        Self::WriteIfMatch,
266        Self::WriteLimit,
267        Self::WriteOwningOperation,
268        Self::WriteRepeatedExecute,
269    ];
270
271    /// Returns the sole phase responsible for this check.
272    ///
273    /// # Returns
274    ///
275    /// The contract phase that owns this check.
276    #[must_use]
277    pub const fn contract(self) -> crate::FileSystemContract {
278        crate::internal::check_catalog::specification(self).contract
279    }
280
281    /// Returns whether missing instrumentation may skip this diagnostic probe.
282    ///
283    /// Executed failures are never optional. Callers can require these probes
284    /// through the report's explicit requirement selection.
285    ///
286    /// # Returns
287    ///
288    /// `true` when missing instrumentation may skip this probe.
289    #[must_use]
290    pub const fn is_optional(self) -> bool {
291        crate::internal::check_catalog::specification(self).optional
292    }
293
294    /// Returns whether the synchronous driver can execute this check.
295    ///
296    /// # Returns
297    ///
298    /// `true` when the synchronous driver supports this check.
299    #[must_use]
300    pub const fn supports_synchronous(self) -> bool {
301        !crate::internal::check_catalog::specification(self).asynchronous_only
302    }
303
304    /// Returns this check's allocation-free stable diagnostic name.
305    ///
306    /// # Returns
307    ///
308    /// A process-lifetime name shared by selection, reports and diagnostics.
309    #[must_use]
310    #[inline]
311    pub const fn as_str(self) -> &'static str {
312        match self {
313            Self::AppendBasic => "append/basic",
314            Self::AsyncCopyCancelCommit => "async-copy/cancel-commit",
315            Self::AsyncCopyCancelNativeAttempt => "async-copy/cancel-native-attempt",
316            Self::AsyncCopyCancelReader => "async-copy/cancel-reader",
317            Self::AsyncCopyCancelWriter => "async-copy/cancel-writer",
318            Self::CopyAtomicFile => "copy/atomic-file",
319            Self::CopyAtomicTree => "copy/atomic-tree",
320            Self::CopyBasic => "copy/basic",
321            Self::CopyDurableFile => "copy/durable-file",
322            Self::CopyDurableTree => "copy/durable-tree",
323            Self::CopyFallbackOverwriteRejected => "copy/fallback-overwrite-rejected",
324            Self::CopyNativeNonEmpty => "copy/native-nonempty",
325            Self::CopyRepeatedExecute => "copy/repeated-execute",
326            Self::CopyServerSide => "copy/server-side",
327            Self::DeleteBasic => "delete/basic",
328            Self::DeleteIfMatch => "delete/if-match",
329            Self::DeleteMissingOk => "delete/missing-ok",
330            Self::DeleteTree => "delete/tree",
331            Self::DirectoryCreate => "directory/create",
332            Self::DirectoryRecursive => "directory/recursive",
333            Self::ErrorContext => "error/context",
334            Self::ListBasic => "list/basic",
335            Self::ListLiteralPrefix => "list/literal-prefix",
336            Self::ListNamespace => "list/namespace",
337            Self::ListRawRootPrefix => "list/raw-root-prefix",
338            Self::ListPagination => "list/pagination",
339            Self::ListPrefix => "list/prefix",
340            Self::PropertiesCapabilityDependencies => "properties/capability-dependencies",
341            Self::PropertiesLimitComponentAdmission => "properties/limit-component-admission",
342            Self::PropertiesLimitListPage => "properties/limit-list-page",
343            Self::PropertiesLimitPathAdmission => "properties/limit-path-admission",
344            Self::PropertiesLimits => "properties/limits",
345            Self::PropertiesPathConstraints => "properties/path-constraints",
346            Self::PropertiesSnapshot => "properties/snapshot",
347            Self::PropertiesSymlinkPolicy => "properties/symlink-policy",
348            Self::ReadBasic => "read/basic",
349            Self::ReadChecksum => "read/checksum",
350            Self::ReadChecksumCorruption => "read/checksum-corruption",
351            Self::ReadIfMatchCurrent => "read/if-match-current",
352            Self::ReadIfMatchStale => "read/if-match-stale",
353            Self::ReadIfNoneMatchCurrent => "read/if-none-match-current",
354            Self::ReadIfNoneMatchStale => "read/if-none-match-stale",
355            Self::ReadRange => "read/range",
356            Self::ReadRangeLimit => "read/range-limit",
357            Self::RandomAccessBasic => "read/random-access-basic",
358            Self::RandomAccessBounds => "read/random-access-bounds",
359            Self::RandomAccessRangeLimit => "read/random-access-range-limit",
360            Self::RandomAccessIdentity => "read/random-access-identity",
361            Self::RandomAccessCancel => "read/random-access-cancel",
362            Self::RenameAtomic => "rename/atomic",
363            Self::RenameBasic => "rename/basic",
364            Self::RenameConflict => "rename/conflict",
365            Self::RenameDurable => "rename/durable",
366            Self::RepresentationEmpty => "representation/empty",
367            Self::RepresentationSymlink => "representation/symlink",
368            Self::StatBasic => "stat/basic",
369            Self::StatFileKind => "stat/file-kind",
370            Self::TempAtomic => "temp/atomic",
371            Self::TempDirectory => "temp/directory",
372            Self::TempFile => "temp/file",
373            Self::TempRepeatedLifecycle => "temp/repeated-lifecycle",
374            Self::WriteAtomicReplaceExisting => "write/atomic-replace-existing",
375            Self::WriteBasic => "write/basic",
376            Self::WriteCreateConflict => "write/create-conflict",
377            Self::WriteReplace => "write/replace",
378            Self::WriteAbort => "write/abort",
379            Self::WriteCancelCommit => "write/cancel-commit",
380            Self::WriteCancelFlush => "write/cancel-flush",
381            Self::WriteCancelOpen => "write/cancel-open",
382            Self::WriteCancelWrite => "write/cancel-write",
383            Self::WriteDurable => "write/durable",
384            Self::WriteIfAbsent => "write/if-absent",
385            Self::WriteIfMatch => "write/if-match",
386            Self::WriteLimit => "write/limit",
387            Self::WriteOwningOperation => "write/owning-operation",
388            Self::WriteRepeatedExecute => "write/repeated-execute",
389        }
390    }
391}
392
393impl Display for ContractCheckId {
394    /// Writes the stable name without allocating or exposing provider data.
395    ///
396    /// # Parameters
397    ///
398    /// - `formatter`: The destination for the stable check name.
399    #[inline]
400    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
401        formatter.write_str(self.as_str())
402    }
403}