Skip to main content

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}