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
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
//! Error types for Mnemo.
use thiserror::Error;
/// All errors the Mnemo engine can produce.
///
/// `#[non_exhaustive]` (v0.14): new variants can arrive in a minor release,
/// so a `match` needs a catch-all arm.
#[derive(Error, Debug)]
#[non_exhaustive]
pub enum MnemoError {
/// An underlying I/O failure.
#[error("io error: {0}")]
Io(#[from] std::io::Error),
/// The file does not begin with the Mnemo magic bytes.
#[error("bad magic bytes — file is not a .mnemo database")]
BadMagic,
/// The on-disk format version is newer than this build understands.
#[error(
"unsupported .mnemo format version {0}: this build opens v4 to v9; \
a newer file needs a newer mnemo-engine"
)]
UnsupportedVersion(u16),
/// The header page failed its CRC check — a torn page-0 write or
/// corruption. [`crate::Mnemo::open`] tries to repair this from the WAL.
#[error("header checksum mismatch — page 0 is torn or corrupt")]
HeaderChecksum,
/// Returned when the supplied passphrase fails to unwrap the data key.
/// The failure is an authenticated-decryption failure, so it is
/// indistinguishable from a tampered key blob — both are rejected cleanly.
#[error("wrong passphrase, or the key material has been tampered with")]
WrongPassphrase,
/// AEAD authentication failed for a page: corruption or tampering.
#[error("page {0} failed authentication — the file is corrupt or tampered")]
PageAuthFailed(u64),
/// The v7 header seal failed authentication — at least one mutable
/// header field has been rewritten without the DEK. Open refuses to
/// proceed so a silent rollback or pointer-rewrite attack can't
/// surface stale data.
#[error("header seal authentication failed — mutable fields tampered with")]
HeaderTampered,
/// A low-level cryptographic operation failed.
#[error("cryptographic operation failed: {0}")]
Crypto(String),
/// Argon2id key derivation failed.
#[error("key derivation failed: {0}")]
Kdf(String),
/// A record failed to (de)serialize.
#[error("serialization error: {0}")]
Serialize(String),
/// No memory exists with the requested ID.
#[error("memory '{0}' not found")]
NotFound(String),
/// A vector did not match the database's configured dimensionality.
#[error("vector dimension mismatch: database expects {expected}, got {got}")]
DimensionMismatch {
/// Dimensionality the database was created with.
expected: usize,
/// Dimensionality of the offending vector.
got: usize,
},
/// A caller-supplied argument was invalid.
#[error("invalid argument: {0}")]
Invalid(String),
/// Another process (or another handle in this process) already holds a
/// conflicting OS file lock on the target `.mnemo` file. Write handles
/// take an exclusive lock; read-only handles take a shared lock. Two
/// writers or a writer + reader will collide.
///
/// A shared-mode call that waits out its deadline also returns this, with
/// `holder` naming the long operation that holds the file when one said
/// so (12.4: "compact since 12:01 (pid 4242, mnemo)").
#[error(
"file already locked by another handle: {path}{}",
holder_suffix(holder)
)]
#[non_exhaustive]
Locked {
/// The path whose lock was requested and refused.
path: std::path::PathBuf,
/// What holds the file, when the holder left a note: a shared-mode
/// long operation (compaction, an index build, an import) writes one.
holder: Option<String>,
},
/// A shared-mode write failed after its commit point and the handle
/// couldn't finish the commit itself, so the write **may have been
/// stored**: the next process to open the file finishes it. Don't retry
/// the same write blindly; check whether it's there.
#[error("the write may have been stored: {0}")]
MaybeStored(String),
/// A shared-mode write committed to a file that something renamed away
/// from the handle's path during the commit (an older `mnemo compact`,
/// say). The write isn't in the file now at the path.
#[error(
"the file at {path} was replaced during the write; the write isn't in the file \
now at that path"
)]
ReplacedDuringWrite {
/// The path that now names a different file.
path: std::path::PathBuf,
},
/// A shared-mode call was cancelled from another thread (an iOS
/// background activity's expiry handler, say) while it waited for the
/// file's lock. It released every lock it held and changed nothing.
#[error("cancelled while waiting for the file's lock; nothing was changed")]
Cancelled,
/// This build or this location can't do what was asked: shared mode on a
/// network or synced filesystem (without `allow_network_fs`), or on a
/// Windows build made with Rust before 1.85. The message says which.
#[error("not supported: {0}")]
Unsupported(String),
/// The file at this handle's path is no longer the file the handle
/// opened: something renamed another file over it (a compaction in
/// another process, or another program), or the file was moved or
/// removed (`missing`). Writing would go to a file nobody finds at the
/// path, so the handle refuses, and writes nothing.
/// A plain handle: reopen the path to use the file that's there now
/// ([`crate::Mnemo::try_close`] hands the handle back). A shared handle
/// (`shared`): the rename came between the window's identity check and
/// its commit (an older build's compaction renames without its lock);
/// calling again is safe, and the next call follows the new file.
#[error("{}", replaced_message(path, *shared, *missing))]
#[non_exhaustive]
Replaced {
/// The handle's path, which no longer names the file it opened.
path: std::path::PathBuf,
/// Raised in a shared-mode write window, where the next call
/// follows the new file by itself.
shared: bool,
/// Nothing is at the path any more: the file was moved or removed,
/// rather than another file renamed over it.
missing: bool,
},
/// A mutation was attempted on a handle opened via
/// [`crate::Mnemo::open_read_only`]. Reopen read-write to mutate.
#[error("operation requires a read-write handle (this one is read-only)")]
ReadOnly,
/// A read-only open was requested but the file has pending on-disk work
/// that requires a write handle to complete — a committed-but-unchecked
/// WAL transaction, or a format-version migration older than the current
/// `VERSION`. Open read-write once, close cleanly, then reopen read-only.
///
/// On a file older than v9 (which no build opens read-write since the
/// v8 sunset) the reason itself says to run `mnemo compact`, which
/// completes the work and converts the file, and the generic advice is
/// left off.
#[error("read-only open blocked: {reason}{}", needs_write_open_hint(reason))]
NeedsWriteOpen {
/// Human-readable reason (e.g. `"pending WAL recovery"`).
reason: &'static str,
},
/// The v8 sunset (v0.13): the file's format is older than v9, so it
/// can't be opened read-write. A v8 file still opens read-only
/// ([`crate::Mnemo::open_read_only`]); `mnemo compact` (or
/// [`crate::Mnemo::compact_file`]) converts any v4–v8 file to v9 and
/// keeps every live memory.
#[error(
"this file is format v{version}, which this build {}; run `mnemo compact <file>` \
(with `--key-file <key>` for a raw-key file) to convert it to v9 (every live \
memory is kept)",
if *version == 8 { "opens read-only" } else { "no longer opens" }
)]
FormatTooOld {
/// The file's on-disk format version.
version: u16,
},
/// EMBED-ID-1: the embedder passed to [`crate::Mnemo::set_embedder`]
/// isn't the one this file's vectors came from. The file records the
/// identity of the first embedder attached to it; a different name,
/// width or `normalize` flag is refused, because mixing two models'
/// vectors in one file silently breaks recall. Use the original
/// embedder, or create a new store for the new model.
///
/// Since v0.15 the identity includes the query convention
/// ([`crate::EmbedderIdentity::query_convention`]), and `mnemo reembed`
/// moves a file to a new embedder.
#[error(
"embedder identity mismatch: this file's vectors come from embedder {}, \
but the embedder given is {}. Open the file with its original embedder, \
create a new store for the new model, or move this file to it with \
`mnemo reembed`.",
stored.describe(),
given.describe()
)]
EmbedderMismatch {
/// The identity the file records (boxed since v0.15, which added
/// `query_convention`, to keep the error small).
stored: Box<crate::embed::EmbedderIdentity>,
/// The identity of the embedder that was passed.
given: Box<crate::embed::EmbedderIdentity>,
},
}
/// Convenience result alias used throughout the crate.
pub type Result<T> = std::result::Result<T, MnemoError>;
/// The advice after a [`MnemoError::NeedsWriteOpen`] reason. A reason that
/// names its own fix (`mnemo compact`, for a pre-v9 file) needs no other.
pub(crate) fn needs_write_open_hint(reason: &str) -> &'static str {
if reason.contains("mnemo compact") {
""
} else {
" — open read-write once to fix"
}
}
fn holder_suffix(holder: &Option<String>) -> String {
match holder {
Some(h) => format!(" (held by {h})"),
None => String::new(),
}
}
fn replaced_message(path: &std::path::Path, shared: bool, missing: bool) -> String {
let path = path.display();
if missing {
format!(
"the file at {path} was moved or removed after this handle opened it, and this \
handle's path no longer names it; nothing was written. Move it back, or open it \
where it is now"
)
} else if shared {
format!(
"the file at {path} was replaced (by an older build's compaction, or by another \
program) before this write; nothing was written, and the next call follows the \
new file"
)
} else {
format!(
"the file at {path} was replaced after this handle opened it (by a compaction, or \
by another program); nothing was written. Reopen it"
)
}
}