Skip to main content

dive_runtime/capture/
evidence.rs

1//! Producer facts independent of retained state and adjacency storage.
2
3use std::time::Duration;
4
5use super::GraphCompletion;
6use crate::{CheckOptions, CheckResult, Stats};
7
8/// Actual completed exploration facts, without retaining its behavior graph.
9///
10/// Only a successful producer with the existing checked [`GraphCompletion`]
11/// creates this value. It certifies exploration, never temporal acceptance.
12/// Public graph edits, statistics and a zero queue cannot create these facts.
13///
14/// ```
15/// use dive_runtime::capture::{Complete, CompleteEvidence};
16/// fn release_graph(captured: Complete) -> CompleteEvidence {
17///     let counters = captured.evidence().stats();
18///     let evidence = captured.into_evidence();
19///     assert_eq!(evidence.stats(), counters);
20///     evidence
21/// }
22/// ```
23///
24/// ```compile_fail
25/// use dive_runtime::capture::CompleteEvidence;
26/// let forged = CompleteEvidence { /* public graph shape is insufficient */ };
27/// ```
28#[derive(Clone, Debug)]
29pub struct CompleteEvidence {
30    result: Box<CheckResult>,
31    options: CheckOptions,
32    stats: Stats,
33    completion: GraphCompletion,
34}
35
36impl CompleteEvidence {
37    #[doc(hidden)]
38    #[must_use]
39    pub fn new(
40        result: CheckResult,
41        options: CheckOptions,
42        stats: Stats,
43        completion: GraphCompletion,
44    ) -> Self {
45        Self {
46            result: Box::new(result),
47            options,
48            stats,
49            completion,
50        }
51    }
52
53    /// The original producer's shape/counter receipt, unchanged by detachment.
54    #[must_use]
55    pub fn completion(&self) -> &GraphCompletion {
56        &self.completion
57    }
58
59    /// The producer's complete ordinary safety result, including qualifications,
60    /// worker metadata, output, warnings and elapsed time.
61    #[must_use]
62    pub fn safety_result(&self) -> &CheckResult {
63        &self.result
64    }
65
66    /// Actual producer counters, independent of later public capture-field edits.
67    #[must_use]
68    pub const fn stats(&self) -> Stats {
69        self.stats
70    }
71
72    /// Original producer settings, including profile, seed, store and run budget.
73    #[must_use]
74    pub fn options(&self) -> &CheckOptions {
75        &self.options
76    }
77
78    #[doc(hidden)]
79    pub fn set_elapsed(&mut self, elapsed: Duration) {
80        self.result.elapsed = elapsed;
81    }
82}
83
84/// Actual successful committed-prefix facts, explicitly without completion.
85///
86/// A prefix has an unexhausted frontier. It can support a candidate word that
87/// still needs independent validation; it cannot establish a holding verdict.
88/// A safety failure or resource stop does not create a successful prefix.
89///
90/// ```
91/// use dive_runtime::capture::{Prefix, PrefixEvidence};
92/// fn release_prefix(captured: Prefix) -> PrefixEvidence {
93///     let level = captured.level();
94///     let evidence = captured.into_evidence();
95///     assert_eq!(evidence.level(), level);
96///     assert!(evidence.stats().left_on_queue > 0);
97///     evidence
98/// }
99/// ```
100///
101/// ```compile_fail
102/// use dive_runtime::capture::{CompleteEvidence, PrefixEvidence};
103/// fn promote(prefix: PrefixEvidence) -> CompleteEvidence { prefix.into() }
104/// ```
105#[derive(Clone, Debug)]
106pub struct PrefixEvidence {
107    result: Box<CheckResult>,
108    options: CheckOptions,
109    stats: Stats,
110    level: u64,
111}
112
113impl PrefixEvidence {
114    #[doc(hidden)]
115    #[must_use]
116    pub fn new(result: CheckResult, options: CheckOptions, stats: Stats, level: u64) -> Self {
117        Self {
118            result: Box::new(result),
119            options,
120            stats,
121            level,
122        }
123    }
124
125    /// Actual successful safety result at the committed boundary. Its nonzero
126    /// queue describes unfinished exploration, not safety/resource failure.
127    #[must_use]
128    pub fn safety_result(&self) -> &CheckResult {
129        &self.result
130    }
131
132    /// Actual counters at the committed boundary, including the nonzero queue.
133    #[must_use]
134    pub const fn stats(&self) -> Stats {
135        self.stats
136    }
137
138    /// Original producer settings, including profile, seed, store and run budget.
139    #[must_use]
140    pub fn options(&self) -> &CheckOptions {
141        &self.options
142    }
143
144    /// Last fully committed expansion level. Exploration remains incomplete.
145    #[must_use]
146    pub const fn level(&self) -> u64 {
147        self.level
148    }
149
150    #[doc(hidden)]
151    #[must_use]
152    pub fn into_result(self) -> Box<CheckResult> {
153        self.result
154    }
155}