khive_db/error.rs
1//! Error types for the SQLite storage layer.
2
3use std::time::Duration;
4
5use thiserror::Error;
6
7/// Errors produced by the SQLite storage backend.
8#[derive(Debug, Error)]
9pub enum SqliteError {
10 /// A request-scoped read or store acquisition stopped, or read cleanup failed.
11 #[error(transparent)]
12 RequestReadStopped(khive_storage::StorageError),
13
14 /// Underlying rusqlite driver error.
15 #[error("sqlite error: {0}")]
16 Rusqlite(#[from] rusqlite::Error),
17
18 /// Data invariant violation (corrupt row, unexpected schema state).
19 #[error("invalid data: {0}")]
20 InvalidData(String),
21
22 /// The process-local writer mutex was not acquired within the pool's
23 /// configured finite checkout deadline. This stage happens before SQLite
24 /// executes, so callers must not conflate it with SQLite busy/locked or
25 /// checkpoint starvation.
26 ///
27 /// The display text intentionally retains the historical `InvalidData`
28 /// prefix for compatibility while the variant supplies stable structural
29 /// classification (ADR-135 F6).
30 #[error("invalid data: timed out after {timeout:?} waiting for sqlite writer connection")]
31 WriterPoolCheckoutTimeout {
32 /// Pool checkout deadline that elapsed.
33 timeout: Duration,
34 },
35
36 /// A `PoolConfig` value violated a validated invariant at configuration
37 /// load time (e.g. ADR-131 Decision 2's `write_admission_deadline_ms`
38 /// range). Fires before any connection is opened, and is never silently
39 /// clamped into range.
40 #[error("invalid config: {0}")]
41 InvalidConfig(String),
42
43 /// Filesystem I/O error.
44 #[error("io error: {0}")]
45 Io(#[from] std::io::Error),
46
47 /// A versioned migration failed to apply.
48 #[error("migration v{version} failed: {error}")]
49 Migration {
50 /// The migration version number that failed.
51 version: u32,
52 /// Human-readable description of the failure.
53 error: String,
54 },
55}