semantic_memory/
error.rs

1/// Error types for the semantic-memory crate.
2///
3/// All errors flow through [`MemoryError`], using `#[from]` for automatic
4/// conversion from rusqlite and reqwest errors.
5#[derive(Debug, thiserror::Error)]
6pub enum MemoryError {
7    /// SQLite / rusqlite error.
8    #[error("Database error: {0}")]
9    Database(#[from] rusqlite::Error),
10
11    /// HTTP error from the embedding provider.
12    #[error("Embedding request failed: {0}")]
13    EmbeddingRequest(#[from] reqwest::Error),
14
15    /// Embedding vector has wrong number of dimensions.
16    #[error("Embedding provider returned {actual} dimensions, expected {expected}")]
17    DimensionMismatch { expected: usize, actual: usize },
18
19    /// Embedding provider returned a different number of vectors than requested.
20    #[error("Embedding provider returned {returned} vectors, expected {requested}")]
21    EmbeddingBatchCountMismatch { requested: usize, returned: usize },
22
23    /// Embedding vector has wrong number of dimensions.
24    #[error("Embedding vector has {actual} dimensions, expected {expected}")]
25    EmbeddingDimensionMismatch { expected: usize, actual: usize },
26
27    /// Embedding vector contains NaN or infinity.
28    #[error("Embedding vector contains non-finite value at index {index}")]
29    NonFiniteEmbeddingValue { index: usize },
30
31    /// Raw vector BLOB length does not match the expected f32 dimensions.
32    #[error("Vector blob length mismatch: expected {expected_bytes} bytes, got {actual_bytes}")]
33    VectorBlobLengthMismatch {
34        expected_bytes: usize,
35        actual_bytes: usize,
36    },
37
38    /// Encoded vector artifact was produced with a different codec profile.
39    #[error("Vector codec profile mismatch: expected {expected_digest}, got {actual_digest}")]
40    VectorCodecProfileMismatch {
41        /// Digest required by the decoding codec.
42        expected_digest: String,
43        /// Digest carried by the encoded artifact.
44        actual_digest: String,
45    },
46
47    /// A durable search receipt ID already exists with different payload bytes.
48    #[error("Search receipt ID conflict for {receipt_id}")]
49    SearchReceiptConflict {
50        /// Conflicting receipt/request ID.
51        receipt_id: String,
52    },
53
54    /// Canonical content digest computation failed.
55    #[error("Digest error: {0}")]
56    DigestError(String),
57
58    /// A requested durable search receipt was not found.
59    #[error("Search receipt not found: {receipt_id}")]
60    SearchReceiptNotFound {
61        /// Requested receipt/request ID.
62        receipt_id: String,
63    },
64
65    /// Raw BLOB data is not a valid embedding.
66    #[error("Invalid embedding data: expected {expected_bytes} bytes, got {actual_bytes}")]
67    InvalidEmbedding {
68        expected_bytes: usize,
69        actual_bytes: usize,
70    },
71
72    /// Database was created with a different embedding model.
73    #[error("Embedding model mismatch: database has '{stored}', config specifies '{configured}'")]
74    ModelMismatch { stored: String, configured: String },
75
76    /// Session with the given ID does not exist.
77    #[error("Session not found: {0}")]
78    SessionNotFound(String),
79
80    /// Fact with the given ID does not exist.
81    #[error("Fact not found: {0}")]
82    FactNotFound(String),
83
84    /// Document with the given ID does not exist.
85    #[error("Document not found: {0}")]
86    DocumentNotFound(String),
87
88    /// Embedding provider is unreachable or misconfigured.
89    #[error("Embedding provider unavailable: {0}")]
90    EmbedderUnavailable(String),
91
92    /// Database migration failed.
93    #[error("Migration failed at version {version}: {reason}")]
94    MigrationFailed { version: u32, reason: String },
95
96    /// HNSW index error.
97    #[error("HNSW index error: {0}")]
98    HnswError(String),
99
100    /// Vector backend not yet implemented (e.g. usearch stub during migration).
101    #[error("Not implemented: {0}")]
102    NotImplemented(String),
103
104    /// Invalid HNSW key format.
105    #[error("Invalid HNSW key format: {0}")]
106    InvalidKey(String),
107
108    /// Quantization error.
109    #[error("Quantization error: {0}")]
110    QuantizationError(String),
111
112    /// Storage path error.
113    #[error("Storage path error: {0}")]
114    StorageError(String),
115
116    /// Index integrity check failed.
117    #[error("Index integrity check failed: {in_sqlite_not_hnsw} items in SQLite but not HNSW, {in_hnsw_not_sqlite} items in HNSW but not SQLite")]
118    IntegrityError {
119        in_sqlite_not_hnsw: usize,
120        in_hnsw_not_sqlite: usize,
121    },
122
123    /// Database schema is newer than this library version can handle.
124    #[error(
125        "Schema version {found} is ahead of max supported {supported} — upgrade semantic-memory"
126    )]
127    SchemaAhead {
128        /// Schema version found in the database.
129        found: u32,
130        /// Maximum version supported by this build.
131        supported: u32,
132    },
133
134    /// Content exceeds configured size limit.
135    #[error("Content too large: {size} bytes exceeds limit of {limit} bytes")]
136    ContentTooLarge {
137        /// Actual content size in bytes.
138        size: usize,
139        /// Configured limit in bytes.
140        limit: usize,
141    },
142
143    /// Namespace fact count would exceed the configured limit.
144    #[error("Namespace '{namespace}' has {count} facts, limit is {limit}")]
145    NamespaceFull {
146        /// Namespace that is full.
147        namespace: String,
148        /// Current fact count.
149        count: usize,
150        /// Configured limit.
151        limit: usize,
152    },
153
154    /// The configured database size ceiling would be exceeded by a new write.
155    #[error("Database size limit exceeded: current footprint is {current} bytes, limit is {limit} bytes")]
156    DatabaseSizeLimitExceeded {
157        /// Current observed database footprint in bytes.
158        current: u64,
159        /// Configured limit in bytes.
160        limit: u64,
161    },
162
163    /// Episode with the given ID does not exist.
164    #[error("Episode not found: {0}")]
165    EpisodeNotFound(String),
166
167    /// Connection pool reader acquisition timed out.
168    #[error("Pool reader acquisition timed out after {elapsed_ms}ms (pool size: {pool_size})")]
169    PoolTimeout {
170        /// How long the caller waited before giving up.
171        elapsed_ms: u64,
172        /// Number of reader slots in the pool.
173        pool_size: usize,
174    },
175
176    /// Brute-force vector search would scan more rows than the configured hard limit.
177    #[error(
178        "Vector scan hard limit exceeded for {table}: scanned {scanned} rows, limit is {limit}"
179    )]
180    VectorScanLimitExceeded {
181        /// Logical table/collection being scanned.
182        table: String,
183        /// Rows scanned before the circuit breaker tripped.
184        scanned: usize,
185        /// Configured hard limit.
186        limit: usize,
187    },
188
189    /// Configuration could not be normalized into a valid runtime state.
190    #[error("Invalid configuration for '{field}': {reason}")]
191    InvalidConfig {
192        /// The config field or section that failed validation.
193        field: &'static str,
194        /// Human-readable explanation of the invalid value.
195        reason: String,
196    },
197
198    /// Stored data is malformed or internally inconsistent.
199    #[error("Corrupt data in {table} ({row_id}): {detail}")]
200    CorruptData {
201        /// Table or logical collection containing the bad row.
202        table: &'static str,
203        /// Primary key / row identifier for the corrupt record.
204        row_id: String,
205        /// Human-readable description of the corruption.
206        detail: String,
207    },
208
209    /// Import envelope is structurally invalid.
210    #[error("Invalid import envelope: {reason}")]
211    ImportInvalid {
212        /// What is wrong with the envelope.
213        reason: String,
214    },
215
216    /// Import envelope has already been ingested (idempotent duplicate).
217    #[error("Import envelope already ingested: {envelope_id}")]
218    ImportDuplicate {
219        /// The duplicate envelope ID.
220        envelope_id: String,
221    },
222
223    /// Import hit a historical digest/receipt drift seam and needs operator repair.
224    #[error(
225        "Import requires digest migration or receipt repair for {source_envelope_id}: {detail}"
226    )]
227    ImportMigrationRequired {
228        /// The source envelope whose historical import receipts no longer line up.
229        source_envelope_id: String,
230        /// Human-readable conflict details and operator guidance.
231        detail: String,
232    },
233
234    /// Catch-all for other errors.
235    #[error("{0}")]
236    Other(String),
237}
238
239impl MemoryError {
240    /// Returns a stable string discriminant for programmatic matching.
241    pub fn kind(&self) -> &'static str {
242        match self {
243            Self::Database(_) => "database",
244            Self::EmbeddingRequest(_) => "embedding_request",
245            Self::DimensionMismatch { .. } => "dimension_mismatch",
246            Self::EmbeddingBatchCountMismatch { .. } => "embedding_batch_count_mismatch",
247            Self::EmbeddingDimensionMismatch { .. } => "embedding_dimension_mismatch",
248            Self::NonFiniteEmbeddingValue { .. } => "non_finite_embedding_value",
249            Self::VectorBlobLengthMismatch { .. } => "vector_blob_length_mismatch",
250            Self::VectorCodecProfileMismatch { .. } => "vector_codec_profile_mismatch",
251            Self::SearchReceiptConflict { .. } => "search_receipt_conflict",
252            Self::DigestError(_) => "digest_error",
253            Self::SearchReceiptNotFound { .. } => "search_receipt_not_found",
254            Self::InvalidEmbedding { .. } => "invalid_embedding",
255            Self::ModelMismatch { .. } => "model_mismatch",
256            Self::SessionNotFound(_) => "session_not_found",
257            Self::FactNotFound(_) => "fact_not_found",
258            Self::DocumentNotFound(_) => "document_not_found",
259            Self::EpisodeNotFound(_) => "episode_not_found",
260            Self::PoolTimeout { .. } => "pool_timeout",
261            Self::VectorScanLimitExceeded { .. } => "vector_scan_limit_exceeded",
262            Self::EmbedderUnavailable(_) => "embedder_unavailable",
263            Self::MigrationFailed { .. } => "migration_failed",
264            Self::HnswError(_) => "hnsw_error",
265            Self::NotImplemented(_) => "not_implemented",
266            Self::InvalidKey(_) => "invalid_key",
267            Self::QuantizationError(_) => "quantization_error",
268            Self::StorageError(_) => "storage_error",
269            Self::IntegrityError { .. } => "integrity_error",
270            Self::SchemaAhead { .. } => "schema_ahead",
271            Self::ContentTooLarge { .. } => "content_too_large",
272            Self::NamespaceFull { .. } => "namespace_full",
273            Self::DatabaseSizeLimitExceeded { .. } => "database_size_limit_exceeded",
274            Self::InvalidConfig { .. } => "invalid_config",
275            Self::CorruptData { .. } => "corrupt_data",
276            Self::ImportInvalid { .. } => "import_invalid",
277            Self::ImportDuplicate { .. } => "import_duplicate",
278            Self::ImportMigrationRequired { .. } => "import_migration_required",
279            Self::Other(_) => "other",
280        }
281    }
282}
semantic_memory/error.rs

semantic_memory/
error.rs
