dive_store/seen.rs
1//! Fallible, private-file seen-state storage.
2//!
3//! Every operation is fallible: an I/O error is returned, never read as absence.
4//! The checker admits this storage through an explicit fallible inline route.
5//! Entries are physical library commits,
6//! not a model checker's ordered discovery-prefix count.
7//!
8//! Keys and offsets remain on disk. At most two key-sized workspaces, scalar index
9//! probes and sequential rehash workspaces are bounded by [`Limits`]. OS page
10//! cache, handles, paths and caller-owned keys are outside these bounds.
11
12mod files;
13
14use std::fs;
15use std::path::{Path, PathBuf};
16use std::sync::atomic::{AtomicU64, Ordering};
17
18use crate::StoreMode;
19
20static NEXT: AtomicU64 = AtomicU64::new(0);
21
22/// Maximum encoded key admitted by the default library policy: 64 MiB.
23pub const MAX_KEY_BYTES: usize = 64 * 1024 * 1024;
24
25/// Deterministic resource bounds, checked before record allocation or index growth.
26#[derive(Clone, Copy, Debug, PartialEq, Eq)]
27pub struct Limits {
28 /// Maximum one-record key buffer. Fingerprint keys always use eight bytes.
29 pub key_bytes: usize,
30 /// Maximum number of physically committed keys.
31 pub entries: u64,
32 /// Maximum slots examined by one index lookup, including rehash insertion.
33 pub probe_steps: u64,
34 /// Maximum pair comparisons for the bounded, quadratic collision summary.
35 /// Exceeding this refuses the summary; it never silently omits metadata.
36 pub summary_pairs: u64,
37}
38
39impl Default for Limits {
40 fn default() -> Self {
41 Self {
42 key_bytes: MAX_KEY_BYTES,
43 entries: 16 * 1024 * 1024,
44 probe_steps: 32 * 1024 * 1024,
45 summary_pairs: 1_000_000,
46 }
47 }
48}
49
50impl Limits {
51 /// Checks policy bounds without allocating, opening files or invoking callbacks.
52 ///
53 /// # Errors
54 /// An invalid key, entry or probe bound. A zero summary budget is valid and
55 /// explicitly refuses a summary requiring pair comparisons.
56 pub fn validate(self) -> Result<(), SeenError> {
57 if self.key_bytes > MAX_KEY_BYTES
58 || self.key_bytes < 8
59 || self.entries == 0
60 || self.entries > u64::from(u32::MAX)
61 || self.probe_steps == 0
62 {
63 return Err(error(
64 Operation::Admission,
65 "invalid disk seen-state limits",
66 ));
67 }
68 Ok(())
69 }
70}
71
72/// Borrowed storage identity; exact keys are existing canonical bytes, unchanged.
73#[derive(Clone, Copy, Debug)]
74pub enum Key<'a> {
75 /// Complete 64-bit fingerprint, including the high bit and zero.
76 Fingerprint(u64),
77 /// Full canonical state encoding. No normalization or provider is invoked.
78 Exact(&'a [u8]),
79}
80
81/// A successful, fully committed insertion.
82/// This is an in-process write commit, not crash durability or recovery.
83#[derive(Clone, Copy, Debug, PartialEq, Eq)]
84pub enum InsertOutcome {
85 /// The complete key already exists.
86 Present,
87 /// Record and index entry were both committed.
88 Inserted,
89}
90
91/// Typed operation at which the first failure occurred.
92#[derive(Clone, Copy, Debug, PartialEq, Eq)]
93pub enum Operation {
94 /// Invalid key mode, resource bound or checked arithmetic.
95 Admission,
96 /// Creating private owned files.
97 Create,
98 /// Reading file bytes or metadata.
99 Read,
100 /// Seeking to a bounded offset.
101 Seek,
102 /// Writing or flushing a record/index entry.
103 Write,
104 /// Allocating the bounded record workspace.
105 Allocate,
106 /// Constructing and committing a larger on-disk index.
107 Rehash,
108 /// Invalid header, offset, length, identity or checksum.
109 Corruption,
110 /// Computing the fingerprint-gap summary.
111 Summary,
112 /// Removing only owned files and their private directory.
113 Cleanup,
114}
115
116/// A storage failure retained by the poisoned store. Checksums detect accidental
117/// corruption; neither these files nor this error are an authenticity certificate.
118#[derive(Clone, Debug, PartialEq, Eq)]
119pub struct SeenError {
120 /// First failing operation; subsequent operations return this same cause.
121 pub operation: Operation,
122 /// Bounded diagnostic context, without a copy of the key.
123 pub message: String,
124 /// Additional cleanup failure, without replacing the original cause.
125 pub cleanup_failure: Option<String>,
126}
127
128impl SeenError {
129 /// Stable code for disk seen-state failures.
130 #[must_use]
131 pub const fn code(&self) -> &'static str {
132 "DIVE-S0700"
133 }
134}
135
136impl std::fmt::Display for SeenError {
137 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
138 write!(f, "{}: {:?}: {}", self.code(), self.operation, self.message)?;
139 if let Some(cleanup) = &self.cleanup_failure {
140 write!(f, "; cleanup also failed: {cleanup}")?;
141 }
142 Ok(())
143 }
144}
145impl std::error::Error for SeenError {}
146
147fn error(operation: Operation, cause: impl std::fmt::Display) -> SeenError {
148 SeenError {
149 operation,
150 message: cause.to_string(),
151 cleanup_failure: None,
152 }
153}
154
155/// Library storage facts, independent of semantic search-prefix statistics.
156#[derive(Clone, Copy, Debug, PartialEq, Eq)]
157pub struct Stats {
158 /// Record/index insertions whose full in-process writes completed. Inserts
159 /// do not fsync data and this library has no restart/import guarantee.
160 pub physical_entries: u64,
161 /// Current expected data/index lengths, not cumulative rehash traffic.
162 pub disk_bytes: u64,
163 /// Zero: there is no resident key/offset collection.
164 pub resident_key_bytes: u64,
165 /// Whether an operation failed and accounting may exclude partial writes.
166 pub poisoned: bool,
167 /// Whether explicit removal of all owned files and directory completed.
168 pub cleanup_completed: bool,
169}
170
171/// Owned transient disk set. Calls are coordinated through exclusive borrowing;
172/// this first library slice does not claim parallel engine integration.
173///
174/// ```
175/// use dive_store::{StoreMode, seen::{DiskSeen, InsertOutcome, Key, Limits}};
176/// let mut set = DiskSeen::create(StoreMode::Exact, &std::env::temp_dir(), Limits::default())?;
177/// assert_eq!(set.insert(Key::Exact(b"canonical-state"))?, InsertOutcome::Inserted);
178/// assert_eq!(set.insert(Key::Exact(b"canonical-state"))?, InsertOutcome::Present);
179/// assert!(set.contains(Key::Exact(b"canonical-state"))?);
180/// assert!(set.close()?.cleanup_completed);
181/// # Ok::<(), Box<dyn std::error::Error>>(())
182/// ```
183#[derive(Debug)]
184pub struct DiskSeen {
185 directory: PathBuf,
186 mode: StoreMode,
187 limits: Limits,
188 capacity: u64,
189 count: u64,
190 data_end: u64,
191 first: Option<SeenError>,
192 closed: bool,
193 audited: bool,
194 #[cfg(test)]
195 fault: Option<(Operation, u64)>,
196 #[cfg(test)]
197 forced_hash: Option<u64>,
198}
199
200impl DiskSeen {
201 /// Creates a unique child directory and versioned files, without clobbering
202 /// or adopting caller files. The parent must already exist.
203 ///
204 /// # Errors
205 /// Invalid bounds or filesystem creation/write/cleanup failures.
206 pub fn create(mode: StoreMode, parent: &Path, limits: Limits) -> Result<Self, SeenError> {
207 limits.validate()?;
208 let directory = parent.join(format!(
209 "dive-seen-{}-{}",
210 std::process::id(),
211 NEXT.fetch_add(1, Ordering::Relaxed)
212 ));
213 fs::create_dir(&directory).map_err(|e| error(Operation::Create, e))?;
214 let mut set = Self {
215 directory,
216 mode,
217 limits,
218 capacity: 8,
219 count: 0,
220 data_end: files::HEADER,
221 first: None,
222 closed: false,
223 audited: false,
224 #[cfg(test)]
225 fault: None,
226 #[cfg(test)]
227 forced_hash: None,
228 };
229 if let Err(mut failure) = set.initialize() {
230 if let Err(cleanup) = set.remove_owned() {
231 failure.cleanup_failure = Some(cleanup.message);
232 }
233 return Err(failure);
234 }
235 Ok(set)
236 }
237
238 /// Current physical facts, also available after a failure.
239 #[must_use]
240 pub fn stats(&self) -> Stats {
241 Stats {
242 physical_entries: self.count,
243 disk_bytes: if self.closed {
244 0
245 } else {
246 self.data_end + files::HEADER + self.capacity * files::SLOT
247 },
248 resident_key_bytes: 0,
249 poisoned: self.first.is_some(),
250 cleanup_completed: self.closed,
251 }
252 }
253
254 /// Tests full identity, never treating an error as absence.
255 ///
256 /// # Errors
257 /// Mode/bounds, file integrity or I/O failure; the first failure poisons future calls.
258 pub fn contains(&mut self, key: Key<'_>) -> Result<bool, SeenError> {
259 self.available()?;
260 let result = self.find_key(key).map(|(_, found)| found);
261 self.retain(result)
262 }
263
264 /// Commits one complete record and index slot. A failed partial write poisons
265 /// the store, never yielding `Inserted` or `Present`.
266 /// These are transient in-process writes, without per-insert data fsync or
267 /// a crash-recovery contract.
268 ///
269 /// # Errors
270 /// Membership, resource, allocation, write or rehash failure.
271 pub fn insert(&mut self, key: Key<'_>) -> Result<InsertOutcome, SeenError> {
272 self.available()?;
273 let result = self.insert_inner(key);
274 self.retain(result)
275 }
276
277 /// Fallible bounded-workspace TLC minimum-gap counterpart. This first slice
278 /// scans pairs quadratically and refuses beyond `summary_pairs`; it does not
279 /// allocate a fingerprint vector or silently remove collision metadata.
280 ///
281 /// # Errors
282 /// Exact mode, policy work limit, corruption or I/O failure.
283 pub fn tlc_min_gap(&mut self, fp_bits: u32) -> Result<u64, SeenError> {
284 self.available()?;
285 let result = self.gap_inner(fp_bits);
286 self.retain(result)
287 }
288
289 /// Explicitly removes owned files before a caller reports completion.
290 /// Unknown caller-added files are never deleted. A prior failure remains
291 /// authoritative even when cleanup succeeds, with any cleanup failure attached.
292 /// Cleanup may remove some owned files before failing; the poisoned store
293 /// cannot be reused, even if later cleanup succeeds.
294 ///
295 /// # Errors
296 /// The first retained failure, or explicit cleanup failure.
297 pub fn close(&mut self) -> Result<Stats, SeenError> {
298 let (stats, audited) = self.close_controlled(true, &|| true)?;
299 if audited {
300 Ok(stats)
301 } else {
302 Err(error(
303 Operation::Admission,
304 "store was discarded without a complete audit",
305 ))
306 }
307 }
308
309 /// Audits retained records under an actual owner, then removes owned files.
310 ///
311 /// `validate = false` discards an already stopped run without scanning its
312 /// remaining records. The Boolean result is true only after a complete
313 /// audit; cancellation still cleans up but can never certify the contents.
314 /// Later calls cannot upgrade discarded files into audited contents.
315 ///
316 /// ```
317 /// use dive_store::{StoreMode, seen::{DiskSeen, Key, Limits, SeenError}};
318 /// let mut seen = DiskSeen::create(StoreMode::Fingerprint, &std::env::temp_dir(), Limits::default())?;
319 /// seen.insert(Key::Fingerprint(7))?;
320 /// let (stats, audited) = seen.close_controlled(true, &|| false)?;
321 /// assert!(stats.cleanup_completed);
322 /// assert!(!audited);
323 /// assert!(seen.close().is_err());
324 /// # Ok::<(), SeenError>(())
325 /// ```
326 ///
327 /// # Errors
328 /// The original storage cause, with cleanup errors retained separately.
329 pub fn close_controlled(
330 &mut self,
331 validate: bool,
332 proceed: &dyn Fn() -> bool,
333 ) -> Result<(Stats, bool), SeenError> {
334 if !self.closed {
335 if validate && self.first.is_none() {
336 match self.audit_inner(proceed) {
337 Ok(audited) => self.audited = audited,
338 Err(failure) => self.first = Some(failure),
339 }
340 }
341 if let Err(cleanup) = self.remove_owned() {
342 if let Some(first) = &mut self.first {
343 first.cleanup_failure.get_or_insert(cleanup.message);
344 } else {
345 self.first = Some(cleanup);
346 }
347 } else {
348 self.closed = true;
349 }
350 }
351 self.first
352 .clone()
353 .map_or_else(|| Ok((self.stats(), self.audited)), Err)
354 }
355
356 fn remove_owned(&mut self) -> Result<(), SeenError> {
357 self.check_fault(Operation::Cleanup)?;
358 for name in ["data", "index", "index-next"] {
359 match fs::remove_file(self.directory.join(name)) {
360 Ok(()) => {}
361 Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
362 Err(e) => return Err(error(Operation::Cleanup, e)),
363 }
364 }
365 fs::remove_dir(&self.directory).map_err(|e| error(Operation::Cleanup, e))
366 }
367
368 fn available(&self) -> Result<(), SeenError> {
369 if let Some(first) = &self.first {
370 return Err(first.clone());
371 }
372 if self.closed {
373 return Err(error(Operation::Admission, "store is closed"));
374 }
375 Ok(())
376 }
377
378 fn retain<T>(&mut self, result: Result<T, SeenError>) -> Result<T, SeenError> {
379 if let Err(failure) = &result {
380 self.first = Some(failure.clone());
381 }
382 result
383 }
384
385 #[allow(
386 clippy::unused_self,
387 clippy::unnecessary_wraps,
388 reason = "test-only fault injection uses the production I/O boundaries"
389 )]
390 fn check_fault(&mut self, operation: Operation) -> Result<(), SeenError> {
391 #[cfg(test)]
392 if let Some((wanted, remaining)) = &mut self.fault
393 && *wanted == operation
394 {
395 if *remaining == 0 {
396 self.fault = None;
397 return Err(error(
398 operation,
399 if operation == Operation::Write {
400 std::io::Error::new(
401 std::io::ErrorKind::StorageFull,
402 "injected storage exhaustion",
403 )
404 .to_string()
405 } else {
406 "injected storage failure".to_owned()
407 },
408 ));
409 }
410 *remaining -= 1;
411 }
412 let _ = operation;
413 Ok(())
414 }
415}
416
417#[cfg(test)]
418mod tests;
419
420impl Drop for DiskSeen {
421 fn drop(&mut self) {
422 if !self.closed {
423 let _ = self.remove_owned();
424 }
425 }
426}