Skip to main content

dive_runtime/
usage.rs

1//! Storage usage evidence and the disk seen-state policy carried by
2//! [`crate::CheckOptions`] and [`crate::CheckResult`]. The stores
3//! themselves belong to the engines.
4
5use std::path::PathBuf;
6
7use dive_store::seen::{Limits, SeenError};
8
9use crate::Verdict;
10
11/// Storage evidence for the frontier only; this does not bound process memory.
12#[derive(Clone, Debug, Default, PartialEq, Eq)]
13pub struct FrontierUsage {
14    /// Encoded frontier resident byte budget, independently for each of the
15    /// current and next queues. `None` keeps both queues in memory.
16    pub memory_bytes_per_queue: Option<usize>,
17    /// Encoded record workspace bound, when spill is enabled.
18    pub max_record_bytes: Option<usize>,
19    /// Peak combined resident encoded data/index capacities of live queues.
20    pub peak_retained_bytes: u64,
21    /// Resident encoded bytes after explicit queue cleanup (normally zero).
22    pub retained_bytes: u64,
23    /// Confirmed complete writes including transient headers and indices.
24    /// A failed filesystem operation marks accounting incomplete; partial writes
25    /// may have left additional bytes and are never reported as exact.
26    pub spilled_bytes: u64,
27    /// Deciding search event before filesystem failure invalidated certification.
28    pub deciding_event_before_failure: Option<String>,
29    /// Filesystem failures, separately from any deciding safety event.
30    pub failures: Vec<String>,
31}
32
33/// Explicit opt-in transient disk seen-state policy.
34/// Default checking retains the original resident store. These bounds cover
35/// on-disk membership and key workspaces, not total search/process memory.
36#[derive(Clone, Debug, Default)]
37pub struct SeenOptions {
38    /// Full key/entry/probe/collision-summary admission limits. Zero entries or
39    /// probes are malformed policies; zero summary pairs is a valid refusal bound.
40    pub limits: Limits,
41    /// Parent for a private owned directory. Omitted uses system temporary storage.
42    /// Caller files are never overwritten or recursively removed.
43    pub directory: Option<PathBuf>,
44}
45
46/// Ordered engine phase of the first observed storage failure.
47#[derive(Clone, Copy, Debug, PartialEq, Eq)]
48#[non_exhaustive]
49pub enum SeenPhase {
50    /// Before generating Init; binding and assumptions may already have run.
51    Creation,
52    /// At one generated state's original key insertion position.
53    Insertion,
54    /// Membership at an explicit search-admission ceiling, before insertion.
55    AdmissionMembership,
56    /// A replay membership query at the original source/successor ordinal.
57    ReplayMembership,
58    /// A new key inserted after the original invariant-evaluation stop.
59    ReplayInsertion,
60    /// After safety EOF, before postconditions; required collision metadata failed.
61    Summary,
62    /// Explicit audit/removal after search and witness reconstruction.
63    Cleanup,
64}
65
66/// First positioned disk failure, never absence or a duplicate-state result.
67#[derive(Clone, Debug, PartialEq, Eq)]
68pub struct SeenFailure {
69    /// Ordered engine phase.
70    pub phase: SeenPhase,
71    /// First typed library or engine protocol cause, including later cleanup failure.
72    pub error: SeenError,
73    /// Generated-state counter at insertion; not a physical record count.
74    pub generated: Option<u64>,
75    /// Concrete predecessor ID at insertion, absent for Init.
76    pub predecessor: Option<u64>,
77    /// Original emitted successor ordinal, absent outside insertion.
78    pub successor_ordinal: Option<u64>,
79}
80
81/// Disk retention and cleanup facts, independent of full model certification.
82#[derive(Clone, Debug)]
83pub struct SeenUsage {
84    /// Resolved policy.
85    pub limits: Limits,
86    /// Successful key admissions at their original ordered positions. A later
87    /// predecessor/frontier failure can mean these are not published discoveries.
88    pub admitted_keys: u64,
89    /// Physical facts before explicit cleanup; expected bytes exclude partial
90    /// writes/staging after failure, and inserts have no crash-durability contract.
91    pub before_cleanup: Option<dive_store::seen::Stats>,
92    /// Facts after explicit cleanup, even when the first error is still returned.
93    pub after_cleanup: Option<dive_store::seen::Stats>,
94    /// First storage failure and position; subsequent cleanup never replaces it.
95    pub first_failure: Option<SeenFailure>,
96    /// Outcome before a later audit/cleanup failure prevented completion. This
97    /// is diagnostic evidence, not the final model verdict.
98    pub deciding_event_before_failure: Option<Verdict>,
99    /// Original stop and ordered replay facts; no generated-counter advance,
100    /// frontier publication or completed witness is implied by key admission.
101    pub replay: Option<SeenReplay>,
102}
103
104/// Positioned invariant-error replay evidence for an inline disk search.
105#[derive(Clone, Debug)]
106pub struct SeenReplay {
107    /// Original invariant evaluation error, retained even after a storage error.
108    pub original_error: Verdict,
109    /// Original concrete predecessor identifier.
110    pub predecessor: u64,
111    /// Original stopping successor ordinal.
112    pub stopped_successor_ordinal: u64,
113    /// Frozen generated count; replay does not count generated successors.
114    pub generated: u64,
115    /// Keys admitted during replay, separate from predecessor/frontier writes.
116    pub admitted_keys: u64,
117    /// TLC's logical replay queue contribution; no native queue is published.
118    pub queued: u64,
119    /// Actual Print/PrintT execution has an unproved repeated-output contract.
120    /// Original counts and error remain diagnostic evidence only.
121    pub unproved_print_output: bool,
122    /// Further error/refusal, when replay did not finish normally.
123    pub halted_by: Option<Verdict>,
124}