memvid_core/
error.rs

1use std::borrow::Cow;
2use std::path::PathBuf;
3
4use thiserror::Error;
5
6/// Result alias used throughout the core crate.
7pub type Result<T> = std::result::Result<T, MemvidError>;
8
9/// Process metadata for a lock holder used to produce human readable diagnostics.
10#[derive(Debug, Clone)]
11pub struct LockOwnerHint {
12    pub pid: Option<u32>,
13    pub cmd: Option<String>,
14    pub started_at: Option<String>,
15    pub file_path: Option<PathBuf>,
16    pub file_id: Option<String>,
17    pub last_heartbeat: Option<String>,
18    pub heartbeat_ms: Option<u64>,
19}
20
21/// Structured error returned when a `.mv2` is locked by another writer.
22#[derive(Debug, Error, Clone)]
23#[error("{message}")]
24pub struct LockedError {
25    pub file: PathBuf,
26    pub message: String,
27    pub owner: Option<LockOwnerHint>,
28    pub stale: bool,
29}
30
31impl LockedError {
32    #[must_use]
33    pub fn new(
34        file: PathBuf,
35        message: impl Into<String>,
36        owner: Option<LockOwnerHint>,
37        stale: bool,
38    ) -> Self {
39        Self {
40            file,
41            message: message.into(),
42            owner,
43            stale,
44        }
45    }
46}
47
48/// Canonical error surface for memvid-core.
49#[derive(Debug, Error)]
50pub enum MemvidError {
51    #[error("I/O error: {source}")]
52    Io {
53        source: std::io::Error,
54        path: Option<PathBuf>,
55    },
56
57    #[error("Serialization error: {0}")]
58    Encode(#[from] bincode::error::EncodeError),
59
60    #[error("Deserialization error: {0}")]
61    Decode(#[from] bincode::error::DecodeError),
62
63    #[error("Lock acquisition failed: {0}")]
64    Lock(String),
65
66    #[error(transparent)]
67    Locked(#[from] LockedError),
68
69    #[error("Checksum mismatch while validating {context}")]
70    ChecksumMismatch { context: &'static str },
71
72    #[error("Header validation failed: {reason}")]
73    InvalidHeader { reason: Cow<'static, str> },
74
75    #[error("Table of contents validation failed: {reason}")]
76    InvalidToc { reason: Cow<'static, str> },
77
78    #[error("Time index track is invalid: {reason}")]
79    InvalidTimeIndex { reason: Cow<'static, str> },
80
81    #[cfg(feature = "temporal_track")]
82    #[error("Temporal track is invalid: {reason}")]
83    InvalidTemporalTrack { reason: Cow<'static, str> },
84
85    #[error("Unsupported tier requested")]
86    InvalidTier,
87
88    #[error("Lexical index is not enabled")]
89    LexNotEnabled,
90
91    #[error("Vector index is not enabled")]
92    VecNotEnabled,
93
94    #[error("Vector dimension mismatch (expected {expected}, got {actual})")]
95    VecDimensionMismatch { expected: u32, actual: usize },
96
97    #[error("Auxiliary file detected: {path:?}")]
98    AuxiliaryFileDetected { path: PathBuf },
99
100    #[error("Embedded WAL is corrupted at offset {offset}: {reason}")]
101    WalCorruption {
102        offset: u64,
103        reason: Cow<'static, str>,
104    },
105
106    #[error("Manifest WAL is corrupted at offset {offset}: {reason}")]
107    ManifestWalCorrupted { offset: u64, reason: &'static str },
108
109    #[error("Unable to checkpoint embedded WAL: {reason}")]
110    CheckpointFailed { reason: String },
111
112    #[error("Ticket sequence is out of order (expected > {expected}, got {actual})")]
113    TicketSequence { expected: i64, actual: i64 },
114
115    #[error("Apply a ticket before mutating this memory (tier {tier:?})")]
116    TicketRequired { tier: crate::types::Tier },
117
118    #[error(
119        "Capacity exceeded. Current: {current} bytes, Limit: {limit} bytes, Required: {required} bytes"
120    )]
121    CapacityExceeded {
122        current: u64,
123        limit: u64,
124        required: u64,
125    },
126
127    #[error("API key required for files larger than {limit} bytes. File size: {file_size} bytes")]
128    ApiKeyRequired { file_size: u64, limit: u64 },
129
130    #[error(
131        "Memory already bound to '{existing_memory_name}' ({existing_memory_id}). Bound at: {bound_at}"
132    )]
133    MemoryAlreadyBound {
134        existing_memory_id: uuid::Uuid,
135        existing_memory_name: String,
136        bound_at: String,
137    },
138
139    #[error("Operation requires a sealed memory")]
140    RequiresSealed,
141
142    #[error("Operation requires an open memory")]
143    RequiresOpen,
144
145    #[error("Doctor command requires at least one operation")]
146    DoctorNoOp,
147
148    #[error("Doctor operation failed: {reason}")]
149    Doctor { reason: String },
150
151    #[error("Feature '{feature}' is not available in this build")]
152    FeatureUnavailable { feature: &'static str },
153
154    #[error("Invalid search cursor: {reason}")]
155    InvalidCursor { reason: &'static str },
156
157    #[error("Invalid frame {frame_id}: {reason}")]
158    InvalidFrame {
159        frame_id: crate::types::FrameId,
160        reason: &'static str,
161    },
162
163    #[error("Frame {frame_id} was not found")]
164    FrameNotFound { frame_id: crate::types::FrameId },
165
166    #[error("Frame with uri '{uri}' was not found")]
167    FrameNotFoundByUri { uri: String },
168
169    #[error("Ticket signature verification failed: {reason}")]
170    TicketSignatureInvalid { reason: Box<str> },
171
172    #[error("Model signature verification failed: {reason}")]
173    ModelSignatureInvalid { reason: Box<str> },
174
175    #[error("Model manifest invalid: {reason}")]
176    ModelManifestInvalid { reason: Box<str> },
177
178    #[error("Model integrity check failed: {reason}")]
179    ModelIntegrity { reason: Box<str> },
180
181    #[error("Extraction failed: {reason}")]
182    ExtractionFailed { reason: Box<str> },
183
184    #[error("Embedding failed: {reason}")]
185    EmbeddingFailed { reason: Box<str> },
186
187    #[error("Reranking failed: {reason}")]
188    RerankFailed { reason: Box<str> },
189
190    #[error("Invalid query: {reason}")]
191    InvalidQuery { reason: String },
192
193    #[error("Tantivy error: {reason}")]
194    Tantivy { reason: String },
195
196    #[error("Table extraction failed: {reason}")]
197    TableExtraction { reason: String },
198}
199
200impl From<std::io::Error> for MemvidError {
201    fn from(source: std::io::Error) -> Self {
202        Self::Io { source, path: None }
203    }
204}
205
206impl From<tantivy::TantivyError> for MemvidError {
207    fn from(value: tantivy::TantivyError) -> Self {
208        Self::Tantivy {
209            reason: value.to_string(),
210        }
211    }
212}
memvid_core/error.rs

memvid_core/
error.rs
