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}