1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
//! Error types for memd
//!
//! Provides a unified error type using thiserror for ergonomic error handling
//! throughout the codebase.
use thiserror::Error;
/// Main error type for memd operations
#[derive(Error, Debug)]
pub enum MemdError {
/// Configuration loading or parsing failures
#[error("configuration error: {0}")]
ConfigError(String),
/// Invalid input validation errors
#[error("validation error: {0}")]
ValidationError(String),
/// Storage operation failures
#[error("storage error: {0}")]
StorageError(String),
/// The dense index is momentarily unavailable because a writer (index
/// repair or bulk insert) holds its lock. Callers should retry shortly
/// or fall back to a degraded path rather than block behind the writer.
/// The display text starts with [`MemdError::INDEX_BUSY_MARKER`] so the
/// condition stays classifiable after crossing stringifying error
/// boundaries (operation error -> CLI -> warm wire).
#[error("{}: {reason}; retry shortly", MemdError::INDEX_BUSY_MARKER)]
IndexBusy {
/// What held the index lock.
reason: String,
},
/// Operation protocol errors.
#[error("protocol error: {0}")]
ProtocolError(String),
/// Warm worker identity does not match this CLI.
#[error(
"warm worker is incompatible: worker version {worker_version}, protocol {worker_protocol}; CLI version {cli_version}, protocol {cli_protocol}"
)]
IncompatibleWarmWorker {
worker_version: String,
worker_protocol: String,
cli_version: String,
cli_protocol: String,
},
/// Warm worker serves a different embedding model or search variant than
/// this CLI requested. Triggers the same shutdown+respawn as a version
/// skew so a resident MiniLM/hybrid worker never answers bge/dense-only
/// requests (and vice versa).
#[error(
"warm worker configuration mismatch: worker serves model {worker_model} / variant {worker_variant}; CLI requested model {cli_model} / variant {cli_variant}"
)]
WarmWorkerConfigMismatch {
worker_model: String,
worker_variant: String,
cli_model: String,
cli_variant: String,
},
/// The persisted dense index was built with a different embedding model
/// (vector dimension) than the one now active — i.e. `--embedding-model`
/// was changed on an existing store. Refused rather than silently wiping
/// the index (dense-only search has no sparse fallback).
#[error(
"dense index at {path} holds {store_dim}-d embeddings but the active embedding model produces {model_dim}-d vectors; this store was built with a different --embedding-model. Re-open with the original model, or set MEMD_BACKFILL_HNSW_ON_STARTUP=1 to discard the dense index and re-embed from segments."
)]
DenseIndexModelMismatch {
/// Path to the embedding cache that could not be reused.
path: std::path::PathBuf,
/// Vector dimension of the persisted index.
store_dim: usize,
/// Vector dimension the active embedding model produces.
model_dim: usize,
},
/// Another process currently owns the persistent-store writer lock.
#[error(
"writer lock held by another process ({holder}) at {lock_path}; if a memd warm worker is running, route this write through it (--warm auto, the default) or stop it with `memd warm stop`; otherwise stop the other memd process or retry later (MEMD_WRITER_LOCK_TIMEOUT_MS)"
)]
WriterLockHeld {
/// Path to the lock file.
lock_path: std::path::PathBuf,
/// Best-effort holder information read from the lock file.
holder: String,
},
/// Mutating operation attempted on a read-only persistent store.
#[error("store opened read-only: operation '{op}' not permitted")]
ReadOnlyStore {
/// Operation name.
op: String,
},
/// Embedding generation errors
#[error("embedding error: {0}")]
EmbeddingError(String),
/// IO errors
#[error("io error: {0}")]
IoError(#[from] std::io::Error),
/// JSON serialization/deserialization errors
#[error("json error: {0}")]
JsonError(#[from] serde_json::Error),
/// TOML deserialization errors (config parsing)
#[error("toml parse error: {0}")]
TomlError(#[from] toml::de::Error),
/// TOML serialization errors
#[error("toml serialization error: {0}")]
TomlSerError(#[from] toml::ser::Error),
/// SQLite database errors
#[error("database error: {0}")]
DatabaseError(#[from] rusqlite::Error),
/// Candle framework errors (for embeddings)
#[error("candle error: {0}")]
CandleError(String),
}
// Manual From implementation for candle_core::Error
impl From<candle_core::Error> for MemdError {
fn from(err: candle_core::Error) -> Self {
MemdError::CandleError(err.to_string())
}
}
impl MemdError {
/// Stable prefix of [`MemdError::IndexBusy`]'s display text. The ops and
/// CLI layers stringify errors between enums, so the warm worker and its
/// clients classify busy-ness by this marker rather than by variant.
/// Deliberately a code-like token: error messages can embed
/// user-controlled text (chunk bodies, echoed fields), and prose like
/// "dense index busy" could collide; `memd:dense-index-busy` cannot
/// plausibly appear in natural content.
pub const INDEX_BUSY_MARKER: &'static str = "memd:dense-index-busy";
/// True when an error message (possibly wrapped by other layers)
/// originated from [`MemdError::IndexBusy`].
pub fn message_indicates_index_busy(message: &str) -> bool {
message.contains(Self::INDEX_BUSY_MARKER)
}
}
/// Result type alias for memd operations
pub type Result<T> = std::result::Result<T, MemdError>;
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn error_display() {
let err = MemdError::ValidationError("test error".to_string());
assert_eq!(err.to_string(), "validation error: test error");
}
#[test]
fn error_from_io() {
let io_err = std::io::Error::new(std::io::ErrorKind::NotFound, "file not found");
let err: MemdError = io_err.into();
assert!(matches!(err, MemdError::IoError(_)));
}
#[test]
fn index_busy_classifiable_through_stringification() {
let err = MemdError::IndexBusy {
reason: "index repair in flight".to_string(),
};
// Direct display carries the marker...
assert!(MemdError::message_indicates_index_busy(&err.to_string()));
// ...and survives one more stringly wrap, as done by ops/CLI layers.
let wrapped = MemdError::ProtocolError(format!("warm worker command failed: {err}"));
assert!(MemdError::message_indicates_index_busy(
&wrapped.to_string()
));
// Unrelated errors are not classified busy.
assert!(!MemdError::message_indicates_index_busy(
&MemdError::StorageError("disk full".into()).to_string()
));
}
}